@glyphteck/veyl 0.67.0 → 0.68.0

package/examples/codex-agent/codex-app-server.js

@@ -0,0 +1,737 @@
+import { spawn } from 'node:child_process';
+import { createInterface } from 'node:readline';
+import process from 'node:process';
+
+const DEFAULT_REQUEST_TIMEOUT_MS = 60_000;
+const DEFAULT_CLOSE_TIMEOUT_MS = 5_000;
+const MAX_STDERR_CHARS = 2_000;
+
+const modernDeclines = new Set([
+    'item/commandExecution/requestApproval',
+    'item/fileChange/requestApproval',
+]);
+
+const legacyDeclines = new Set([
+    'applyPatchApproval',
+    'execCommandApproval',
+]);
+
+function cleanText(value) {
+    return typeof value === 'string' ? value.trim() : '';
+}
+
+function optional(target, key, value) {
+    if (value !== undefined && value !== null && value !== '') target[key] = value;
+    return target;
+}
+
+function processError(message, details = {}) {
+    const error = new Error(message);
+    error.name = 'CodexAppServerProcessError';
+    Object.assign(error, details);
+    return error;
+}
+
+function missingRollout(error) {
+    return error instanceof CodexRpcError
+        && error.method === 'thread/resume'
+        && /no rollout found for thread id/iu.test(error.message);
+}
+
+function turnMessage(items = []) {
+    const messages = items.filter((item) => item?.type === 'agentMessage');
+    const final = messages.findLast((item) => item.phase === 'final_answer');
+    const selected = final || messages.at(-1);
+    return cleanText(selected?.text);
+}
+
+function normalizeTurn(turn = {}) {
+    const items = Array.isArray(turn.items) ? turn.items : [];
+    const inputIds = items
+        .filter((item) => item?.type === 'userMessage')
+        .map((item) => cleanText(item.clientId))
+        .filter(Boolean);
+    return {
+        id: cleanText(turn.id),
+        status: cleanText(turn.status),
+        error: turn.error ?? null,
+        inputIds: inputIds.length || turn.itemsView === 'full'
+            ? inputIds
+            : null,
+        finalText: turnMessage(items),
+    };
+}
+
+function normalizeThread(result, threadId) {
+    const turns = Array.isArray(result?.initialTurnsPage?.data)
+        ? result.initialTurnsPage.data
+        : result?.thread?.turns || [];
+    return {
+        threadId,
+        turns: turns
+            .map(normalizeTurn)
+            .filter((turn) => turn.id),
+    };
+}
+
+function inputParams(input, clientUserMessageId) {
+    if (!Array.isArray(input) || input.length === 0) {
+        throw new Error('Codex turn input must be a non-empty array');
+    }
+    const params = { input };
+    if (clientUserMessageId !== undefined) {
+        params.clientUserMessageId = clientUserMessageId;
+    }
+    return params;
+}
+
+export class CodexRpcError extends Error {
+    constructor(method, error = {}) {
+        super(cleanText(error.message) || `${method} failed`);
+        this.name = 'CodexRpcError';
+        this.method = method;
+        if (error.code !== undefined) this.code = error.code;
+        if (error.data !== undefined) this.data = error.data;
+    }
+}
+
+export class CodexAppServer {
+    constructor(options = {}) {
+        this.codexPath = cleanText(options.codexPath)
+            || cleanText(process.env.CODEX_PATH)
+            || 'codex';
+        this.cwd = cleanText(options.cwd) || process.cwd();
+        this.threadId = cleanText(options.threadId) || '';
+        this.model = cleanText(options.model) || '';
+        this.effort = cleanText(options.effort) || '';
+        this.developerInstructions = cleanText(options.developerInstructions) || '';
+        this.replaceMissingThread = options.replaceMissingThread === true;
+        this.serviceName = cleanText(options.serviceName) || 'veyl';
+        this.sandbox = options.sandbox ?? 'danger-full-access';
+        this.sandboxPolicy = options.sandboxPolicy ?? { type: 'dangerFullAccess' };
+        this.requestTimeoutMs = options.requestTimeoutMs
+            ?? DEFAULT_REQUEST_TIMEOUT_MS;
+        this.closeTimeoutMs = options.closeTimeoutMs
+            ?? DEFAULT_CLOSE_TIMEOUT_MS;
+        this.spawnProcess = options.spawnProcess || spawn;
+        this.onEventError = typeof options.onEventError === 'function'
+            ? options.onEventError
+            : () => {};
+        this.now = typeof options.now === 'function' ? options.now : Date.now;
+        this.listeners = new Set();
+        if (typeof options.onEvent === 'function') this.listeners.add(options.onEvent);
+
+        this.process = null;
+        this.reader = null;
+        this.opening = null;
+        this.openResult = null;
+        this.nextId = 1;
+        this.pending = new Map();
+        this.turns = new Map();
+        this.writeChain = Promise.resolve();
+        this.exitPromise = Promise.resolve();
+        this.resolveExit = null;
+        this.closed = false;
+        this.closing = false;
+    }
+
+    subscribe(listener) {
+        if (typeof listener !== 'function') {
+            throw new Error('Codex event listener must be a function');
+        }
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+
+    async open() {
+        if (this.closed) throw new Error('Codex App Server is closed');
+        if (this.openResult) return this.openResult;
+        if (!this.opening) {
+            const opening = this.startProcess();
+            this.opening = opening;
+            opening.finally(() => {
+                if (this.opening === opening) this.opening = null;
+            }).catch(() => {});
+        }
+        return this.opening;
+    }
+
+    async startTurn({ input, clientUserMessageId } = {}) {
+        await this.open();
+        const params = {
+            threadId: this.threadId,
+            ...inputParams(input, clientUserMessageId),
+            cwd: this.cwd,
+            approvalPolicy: 'never',
+            sandboxPolicy: this.sandboxPolicy,
+        };
+        optional(params, 'model', this.model);
+        optional(params, 'effort', this.effort);
+        const result = await this.request('turn/start', params);
+        const turnId = cleanText(result?.turn?.id);
+        if (!turnId) throw new Error('Codex App Server did not return a turn id');
+        return { turnId };
+    }
+
+    async steerTurn({ input, clientUserMessageId, expectedTurnId } = {}) {
+        const turnId = cleanText(expectedTurnId);
+        if (!turnId) throw new Error('expectedTurnId is required to steer a Codex turn');
+        await this.open();
+        return this.request('turn/steer', {
+            threadId: this.threadId,
+            ...inputParams(input, clientUserMessageId),
+            expectedTurnId: turnId,
+        });
+    }
+
+    async close() {
+        if (this.closed) return;
+        this.closed = true;
+        this.closing = true;
+        const child = this.process;
+        if (!child) return;
+
+        this.rejectPending(processError('Codex App Server closed'));
+        if (child.stdin?.writable) child.stdin.end();
+        if (child.exitCode === null && child.signalCode === null) child.kill('SIGTERM');
+
+        const timeout = new Promise((resolve) => {
+            const timer = setTimeout(() => resolve('timeout'), this.closeTimeoutMs);
+            timer.unref?.();
+        });
+        if (await Promise.race([this.exitPromise, timeout]) === 'timeout'
+            && child.exitCode === null && child.signalCode === null) {
+            child.kill('SIGKILL');
+            await this.exitPromise;
+        }
+    }
+
+    async startProcess() {
+        let child;
+        try {
+            child = this.spawnProcess(this.codexPath, ['app-server'], {
+                cwd: this.cwd,
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+        } catch (error) {
+            throw processError('Could not start Codex App Server', { cause: error });
+        }
+        this.attachProcess(child);
+
+        try {
+            await this.request('initialize', {
+                clientInfo: {
+                    name: 'veyl_codex_agent',
+                    title: 'Veyl Codex Agent',
+                    version: '1.0.0',
+                },
+                capabilities: {
+                    experimentalApi: true,
+                },
+            });
+            await this.notify('initialized', {});
+            let resumed = Boolean(this.threadId);
+            let replacedThreadId = '';
+            let result;
+            if (resumed) {
+                try {
+                    result = await this.resumeThread();
+                } catch (error) {
+                    if (!this.replaceMissingThread || !missingRollout(error)) {
+                        throw error;
+                    }
+                    replacedThreadId = this.threadId;
+                    this.threadId = '';
+                    resumed = false;
+                    result = await this.createThread();
+                }
+            } else {
+                result = await this.createThread();
+            }
+            const actualThreadId = cleanText(result?.thread?.id);
+            if (!actualThreadId) {
+                throw new Error('Codex App Server did not return a thread id');
+            }
+            if (this.threadId && actualThreadId !== this.threadId) {
+                throw new Error(`Codex resumed an unexpected thread: ${actualThreadId}`);
+            }
+            this.threadId = actualThreadId;
+            const opened = {
+                ...normalizeThread(result, actualThreadId),
+                ...(replacedThreadId ? { replacedThreadId } : {}),
+            };
+            this.openResult = opened;
+            this.emit({
+                type: 'server.ready',
+                threadId: actualThreadId,
+                resumed,
+                result: opened,
+            });
+            return opened;
+        } catch (error) {
+            await this.stopFailedProcess(child);
+            throw error;
+        }
+    }
+
+    attachProcess(child) {
+        if (!child?.stdin || !child?.stdout || !child?.stderr) {
+            throw processError('Codex App Server did not provide stdio streams');
+        }
+        this.process = child;
+        this.openResult = null;
+        this.writeChain = Promise.resolve();
+        this.exitPromise = new Promise((resolve) => {
+            this.resolveExit = resolve;
+        });
+        child.stdout.setEncoding?.('utf8');
+        child.stderr.setEncoding?.('utf8');
+        this.reader = createInterface({ input: child.stdout });
+        this.reader.on('line', (line) => this.handleLine(line));
+        child.stderr.on('data', (chunk) => {
+            const text = String(chunk).slice(0, MAX_STDERR_CHARS);
+            this.emit({ type: 'server.stderr', text });
+        });
+        child.stdin.on('error', (error) => this.handleProcessError(child, error));
+        child.once('error', (error) => this.handleProcessError(child, error));
+        child.once('exit', (code, signal) => this.handleExit(child, code, signal));
+        child.once('close', (code, signal) => this.handleExit(child, code, signal));
+    }
+
+    async createThread() {
+        const params = {
+            cwd: this.cwd,
+            approvalPolicy: 'never',
+            sandbox: this.sandbox,
+            serviceName: this.serviceName,
+        };
+        optional(params, 'model', this.model);
+        optional(params, 'developerInstructions', this.developerInstructions);
+        return this.request('thread/start', params);
+    }
+
+    async resumeThread() {
+        const params = {
+            threadId: this.threadId,
+            cwd: this.cwd,
+            approvalPolicy: 'never',
+            sandbox: this.sandbox,
+            excludeTurns: true,
+            initialTurnsPage: {
+                limit: 100,
+                sortDirection: 'desc',
+                itemsView: 'full',
+            },
+        };
+        optional(params, 'model', this.model);
+        optional(params, 'developerInstructions', this.developerInstructions);
+        return this.request('thread/resume', params);
+    }
+
+    async turnItems(turnId) {
+        const items = [];
+        let cursor = '';
+        do {
+            const params = {
+                threadId: this.threadId,
+                turnId,
+                limit: 200,
+                sortDirection: 'asc',
+            };
+            optional(params, 'cursor', cursor);
+            const result = await this.request('thread/items/list', params);
+            for (const entry of result?.data || []) {
+                if (entry?.item) items.push(entry.item);
+            }
+            cursor = cleanText(result?.nextCursor);
+        } while (cursor);
+        return items;
+    }
+
+    async hydrateCompletedTurn(turn) {
+        if (turn?.itemsView !== 'summary') return turn;
+        try {
+            return {
+                ...turn,
+                items: await this.turnItems(cleanText(turn.id)),
+                itemsView: 'full',
+            };
+        } catch (error) {
+            this.emit({
+                type: 'protocol.error',
+                reason: 'turn-items-unavailable',
+                error,
+            });
+            return turn;
+        }
+    }
+
+    request(method, params, timeoutMs = this.requestTimeoutMs) {
+        const id = this.nextId;
+        this.nextId += 1;
+        let timer;
+        const response = new Promise((resolve, reject) => {
+            timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(processError(`${method} timed out`, {
+                    method,
+                    outcomeUnknown: true,
+                }));
+                const child = this.process;
+                if (
+                    child
+                    && child.exitCode === null
+                    && child.signalCode === null
+                ) {
+                    child.kill('SIGTERM');
+                }
+            }, timeoutMs);
+            timer.unref?.();
+            this.pending.set(id, { method, resolve, reject, timer });
+        });
+        const sent = this.write({ id, method, params }).catch((error) => {
+            const pending = this.pending.get(id);
+            if (pending) {
+                this.pending.delete(id);
+                clearTimeout(pending.timer);
+                pending.reject(error);
+            }
+            throw error;
+        });
+        return Promise.all([sent, response]).then(([, result]) => result);
+    }
+
+    notify(method, params) {
+        return this.write({ method, params });
+    }
+
+    write(message) {
+        const operation = this.writeChain.then(() => this.writeLine(message));
+        this.writeChain = operation.catch(() => {});
+        return operation;
+    }
+
+    async writeLine(message) {
+        const input = this.process?.stdin;
+        if (!input?.writable) {
+            throw processError('Codex App Server is not writable', {
+                outcomeUnknown: true,
+            });
+        }
+        if (input.write(`${JSON.stringify(message)}\n`)) return;
+        await new Promise((resolve, reject) => {
+            const cleanup = () => {
+                input.off('drain', onDrain);
+                input.off('error', onError);
+                input.off('close', onClose);
+            };
+            const onDrain = () => {
+                cleanup();
+                resolve();
+            };
+            const onError = (error) => {
+                cleanup();
+                reject(processError('Could not write to Codex App Server', {
+                    cause: error,
+                    outcomeUnknown: true,
+                }));
+            };
+            const onClose = () => {
+                cleanup();
+                reject(processError('Codex App Server input closed', {
+                    outcomeUnknown: true,
+                }));
+            };
+            input.once('drain', onDrain);
+            input.once('error', onError);
+            input.once('close', onClose);
+        });
+    }
+
+    handleLine(line) {
+        if (!line.trim()) return;
+        let message;
+        try {
+            message = JSON.parse(line);
+        } catch {
+            this.emit({ type: 'protocol.error', reason: 'invalid-json' });
+            return;
+        }
+
+        if (message.id !== undefined
+            && (Object.hasOwn(message, 'result') || Object.hasOwn(message, 'error'))) {
+            this.handleResponse(message);
+            return;
+        }
+        if (message.id !== undefined && cleanText(message.method)) {
+            void this.handleServerRequest(message).catch((error) => {
+                this.emit({ type: 'protocol.error', reason: 'response-failed', error });
+            });
+            return;
+        }
+        if (cleanText(message.method)) {
+            this.handleNotification(message.method, message.params || {});
+        }
+    }
+
+    handleResponse(message) {
+        const pending = this.pending.get(message.id);
+        if (!pending) return;
+        this.pending.delete(message.id);
+        clearTimeout(pending.timer);
+        if (message.error) {
+            pending.reject(new CodexRpcError(pending.method, message.error));
+            return;
+        }
+        pending.resolve(message.result);
+    }
+
+    async handleServerRequest(message) {
+        const method = cleanText(message.method);
+        if (modernDeclines.has(method)) {
+            await this.write({ id: message.id, result: { decision: 'decline' } });
+            return;
+        }
+        if (legacyDeclines.has(method)) {
+            await this.write({ id: message.id, result: { decision: 'abort' } });
+            return;
+        }
+        if (method === 'item/tool/requestUserInput') {
+            const answers = Object.fromEntries(
+                (message.params?.questions || []).map((question) => [
+                    question.id,
+                    { answers: [] },
+                ])
+            );
+            await this.write({ id: message.id, result: { answers } });
+            return;
+        }
+        if (method === 'mcpServer/elicitation/request') {
+            await this.write({
+                id: message.id,
+                result: { action: 'decline', content: null, _meta: null },
+            });
+            return;
+        }
+        if (method === 'item/permissions/requestApproval') {
+            await this.write({
+                id: message.id,
+                result: { permissions: {}, scope: 'turn' },
+            });
+            return;
+        }
+        if (method === 'currentTime/read') {
+            await this.write({
+                id: message.id,
+                result: { currentTimeAt: Math.floor(this.now() / 1_000) },
+            });
+            return;
+        }
+        await this.write({
+            id: message.id,
+            error: {
+                code: -32601,
+                message: `Unsupported Codex client request: ${method}`,
+            },
+        });
+    }
+
+    handleNotification(method, params) {
+        if (params.threadId && this.threadId && params.threadId !== this.threadId) return;
+        if (method === 'turn/started') {
+            const turnId = cleanText(params.turn?.id);
+            if (!turnId) return;
+            this.turns.set(turnId, {
+                deltas: new Map(),
+                finalText: '',
+                lastText: '',
+                lastItemId: '',
+            });
+            this.emit({
+                type: 'turn.started',
+                threadId: params.threadId,
+                turnId,
+                turn: params.turn,
+            });
+            return;
+        }
+        if (method === 'item/agentMessage/delta') {
+            this.handleAgentDelta(params);
+            return;
+        }
+        if (method === 'item/completed') {
+            this.handleItemCompleted(params);
+            return;
+        }
+        if (method === 'turn/completed') {
+            void this.handleTurnCompleted(params).catch((error) => {
+                this.emit({
+                    type: 'protocol.error',
+                    reason: 'turn-completion-failed',
+                    error,
+                });
+            });
+            return;
+        }
+        this.emit({ type: 'notification', method, params });
+    }
+
+    turnState(turnId) {
+        let state = this.turns.get(turnId);
+        if (!state) {
+            state = {
+                deltas: new Map(),
+                finalText: '',
+                lastText: '',
+                lastItemId: '',
+            };
+            this.turns.set(turnId, state);
+        }
+        return state;
+    }
+
+    handleAgentDelta(params) {
+        const turnId = cleanText(params.turnId);
+        const itemId = cleanText(params.itemId);
+        if (!turnId || !itemId) return;
+        const state = this.turnState(turnId);
+        const delta = typeof params.delta === 'string' ? params.delta : '';
+        const text = `${state.deltas.get(itemId) || ''}${delta}`;
+        state.deltas.set(itemId, text);
+        state.lastItemId = itemId;
+        this.emit({
+            type: 'message.delta',
+            threadId: params.threadId,
+            turnId,
+            itemId,
+            delta,
+            text,
+        });
+    }
+
+    handleItemCompleted(params) {
+        const item = params.item;
+        if (item?.type !== 'agentMessage') {
+            this.emit({
+                type: 'item.completed',
+                threadId: params.threadId,
+                turnId: params.turnId,
+                item,
+            });
+            return;
+        }
+        const turnId = cleanText(params.turnId);
+        if (!turnId) return;
+        const state = this.turnState(turnId);
+        const itemId = cleanText(item.id);
+        const text = cleanText(item.text)
+            || cleanText(state.deltas.get(itemId));
+        state.lastText = text;
+        state.lastItemId = itemId;
+        if (item.phase === 'final_answer') state.finalText = text;
+        this.emit({
+            type: 'message.completed',
+            threadId: params.threadId,
+            turnId,
+            itemId,
+            phase: item.phase ?? null,
+            text,
+            item,
+        });
+    }
+
+    async handleTurnCompleted(params) {
+        const turn = await this.hydrateCompletedTurn(params.turn || {});
+        const turnId = cleanText(turn.id);
+        if (!turnId) return;
+        const normalized = normalizeTurn(turn);
+        const state = this.turns.get(turnId);
+        const turnFinal = turnMessage(turn.items);
+        const explicitTurnFinal = turnMessage(
+            (turn.items || []).filter((item) => item?.phase === 'final_answer')
+        );
+        const deltaText = cleanText(state?.deltas.get(state?.lastItemId));
+        const finalText = explicitTurnFinal
+            || state?.finalText
+            || turnFinal
+            || state?.lastText
+            || deltaText;
+        this.turns.delete(turnId);
+        this.emit({
+            type: 'turn.completed',
+            threadId: params.threadId,
+            turnId,
+            status: turn.status,
+            error: turn.error ?? null,
+            inputIds: normalized.inputIds,
+            finalText: finalText || '',
+            turn,
+        });
+    }
+
+    emit(event) {
+        for (const listener of this.listeners) {
+            try {
+                Promise.resolve(listener(event)).catch(this.onEventError);
+            } catch (error) {
+                this.onEventError(error);
+            }
+        }
+    }
+
+    handleProcessError(child, error) {
+        if (this.process !== child) return;
+        const wrapped = processError('Codex App Server process failed', {
+            cause: error,
+            outcomeUnknown: true,
+        });
+        this.rejectPending(wrapped);
+        this.emit({ type: 'server.error', error: wrapped });
+        if (
+            child.exitCode === null
+            && child.signalCode === null
+        ) {
+            child.kill('SIGTERM');
+        }
+    }
+
+    handleExit(child, code, signal) {
+        if (this.process !== child) return;
+        this.reader?.close();
+        this.reader = null;
+        this.process = null;
+        this.openResult = null;
+        this.resolveExit?.({ code, signal });
+        this.resolveExit = null;
+        const error = processError('Codex App Server exited', {
+            code,
+            signal,
+            outcomeUnknown: true,
+        });
+        this.rejectPending(error);
+        this.emit({
+            type: 'server.exit',
+            code,
+            signal,
+            expected: this.closing,
+        });
+    }
+
+    rejectPending(error) {
+        for (const pending of this.pending.values()) {
+            clearTimeout(pending.timer);
+            pending.reject(error);
+        }
+        this.pending.clear();
+    }
+
+    async stopFailedProcess(child) {
+        if (this.process !== child) return;
+        if (child.exitCode === null && child.signalCode === null) child.kill('SIGTERM');
+        await this.exitPromise;
+    }
+}
+
+export function createCodexAppServer(options = {}) {
+    return new CodexAppServer(options);
+}