@agentclientprotocol/claude-agent-acp 0.81.3-preview.1 → 0.82.0

package/dist/resumed-session.js

@@ -1,5 +1,10 @@
 import { getSessionMessages } from "@anthropic-ai/claude-agent-sdk";
+import { access, open, readdir } from "node:fs/promises";
+import path from "node:path";
+import { claudeConfigDir } from "./paths.js";
 import { SessionTiming } from "./session-timing.js";
+/** The size of one backward read of a transcript. */
+const TAIL_CHUNK_BYTES = 64 * 1024;
 /** Return the concrete model recorded by the last real assistant response.
  * Claude Code restores a resumed query from this same transcript field.
  * Synthetic assistant records use angle-bracket placeholders and do not
@@ -14,13 +19,19 @@ export function resumedModelFromTranscript(messages) {
             typeof entry.message !== "object") {
             continue;
         }
-        const model = entry.message.model;
-        if (typeof model === "string" && model.trim().length > 0 && !/^<[^>]+>$/.test(model.trim())) {
-            return model.trim();
-        }
+        const model = concreteModel(entry.message.model);
+        if (model)
+            return model;
     }
     return undefined;
 }
+/** The model name, or undefined for a missing or a synthetic `<…>` model. */
+function concreteModel(model) {
+    if (typeof model !== "string")
+        return undefined;
+    const name = model.trim();
+    return name.length > 0 && !/^<[^>]+>$/.test(name) ? name : undefined;
+}
 /** Read the resume model from the local transcript without starting a Claude
  * control request. This is intentionally on the load critical path. */
 export async function readResumedSession(sessionId, logger) {
@@ -40,3 +51,94 @@ export async function readResumedSession(sessionId, logger) {
         return {};
     }
 }
+/**
+ * Read the resume model of a session from the end of its local transcript.
+ *
+ * A resume needs only the model, not the messages. The transcript file is
+ * read backwards until the last real assistant record of the main thread, so
+ * the cost does not grow with the length of the session. A session without a
+ * local transcript file falls back to {@link readResumedSession}.
+ */
+export async function readResumedModel(sessionId, logger) {
+    const timing = new SessionTiming(logger, "models", sessionId);
+    try {
+        const filePath = await findTranscript(sessionId);
+        if (filePath) {
+            const model = await lastAssistantModel(filePath);
+            timing.phase("read-transcript-tail", ` model=${model ?? "unknown"}`);
+            return model;
+        }
+    }
+    catch (error) {
+        timing.phase("read-transcript-tail", " outcome=error");
+        logger?.error(`Failed to read the transcript tail of resumed session ${sessionId}:`, error);
+    }
+    return (await readResumedSession(sessionId, logger)).model;
+}
+/** The local transcript of a session in any project directory, as the SDK looks it up. */
+export async function findTranscript(sessionId) {
+    const projects = path.join(claudeConfigDir(), "projects");
+    let directories;
+    try {
+        directories = await readdir(projects);
+    }
+    catch {
+        return undefined;
+    }
+    for (const directory of directories) {
+        const candidate = path.join(projects, directory, `${sessionId}.jsonl`);
+        try {
+            await access(candidate);
+            return candidate;
+        }
+        catch {
+            // Not in this project directory.
+        }
+    }
+    return undefined;
+}
+/** The model of the last real assistant record of the main thread in a JSONL transcript. */
+async function lastAssistantModel(filePath) {
+    const handle = await open(filePath, "r");
+    try {
+        let end = (await handle.stat()).size;
+        // The bytes of the line whose start is not read yet, in file order.
+        let pending = [];
+        while (end > 0) {
+            const start = Math.max(0, end - TAIL_CHUNK_BYTES);
+            let chunk = Buffer.alloc(end - start);
+            await handle.read(chunk, 0, chunk.length, start);
+            for (let at = chunk.lastIndexOf(0x0a); at >= 0; at = chunk.lastIndexOf(0x0a)) {
+                const model = assistantModelOfLine(Buffer.concat([chunk.subarray(at + 1), ...pending]));
+                if (model)
+                    return model;
+                pending = [];
+                chunk = chunk.subarray(0, at);
+            }
+            pending.unshift(chunk);
+            end = start;
+        }
+        return assistantModelOfLine(Buffer.concat(pending));
+    }
+    finally {
+        await handle.close();
+    }
+}
+function assistantModelOfLine(line) {
+    // Most lines are not assistant records. The check skips their JSON parse.
+    if (line.indexOf('"assistant"') < 0)
+        return undefined;
+    let entry;
+    try {
+        entry = JSON.parse(line.toString("utf8"));
+    }
+    catch {
+        return undefined;
+    }
+    if (!entry || typeof entry !== "object")
+        return undefined;
+    const record = entry;
+    if (record.type !== "assistant" || record.isSidechain === true)
+        return undefined;
+    return concreteModel(record.message?.model);
+}

package/dist/session-mode.d.ts

@@ -27,6 +27,8 @@ export type SessionModeManagerOptions<S extends SessionMode> = {
      *  known after `initialize`. */
     supportsNotices?(): boolean;
     logError(...args: unknown[]): void;
+    /** Whether the client is AIR. Only AIR gets the mode kind, under `_meta.jetbrains.air`. */
+    airClient?(): boolean;
 };
 type ModeConfigSession = SessionMode & {
     configOptions: SessionConfigOption[];

package/dist/session-mode.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-mode.d.ts","sourceRoot":"","sources":["../src/session-mode.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"session-mode.d.ts","sourceRoot":"","sources":["../src/session-mode.ts"],"names":[],"mappings":"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"}

package/dist/session-mode.js

@@ -1,4 +1,5 @@
 import { RequestError, } from "@agentclientprotocol/sdk";
+import { AIR_KIND_KEY, airOnlyMeta } from "./air-extension.js";
 import { noticeOrTranscriptUpdate, noticeTranscriptText, sentenceCase, } from "./session-notices.js";
 export const MODE_CONFIG_ID = "mode";
 export const AUTO_MODE_FALLBACK = "acceptEdits";
@@ -201,30 +202,36 @@ export class SessionModeManager {
         }
     }
     buildAvailableModes(allowBypass) {
+        // Only AIR gets the mode kind.
+        const air = this.options.airClient?.() ?? false;
+        const kind = (value) => {
+            const meta = airOnlyMeta(air, AIR_KIND_KEY, value);
+            return meta ? { _meta: meta } : {};
+        };
         const modes = [
             {
                 id: "default",
                 name: "Manual",
                 description: "Always ask before making changes",
-                _meta: { kind: "standard" },
+                ...kind("standard"),
             },
             {
                 id: "acceptEdits",
                 name: "Accept edits",
                 description: "Automatically accept all file edits",
-                _meta: { kind: "standard" },
+                ...kind("standard"),
             },
             {
                 id: "plan",
                 name: "Plan",
                 description: "Create a plan before making changes",
-                _meta: { kind: "plan" },
+                ...kind("plan"),
             },
             {
                 id: "auto",
                 name: "Auto",
                 description: "Claude handles permission decisions",
-                _meta: { kind: "auto_review" },
+                ...kind("auto_review"),
             },
         ];
         if (allowBypass) {
@@ -232,7 +239,7 @@ export class SessionModeManager {
                 id: "bypassPermissions",
                 name: "Bypass permissions",
                 description: "Accepts all permissions",
-                _meta: { kind: "full_access" },
+                ...kind("full_access"),
             });
         }
         return modes;

package/dist/settings.js

@@ -3,7 +3,7 @@ import * as path from "node:path";
 // resolveSettings and filterEscalatingDefaultMode are marked @alpha in the
 // SDK; API may shift in a future release.
 import { filterEscalatingDefaultMode, resolveSettings, } from "@anthropic-ai/claude-agent-sdk";
-import { CLAUDE_CONFIG_DIR } from "./acp-agent.js";
+import { claudeConfigDir } from "./paths.js";
 /**
  * Permission rule format examples:
  * - "Read" - matches all Read tool calls
@@ -75,7 +75,7 @@ export class SettingsManager {
      */
     getWatchedPaths() {
         return [
-            path.join(CLAUDE_CONFIG_DIR, "settings.json"),
+            path.join(claudeConfigDir(), "settings.json"),
             path.join(this.cwd, ".claude", "settings.json"),
             path.join(this.cwd, ".claude", "settings.local.json"),
             getManagedSettingsPath(),

package/dist/subagent-history.d.ts

@@ -0,0 +1,20 @@
+/** Where the subagent transcripts of a session are. */
+export interface SubagentHistory {
+    /** The subagent id of each Agent or Task tool use that launched a subagent. */
+    ids: Map<string, string>;
+    /**
+     * The project directory of the session, as the SDK takes it in `dir`. With
+     * it, the SDK reads a subagent transcript without a search of every project.
+     */
+    dir?: string;
+}
+/**
+ * Finds the subagent transcripts of a session.
+ *
+ * Claude keeps the history of a subagent in its own transcript,
+ * `<session>/subagents/agent-<id>.jsonl`, next to the session transcript.
+ * The `agent-<id>.meta.json` file beside it names the launching tool use.
+ * The ids are empty for a session without a local transcript.
+ */
+export declare function subagentHistory(sessionId: string): Promise<SubagentHistory>;
+//# sourceMappingURL=subagent-history.d.ts.map

package/dist/subagent-history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent-history.d.ts","sourceRoot":"","sources":["../src/subagent-history.ts"],"names":[],"mappings":"AAKA,uDAAuD;AACvD,MAAM,WAAW,eAAe;IAC9B,+EAA+E;IAC/E,GAAG,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzB;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;GAOG;AACH,wBAAsB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CA6BjF"}

package/dist/subagent-history.js

@@ -0,0 +1,46 @@
+import { getSessionInfo } from "@anthropic-ai/claude-agent-sdk";
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { findTranscript } from "./resumed-session.js";
+/**
+ * Finds the subagent transcripts of a session.
+ *
+ * Claude keeps the history of a subagent in its own transcript,
+ * `<session>/subagents/agent-<id>.jsonl`, next to the session transcript.
+ * The `agent-<id>.meta.json` file beside it names the launching tool use.
+ * The ids are empty for a session without a local transcript.
+ */
+export async function subagentHistory(sessionId) {
+    const ids = new Map();
+    const transcript = await findTranscript(sessionId);
+    if (!transcript)
+        return { ids };
+    const directory = path.join(path.dirname(transcript), sessionId, "subagents");
+    let names;
+    try {
+        names = await readdir(directory);
+    }
+    catch {
+        return { ids };
+    }
+    await Promise.all(names.map(async (name) => {
+        const match = /^agent-(.+)\.meta\.json$/.exec(name);
+        if (!match)
+            return;
+        try {
+            const meta = JSON.parse(await readFile(path.join(directory, name), "utf8"));
+            const toolUseId = meta?.toolUseId;
+            if (typeof toolUseId === "string")
+                ids.set(toolUseId, match[1]);
+        }
+        catch {
+            // A damaged meta file leaves its subagent without history.
+        }
+    }));
+    if (ids.size === 0)
+        return { ids };
+    // The folder name encodes the project directory, and the encoding loses
+    // characters. The session info reads it back from the transcript.
+    const dir = (await getSessionInfo(sessionId).catch(() => undefined))?.cwd;
+    return dir ? { ids, dir } : { ids };
+}

package/dist/tool-calls/background.d.ts

@@ -0,0 +1,20 @@
+import type { SessionNotification } from "@agentclientprotocol/sdk";
+import type { AsyncTaskStarted } from "../async-tasks.js";
+/**
+ * Marks the Bash `tool_call_update` whose command detached into the background.
+ *
+ * A backgrounded Bash call returns as soon as the command is handed off, so the
+ * card reaches `completed` while the command itself runs on for minutes. ACP has
+ * no tool-call status for "still running elsewhere", so this marker is what lets
+ * a client render the card as backgrounded work instead of finished work. It
+ * rides the update the tool result already emits, so it costs no extra
+ * notification and cannot arrive out of order.
+ *
+ * The command's own lifecycle -- progress, completion, the stop control -- is
+ * published separately as an async task; this says only that the card has one.
+ * Hence the AIR namespace rather than `claudeCode`: to a client without the
+ * `asyncTasks` capability, which is never sent that lifecycle, the marker would
+ * promise a card state it has no way to ever resolve.
+ */
+export declare function backgroundedBashToolCall(notification: SessionNotification, task: AsyncTaskStarted | undefined, asyncTasksSupported: boolean): SessionNotification;
+//# sourceMappingURL=background.d.ts.map

package/dist/tool-calls/background.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"background.d.ts","sourceRoot":"","sources":["../../src/tool-calls/background.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAEpE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAE1D;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,wBAAwB,CACtC,YAAY,EAAE,mBAAmB,EACjC,IAAI,EAAE,gBAAgB,GAAG,SAAS,EAClC,mBAAmB,EAAE,OAAO,GAC3B,mBAAmB,CAkBrB"}

package/dist/tool-calls/background.js

@@ -0,0 +1,41 @@
+import { AIR_ASYNC_TASKS_CAPABILITY, withAirMeta } from "../air-extension.js";
+/**
+ * Marks the Bash `tool_call_update` whose command detached into the background.
+ *
+ * A backgrounded Bash call returns as soon as the command is handed off, so the
+ * card reaches `completed` while the command itself runs on for minutes. ACP has
+ * no tool-call status for "still running elsewhere", so this marker is what lets
+ * a client render the card as backgrounded work instead of finished work. It
+ * rides the update the tool result already emits, so it costs no extra
+ * notification and cannot arrive out of order.
+ *
+ * The command's own lifecycle -- progress, completion, the stop control -- is
+ * published separately as an async task; this says only that the card has one.
+ * Hence the AIR namespace rather than `claudeCode`: to a client without the
+ * `asyncTasks` capability, which is never sent that lifecycle, the marker would
+ * promise a card state it has no way to ever resolve.
+ */
+export function backgroundedBashToolCall(notification, task, asyncTasksSupported) {
+    const update = notification.update;
+    const toolCallId = task ? nonBlankTaskField(task.toolCallId ?? task.tool_use_id) : undefined;
+    if (!asyncTasksSupported ||
+        !toolCallId ||
+        update.sessionUpdate !== "tool_call_update" ||
+        update.toolCallId !== toolCallId) {
+        return notification;
+    }
+    return {
+        ...notification,
+        update: {
+            ...update,
+            _meta: withAirMeta(update._meta, AIR_ASYNC_TASKS_CAPABILITY, { backgrounded: true }),
+        },
+    };
+}
+/** The task fields arrive as `unknown` off the wire; only non-blank strings carry a link. */
+function nonBlankTaskField(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed ? trimmed : undefined;
+}

package/dist/tool-calls/changed-meta-filter.d.ts

@@ -0,0 +1,27 @@
+import type { SessionNotification } from "@agentclientprotocol/sdk";
+type SessionUpdate = SessionNotification["update"];
+/**
+ * Removes the `_meta` keys of a `tool_call_update` that an earlier report of
+ * the same tool call already sent with the same value.
+ *
+ * Only an AIR client gets the filtered updates, because AIR merges these
+ * `_meta` keys. ACP does not define a merge for `_meta` keys, so another
+ * client gets every key on every update.
+ *
+ * It runs on the final notification, after the native subagent routing,
+ * because the routing reads `claudeCode.toolName` and
+ * `claudeCode.parentToolUseId` on every update. It compares the keys of
+ * `claudeCode`, of `jetbrains.air`, and the flags `is_mcp_tool_call` and
+ * `terminal_info`. It never compares `terminal_output`,
+ * `terminal_output_delta`, `terminal_exit`, or `mcp_output_delta`: a client
+ * appends their data. An update with nothing left is dropped.
+ */
+export declare class ChangedMetaFilter {
+    private readonly sent;
+    /** Returns the update without the unchanged keys, or null when nothing is left. */
+    apply(update: SessionUpdate): SessionUpdate | null;
+    /** Stores the entry as the most recent one, and forgets the oldest one past the limit. */
+    private remember;
+}
+export {};
+//# sourceMappingURL=changed-meta-filter.d.ts.map

package/dist/tool-calls/changed-meta-filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"changed-meta-filter.d.ts","sourceRoot":"","sources":["../../src/tool-calls/changed-meta-filter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAEpE,KAAK,aAAa,GAAG,mBAAmB,CAAC,QAAQ,CAAC,CAAC;AAWnD;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA0C;IAE/D,mFAAmF;IACnF,KAAK,CAAC,MAAM,EAAE,aAAa,GAAG,aAAa,GAAG,IAAI;IAuBlD,0FAA0F;IAC1F,OAAO,CAAC,QAAQ;CAQjB"}

package/dist/tool-calls/changed-meta-filter.js

@@ -0,0 +1,102 @@
+/** The `_meta` namespaces whose keys a client merges one by one. */
+const MERGED_NAMESPACES = ["claudeCode"];
+/** The top-level `_meta` flags that stay the same for a tool call. */
+const FLAGS = ["is_mcp_tool_call", "terminal_info"];
+/** The number of tool calls whose `_meta` the filter remembers. */
+const TOOL_CALL_LIMIT = 2048;
+/**
+ * Removes the `_meta` keys of a `tool_call_update` that an earlier report of
+ * the same tool call already sent with the same value.
+ *
+ * Only an AIR client gets the filtered updates, because AIR merges these
+ * `_meta` keys. ACP does not define a merge for `_meta` keys, so another
+ * client gets every key on every update.
+ *
+ * It runs on the final notification, after the native subagent routing,
+ * because the routing reads `claudeCode.toolName` and
+ * `claudeCode.parentToolUseId` on every update. It compares the keys of
+ * `claudeCode`, of `jetbrains.air`, and the flags `is_mcp_tool_call` and
+ * `terminal_info`. It never compares `terminal_output`,
+ * `terminal_output_delta`, `terminal_exit`, or `mcp_output_delta`: a client
+ * appends their data. An update with nothing left is dropped.
+ */
+export class ChangedMetaFilter {
+    sent = new Map();
+    /** Returns the update without the unchanged keys, or null when nothing is left. */
+    apply(update) {
+        if (update.sessionUpdate !== "tool_call" && update.sessionUpdate !== "tool_call_update") {
+            return update;
+        }
+        let held = this.sent.get(update.toolCallId);
+        if (update.sessionUpdate === "tool_call" || !held) {
+            held = new Map();
+            this.remember(update.toolCallId, held);
+            recordAndStrip(held, update._meta, false);
+            return update;
+        }
+        this.remember(update.toolCallId, held);
+        if (!update._meta)
+            return update;
+        const meta = structuredClone(update._meta);
+        recordAndStrip(held, meta, true);
+        const filtered = { ...update, _meta: meta };
+        if (Object.keys(meta).length === 0)
+            delete filtered._meta;
+        const carriesSomething = Object.keys(filtered).some((key) => key !== "sessionUpdate" && key !== "toolCallId");
+        return carriesSomething ? filtered : null;
+    }
+    /** Stores the entry as the most recent one, and forgets the oldest one past the limit. */
+    remember(toolCallId, held) {
+        this.sent.delete(toolCallId);
+        this.sent.set(toolCallId, held);
+        if (this.sent.size > TOOL_CALL_LIMIT) {
+            const oldest = this.sent.keys().next().value;
+            if (oldest !== undefined)
+                this.sent.delete(oldest);
+        }
+    }
+}
+/** Records the compared keys of `meta`. With `strip`, deletes the unchanged ones. */
+function recordAndStrip(held, meta, strip) {
+    if (!meta)
+        return;
+    const keep = (key, value) => {
+        const json = JSON.stringify(value);
+        if (strip && held.get(key) === json)
+            return false;
+        held.set(key, json);
+        return true;
+    };
+    const mergeKeys = (prefix, values) => {
+        for (const [key, value] of Object.entries(values)) {
+            if (!keep(prefix + key, value))
+                delete values[key];
+        }
+    };
+    for (const namespace of MERGED_NAMESPACES) {
+        const values = asRecord(meta[namespace]);
+        if (!values)
+            continue;
+        mergeKeys(`${namespace}.`, values);
+        if (Object.keys(values).length === 0)
+            delete meta[namespace];
+    }
+    const jetbrains = asRecord(meta.jetbrains);
+    const air = asRecord(jetbrains?.air);
+    if (jetbrains && air) {
+        mergeKeys("jetbrains.air.", air);
+        if (Object.keys(air).length === 0)
+            delete jetbrains.air;
+        if (Object.keys(jetbrains).length === 0)
+            delete meta.jetbrains;
+    }
+    for (const flag of FLAGS) {
+        if (meta[flag] !== undefined && !keep(flag, meta[flag]))
+            delete meta[flag];
+    }
+}
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}

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

@@ -0,0 +1,51 @@
+import type { ClientCapabilities as AcpClientCapabilities } from "@agentclientprotocol/sdk";
+/**
+ * The client choices that decide the shape of a tool call report.
+ *
+ * The agent reads them once from `initialize.clientCapabilities`. The public
+ * `toAcpNotifications` functions take the ACP capabilities and read them on
+ * each call. The {@link AcpToolCallRenderer} reads nothing else, so one object
+ * holds every capability choice of a tool call report.
+ */
+export declare class ClientCapabilities {
+    /** The client renders a terminal from `_meta.terminal_info`, `terminal_output`, and `terminal_exit`. */
+    readonly terminalOutput: boolean;
+    /** The client appends `_meta.terminal_output_delta` instead of `terminal_output` chunks. */
+    readonly terminalOutputDelta: boolean;
+    /** The client accepts an exact git patch in a diff (`jetbrains.air` `diffPatch`). */
+    readonly diffPatch: boolean;
+    /** The capabilities that only JetBrains AIR declares. */
+    readonly air: AirCapabilities;
+    constructor(
+    /** The client renders a terminal from `_meta.terminal_info`, `terminal_output`, and `terminal_exit`. */
+    terminalOutput?: boolean, 
+    /** The client appends `_meta.terminal_output_delta` instead of `terminal_output` chunks. */
+    terminalOutputDelta?: boolean, 
+    /** The client accepts an exact git patch in a diff (`jetbrains.air` `diffPatch`). */
+    diffPatch?: boolean, 
+    /** The capabilities that only JetBrains AIR declares. */
+    air?: AirCapabilities);
+    static from(capabilities: AcpClientCapabilities | null | undefined): ClientCapabilities;
+}
+/** The capabilities of JetBrains AIR, read from `_meta.jetbrains.air`. */
+export interface AirCapabilities {
+    /**
+     * The client declared `_meta.jetbrains.air`. Only then does a report follow
+     * the tool call contract of `docs/air-extensions.md`. Every other client
+     * gets the fields of the upstream adapter, and only the unchanged fields of
+     * an update are left out.
+     */
+    readonly client: boolean;
+    /**
+     * AIR renders `rawInput` itself. A tool call report for AIR then carries no
+     * display copy of the input in `content`.
+     */
+    readonly rawInputRendering: boolean;
+    /**
+     * AIR reads the plan of an ExitPlanMode from the file that
+     * `rawInput.planFilePath` names. A report then carries the path and not the
+     * plan text, when the plan file exists.
+     */
+    readonly planFile: boolean;
+}
+//# sourceMappingURL=client-capabilities.d.ts.map

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

@@ -0,0 +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;;IAP7B,wGAAwG;IAC/F,cAAc,GAAE,OAAe;IACxC,4FAA4F;IACnF,mBAAmB,GAAE,OAAe;IAC7C,qFAAqF;IAC5E,SAAS,GAAE,OAAe;IACnC,yDAAyD;IAChD,GAAG,GAAE,eAAwB;IAGxC,MAAM,CAAC,IAAI,CAAC,YAAY,EAAE,qBAAqB,GAAG,IAAI,GAAG,SAAS,GAAG,kBAAkB;CAiBxF;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

@@ -0,0 +1,43 @@
+import { AIR_DIFF_PATCH_CAPABILITY, AIR_PLAN_FILE_CAPABILITY, AIR_RAW_INPUT_RENDERING_CAPABILITY, clientSupportsAirCapability, isAirClient, } from "../air-extension.js";
+/**
+ * The client choices that decide the shape of a tool call report.
+ *
+ * The agent reads them once from `initialize.clientCapabilities`. The public
+ * `toAcpNotifications` functions take the ACP capabilities and read them on
+ * each call. The {@link AcpToolCallRenderer} reads nothing else, so one object
+ * holds every capability choice of a tool call report.
+ */
+export class ClientCapabilities {
+    terminalOutput;
+    terminalOutputDelta;
+    diffPatch;
+    air;
+    constructor(
+    /** The client renders a terminal from `_meta.terminal_info`, `terminal_output`, and `terminal_exit`. */
+    terminalOutput = false, 
+    /** The client appends `_meta.terminal_output_delta` instead of `terminal_output` chunks. */
+    terminalOutputDelta = false, 
+    /** The client accepts an exact git patch in a diff (`jetbrains.air` `diffPatch`). */
+    diffPatch = false, 
+    /** The capabilities that only JetBrains AIR declares. */
+    air = NO_AIR) {
+        this.terminalOutput = terminalOutput;
+        this.terminalOutputDelta = terminalOutputDelta;
+        this.diffPatch = diffPatch;
+        this.air = air;
+    }
+    static from(capabilities) {
+        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), {
+            client: isAirClient(capabilities),
+            rawInputRendering: clientSupportsAirCapability(capabilities, AIR_RAW_INPUT_RENDERING_CAPABILITY),
+            planFile: clientSupportsAirCapability(capabilities, AIR_PLAN_FILE_CAPABILITY),
+        });
+    }
+}
+const NO_AIR = {
+    client: false,
+    rawInputRendering: false,
+    planFile: false,
+};