@adecore/agents 0.0.1 → 0.17.0-beta.2

package/src/chat/codex-backend.ts

@@ -0,0 +1,397 @@
+import { accessSync, constants } from 'node:fs';
+import { attachmentImageMime, type ChatSkill } from '@adecore/agent-contracts';
+import { codexServiceTier, codexThreadOptions } from '../providers/codex.ts';
+import type { ApprovalDecision, BackendEvent, BackendHost, BackendLaunch, ChatBackend, TurnInput } from './backend.ts';
+import { CodexProtocol } from './codex-protocol.ts';
+import { attachmentNote } from './input.ts';
+import { CodexTransport, DEFAULT_CODEX_CLIENT, type CodexClientInfo, type CodexFrame } from './codex-transport.ts';
+import { errorText } from '../error-text.ts';
+
+function textInput(text: string) {
+    return [{ type: 'text', text, text_elements: [] }];
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/* The enabled skills of a `skills/list` answer; Codex reports one entry per folder it was asked about. */
+export function parseSkillsList(result: unknown): ChatSkill[] {
+    const data = isRecord(result) && Array.isArray(result.data) ? result.data : [];
+    const skills = new Map<string, ChatSkill>();
+    for (const entry of data) {
+        for (const skill of isRecord(entry) && Array.isArray(entry.skills) ? entry.skills : []) {
+            if (!isRecord(skill) || typeof skill.name !== 'string' || skill.enabled === false || skills.has(skill.name)) {
+                continue;
+            }
+            skills.set(skill.name, {
+                name: skill.name,
+                description: typeof skill.description === 'string' ? skill.description : '',
+                source: skill.pluginId ? 'plugin' : skill.scope === 'repo' ? 'project' : 'user'
+            });
+        }
+    }
+    return [...skills.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export interface CodexBackendOptions {
+    client?: CodexClientInfo;
+}
+
+/*
+ * One `codex app-server` process on JSON-RPC over stdio. `start` handshakes (initialize, then
+ * thread/start or thread/resume) before the first turn goes out, so every later request knows the
+ * thread id. What the host tells the agent goes in as the thread's developer instructions, which
+ * Codex keeps with the thread. The runtime modes are an approval policy plus a sandbox.
+ */
+export class CodexBackend implements ChatBackend {
+    readonly acknowledgesTurns = true;
+    private promptId: string | null = null;
+    private readonly launch: BackendLaunch;
+    private readonly host: BackendHost;
+    private readonly protocol: CodexProtocol;
+    private readonly client: CodexClientInfo;
+    private transport: CodexTransport | null = null;
+    private threadId = '';
+    /*
+     * Codex 0.154 ignores developer instructions on `thread/resume` (measured), so a thread started
+     * before anything was linked would never hear of its links; the first prompt of a resumed process says so instead.
+     */
+    private contextPending: string | null = null;
+    private imageInputSupported: boolean | null = null;
+    /* A turn asked for that Codex has not named yet; `turn/interrupt` needs that name. */
+    private turnUnnamed = false;
+    /* A stop that came in while the turn was unnamed, sent once `turn/started` names it. */
+    private interruptOwed = false;
+
+    constructor(launch: BackendLaunch, host: BackendHost, options: CodexBackendOptions = {}) {
+        this.launch = launch;
+        this.host = host;
+        this.client = options.client ?? DEFAULT_CODEX_CLIENT;
+        this.protocol = new CodexProtocol(launch.generation);
+        this.threadId = launch.resume ?? '';
+    }
+
+    get running(): boolean {
+        return this.transport !== null;
+    }
+
+    get pid(): number | null {
+        return this.transport?.pid ?? null;
+    }
+
+    async start(): Promise<void> {
+        if (this.transport) {
+            return;
+        }
+        const transport = new CodexTransport({
+            command: this.launch.command,
+            cwd: this.launch.cwd,
+            env: this.launch.env,
+            ...(this.launch.spawn ? { spawn: this.launch.spawn } : {}),
+            onError: (error) => this.fail(error),
+            onFrame: (frame) => this.handleFrame(transport, frame),
+            onExit: (exitCode, stderr) => this.handleExit(transport, exitCode, stderr)
+        });
+        this.transport = transport;
+        await transport.request('initialize', { clientInfo: this.client, capabilities: { experimentalApi: true, requestAttestation: false } });
+        transport.notify('initialized', {});
+        const tier = codexServiceTier(this.launch.selection);
+        const params = {
+            cwd: this.launch.cwd,
+            model: this.launch.selection.model,
+            ...(tier === null ? {} : { serviceTier: tier }),
+            ...codexThreadOptions(this.launch.runtimeMode)
+        };
+        const instructions = this.launch.instructions === null ? {} : { developerInstructions: this.launch.instructions };
+        let result: unknown;
+        if (this.launch.resume) {
+            try {
+                result = await transport.request('thread/resume', { threadId: this.launch.resume, excludeTurns: true, ...params });
+                this.contextPending = this.launch.resumeNote;
+            } catch (error) {
+                // The thread is gone from Codex's store; a fresh one keeps the chat usable.
+                this.emit({ type: 'note', level: 'warning', text: `Codex could not resume its thread (${errorText(error)}). Started a new one.` });
+                result = await transport.request('thread/start', { ...params, ...instructions });
+            }
+        } else {
+            result = await transport.request('thread/start', { ...params, ...instructions });
+        }
+        this.imageInputSupported = await this.readImageSupport(transport);
+        for (const event of this.protocol.threadReady(result)) {
+            if (event.type === 'session' && event.agentSessionId) {
+                this.threadId = event.agentSessionId;
+            }
+            this.emit(event);
+        }
+    }
+
+    sendTurn(input: TurnInput): void {
+        const images = input.attachments.filter((attachment) => attachmentImageMime(attachment) !== null);
+        if (images.length > 0 && this.imageInputSupported === false) {
+            throw new Error(`${this.launch.modelName} does not support image input. Choose a model that accepts images.`);
+        }
+        for (const attachment of images) {
+            try {
+                accessSync(attachment.path, constants.R_OK);
+            } catch {
+                throw new Error(`Could not read attached image "${attachment.name}". Attach it again and retry.`);
+            }
+        }
+        const parts: string[] = [];
+        if (this.contextPending !== null) {
+            parts.push(`${this.contextPending}\n\n`);
+            this.contextPending = null;
+        }
+        if (input.preamble !== null) {
+            parts.push(`${input.preamble}\n\n`);
+        }
+        parts.push(input.text);
+        const note = attachmentNote(input.attachments);
+        if (note !== '') {
+            parts.push(`\n\n${note}`);
+        }
+        const effort = this.launch.selection.options.effort;
+        const tier = codexServiceTier(this.launch.selection);
+        this.turnUnnamed = true;
+        this.promptId = input.promptId ?? null;
+        this.request(
+            'turn/start',
+            {
+                threadId: this.threadId,
+                input: [...textInput(parts.join('')), ...images.map((attachment) => ({ type: 'localImage', path: attachment.path }))],
+                model: this.launch.selection.model,
+                ...(typeof effort === 'string' ? { effort } : {}),
+                ...(tier === null ? {} : { serviceTier: tier })
+            },
+            () => this.acceptPrompt(input.promptId)
+        );
+    }
+
+    private acceptPrompt(promptId: string | undefined): void {
+        if (promptId !== undefined && this.promptId === promptId) {
+            this.emit({ type: 'turn.accepted', promptId });
+        }
+    }
+
+    private fail(error: unknown): void {
+        this.protocol.forgetPending();
+        this.emit({ type: 'failed', message: errorText(error), processAlive: this.running });
+    }
+
+    private respond(requestId: string, rpcId: number | string, result: unknown): boolean {
+        try {
+            if (!this.transport) {
+                throw new Error('Codex is not running');
+            }
+            this.transport.respond(rpcId, result);
+            return true;
+        } catch (error) {
+            this.emit({ type: 'request.withdrawn', requestId });
+            this.fail(error);
+            return false;
+        }
+    }
+
+    private async readImageSupport(transport: CodexTransport): Promise<boolean | null> {
+        let cursor: string | null = null;
+        const seen = new Set<string>();
+        try {
+            do {
+                const result = await transport.request('model/list', { includeHidden: true, ...(cursor === null ? {} : { cursor }) });
+                if (!isRecord(result) || !Array.isArray(result.data)) {
+                    return null;
+                }
+                const model = result.data.find((entry) => isRecord(entry) && entry.model === this.launch.selection.model);
+                if (isRecord(model)) {
+                    return Array.isArray(model.inputModalities) ? model.inputModalities.includes('image') : null;
+                }
+                cursor = typeof result.nextCursor === 'string' ? result.nextCursor : null;
+                if (cursor !== null) {
+                    if (seen.has(cursor)) {
+                        return null;
+                    }
+                    seen.add(cursor);
+                }
+            } while (cursor !== null);
+        } catch {
+            // Older app-servers may not report modalities; their turn response remains authoritative.
+        }
+        return null;
+    }
+
+    compact(): void {
+        this.turnUnnamed = true;
+        this.request('thread/compact/start', { threadId: this.threadId });
+    }
+
+    /* Not a turn: a name Codex refuses is not something the person has to hear about. */
+    setTitle(title: string): void {
+        if (!this.transport || this.threadId === '') {
+            return;
+        }
+        void this.transport.request('thread/name/set', { threadId: this.threadId, name: title }).catch(() => undefined);
+    }
+
+    /* Codex keeps its own skill index, so the running app-server is the authority on what it will run. */
+    async listSkills(): Promise<ChatSkill[]> {
+        const transport = this.transport;
+        if (!transport) {
+            return [];
+        }
+        return parseSkillsList(await transport.request('skills/list', { cwds: [this.launch.cwd] }));
+    }
+
+    listThreadItems(params: { threadId: string; cursor?: string; limit: number; sortDirection: 'asc' | 'desc' }): Promise<unknown> {
+        const transport = this.transport;
+        if (!transport) {
+            return Promise.reject(new Error('thread/items/list failed: Codex is not running'));
+        }
+        return transport.request('thread/items/list', params);
+    }
+
+    interrupt(): void {
+        const turnId = this.protocol.turnId;
+        if (!this.transport) {
+            return;
+        }
+        if (!turnId) {
+            this.interruptOwed = this.turnUnnamed;
+            // A child request can open a host turn after the root's native turn already ended.
+            if (!this.turnUnnamed) {
+                this.emit({ type: 'turn.done', state: 'aborted', costUsd: 0 });
+            }
+            return;
+        }
+        void this.transport.request('turn/interrupt', { threadId: this.threadId, turnId }).catch(() => {
+            // A turn that already ended has nothing to interrupt.
+        });
+    }
+
+    stopTask(taskId: string): void {
+        if (!this.transport) {
+            return;
+        }
+        void this.transport.request('thread/backgroundTerminals/terminate', { threadId: this.threadId, processId: taskId }).catch(() => {
+            // A process that already ended has nothing to terminate; its item says so on its own.
+        });
+    }
+
+    respondApproval(requestId: string, decision: ApprovalDecision): boolean {
+        if (!this.transport) {
+            return false;
+        }
+        const answer = this.protocol.approvalDecision(requestId, decision);
+        if (!answer) {
+            return false;
+        }
+        return this.respond(requestId, answer.rpcId, answer.result);
+    }
+
+    respondQuestion(requestId: string, answers: Record<string, string>): boolean {
+        if (!this.transport) {
+            return false;
+        }
+        const answer = this.protocol.questionAnswer(requestId, answers);
+        if (!answer) {
+            return false;
+        }
+        if (answer.kind === 'respond') {
+            return this.respond(requestId, answer.rpcId, answer.result);
+        }
+        const turnId = this.protocol.turnId;
+        if (!turnId) {
+            // Codex refuses a steer without the turn it is meant for, and there is none left to join.
+            return false;
+        }
+        this.request('turn/steer', { threadId: this.threadId, expectedTurnId: turnId, input: textInput(answer.text) });
+        return true;
+    }
+
+    /* Codex asks its async question once and waits; forgetting it locally is all a dismissal is. */
+    dismissRequest(requestId: string): boolean {
+        return this.protocol.dismissQuestion(requestId);
+    }
+
+    declineRequest(requestId: string, _message: string): boolean {
+        const answer = this.protocol.declineRequest(requestId);
+        if (!this.transport || !answer) {
+            return false;
+        }
+        return this.respond(requestId, answer.rpcId, answer.result);
+    }
+
+    stop(): void {
+        this.transport?.stop();
+    }
+
+    dispose(): Promise<void> {
+        const transport = this.transport;
+        this.transport = null;
+        return transport?.dispose() ?? Promise.resolve();
+    }
+
+    /* A request whose failure the person has to hear about, since it is the turn that cannot go on. */
+    private request(method: string, params: unknown, accepted?: () => void): void {
+        const transport = this.transport;
+        if (!transport) {
+            this.emit({ type: 'failed', message: `${method} failed: Codex is not running` });
+            return;
+        }
+        void transport
+            .request(method, params)
+            .then(() => {
+                if (this.transport === transport) {
+                    accepted?.();
+                }
+            })
+            .catch((error: unknown) => {
+                if (this.transport === transport) {
+                    this.emit({ type: 'failed', message: errorText(error) });
+                }
+            });
+    }
+
+    private handleFrame(transport: CodexTransport, frame: CodexFrame): void {
+        if (this.transport !== transport) {
+            return;
+        }
+        const events = this.protocol.handle(frame);
+        // A server request the protocol did not take still needs an answer, or Codex waits forever.
+        if (frame.id !== undefined && events.length === 0 && (typeof frame.id === 'number' || typeof frame.id === 'string')) {
+            transport.respondError(frame.id, -32601, `${this.client.title} does not handle ${String(frame.method)}`);
+        }
+        if (frame.method === 'turn/started' && this.protocol.turnId !== null) {
+            this.acceptPrompt(this.promptId ?? undefined);
+        }
+        for (const event of events) {
+            this.emit(event);
+        }
+        if (this.turnUnnamed && this.protocol.turnId !== null) {
+            this.turnUnnamed = false;
+            if (this.interruptOwed) {
+                this.interruptOwed = false;
+                this.interrupt();
+            }
+        }
+    }
+
+    private handleExit(transport: CodexTransport, exitCode: number | null, stderr: string | null): void {
+        if (this.transport !== transport) {
+            return;
+        }
+        this.transport = null;
+        this.protocol.forgetPending();
+        this.emit({ type: 'exit', exitCode, ...(stderr === null ? {} : { stderr }) });
+    }
+
+    private emit(event: BackendEvent): void {
+        // A turn that ended or never started leaves no stop for the next one to take.
+        if (event.type === 'turn.done' || event.type === 'failed' || event.type === 'exit') {
+            this.turnUnnamed = false;
+            this.interruptOwed = false;
+            this.promptId = null;
+        }
+        this.host.onEvent(event);
+    }
+}