@adecore/agents 0.29.2 → 0.30.0

package/src/chat/chat-session.ts

@@ -198,6 +198,8 @@ export class ChatSession {
     // The last turn the main agent spoke in; a turn opened only for a subagent's request gets no `result`.
     private spokenTurnId: string | null = null;
     private titleTimer: ReturnType<typeof setTimeout> | null = null;
+    /* Checkpoints still asking git, which `dispose` waits for: the host may remove the folder next. */
+    private readonly checkpointWork = new Set<Promise<void>>();
     // A name is asked for once per chat this host holds; the turn count keeps it once across restarts.
     private naming = false;
     // Set while the host goes down: a CLI dying with it must not end the turn a restart takes up again.
@@ -1341,7 +1343,7 @@ export class ChatSession {
         this.backend?.stop();
     }
 
-    /* Ends the CLI and everything it started; settles once it exited or was sent the SIGKILL. */
+    /* Ends the CLI and everything it started; settles once it exited or was sent the SIGKILL and no checkpoint asks git any more. */
     dispose(): Promise<void> {
         this.uiReplies.clear();
         this.clearStartWarning();
@@ -1353,7 +1355,7 @@ export class ChatSession {
         const ended = this.backend?.dispose() ?? Promise.resolve();
         this.backend = null;
         this.starting = null;
-        return ended;
+        return Promise.all([ended, ...this.checkpointWork]).then(() => undefined);
     }
 
     /* What a turn changed against its checkpoint: the stored answer, or one taken now while it runs. */
@@ -1645,15 +1647,15 @@ export class ChatSession {
             return Promise.resolve();
         }
         const cwd = this.thread.info.cwd;
-        return Promise.all([checkpoints.take(cwd), checkpoints.head?.(cwd) ?? null])
-            .then(([tree, head]) => {
+        return this.trackCheckpoint(
+            Promise.all([checkpoints.take(cwd), checkpoints.head?.(cwd) ?? null]).then(([tree, head]) => {
                 const turn = this.thread.get(turnId);
                 if (tree === null || turn?.kind !== 'turn' || turn.state !== 'running' || this.info.activeTurnId !== turnId) {
                     return;
                 }
                 this.emit([this.thread.upsert({ ...turn, checkpoint: tree, ...(head === null ? {} : { checkpointHead: head }) })]);
             })
-            .catch(() => undefined);
+        );
     }
 
     /* The diff of a turn that just ended, so a reload shows it without asking git again, and the tree a fork after it starts from. */
@@ -1664,8 +1666,8 @@ export class ChatSession {
         }
         const { checkpoints } = this.options;
         const cwd = this.thread.info.cwd;
-        void Promise.all([checkpoints.settle(cwd, turn.checkpoint), checkpoints.head?.(cwd) ?? null])
-            .then(([answer, head]) => {
+        void this.trackCheckpoint(
+            Promise.all([checkpoints.settle(cwd, turn.checkpoint), checkpoints.head?.(cwd) ?? null]).then(([answer, head]) => {
                 const settled = this.thread.get(turnId);
                 if (answer === null || settled?.kind !== 'turn') {
                     return;
@@ -1680,7 +1682,14 @@ export class ChatSession {
                 ]);
                 this.options.persist();
             })
-            .catch(() => undefined);
+        );
+    }
+
+    /* Keeps the work in `checkpointWork` until it settled; a failure leaves the turn without a checkpoint. */
+    private trackCheckpoint(work: Promise<void>): Promise<void> {
+        const tracked = work.catch(() => undefined).finally(() => this.checkpointWork.delete(tracked));
+        this.checkpointWork.add(tracked);
+        return tracked;
     }
 
     /*

package/src/chat/codex-transport.ts

@@ -1,7 +1,7 @@
-import { errorText } from '../error-text.ts';
-import { ChatChild, MAX_LINE_LENGTH, readStreamLines, type SpawnChatProcess } from './chat-process.ts';
+import type { SpawnChatProcess } from './chat-process.ts';
+import { JsonRpcTransport, type JsonRpcFrame } from './json-rpc-transport.ts';
 
-export type CodexFrame = Record<string, unknown>;
+export type CodexFrame = JsonRpcFrame;
 
 /* How the host names itself in the `initialize` every app-server is opened with. */
 export interface CodexClientInfo {
@@ -17,218 +17,17 @@ interface CodexTransportOptions {
     cwd: string;
     env: Record<string, string>;
     spawn?: SpawnChatProcess;
-    // Notifications and server requests; responses to our own requests settle their promise instead.
     onFrame(frame: CodexFrame): void;
     onError?(error: Error): void;
-    // `stderr` is the tail of what the app-server wrote there, for an exit with an error code only.
     onExit(exitCode: number | null, stderr: string | null): void;
 }
 
-class CodexRpcError extends Error {
-    readonly code: number | null;
-
-    constructor(method: string, error: unknown) {
-        const detail = typeof error === 'object' && error !== null ? (error as { message?: unknown; code?: unknown }) : {};
-        super(`${method} failed: ${typeof detail.message === 'string' ? detail.message : JSON.stringify(error)}`);
-        this.name = 'CodexRpcError';
-        this.code = typeof detail.code === 'number' ? detail.code : null;
-    }
-}
-
-type Settle = { resolve(value: unknown): void; reject(reason: Error): void; method: string; timer: ReturnType<typeof setTimeout> };
-
 // The app-server answers every request it takes at once and does the work in notifications, so a silent one is stuck.
 const REQUEST_TIMEOUT_MS = 60_000;
 
-/*
- * One `codex app-server` process and the JSON-RPC framing on its stdio: newline-delimited JSON,
- * a request carries an id and gets a result or an error back under the same id, a notification
- * has no id. The app-server also sends requests of its own (approvals), answered with `respond`.
- */
-export class CodexTransport {
-    private readonly child: ChatChild;
-    private readonly options: CodexTransportOptions;
-    private readonly pending = new Map<number, Settle>();
-    private nextId = 1;
-    private closed = false;
-    // Set once stdin ended or broke; a write after an EPIPE only raises the next one.
-    private inputClosed = false;
-
+/* One `codex app-server` process. Its frames leave out the `jsonrpc` field, and an error it answers with is named `CodexRpcError`. */
+export class CodexTransport extends JsonRpcTransport {
     constructor(options: CodexTransportOptions) {
-        this.options = options;
-        this.child = new ChatChild({
-            command: options.command,
-            cwd: options.cwd,
-            env: options.env,
-            ...(options.spawn ? { spawn: options.spawn } : {}),
-            onError: (error) => this.broken(error),
-            onExit: (exitCode, stderr) => this.handleExit(exitCode, stderr)
-        });
-        void this.readLines();
-    }
-
-    get pid(): number {
-        return this.child.pid;
-    }
-
-    get alive(): boolean {
-        return !this.closed;
-    }
-
-    request(method: string, params: unknown): Promise<unknown> {
-        return new Promise((resolve, reject) => {
-            if (this.closed) {
-                reject(new Error(`${method} failed: Codex is not running`));
-                return;
-            }
-            const id = this.nextId++;
-            const timer = setTimeout(() => {
-                this.pending.delete(id);
-                reject(new Error(`${method} failed: Codex did not answer in ${REQUEST_TIMEOUT_MS / 1000} seconds`));
-            }, REQUEST_TIMEOUT_MS);
-            timer.unref?.();
-            this.pending.set(id, { resolve, reject, method, timer });
-            try {
-                this.write({ id, method, params });
-            } catch (error) {
-                clearTimeout(timer);
-                this.pending.delete(id);
-                reject(error);
-            }
-        });
-    }
-
-    notify(method: string, params: unknown): void {
-        this.write({ method, params });
-    }
-
-    respond(id: number | string, result: unknown): void {
-        this.write({ id, result });
-    }
-
-    respondError(id: number | string, code: number, message: string): void {
-        this.write({ id, error: { code, message } });
-    }
-
-    /* Closes stdin; the app-server ends on its own once it has nothing more to say. */
-    end(): void {
-        this.inputClosed = true;
-        try {
-            this.child.process.stdin.end();
-        } catch {
-            // Already closed by the other side.
-        }
-    }
-
-    kill(signal: 'SIGTERM' | 'SIGKILL' = 'SIGTERM'): void {
-        this.child.process.kill(signal);
-    }
-
-    stop(): void {
-        this.end();
-        this.child.endAfterGrace();
-    }
-
-    dispose(): Promise<void> {
-        return this.child.end();
-    }
-
-    private write(frame: CodexFrame): void {
-        if (this.closed || this.inputClosed) {
-            throw new Error('Codex stdin is closed');
-        }
-        try {
-            this.child.process.stdin.write(`${JSON.stringify(frame)}\n`);
-            this.child.process.stdin.flush();
-        } catch (error) {
-            this.inputClosed = true;
-            throw error;
-        }
-    }
-
-    /* A pipe that failed takes no more writes; a frame a consumer choked on leaves it as it was. */
-    private broken(error: unknown): void {
-        this.inputClosed = true;
-        this.failed(error);
-    }
-
-    private failed(error: unknown): void {
-        const failure = new Error(`Codex transport failed: ${errorText(error)}`);
-        this.rejectPending(() => failure);
-        try {
-            this.options.onError?.(failure);
-        } catch (reportError) {
-            console.error('Reporting a Codex transport failure failed:', errorText(reportError));
-        }
-    }
-
-    private readLine(line: string): void {
-        try {
-            this.handleLine(line);
-        } catch (error) {
-            this.failed(error);
-        }
-    }
-
-    private async readLines(): Promise<void> {
-        try {
-            await readStreamLines(
-                this.child.process.stdout,
-                (line) => this.readLine(line),
-                () => this.failed(new Error(`Codex wrote a frame of more than ${MAX_LINE_LENGTH / 1_000_000} million characters, which was dropped`))
-            );
-        } catch (error) {
-            if (!this.closed) {
-                this.broken(error);
-            }
-        }
-    }
-
-    private handleLine(line: string): void {
-        if (this.closed || line.trim() === '') {
-            return;
-        }
-        let frame: unknown;
-        try {
-            frame = JSON.parse(line);
-        } catch {
-            return;
-        }
-        if (typeof frame !== 'object' || frame === null || Array.isArray(frame)) {
-            return;
-        }
-        const message = frame as CodexFrame;
-        if (typeof message.method === 'string') {
-            this.options.onFrame(message);
-            return;
-        }
-        const settle = typeof message.id === 'number' ? this.pending.get(message.id) : undefined;
-        if (!settle) {
-            return;
-        }
-        this.pending.delete(message.id as number);
-        clearTimeout(settle.timer);
-        if (message.error !== undefined) {
-            settle.reject(new CodexRpcError(settle.method, message.error));
-        } else {
-            settle.resolve(message.result);
-        }
-    }
-
-    private handleExit(exitCode: number | null, stderr: string | null): void {
-        if (this.closed) {
-            return;
-        }
-        this.closed = true;
-        this.rejectPending((method) => new Error(`${method} failed: Codex exited`));
-        this.options.onExit(exitCode, stderr);
-    }
-
-    private rejectPending(reason: (method: string) => Error): void {
-        for (const settle of this.pending.values()) {
-            clearTimeout(settle.timer);
-            settle.reject(reason(settle.method));
-        }
-        this.pending.clear();
+        super({ ...options, label: 'Codex', errorName: 'CodexRpcError', requestTimeoutMs: REQUEST_TIMEOUT_MS });
     }
 }

package/src/chat/fixtures/acp-v1-turn.json

@@ -0,0 +1,240 @@
+{
+  "version": "ACP protocol version 1",
+  "source": "Written by hand from the schema at agentclientprotocol.com: one turn of an agent that thinks, answers, runs a command behind a permission request, edits a file, keeps a plan and reports usage. Frames go from the agent to the client; `response` is the client's answer where one is due. Unknown fields and an unknown update kind are there on purpose.",
+  "sessionId": "sess_7f2a",
+  "initialize": {
+    "jsonrpc": "2.0",
+    "id": 1,
+    "result": {
+      "protocolVersion": 1,
+      "agentCapabilities": {
+        "loadSession": true,
+        "promptCapabilities": { "image": true, "audio": false, "embeddedContext": true },
+        "mcpCapabilities": { "http": false, "sse": false },
+        "sessionCapabilities": { "additionalDirectories": {} },
+        "futureCapability": { "anything": true }
+      },
+      "authMethods": [{ "id": "api-key", "name": "API key", "description": "Reads a key from the environment" }, { "broken": true }],
+      "agentInfo": { "name": "example-agent", "title": "Example Agent", "version": "1.4.0" }
+    }
+  },
+  "sessionNew": {
+    "jsonrpc": "2.0",
+    "id": 2,
+    "result": {
+      "sessionId": "sess_7f2a",
+      "modes": {
+        "currentModeId": "default",
+        "availableModes": [
+          { "id": "default", "name": "Ask before changes" },
+          { "id": "accept-edits", "name": "Accept edits" },
+          { "id": "plan", "name": "Plan" },
+          { "name": "missing an id" }
+        ]
+      },
+      "configOptions": [
+        {
+          "id": "model",
+          "name": "Model",
+          "category": "model",
+          "type": "select",
+          "currentValue": "example-fast",
+          "options": [
+            { "group": "fast", "name": "Fast", "options": [{ "value": "example-fast", "name": "Example Fast" }] },
+            { "group": "deep", "name": "Deep", "options": [{ "value": "example-deep", "name": "Example Deep" }] }
+          ]
+        },
+        {
+          "id": "reasoning",
+          "name": "Reasoning",
+          "category": "thought_level",
+          "type": "select",
+          "currentValue": "medium",
+          "options": [
+            { "value": "low", "name": "Low" },
+            { "value": "medium", "name": "Medium" },
+            { "value": "high", "name": "High" }
+          ]
+        },
+        { "id": "web", "name": "Web access", "type": "boolean", "currentValue": true }
+      ]
+    }
+  },
+  "frames": [
+    {
+      "jsonrpc": "2.0",
+      "method": "session/update",
+      "params": {
+        "sessionId": "sess_7f2a",
+        "update": {
+          "sessionUpdate": "available_commands_update",
+          "availableCommands": [
+            { "name": "review", "description": "Review the changes", "input": null },
+            { "name": "init", "description": "Write an instructions file" },
+            { "description": "missing a name" }
+          ]
+        }
+      }
+    },
+    {
+      "jsonrpc": "2.0",
+      "method": "session/update",
+      "params": { "sessionId": "sess_7f2a", "update": { "sessionUpdate": "agent_thought_chunk", "content": { "type": "text", "text": "The test fails on " } } }
+    },
+    {
+      "jsonrpc": "2.0",
+      "method": "session/update",
+      "params": { "sessionId": "sess_7f2a", "update": { "sessionUpdate": "agent_thought_chunk", "content": { "type": "text", "text": "an off-by-one." } } }
+    },
+    {
+      "jsonrpc": "2.0",
+      "method": "session/update",
+      "params": { "sessionId": "sess_7f2a", "update": { "sessionUpdate": "agent_message_chunk", "messageId": "msg_1", "content": { "type": "text", "text": "Let me run " } } }
+    },
+    {
+      "jsonrpc": "2.0",
+      "method": "session/update",
+      "params": { "sessionId": "sess_7f2a", "update": { "sessionUpdate": "agent_message_chunk", "messageId": "msg_1", "content": { "type": "text", "text": "the tests." } } }
+    },
+    {
+      "jsonrpc": "2.0",
+      "method": "session/update",
+      "params": { "sessionId": "sess_7f2a", "update": { "sessionUpdate": "agent_message_chunk", "content": { "type": "image", "data": "iVBORw0KGgo=", "mimeType": "image/png" } } }
+    },
+    {
+      "jsonrpc": "2.0",
+      "method": "session/update",
+      "params": {
+        "sessionId": "sess_7f2a",
+        "update": {
+          "sessionUpdate": "tool_call",
+          "toolCallId": "call_001",
+          "title": "Run the test suite",
+          "kind": "execute",
+          "status": "pending",
+          "rawInput": { "command": ["bun", "test"], "timeout": 120 }
+        }
+      }
+    },
+    {
+      "jsonrpc": "2.0",
+      "id": 0,
+      "method": "session/request_permission",
+      "params": {
+        "sessionId": "sess_7f2a",
+        "toolCall": { "toolCallId": "call_001" },
+        "options": [
+          { "optionId": "allow", "name": "Allow", "kind": "allow_once" },
+          { "optionId": "allow-bun", "name": "Always allow bun", "kind": "allow_always" },
+          { "optionId": "deny", "name": "Deny", "kind": "reject_once" }
+        ]
+      },
+      "response": { "decision": "allow", "result": { "outcome": { "outcome": "selected", "optionId": "allow" } } }
+    },
+    {
+      "jsonrpc": "2.0",
+      "method": "session/update",
+      "params": { "sessionId": "sess_7f2a", "update": { "sessionUpdate": "tool_call_update", "toolCallId": "call_001", "status": "in_progress" } }
+    },
+    {
+      "jsonrpc": "2.0",
+      "method": "session/update",
+      "params": {
+        "sessionId": "sess_7f2a",
+        "update": {
+          "sessionUpdate": "tool_call_update",
+          "toolCallId": "call_001",
+          "status": "failed",
+          "content": [
+            { "type": "content", "content": { "type": "text", "text": "1 fail" } },
+            { "type": "content", "content": { "type": "text", "text": "expected 3, received 4" } }
+          ]
+        }
+      }
+    },
+    {
+      "jsonrpc": "2.0",
+      "method": "session/update",
+      "params": {
+        "sessionId": "sess_7f2a",
+        "update": {
+          "sessionUpdate": "plan",
+          "entries": [
+            { "content": "Find the off-by-one", "priority": "high", "status": "completed" },
+            { "content": "Fix the loop bound", "priority": "high", "status": "in_progress" },
+            { "content": "Run the tests again", "priority": "medium", "status": "pending" }
+          ]
+        }
+      }
+    },
+    {
+      "jsonrpc": "2.0",
+      "method": "session/update",
+      "params": {
+        "sessionId": "sess_7f2a",
+        "update": {
+          "sessionUpdate": "tool_call",
+          "toolCallId": "call_002",
+          "title": "Edit src/range.ts",
+          "kind": "edit",
+          "status": "pending",
+          "locations": [{ "path": "/work/demo/src/range.ts", "line": 12 }]
+        }
+      }
+    },
+    {
+      "jsonrpc": "2.0",
+      "method": "session/update",
+      "params": {
+        "sessionId": "sess_7f2a",
+        "update": {
+          "sessionUpdate": "tool_call_update",
+          "toolCallId": "call_002",
+          "status": "completed",
+          "content": [
+            {
+              "type": "diff",
+              "path": "/work/demo/src/range.ts",
+              "oldText": "for (let i = 0; i <= end; i++) {\n",
+              "newText": "for (let i = 0; i < end; i++) {\n"
+            }
+          ]
+        }
+      }
+    },
+    {
+      "jsonrpc": "2.0",
+      "method": "session/update",
+      "params": { "sessionId": "sess_7f2a", "update": { "sessionUpdate": "a_future_update", "payload": { "anything": true } } }
+    },
+    {
+      "jsonrpc": "2.0",
+      "method": "session/update",
+      "params": { "sessionId": "another_session", "update": { "sessionUpdate": "agent_message_chunk", "content": { "type": "text", "text": "not ours" } } }
+    },
+    {
+      "jsonrpc": "2.0",
+      "method": "session/update",
+      "params": { "sessionId": "sess_7f2a", "update": { "sessionUpdate": "current_mode_update", "currentModeId": "accept-edits" } }
+    },
+    {
+      "jsonrpc": "2.0",
+      "method": "session/update",
+      "params": { "sessionId": "sess_7f2a", "update": { "sessionUpdate": "agent_message_chunk", "messageId": "msg_2", "content": { "type": "text", "text": "Fixed the bound." } } }
+    },
+    {
+      "jsonrpc": "2.0",
+      "method": "session/update",
+      "params": {
+        "sessionId": "sess_7f2a",
+        "update": { "sessionUpdate": "usage_update", "used": 48210, "size": 200000, "cost": { "amount": 0.0421, "currency": "USD" } }
+      }
+    },
+    {
+      "jsonrpc": "2.0",
+      "method": "session/update",
+      "params": { "sessionId": "sess_7f2a", "update": { "sessionUpdate": "session_info_update", "title": "Fix the range off-by-one" } }
+    }
+  ],
+  "promptResponse": { "jsonrpc": "2.0", "id": 3, "result": { "stopReason": "end_turn" } }
+}

package/src/chat/index.ts

@@ -1,4 +1,6 @@
 // Public API: exports.test.ts snapshots this list, so a name added or dropped here is an API change.
+export { type AcpAgentSpec, type AcpClientInfo, createAcpBackend } from './acp-backend.ts';
+export type { AcpAgentInfo, AcpModel, AcpModelState, AcpMode, AcpModeState, AcpSessionInfo, AcpModeMap } from './acp-protocol.ts';
 export { AttachmentStore } from './attachment-store.ts';
 export type { BackendLaunch, TurnInput, ApprovalDecision, BackendEvent, BackendHost, ChatBackend } from './backend.ts';
 export { runningInBackground, type BackgroundWork } from './background-work.ts';