@adecore/agents 0.29.2 → 0.30.0

package/dist/chat/chat-session.js

@@ -71,6 +71,8 @@ export class ChatSession {
     // The last turn the main agent spoke in; a turn opened only for a subagent's request gets no `result`.
     spokenTurnId = null;
     titleTimer = null;
+    /* Checkpoints still asking git, which `dispose` waits for: the host may remove the folder next. */
+    checkpointWork = new Set();
     // A name is asked for once per chat this host holds; the turn count keeps it once across restarts.
     naming = false;
     // Set while the host goes down: a CLI dying with it must not end the turn a restart takes up again.
@@ -1126,7 +1128,7 @@ export class ChatSession {
         this.frozen = true;
         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() {
         this.uiReplies.clear();
         this.clearStartWarning();
@@ -1138,7 +1140,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. */
     async turnDiff(turnId) {
@@ -1412,15 +1414,13 @@ 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. */
     settleCheckpoint(turnId) {
@@ -1430,8 +1430,7 @@ 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;
@@ -1445,8 +1444,13 @@ export class ChatSession {
                 })
             ]);
             this.options.persist();
-        })
-            .catch(() => undefined);
+        }));
+    }
+    /* Keeps the work in `checkpointWork` until it settled; a failure leaves the turn without a checkpoint. */
+    trackCheckpoint(work) {
+        const tracked = work.catch(() => undefined).finally(() => this.checkpointWork.delete(tracked));
+        this.checkpointWork.add(tracked);
+        return tracked;
     }
     /*
      * What the agent has to hear before this prompt: what the chat kept for it and what the host says.

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

@@ -1,5 +1,6 @@
-import { type SpawnChatProcess } from './chat-process.ts';
-export type CodexFrame = Record<string, unknown>;
+import type { SpawnChatProcess } from './chat-process.ts';
+import { JsonRpcTransport, type JsonRpcFrame } from './json-rpc-transport.ts';
+export type CodexFrame = JsonRpcFrame;
 export interface CodexClientInfo {
     name: string;
     title: string;
@@ -15,31 +16,7 @@ interface CodexTransportOptions {
     onError?(error: Error): void;
     onExit(exitCode: number | null, stderr: string | null): void;
 }
-export declare class CodexTransport {
-    private readonly child;
-    private readonly options;
-    private readonly pending;
-    private nextId;
-    private closed;
-    private inputClosed;
+export declare class CodexTransport extends JsonRpcTransport {
     constructor(options: CodexTransportOptions);
-    get pid(): number;
-    get alive(): boolean;
-    request(method: string, params: unknown): Promise<unknown>;
-    notify(method: string, params: unknown): void;
-    respond(id: number | string, result: unknown): void;
-    respondError(id: number | string, code: number, message: string): void;
-    end(): void;
-    kill(signal?: 'SIGTERM' | 'SIGKILL'): void;
-    stop(): void;
-    dispose(): Promise<void>;
-    private write;
-    private broken;
-    private failed;
-    private readLine;
-    private readLines;
-    private handleLine;
-    private handleExit;
-    private rejectPending;
 }
 export {};

package/dist/chat/codex-transport.js

@@ -1,191 +1,10 @@
-import { errorText } from '../error-text.js';
-import { ChatChild, MAX_LINE_LENGTH, readStreamLines } from './chat-process.js';
+import { JsonRpcTransport } from './json-rpc-transport.js';
 export const DEFAULT_CODEX_CLIENT = { name: 'agents', title: 'Agents', version: '0.1.0' };
-class CodexRpcError extends Error {
-    code;
-    constructor(method, error) {
-        const detail = typeof error === 'object' && error !== null ? error : {};
-        super(`${method} failed: ${typeof detail.message === 'string' ? detail.message : JSON.stringify(error)}`);
-        this.name = 'CodexRpcError';
-        this.code = typeof detail.code === 'number' ? detail.code : null;
-    }
-}
 // 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 {
-    child;
-    options;
-    pending = new Map();
-    nextId = 1;
-    closed = false;
-    // Set once stdin ended or broke; a write after an EPIPE only raises the next one.
-    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) {
-        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() {
-        return this.child.pid;
-    }
-    get alive() {
-        return !this.closed;
-    }
-    request(method, params) {
-        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, params) {
-        this.write({ method, params });
-    }
-    respond(id, result) {
-        this.write({ id, result });
-    }
-    respondError(id, code, message) {
-        this.write({ id, error: { code, message } });
-    }
-    /* Closes stdin; the app-server ends on its own once it has nothing more to say. */
-    end() {
-        this.inputClosed = true;
-        try {
-            this.child.process.stdin.end();
-        }
-        catch {
-            // Already closed by the other side.
-        }
-    }
-    kill(signal = 'SIGTERM') {
-        this.child.process.kill(signal);
-    }
-    stop() {
-        this.end();
-        this.child.endAfterGrace();
-    }
-    dispose() {
-        return this.child.end();
-    }
-    write(frame) {
-        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. */
-    broken(error) {
-        this.inputClosed = true;
-        this.failed(error);
-    }
-    failed(error) {
-        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));
-        }
-    }
-    readLine(line) {
-        try {
-            this.handleLine(line);
-        }
-        catch (error) {
-            this.failed(error);
-        }
-    }
-    async readLines() {
-        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);
-            }
-        }
-    }
-    handleLine(line) {
-        if (this.closed || line.trim() === '') {
-            return;
-        }
-        let frame;
-        try {
-            frame = JSON.parse(line);
-        }
-        catch {
-            return;
-        }
-        if (typeof frame !== 'object' || frame === null || Array.isArray(frame)) {
-            return;
-        }
-        const message = frame;
-        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);
-        clearTimeout(settle.timer);
-        if (message.error !== undefined) {
-            settle.reject(new CodexRpcError(settle.method, message.error));
-        }
-        else {
-            settle.resolve(message.result);
-        }
-    }
-    handleExit(exitCode, stderr) {
-        if (this.closed) {
-            return;
-        }
-        this.closed = true;
-        this.rejectPending((method) => new Error(`${method} failed: Codex exited`));
-        this.options.onExit(exitCode, stderr);
-    }
-    rejectPending(reason) {
-        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/dist/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/dist/chat/index.d.ts

@@ -1,3 +1,5 @@
+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';

package/dist/chat/index.js

@@ -1,4 +1,5 @@
 // Public API: exports.test.ts snapshots this list, so a name added or dropped here is an API change.
+export { createAcpBackend } from './acp-backend.js';
 export { AttachmentStore } from './attachment-store.js';
 export { runningInBackground } from './background-work.js';
 export { BookmarkStore } from './bookmark-store.js';

package/dist/chat/json-rpc-transport.d.ts

@@ -0,0 +1,50 @@
+import { type SpawnChatProcess } from './chat-process.ts';
+export type JsonRpcFrame = Record<string, unknown>;
+export interface JsonRpcTransportOptions {
+    command: string[];
+    cwd: string;
+    env: Record<string, string>;
+    spawn?: SpawnChatProcess;
+    label: string;
+    errorName?: string;
+    requestTimeoutMs: number | null;
+    versionField?: boolean;
+    onFrame(frame: JsonRpcFrame): void;
+    onError?(error: Error): void;
+    onExit(exitCode: number | null, stderr: string | null): void;
+}
+export interface JsonRpcRequestOptions {
+    timeoutMs?: number | null;
+}
+export declare class JsonRpcError extends Error {
+    readonly code: number | null;
+    readonly data: unknown;
+    constructor(name: string, method: string, error: unknown);
+}
+export declare class JsonRpcTransport {
+    private readonly child;
+    private readonly options;
+    private readonly pending;
+    private nextId;
+    private closed;
+    private inputClosed;
+    constructor(options: JsonRpcTransportOptions);
+    get pid(): number;
+    get alive(): boolean;
+    request(method: string, params: unknown, options?: JsonRpcRequestOptions): Promise<unknown>;
+    notify(method: string, params: unknown): void;
+    respond(id: number | string, result: unknown): void;
+    respondError(id: number | string, code: number, message: string): void;
+    end(): void;
+    kill(signal?: 'SIGTERM' | 'SIGKILL'): void;
+    stop(): void;
+    dispose(): Promise<void>;
+    private write;
+    private broken;
+    private failed;
+    private readLine;
+    private readLines;
+    private handleLine;
+    private handleExit;
+    private rejectPending;
+}