@adecore/agents 0.0.1 → 0.17.0-beta.2

package/dist/chat/codex-backend.js

@@ -0,0 +1,364 @@
+import { accessSync, constants } from 'node:fs';
+import { attachmentImageMime } from '@adecore/agent-contracts';
+import { codexServiceTier, codexThreadOptions } from '../providers/codex.js';
+import { CodexProtocol } from './codex-protocol.js';
+import { attachmentNote } from './input.js';
+import { CodexTransport, DEFAULT_CODEX_CLIENT } from './codex-transport.js';
+import { errorText } from '../error-text.js';
+function textInput(text) {
+    return [{ type: 'text', text, text_elements: [] }];
+}
+function isRecord(value) {
+    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) {
+    const data = isRecord(result) && Array.isArray(result.data) ? result.data : [];
+    const skills = new Map();
+    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));
+}
+/*
+ * 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 {
+    acknowledgesTurns = true;
+    promptId = null;
+    launch;
+    host;
+    protocol;
+    client;
+    transport = null;
+    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.
+     */
+    contextPending = null;
+    imageInputSupported = null;
+    /* A turn asked for that Codex has not named yet; `turn/interrupt` needs that name. */
+    turnUnnamed = false;
+    /* A stop that came in while the turn was unnamed, sent once `turn/started` names it. */
+    interruptOwed = false;
+    constructor(launch, host, options = {}) {
+        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() {
+        return this.transport !== null;
+    }
+    get pid() {
+        return this.transport?.pid ?? null;
+    }
+    async start() {
+        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;
+        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) {
+        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 = [];
+        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));
+    }
+    acceptPrompt(promptId) {
+        if (promptId !== undefined && this.promptId === promptId) {
+            this.emit({ type: 'turn.accepted', promptId });
+        }
+    }
+    fail(error) {
+        this.protocol.forgetPending();
+        this.emit({ type: 'failed', message: errorText(error), processAlive: this.running });
+    }
+    respond(requestId, rpcId, result) {
+        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;
+        }
+    }
+    async readImageSupport(transport) {
+        let cursor = null;
+        const seen = new Set();
+        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() {
+        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) {
+        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() {
+        const transport = this.transport;
+        if (!transport) {
+            return [];
+        }
+        return parseSkillsList(await transport.request('skills/list', { cwds: [this.launch.cwd] }));
+    }
+    listThreadItems(params) {
+        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() {
+        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) {
+        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, decision) {
+        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, answers) {
+        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) {
+        return this.protocol.dismissQuestion(requestId);
+    }
+    declineRequest(requestId, _message) {
+        const answer = this.protocol.declineRequest(requestId);
+        if (!this.transport || !answer) {
+            return false;
+        }
+        return this.respond(requestId, answer.rpcId, answer.result);
+    }
+    stop() {
+        this.transport?.stop();
+    }
+    dispose() {
+        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. */
+    request(method, params, accepted) {
+        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) => {
+            if (this.transport === transport) {
+                this.emit({ type: 'failed', message: errorText(error) });
+            }
+        });
+    }
+    handleFrame(transport, frame) {
+        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();
+            }
+        }
+    }
+    handleExit(transport, exitCode, stderr) {
+        if (this.transport !== transport) {
+            return;
+        }
+        this.transport = null;
+        this.protocol.forgetPending();
+        this.emit({ type: 'exit', exitCode, ...(stderr === null ? {} : { stderr }) });
+    }
+    emit(event) {
+        // 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);
+    }
+}

package/dist/chat/codex-protocol.d.ts

@@ -0,0 +1,56 @@
+import type { ApprovalDecision, BackendEvent } from './backend.ts';
+import type { CodexFrame } from './codex-transport.ts';
+type CodexRpcId = number | string;
+type CodexAnswer = {
+    kind: 'respond';
+    rpcId: CodexRpcId;
+    result: unknown;
+} | {
+    kind: 'steer';
+    text: string;
+};
+export declare function unwrapCommand(command: string): string;
+export declare class CodexProtocol {
+    private readonly generation;
+    private readonly pending;
+    private readonly toolInputs;
+    private codexTurnId;
+    private readonly openTerminals;
+    private readonly backgroundTerminals;
+    private spentUntil;
+    private ownThreadId;
+    private readonly agentRows;
+    constructor(generation: number);
+    get turnId(): string | null;
+    threadReady(result: unknown): BackendEvent[];
+    handle(frame: CodexFrame): BackendEvent[];
+    approvalDecision(requestId: string, decision: ApprovalDecision): {
+        rpcId: CodexRpcId;
+        result: unknown;
+    } | null;
+    questionAnswer(requestId: string, answers: Record<string, string>): CodexAnswer | null;
+    dismissQuestion(requestId: string): boolean;
+    forgetPending(): void;
+    declineRequest(requestId: string): {
+        rpcId: CodexRpcId;
+        result: unknown;
+    } | null;
+    private owner;
+    private toolKey;
+    private rememberPatch;
+    private withdrawOwner;
+    private isChildRequest;
+    private requestDescription;
+    private requestId;
+    private handleServerRequest;
+    private elicitation;
+    private handleItem;
+    private handleTurnCompleted;
+    private limitOf;
+    private text;
+    private spawnedAgent;
+    private settleEndedAgents;
+    private subAgentActivity;
+    private tool;
+}
+export {};