@agentclientprotocol/claude-agent-acp 0.85.2-preview.16 → 0.85.2-preview.17

package/dist/tool-calls/client-capabilities.d.ts

@@ -19,7 +19,9 @@ export declare class ClientCapabilities {
     /**
      * The client speaks ACP v2. Its diffs carry structured `changes` and an
      * optional git patch, which a v1 diff cannot express. Only the v2 surface
-     * sets this, never the capabilities that a client sends.
+     * sets this, never the capabilities that a client sends. A v2 client also
+     * takes the terminal extension (`terminalOutput`), which the v2 surface
+     * sends as display terminals.
      */
     readonly v2: boolean;
     constructor(
@@ -34,7 +36,9 @@ export declare class ClientCapabilities {
     /**
      * The client speaks ACP v2. Its diffs carry structured `changes` and an
      * optional git patch, which a v1 diff cannot express. Only the v2 surface
-     * sets this, never the capabilities that a client sends.
+     * sets this, never the capabilities that a client sends. A v2 client also
+     * takes the terminal extension (`terminalOutput`), which the v2 surface
+     * sends as display terminals.
      */
     v2?: boolean);
     static from(capabilities: AcpClientCapabilities | null | undefined, { v2 }?: {

package/dist/tool-calls/client-capabilities.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client-capabilities.d.ts","sourceRoot":"","sources":["../../src/tool-calls/client-capabilities.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,IAAI,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAS5F;;;;;;;GAOG;AACH,qBAAa,kBAAkB;IAE3B,wGAAwG;IACxG,QAAQ,CAAC,cAAc,EAAE,OAAO;IAChC,4FAA4F;IAC5F,QAAQ,CAAC,mBAAmB,EAAE,OAAO;IACrC,qFAAqF;IACrF,QAAQ,CAAC,SAAS,EAAE,OAAO;IAC3B,yDAAyD;IACzD,QAAQ,CAAC,GAAG,EAAE,eAAe;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,EAAE,OAAO;;IAbpB,wGAAwG;IAC/F,cAAc,GAAE,OAAe;IACxC,4FAA4F;IACnF,mBAAmB,GAAE,OAAe;IAC7C,qFAAqF;IAC5E,SAAS,GAAE,OAAe;IACnC,yDAAyD;IAChD,GAAG,GAAE,eAAwB;IACtC;;;;OAIG;IACM,EAAE,GAAE,OAAe;IAG9B,MAAM,CAAC,IAAI,CACT,YAAY,EAAE,qBAAqB,GAAG,IAAI,GAAG,SAAS,EACtD,EAAE,EAAU,EAAE,GAAE;QAAE,EAAE,CAAC,EAAE,OAAO,CAAA;KAAO,GACpC,kBAAkB;CAkBtB;AAED,0EAA0E;AAC1E,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,iBAAiB,EAAE,OAAO,CAAC;IACpC;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B"}
+{"version":3,"file":"client-capabilities.d.ts","sourceRoot":"","sources":["../../src/tool-calls/client-capabilities.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,IAAI,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAS5F;;;;;;;GAOG;AACH,qBAAa,kBAAkB;IAE3B,wGAAwG;IACxG,QAAQ,CAAC,cAAc,EAAE,OAAO;IAChC,4FAA4F;IAC5F,QAAQ,CAAC,mBAAmB,EAAE,OAAO;IACrC,qFAAqF;IACrF,QAAQ,CAAC,SAAS,EAAE,OAAO;IAC3B,yDAAyD;IACzD,QAAQ,CAAC,GAAG,EAAE,eAAe;IAC7B;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,EAAE,OAAO;;IAfpB,wGAAwG;IAC/F,cAAc,GAAE,OAAe;IACxC,4FAA4F;IACnF,mBAAmB,GAAE,OAAe;IAC7C,qFAAqF;IAC5E,SAAS,GAAE,OAAe;IACnC,yDAAyD;IAChD,GAAG,GAAE,eAAwB;IACtC;;;;;;OAMG;IACM,EAAE,GAAE,OAAe;IAG9B,MAAM,CAAC,IAAI,CACT,YAAY,EAAE,qBAAqB,GAAG,IAAI,GAAG,SAAS,EACtD,EAAE,EAAU,EAAE,GAAE;QAAE,EAAE,CAAC,EAAE,OAAO,CAAA;KAAO,GACpC,kBAAkB;CAkBtB;AAED,0EAA0E;AAC1E,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,iBAAiB,EAAE,OAAO,CAAC;IACpC;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B"}

package/dist/tool-calls/client-capabilities.js

@@ -25,7 +25,9 @@ export class ClientCapabilities {
     /**
      * The client speaks ACP v2. Its diffs carry structured `changes` and an
      * optional git patch, which a v1 diff cannot express. Only the v2 surface
-     * sets this, never the capabilities that a client sends.
+     * sets this, never the capabilities that a client sends. A v2 client also
+     * takes the terminal extension (`terminalOutput`), which the v2 surface
+     * sends as display terminals.
      */
     v2 = false) {
         this.terminalOutput = terminalOutput;
@@ -37,7 +39,7 @@ export class ClientCapabilities {
     static from(capabilities, { v2 = false } = {}) {
         const meta = capabilities?._meta;
         const terminalOutputDelta = meta?.["terminal_output_delta"] === true;
-        return new ClientCapabilities(terminalOutputDelta || meta?.["terminal_output"] === true, terminalOutputDelta, clientSupportsAirCapability(capabilities, AIR_DIFF_PATCH_CAPABILITY), {
+        return new ClientCapabilities(v2 || terminalOutputDelta || meta?.["terminal_output"] === true, terminalOutputDelta, clientSupportsAirCapability(capabilities, AIR_DIFF_PATCH_CAPABILITY), {
             client: isAirClient(capabilities),
             rawInputRendering: clientSupportsAirCapability(capabilities, AIR_RAW_INPUT_RENDERING_CAPABILITY),
             planFile: clientSupportsAirCapability(capabilities, AIR_PLAN_FILE_CAPABILITY),

package/dist/v2/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/v2/agent.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,MAAM,0CAA0C,CAAC;AAC/D,OAAO,EAAE,cAAc,EAAkB,KAAK,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAgB9E;;;;;;GAMG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,OAAO,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,GACvC,EAAE,CAAC,QAAQ,CAyCb"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/v2/agent.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,MAAM,0CAA0C,CAAC;AAC/D,OAAO,EAAE,cAAc,EAAkB,KAAK,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAiB9E;;;;;;GAMG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,OAAO,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,GACvC,EAAE,CAAC,QAAQ,CA6Cb"}

package/dist/v2/agent.js

@@ -5,6 +5,7 @@ import { v1PermissionResponse, v2PermissionRequest } from "./permission.js";
 import { v2Prompt } from "./prompt.js";
 import { v1NewSessionRequest, v1RestoreSessionRequest, v1SetSessionConfigOptionRequest, v2ConfigOptions, v2NewSessionResponse, v2ResumeSessionResponse, } from "./session.js";
 import { v2SessionUpdate } from "./session-update.js";
+import { V2Terminals } from "./terminal.js";
 /**
  * The ACP v2 surface, for one connection.
  *
@@ -33,7 +34,11 @@ export function v2AgentApp(logger, onAgent) {
             ? await agent.resumeSession(restore.request)
             : await client.replaying(params.sessionId, () => agent.loadSession(restore.request)));
     })
-        .onRequest(v2.methods.agent.session.close, ({ params }) => agent.closeSession(params))
+        .onRequest(v2.methods.agent.session.close, async ({ params }) => {
+        const response = await agent.closeSession(params);
+        client.terminals.forget(params.sessionId);
+        return response;
+    })
         .onRequest(v2.methods.agent.session.delete, ({ params }) => agent.deleteSession(params))
         .onRequest(v2.methods.agent.session.setConfigOption, async ({ params }) => {
         const { configOptions, ...response } = await agent.setSessionConfigOption(v1SetSessionConfigOptionRequest(params));
@@ -56,6 +61,8 @@ class V2ClientConnection {
      * replay has cleared so far.
      */
     replays = new Map();
+    /** The display terminals of the commands that the agent runs. */
+    terminals = new V2Terminals();
     constructor(ctx, logger) {
         this.ctx = ctx;
         this.logger = logger;
@@ -98,18 +105,26 @@ class V2ClientConnection {
         return this.ctx.notify(method, params);
     }
     async sessionUpdate({ update, ...notification }) {
-        const v2Update = v2SessionUpdate(update);
-        if (!v2Update)
-            return;
-        const clear = this.replayClear(notification.sessionId, v2Update);
-        // Both go to the connection before either is awaited, so a chunk that
-        // another call sends meanwhile cannot come between them.
-        await Promise.all([
-            ...(clear
-                ? [this.ctx.notify(v2.methods.client.session.update, { ...notification, update: clear })]
-                : []),
-            this.ctx.notify(v2.methods.client.session.update, { ...notification, update: v2Update }),
-        ]);
+        const updates = this.v2Updates(notification.sessionId, update).flatMap((v2Update) => {
+            const clear = this.replayClear(notification.sessionId, v2Update);
+            return clear ? [clear, v2Update] : [v2Update];
+        });
+        // Every update goes to the connection before any is awaited, so an update
+        // that another call sends meanwhile cannot come between them.
+        await Promise.all(updates.map((v2Update) => this.ctx.notify(v2.methods.client.session.update, { ...notification, update: v2Update })));
+    }
+    /**
+     * The v2 updates of a v1 update: for a tool call report, the updates of its
+     * terminal first, then the report itself (see {@link V2Terminals}).
+     */
+    v2Updates(sessionId, update) {
+        if (update.sessionUpdate !== "tool_call" && update.sessionUpdate !== "tool_call_update") {
+            const v2Update = v2SessionUpdate(update);
+            return v2Update ? [v2Update] : [];
+        }
+        const { terminal, report } = this.terminals.split(sessionId, update);
+        const reportUpdate = report && v2SessionUpdate(report);
+        return [...terminal, ...(reportUpdate ? [reportUpdate] : [])];
     }
     /**
      * The update that clears the message of a replayed chunk, when it is the

package/dist/v2/terminal.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Agent-owned display terminals for the commands that the agent runs.
+ *
+ * The agent reports a command through the terminal extension of ACP v1
+ * clients, as codex-acp does: `_meta.terminal_info` names the terminal of a
+ * tool call, whose content references it; `terminal_output` (a snapshot) or
+ * `terminal_output_delta` (a chunk) carries the output, and `terminal_exit` the
+ * exit. ACP v2 standardizes this as display-only terminals: the same content
+ * reference, and `terminal_update` and `terminal_output_chunk` for the
+ * terminal's state. The agent reports to a v2 client as to a client of the
+ * extension (`ToolCallClientCapabilities.from`), and {@link V2Terminals} turns
+ * the extension's keys into those updates.
+ */
+import type { ToolCall, ToolCallUpdate } from "@agentclientprotocol/sdk";
+import type * as v2 from "@agentclientprotocol/sdk/experimental/v2";
+type V1ToolCallReport = (ToolCall & {
+    sessionUpdate: "tool_call";
+}) | (ToolCallUpdate & {
+    sessionUpdate: "tool_call_update";
+});
+/** The terminal updates of the tool call reports of one v2 connection. */
+export declare class V2Terminals {
+    /** The terminal and the last reported command of each running command, by session and tool call. */
+    private readonly running;
+    /**
+     * The terminal updates that a tool call report carries in the extension's
+     * keys, and the report without them, or undefined when nothing else is left
+     * in it.
+     *
+     * The extension names no command, so the terminal gets the command of the
+     * tool call's `rawInput` once a report carries it: the first report of a
+     * streamed tool use has no input yet.
+     */
+    split(sessionId: string, report: V1ToolCallReport): {
+        terminal: v2.SessionUpdate[];
+        report: V1ToolCallReport | undefined;
+    };
+    /** Forgets the terminals of a session. */
+    forget(sessionId: string): void;
+}
+export {};
+//# sourceMappingURL=terminal.d.ts.map

package/dist/v2/terminal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal.d.ts","sourceRoot":"","sources":["../../src/v2/terminal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AACzE,OAAO,KAAK,KAAK,EAAE,MAAM,0CAA0C,CAAC;AAEpE,KAAK,gBAAgB,GACjB,CAAC,QAAQ,GAAG;IAAE,aAAa,EAAE,WAAW,CAAA;CAAE,CAAC,GAC3C,CAAC,cAAc,GAAG;IAAE,aAAa,EAAE,kBAAkB,CAAA;CAAE,CAAC,CAAC;AAiB7D,0EAA0E;AAC1E,qBAAa,WAAW;IACtB,oGAAoG;IACpG,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA+D;IAEvF;;;;;;;;OAQG;IACH,KAAK,CACH,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,gBAAgB,GACvB;QAAE,QAAQ,EAAE,EAAE,CAAC,aAAa,EAAE,CAAC;QAAC,MAAM,EAAE,gBAAgB,GAAG,SAAS,CAAA;KAAE;IAuCzE,0CAA0C;IAC1C,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;CAKhC"}

package/dist/v2/terminal.js

@@ -0,0 +1,95 @@
+const TERMINAL_KEYS = [
+    "terminal_info",
+    "terminal_output",
+    "terminal_output_delta",
+    "terminal_exit",
+];
+/** The terminal updates of the tool call reports of one v2 connection. */
+export class V2Terminals {
+    /** The terminal and the last reported command of each running command, by session and tool call. */
+    running = new Map();
+    /**
+     * The terminal updates that a tool call report carries in the extension's
+     * keys, and the report without them, or undefined when nothing else is left
+     * in it.
+     *
+     * The extension names no command, so the terminal gets the command of the
+     * tool call's `rawInput` once a report carries it: the first report of a
+     * streamed tool use has no input yet.
+     */
+    split(sessionId, report) {
+        const meta = (report._meta ?? {});
+        const key = `${sessionId} ${report.toolCallId}`;
+        if (meta.terminal_info)
+            this.running.set(key, { terminalId: meta.terminal_info.terminal_id });
+        const terminal = [];
+        const running = this.running.get(key);
+        if (running) {
+            const command = commandOf(report.rawInput);
+            const newCommand = command !== undefined && command !== running.command;
+            if (newCommand)
+                running.command = command;
+            const { terminal_output: output, terminal_output_delta: delta, terminal_exit: exit } = meta;
+            if (meta.terminal_info || newCommand || output || exit) {
+                terminal.push({
+                    sessionUpdate: "terminal_update",
+                    terminalId: running.terminalId,
+                    ...(newCommand ? { command } : {}),
+                    ...(output ? { output: { data: base64(output.data) } } : {}),
+                    ...(exit
+                        ? {
+                            exitStatus: {
+                                exitCode: exit.exit_code,
+                                ...(exit.signal != null ? { signal: exit.signal } : {}),
+                            },
+                        }
+                        : {}),
+                });
+            }
+            if (delta) {
+                terminal.push({
+                    sessionUpdate: "terminal_output_chunk",
+                    terminalId: running.terminalId,
+                    data: base64(delta.data),
+                });
+            }
+            if (exit)
+                this.running.delete(key);
+        }
+        return { terminal, report: withoutTerminalKeys(report) };
+    }
+    /** Forgets the terminals of a session. */
+    forget(sessionId) {
+        for (const key of this.running.keys()) {
+            if (key.startsWith(`${sessionId} `))
+                this.running.delete(key);
+        }
+    }
+}
+/**
+ * The report without the extension's keys, or undefined when it carried
+ * nothing else but `_meta`: the output report of a command carries the output
+ * alone, and only the stamps that every report of the tool call repeats. In v2
+ * a concrete `_meta` replaces the stored one, so sending them would drop the
+ * other keys that the tool call holds.
+ */
+function withoutTerminalKeys(report) {
+    if (!report._meta || !TERMINAL_KEYS.some((key) => key in report._meta))
+        return report;
+    const meta = Object.fromEntries(Object.entries(report._meta).filter(([key]) => !TERMINAL_KEYS.includes(key)));
+    const stripped = { ...report };
+    if (Object.keys(meta).length > 0)
+        stripped._meta = meta;
+    else
+        delete stripped._meta;
+    const fields = Object.keys(stripped).filter((key) => key !== "sessionUpdate" && key !== "toolCallId" && key !== "_meta");
+    return fields.length > 0 || report.sessionUpdate === "tool_call" ? stripped : undefined;
+}
+function commandOf(rawInput) {
+    const command = rawInput?.command;
+    return typeof command === "string" && command.length > 0 ? command : undefined;
+}
+/** The output bytes, base64-encoded as a v2 terminal carries them. */
+function base64(text) {
+    return Buffer.from(text, "utf8").toString("base64");
+}

package/dist/v2/tool-call.d.ts

@@ -24,8 +24,9 @@ type V2ToolCallUpdate = v2.ToolCallUpdate & {
  *
  * Diffs need what a v1 diff does not say, so the agent builds them in v2 form
  * for a v2 client (`v2DiffContent`), and they pass as they are. Terminal
- * content throws until the v2 surface translates it (step 4 of
- * `docs/acp-v2.md`).
+ * content references a display terminal, as in v2: a v2 client has no client
+ * terminals, so the agent's only terminals are those of its terminal extension
+ * (see `terminal.ts`).
  */
 export declare function v2ToolCallUpdate(report: V1ToolCallReport): V2ToolCallUpdate;
 /**

package/dist/v2/tool-call.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-call.d.ts","sourceRoot":"","sources":["../../src/v2/tool-call.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAmB,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1F,OAAO,KAAK,KAAK,EAAE,MAAM,0CAA0C,CAAC;AAEpE,KAAK,gBAAgB,GACjB,CAAC,QAAQ,GAAG;IAAE,aAAa,EAAE,WAAW,CAAA;CAAE,CAAC,GAC3C,CAAC,cAAc,GAAG;IAAE,aAAa,EAAE,kBAAkB,CAAA;CAAE,CAAC,CAAC;AAE7D,KAAK,gBAAgB,GAAG,EAAE,CAAC,cAAc,GAAG;IAAE,aAAa,EAAE,kBAAkB,CAAA;CAAE,CAAC;AAElF;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,gBAAgB,CAE3E;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,QAAQ,GAAG,cAAc,GAAG,EAAE,CAAC,cAAc,CAUtF"}
+{"version":3,"file":"tool-call.d.ts","sourceRoot":"","sources":["../../src/v2/tool-call.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAmB,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1F,OAAO,KAAK,KAAK,EAAE,MAAM,0CAA0C,CAAC;AAEpE,KAAK,gBAAgB,GACjB,CAAC,QAAQ,GAAG;IAAE,aAAa,EAAE,WAAW,CAAA;CAAE,CAAC,GAC3C,CAAC,cAAc,GAAG;IAAE,aAAa,EAAE,kBAAkB,CAAA;CAAE,CAAC,CAAC;AAE7D,KAAK,gBAAgB,GAAG,EAAE,CAAC,cAAc,GAAG;IAAE,aAAa,EAAE,kBAAkB,CAAA;CAAE,CAAC;AAElF;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,gBAAgB,CAE3E;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,QAAQ,GAAG,cAAc,GAAG,EAAE,CAAC,cAAc,CAUtF"}

package/dist/v2/tool-call.js

@@ -10,8 +10,9 @@
  *
  * Diffs need what a v1 diff does not say, so the agent builds them in v2 form
  * for a v2 client (`v2DiffContent`), and they pass as they are. Terminal
- * content throws until the v2 surface translates it (step 4 of
- * `docs/acp-v2.md`).
+ * content references a display terminal, as in v2: a v2 client has no client
+ * terminals, so the agent's only terminals are those of its terminal extension
+ * (see `terminal.ts`).
  */
 export function v2ToolCallUpdate(report) {
     return { ...v2ToolCallPatch(report), sessionUpdate: "tool_call_update" };
@@ -32,14 +33,14 @@ function v2ToolCallContent(item) {
         case "content":
             // v2 content blocks are a superset of the v1 blocks.
             return item;
-        case "diff":
+        case "terminal":
+            return item;
+        default:
             if (isV2Diff(item))
                 return item;
             // A v1 diff names one path, with old and new texts that can be a
             // snippet: v2 cannot say which operation it is, nor give its patch.
             throw new Error("An ACP v2 client cannot take a v1 diff");
-        default:
-            throw new Error(`The ACP v2 surface does not translate ${item.type} tool call content yet`);
     }
 }
 /** A diff that the agent built in v2 form, which travels as v1 content. */

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.85.2-preview.16",
+  "version": "0.85.2-preview.17",
   "description": "An ACP-compatible coding agent powered by the Claude Agent SDK (TypeScript)",
   "main": "dist/lib.js",
   "types": "dist/lib.d.ts",