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

package/dist/acp-subagents.d.ts

@@ -18,6 +18,12 @@ export type SubagentSpawnedUpdate = {
     subagentSessionId: string;
     name: string;
     task: string;
+    /**
+     * Adapter extension: the exact prompt of the subagent. A client can show it
+     * as the first user message of the subagent session. It is absent when the
+     * adapter does not know the prompt.
+     */
+    prompt?: string;
     capabilities: SubagentSessionCapabilities;
     _meta?: Record<string, unknown> | null;
 };

package/dist/acp-subagents.d.ts.map

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

package/dist/air-extension.d.ts

@@ -2,7 +2,23 @@ export declare const AIR_NATIVE_SUBAGENT_SESSIONS_CAPABILITY = "nativeSubagentSe
 export declare const AIR_ASYNC_TASKS_CAPABILITY = "asyncTasks";
 export declare const AIR_SESSION_FAILURE_CAPABILITY = "sessionFailure";
 export declare const AIR_RECOMMENDED_CONFIG_VALUE_CAPABILITY = "recommendedValue";
-export declare const AIR_DIFF_STATS_KEY = "diffStats";
+export declare const AIR_DIFF_PATCH_CAPABILITY = "diffPatch";
+/** AIR renders `rawInput` itself and needs no display copy of the input. */
+export declare const AIR_RAW_INPUT_RENDERING_CAPABILITY = "rawInputRendering";
+/**
+ * The plan of an ExitPlanMode is a file. `rawInput.planFilePath` names the
+ * file, and AIR reads the plan from it.
+ */
+export declare const AIR_PLAN_FILE_CAPABILITY = "planFile";
+/** The `_meta.jetbrains.air` keys that the ACP tool call contract defines. */
+export declare const AIR_COMMAND_TITLE_KEY = "commandTitle";
+export declare const AIR_SUBAGENT_KEY = "subagent";
+export declare const AIR_SKILL_KEY = "skill";
+export declare const AIR_CONTEXT_COMPACTION_KEY = "contextCompaction";
+export declare const AIR_GOAL_KEY = "goal";
+export declare const AIR_KIND_KEY = "kind";
+export declare const AIR_PERMISSION_KEY = "permission";
+export declare const AIR_CUSTOM_ANSWER_KEY = "customAnswer";
 /** The capability list this side advertises, as its own `_meta` object. */
 export declare function airCapabilityMeta(...capabilities: string[]): Record<string, unknown>;
 /**
@@ -13,6 +29,20 @@ export declare function airCapabilityMeta(...capabilities: string[]): Record<str
  * same `air` object. Pass `undefined` to build a fresh `_meta`.
  */
 export declare function withAirMeta(meta: Record<string, unknown> | null | undefined, capability: string, payload: unknown): Record<string, unknown>;
+/**
+ * Whether the client is JetBrains AIR: it declared `_meta.jetbrains.air` in
+ * its capabilities.
+ *
+ * Only AIR gets the AIR extensions of `docs/air-extensions.md`. Every other
+ * client, Zed too, gets the fields and the upstream `_meta` keys of the
+ * upstream adapter, and no key that exists only for AIR.
+ */
+export declare function isAirClient(capabilities: unknown): boolean;
+/**
+ * The `_meta` of an AIR client with one more AIR payload, or undefined for
+ * every other client: a client that is not AIR gets no AIR key.
+ */
+export declare function airOnlyMeta(airClient: boolean, capability: string, payload: unknown, meta?: Record<string, unknown> | null): Record<string, unknown> | undefined;
 /** The `air` object inside a `_meta`, or undefined when the peer sent no AIR extension. */
 export declare function airExtensionMeta(meta: unknown): Record<string, unknown> | undefined;
 /**

package/dist/air-extension.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"air-extension.d.ts","sourceRoot":"","sources":["../src/air-extension.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,uCAAuC,2BAA2B,CAAC;AAChF,eAAO,MAAM,0BAA0B,eAAe,CAAC;AACvD,eAAO,MAAM,8BAA8B,mBAAmB,CAAC;AAC/D,eAAO,MAAM,uCAAuC,qBAAqB,CAAC;AAC1E,eAAO,MAAM,kBAAkB,cAAc,CAAC;AAQ9C,2EAA2E;AAC3E,wBAAgB,iBAAiB,CAAC,GAAG,YAAY,EAAE,MAAM,EAAE,2BAE1D;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,EAChD,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,OAAO,GACf,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAczB;AAED,2FAA2F;AAC3F,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAKnF;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,YAAY,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAY9F"}
+{"version":3,"file":"air-extension.d.ts","sourceRoot":"","sources":["../src/air-extension.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,uCAAuC,2BAA2B,CAAC;AAChF,eAAO,MAAM,0BAA0B,eAAe,CAAC;AACvD,eAAO,MAAM,8BAA8B,mBAAmB,CAAC;AAC/D,eAAO,MAAM,uCAAuC,qBAAqB,CAAC;AAC1E,eAAO,MAAM,yBAAyB,cAAc,CAAC;AACrD,4EAA4E;AAC5E,eAAO,MAAM,kCAAkC,sBAAsB,CAAC;AACtE;;;GAGG;AACH,eAAO,MAAM,wBAAwB,aAAa,CAAC;AAEnD,8EAA8E;AAC9E,eAAO,MAAM,qBAAqB,iBAAiB,CAAC;AACpD,eAAO,MAAM,gBAAgB,aAAa,CAAC;AAC3C,eAAO,MAAM,aAAa,UAAU,CAAC;AACrC,eAAO,MAAM,0BAA0B,sBAAsB,CAAC;AAC9D,eAAO,MAAM,YAAY,SAAS,CAAC;AACnC,eAAO,MAAM,YAAY,SAAS,CAAC;AACnC,eAAO,MAAM,kBAAkB,eAAe,CAAC;AAC/C,eAAO,MAAM,qBAAqB,iBAAiB,CAAC;AAQpD,2EAA2E;AAC3E,wBAAgB,iBAAiB,CAAC,GAAG,YAAY,EAAE,MAAM,EAAE,2BAE1D;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,EAChD,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,OAAO,GACf,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAczB;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,YAAY,EAAE,OAAO,GAAG,OAAO,CAE1D;AAED;;;GAGG;AACH,wBAAgB,WAAW,CACzB,SAAS,EAAE,OAAO,EAClB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,OAAO,EAChB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GACpC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAErC;AAED,2FAA2F;AAC3F,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAKnF;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,YAAY,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAY9F"}

package/dist/air-extension.js

@@ -2,7 +2,23 @@ export const AIR_NATIVE_SUBAGENT_SESSIONS_CAPABILITY = "nativeSubagentSessions";
 export const AIR_ASYNC_TASKS_CAPABILITY = "asyncTasks";
 export const AIR_SESSION_FAILURE_CAPABILITY = "sessionFailure";
 export const AIR_RECOMMENDED_CONFIG_VALUE_CAPABILITY = "recommendedValue";
-export const AIR_DIFF_STATS_KEY = "diffStats";
+export const AIR_DIFF_PATCH_CAPABILITY = "diffPatch";
+/** AIR renders `rawInput` itself and needs no display copy of the input. */
+export const AIR_RAW_INPUT_RENDERING_CAPABILITY = "rawInputRendering";
+/**
+ * The plan of an ExitPlanMode is a file. `rawInput.planFilePath` names the
+ * file, and AIR reads the plan from it.
+ */
+export const AIR_PLAN_FILE_CAPABILITY = "planFile";
+/** The `_meta.jetbrains.air` keys that the ACP tool call contract defines. */
+export const AIR_COMMAND_TITLE_KEY = "commandTitle";
+export const AIR_SUBAGENT_KEY = "subagent";
+export const AIR_SKILL_KEY = "skill";
+export const AIR_CONTEXT_COMPACTION_KEY = "contextCompaction";
+export const AIR_GOAL_KEY = "goal";
+export const AIR_KIND_KEY = "kind";
+export const AIR_PERMISSION_KEY = "permission";
+export const AIR_CUSTOM_ANSWER_KEY = "customAnswer";
 const JETBRAINS_META_KEY = "jetbrains";
 const AIR_META_KEY = "air";
 const AIR_EXTENSION_VERSION_KEY = "version";
@@ -34,6 +50,24 @@ export function withAirMeta(meta, capability, payload) {
         },
     };
 }
+/**
+ * Whether the client is JetBrains AIR: it declared `_meta.jetbrains.air` in
+ * its capabilities.
+ *
+ * Only AIR gets the AIR extensions of `docs/air-extensions.md`. Every other
+ * client, Zed too, gets the fields and the upstream `_meta` keys of the
+ * upstream adapter, and no key that exists only for AIR.
+ */
+export function isAirClient(capabilities) {
+    return airExtensionMeta(asRecord(capabilities)._meta) !== undefined;
+}
+/**
+ * The `_meta` of an AIR client with one more AIR payload, or undefined for
+ * every other client: a client that is not AIR gets no AIR key.
+ */
+export function airOnlyMeta(airClient, capability, payload, meta) {
+    return airClient ? withAirMeta(meta, capability, payload) : (meta ?? undefined);
+}
 /** The `air` object inside a `_meta`, or undefined when the peer sent no AIR extension. */
 export function airExtensionMeta(meta) {
     const air = asRecord(asRecord(meta)[JETBRAINS_META_KEY])[AIR_META_KEY];

package/dist/async-tasks.d.ts

@@ -1,6 +1,8 @@
 import type { ClientCapabilities } from "@agentclientprotocol/sdk";
 import type { AcpSessionNotification, AsyncTaskState } from "./acp-subagents.js";
 type Publish = (notification: AcpSessionNotification) => Promise<void>;
+/** Moves an update to its owner session, or drops it with `null`. */
+type Route = (notification: AcpSessionNotification) => AcpSessionNotification | null;
 type TaskIdentity = {
     taskId?: unknown;
     task_id?: unknown;
@@ -36,12 +38,16 @@ type TaskPatch = {
 };
 export type AsyncTaskNotification = TaskIdentity & {
     status?: unknown;
+    toolCallId?: unknown;
+    tool_use_id?: unknown;
     summary?: unknown;
     outputFilePath?: unknown;
     output_file?: unknown;
 };
 type TaskProgress = TaskIdentity & {
     description?: unknown;
+    toolCallId?: unknown;
+    tool_use_id?: unknown;
     summary?: unknown;
     lastToolName?: unknown;
     last_tool_name?: unknown;
@@ -61,7 +67,9 @@ export declare class AsyncTaskRuntime {
     private readonly sessionId;
     private readonly publish;
     /** `notices`: the client can present `notice` updates, so the stop
-     *  acknowledgement need not be a transcript line. */
+     *  acknowledgement need not be a transcript line. `routeOf`: the route of
+     *  the tasks that a tool call in another session started, for example in
+     *  a native subagent session. */
     private readonly options;
     /**
      * One registry owns both active tasks and terminal tombstones. Keeping an
@@ -71,9 +79,12 @@ export declare class AsyncTaskRuntime {
     private readonly tasks;
     constructor(enabled: boolean, sessionId: string, publish: Publish, 
     /** `notices`: the client can present `notice` updates, so the stop
-     *  acknowledgement need not be a transcript line. */
+     *  acknowledgement need not be a transcript line. `routeOf`: the route of
+     *  the tasks that a tool call in another session started, for example in
+     *  a native subagent session. */
     options?: {
         notices?: boolean;
+        routeOf?: (toolCallId: string) => Route | undefined;
     });
     taskStarted(message: AsyncTaskStarted): Promise<void>;
     taskBackgrounded(message: AsyncTaskStarted): Promise<void>;
@@ -96,17 +107,43 @@ export declare class AsyncTaskRuntime {
     claimStop(taskId: string): boolean;
     releaseStop(taskId: string): void;
     taskStopped(taskId: string): Promise<void>;
+    /**
+     * Sends the spawn of each held task without a tool call id. The prompt
+     * result ends the model turn, and the result of the tool call that started a
+     * task comes before it. So a held task is never held for longer than one turn.
+     */
+    releaseHeld(): Promise<void>;
     clear(): void;
     private task;
     private mergeStarted;
+    /** Keeps the first tool call id that a later SDK message brings. */
+    private mergeToolCallId;
+    /** Sends an update of an announced task. A held task sends it after its spawn. */
+    private whenAnnounced;
     private mergePatch;
     private mergeLevel;
     private mergeOutputFilePath;
+    /**
+     * Sends the spawn of the task. The spawn names the tool call that started the
+     * task, so it waits for the tool call id: the task is held until the id
+     * arrives. The id comes as `tool_use_id` of the SDK `task_started`,
+     * `task_progress`, or `task_notification`, or from the Bash result of a
+     * backgrounded command. A held task gets its spawn without the id when it
+     * ends first, or when the prompt result ends the model turn
+     * ({@link releaseHeld}). No guess by the command text binds a task.
+     */
     private announce;
     private finish;
     private publishMetadata;
+    /**
+     * Publishes the progress fields that changed since the last report of the
+     * task. A beat with nothing new is not sent.
+     */
     private publishProgress;
+    /** Publishes a state, with the output path and the tool call only when they changed. */
     private publishState;
+    /** Publishes an update of the task in the session that owns the task. */
+    private send;
 }
 /** Recovers background Bash lifecycle data exposed only on its tool result. */
 export declare function backgroundBashTaskFromToolResult(content: unknown, toolUseResult: unknown, toolUses: Record<string, {

package/dist/async-tasks.d.ts.map

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

package/dist/async-tasks.js

@@ -17,7 +17,9 @@ export class AsyncTaskRuntime {
     tasks = new Map();
     constructor(enabled, sessionId, publish, 
     /** `notices`: the client can present `notice` updates, so the stop
-     *  acknowledgement need not be a transcript line. */
+     *  acknowledgement need not be a transcript line. `routeOf`: the route of
+     *  the tasks that a tool call in another session started, for example in
+     *  a native subagent session. */
     options = {}) {
         this.enabled = enabled;
         this.sessionId = sessionId;
@@ -39,7 +41,8 @@ export class AsyncTaskRuntime {
         const previousToolCallId = task.toolCallId;
         const wasAnnounced = task.announced;
         this.mergeStarted(task, message);
-        if (isBackgroundTask(field(message, "isBackgrounded", "is_backgrounded"), field(message, "taskType", "task_type"))) {
+        if (isBackgroundTask(field(message, "isBackgrounded", "is_backgrounded"), field(message, "taskType", "task_type")) ||
+            task.held) {
             await this.announce(task);
         }
         if (wasAnnounced &&
@@ -97,8 +100,8 @@ export class AsyncTaskRuntime {
             }
             if (task.state !== state) {
                 task.state = state;
-                if (task.announced)
-                    await this.publishState(task, state, nonBlankString(patch.error));
+                const error = nonBlankString(patch.error);
+                await this.whenAnnounced(task, () => this.publishState(task, state, error));
             }
             else if (task.announced && task.outputFilePath !== previousOutputFilePath) {
                 await this.publishMetadata(task);
@@ -114,10 +117,12 @@ export class AsyncTaskRuntime {
         if (!taskId)
             return;
         const task = this.tasks.get(taskId);
-        if (!task || !task.announced || task.ignored)
+        if (!task || task.ignored || !(task.announced || task.held))
             return;
         const previousOutputFilePath = task.outputFilePath;
+        const previousToolCallId = task.toolCallId;
         this.mergeOutputFilePath(task, message);
+        this.mergeToolCallId(task, message);
         const outputChanged = task.outputFilePath !== previousOutputFilePath;
         if (isTerminal(task.state)) {
             if (outputChanged)
@@ -128,13 +133,21 @@ export class AsyncTaskRuntime {
         const description = nonBlankString(message.description);
         const summary = nonBlankString(message.summary);
         const lastToolName = nonBlankString(field(message, "lastToolName", "last_tool_name"));
-        await this.publishProgress(task, {
+        const progress = {
             ...(description ? { description } : {}),
             ...(summary ? { summary } : {}),
             ...(lastToolName ? { lastToolName } : {}),
             ...(usage ? { usage } : {}),
             ...(outputChanged && task.outputFilePath ? { outputFilePath: task.outputFilePath } : {}),
-        });
+            ...(task.toolCallId !== previousToolCallId && task.toolCallId
+                ? { toolCallId: task.toolCallId }
+                : {}),
+        };
+        await this.whenAnnounced(task, () => this.publishProgress(task, progress));
+        // The progress brought the tool call id of a held task: send the spawn,
+        // then the progress beats that waited for it.
+        if (task.held && task.toolCallId)
+            await this.announce(task);
     }
     async taskNotification(taskOrId, legacyStatus, legacySummary, legacyOutputFilePath) {
         if (!this.enabled)
@@ -156,6 +169,7 @@ export class AsyncTaskRuntime {
         const correctsLevelState = wasTerminal && task.terminalSource === "level";
         const previousOutputFilePath = task.outputFilePath;
         this.mergeOutputFilePath(task, message);
+        this.mergeToolCallId(task, message);
         await this.finish(task, state, nonBlankString(message.summary), "event");
         if (wasTerminal &&
             !correctsLevelState &&
@@ -207,7 +221,10 @@ export class AsyncTaskRuntime {
             await this.announce(task);
         }
         for (const task of this.tasks.values()) {
-            if (task.announced && !task.ignored && !isTerminal(task.state) && !live.has(task.id)) {
+            if ((task.announced || task.held) &&
+                !task.ignored &&
+                !isTerminal(task.state) &&
+                !live.has(task.id)) {
                 // This replace-semantics level is itself the authoritative liveness
                 // boundary. Close immediately so a lost terminal edge cannot leave a
                 // permanent running card; a following task_notification may correct
@@ -219,7 +236,7 @@ export class AsyncTaskRuntime {
     async finishAll(state) {
         const errors = [];
         for (const task of this.tasks.values()) {
-            if (task.announced && !task.ignored && !isTerminal(task.state)) {
+            if ((task.announced || task.held) && !task.ignored && !isTerminal(task.state)) {
                 try {
                     await this.finish(task, state, undefined, "shutdown");
                 }
@@ -270,10 +287,20 @@ export class AsyncTaskRuntime {
         // `showInTranscript` does not gate it either: that flag decides whether the
         // task owns a transcript *card* (a background Bash task is already drawn as
         // its tool call), not whether the agent may answer a direct user action.
-        await this.publish({
-            sessionId: this.sessionId,
-            update: noticeOrTranscriptUpdate({ severity: "info", title: "Task stopped by user", description: `${task.name}.` }, this.options.notices ?? false),
-        });
+        await this.send(task, noticeOrTranscriptUpdate({ severity: "info", title: "Task stopped by user", description: `${task.name}.` }, this.options.notices ?? false));
+    }
+    /**
+     * Sends the spawn of each held task without a tool call id. The prompt
+     * result ends the model turn, and the result of the tool call that started a
+     * task comes before it. So a held task is never held for longer than one turn.
+     */
+    async releaseHeld() {
+        if (!this.enabled)
+            return;
+        for (const task of this.tasks.values()) {
+            if (task.held)
+                await this.announce(task, { withoutToolCall: true });
+        }
     }
     clear() {
         this.tasks.clear();
@@ -289,12 +316,15 @@ export class AsyncTaskRuntime {
             description: "Background task",
             showInTranscript: true,
             announced: false,
+            held: false,
+            deferred: [],
             ignored: false,
             startedObserved: false,
             panelOnlyRecovery: false,
             stopping: false,
             stopAnnounced: false,
             state: "running",
+            published: new Map(),
         };
         this.tasks.set(taskId, task);
         return task;
@@ -325,6 +355,17 @@ export class AsyncTaskRuntime {
         if (toolCallId)
             task.toolCallId = toolCallId;
     }
+    /** Keeps the first tool call id that a later SDK message brings. */
+    mergeToolCallId(task, value) {
+        task.toolCallId ??= nonBlankString(field(value, "toolCallId", "tool_use_id"));
+    }
+    /** Sends an update of an announced task. A held task sends it after its spawn. */
+    async whenAnnounced(task, send) {
+        if (task.announced)
+            await send();
+        else if (task.held)
+            task.deferred.push(send);
+    }
     mergePatch(task, patch) {
         const description = nonBlankString(patch.description);
         if (description) {
@@ -348,24 +389,44 @@ export class AsyncTaskRuntime {
         if (outputFilePath)
             task.outputFilePath = outputFilePath;
     }
-    async announce(task) {
+    /**
+     * Sends the spawn of the task. The spawn names the tool call that started the
+     * task, so it waits for the tool call id: the task is held until the id
+     * arrives. The id comes as `tool_use_id` of the SDK `task_started`,
+     * `task_progress`, or `task_notification`, or from the Bash result of a
+     * backgrounded command. A held task gets its spawn without the id when it
+     * ends first, or when the prompt result ends the model turn
+     * ({@link releaseHeld}). No guess by the command text binds a task.
+     */
+    async announce(task, options = {}) {
         if (task.announced || task.ignored)
             return;
-        await this.publish({
-            sessionId: this.sessionId,
-            update: {
-                sessionUpdate: "async_task_spawned",
-                asyncTaskId: task.id,
-                name: task.name,
-                taskType: task.taskType,
-                description: task.description,
-                showInTranscript: task.showInTranscript,
-                canStop: true,
-                ...(task.outputFilePath ? { outputFilePath: task.outputFilePath } : {}),
-                ...(task.toolCallId ? { toolCallId: task.toolCallId } : {}),
-            },
+        if (!task.toolCallId && !options.withoutToolCall && !isTerminal(task.state)) {
+            task.held = true;
+            return;
+        }
+        if (task.toolCallId)
+            task.route ??= this.options.routeOf?.(task.toolCallId);
+        await this.send(task, {
+            sessionUpdate: "async_task_spawned",
+            asyncTaskId: task.id,
+            name: task.name,
+            taskType: task.taskType,
+            description: task.description,
+            showInTranscript: task.showInTranscript,
+            canStop: true,
+            ...(task.outputFilePath ? { outputFilePath: task.outputFilePath } : {}),
+            ...(task.toolCallId ? { toolCallId: task.toolCallId } : {}),
         });
         task.announced = true;
+        task.held = false;
+        recordPublished(task, {
+            description: task.description,
+            outputFilePath: task.outputFilePath,
+            toolCallId: task.toolCallId,
+        });
+        for (const send of task.deferred.splice(0))
+            await send();
         if (isTerminal(task.state)) {
             await this.publishState(task, task.state, task.terminalSummary);
         }
@@ -390,6 +451,10 @@ export class AsyncTaskRuntime {
         try {
             if (task.announced)
                 await this.publishState(task, state, summary);
+            // The task ended before its tool call id arrived. The spawn goes out now
+            // without the id, so the task still appears.
+            else if (task.held)
+                await this.announce(task);
         }
         catch (error) {
             task.state = previous.state;
@@ -411,28 +476,66 @@ export class AsyncTaskRuntime {
             }
         }
     }
+    /**
+     * Publishes the progress fields that changed since the last report of the
+     * task. A beat with nothing new is not sent.
+     */
     async publishProgress(task, update) {
-        await this.publish({
-            sessionId: this.sessionId,
-            update: {
-                sessionUpdate: "async_task_progress",
-                asyncTaskId: task.id,
-                ...update,
-            },
+        const changed = changedFields(task, update);
+        if (Object.keys(changed).length === 0)
+            return;
+        await this.send(task, {
+            sessionUpdate: "async_task_progress",
+            asyncTaskId: task.id,
+            ...changed,
         });
+        recordPublished(task, changed);
     }
+    /** Publishes a state, with the output path and the tool call only when they changed. */
     async publishState(task, state, summary) {
-        await this.publish({
-            sessionId: this.sessionId,
-            update: {
-                sessionUpdate: "async_task_state_update",
-                asyncTaskId: task.id,
-                state,
-                ...(summary ? { summary } : {}),
-                ...(task.outputFilePath ? { outputFilePath: task.outputFilePath } : {}),
-                ...(task.toolCallId ? { toolCallId: task.toolCallId } : {}),
-            },
+        const changed = changedFields(task, {
+            outputFilePath: task.outputFilePath,
+            toolCallId: task.toolCallId,
+        });
+        await this.send(task, {
+            sessionUpdate: "async_task_state_update",
+            asyncTaskId: task.id,
+            state,
+            ...(summary ? { summary } : {}),
+            ...changed,
         });
+        recordPublished(task, changed);
+    }
+    /** Publishes an update of the task in the session that owns the task. */
+    async send(task, update) {
+        const notification = { sessionId: this.sessionId, update };
+        const routed = task.route ? task.route(notification) : notification;
+        if (routed)
+            await this.publish(routed);
+    }
+}
+/**
+ * The fields whose value differs from what the client holds. An undefined
+ * value is not a field. The caller records the fields with
+ * {@link recordPublished} after the send succeeds, so a retry after a failed
+ * send carries them again.
+ */
+function changedFields(task, fields) {
+    const changed = {};
+    for (const [key, value] of Object.entries(fields)) {
+        if (value === undefined)
+            continue;
+        if (task.published.get(key) === JSON.stringify(value))
+            continue;
+        changed[key] = value;
+    }
+    return changed;
+}
+/** Records the fields that the client holds now. An undefined value is not a field. */
+function recordPublished(task, fields) {
+    for (const [key, value] of Object.entries(fields)) {
+        if (value !== undefined)
+            task.published.set(key, JSON.stringify(value));
     }
 }
 /** Recovers background Bash lifecycle data exposed only on its tool result. */

package/dist/context-compaction-meta.d.ts

@@ -1,4 +1,3 @@
-export declare const CONTEXT_COMPACTION_META_KEY = "contextCompaction";
 export declare const CONTEXT_COMPACTION_META_VERSION = 1;
 export type ContextCompactionTrigger = "manual" | "automatic";
 export interface ContextCompactionMetadata {
@@ -10,9 +9,11 @@ export interface ContextCompactionMetadata {
     error?: string;
 }
 /**
- * Provider-neutral metadata for a synthetic ACP context-compaction tool call.
- * The standard toolCallId and status fields own lifecycle identity and phase;
- * this extension carries only compaction-specific facts.
+ * The `_meta` of a context compaction report:
+ * `_meta.jetbrains.air.contextCompaction`, as `docs/air-extensions.md`
+ * defines. The standard toolCallId and status fields own lifecycle identity
+ * and phase; this extension carries only compaction-specific facts. Only AIR
+ * gets it.
  */
-export declare function createContextCompactionMeta(metadata?: Omit<ContextCompactionMetadata, "version">): Record<typeof CONTEXT_COMPACTION_META_KEY, ContextCompactionMetadata>;
+export declare function createContextCompactionMeta(metadata?: Omit<ContextCompactionMetadata, "version">): Record<string, unknown>;
 //# sourceMappingURL=context-compaction-meta.d.ts.map

package/dist/context-compaction-meta.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context-compaction-meta.d.ts","sourceRoot":"","sources":["../src/context-compaction-meta.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,2BAA2B,sBAAsB,CAAC;AAC/D,eAAO,MAAM,+BAA+B,IAAI,CAAC;AAEjD,MAAM,MAAM,wBAAwB,GAAG,QAAQ,GAAG,WAAW,CAAC;AAE9D,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,OAAO,+BAA+B,CAAC;IAChD,OAAO,CAAC,EAAE,wBAAwB,CAAC;IACnC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CACzC,QAAQ,GAAE,IAAI,CAAC,yBAAyB,EAAE,SAAS,CAAM,GACxD,MAAM,CAAC,OAAO,2BAA2B,EAAE,yBAAyB,CAAC,CAOvE"}
+{"version":3,"file":"context-compaction-meta.d.ts","sourceRoot":"","sources":["../src/context-compaction-meta.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,+BAA+B,IAAI,CAAC;AAEjD,MAAM,MAAM,wBAAwB,GAAG,QAAQ,GAAG,WAAW,CAAC;AAE9D,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,OAAO,+BAA+B,CAAC;IAChD,OAAO,CAAC,EAAE,wBAAwB,CAAC;IACnC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CACzC,QAAQ,GAAE,IAAI,CAAC,yBAAyB,EAAE,SAAS,CAAM,GACxD,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAKzB"}

package/dist/context-compaction-meta.js

@@ -1,15 +1,15 @@
-export const CONTEXT_COMPACTION_META_KEY = "contextCompaction";
+import { AIR_CONTEXT_COMPACTION_KEY, withAirMeta } from "./air-extension.js";
 export const CONTEXT_COMPACTION_META_VERSION = 1;
 /**
- * Provider-neutral metadata for a synthetic ACP context-compaction tool call.
- * The standard toolCallId and status fields own lifecycle identity and phase;
- * this extension carries only compaction-specific facts.
+ * The `_meta` of a context compaction report:
+ * `_meta.jetbrains.air.contextCompaction`, as `docs/air-extensions.md`
+ * defines. The standard toolCallId and status fields own lifecycle identity
+ * and phase; this extension carries only compaction-specific facts. Only AIR
+ * gets it.
  */
 export function createContextCompactionMeta(metadata = {}) {
-    return {
-        [CONTEXT_COMPACTION_META_KEY]: {
-            version: CONTEXT_COMPACTION_META_VERSION,
-            ...metadata,
-        },
-    };
+    return withAirMeta(undefined, AIR_CONTEXT_COMPACTION_KEY, {
+        version: CONTEXT_COMPACTION_META_VERSION,
+        ...metadata,
+    });
 }

package/dist/context-compaction.d.ts

@@ -18,6 +18,8 @@ export type ContextCompactionLifecycleOptions = {
     /** Receives failures of the send that must not propagate: the turn-boundary
      *  `cancelled` terminal. */
     logError?: (message: string, error: unknown) => void;
+    /** The client is AIR. Only AIR gets the compaction facts, under `_meta.jetbrains.air`. */
+    airClient?: boolean;
 };
 export declare function clientSupportsCompactionUpdates(capabilities?: ClientCapabilities | null): boolean;
 /**
@@ -60,6 +62,7 @@ export declare class ContextCompactionLifecycle {
     private readonly sessionId;
     readonly presentation: CompactionPresentation;
     private readonly logError;
+    private readonly airClient;
     constructor(sendUpdate: SendUpdate, options: ContextCompactionLifecycleOptions);
     get hasDeliveredOutput(): boolean;
     /**

package/dist/context-compaction.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context-compaction.d.ts","sourceRoot":"","sources":["../src/context-compaction.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AACnF,OAAO,EACL,yBAAyB,EAE1B,MAAM,8BAA8B,CAAC;AAEtC,KAAK,gBAAgB,GAAG,WAAW,GAAG,QAAQ,CAAC;AAG/C;;;;;;;;GAQG;AACH,MAAM,MAAM,sBAAsB,GAAG,WAAW,GAAG,mBAAmB,CAAC;AAavE,KAAK,UAAU,GAAG,CAAC,YAAY,EAAE,mBAAmB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAEvE,MAAM,MAAM,iCAAiC,GAAG;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,sBAAsB,CAAC;IACtC;gCAC4B;IAC5B,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACtD,CAAC;AAEF,wBAAgB,+BAA+B,CAAC,YAAY,CAAC,EAAE,kBAAkB,GAAG,IAAI,GAAG,OAAO,CAGjG;AAyBD;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAkBrE;AAoBD;6EAC6E;AAC7E,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAOjE;AAED;;;;;;;GAOG;AACH,qBAAa,0BAA0B;IAmBnC,OAAO,CAAC,QAAQ,CAAC,UAAU;IAlB7B,OAAO,CAAC,gBAAgB,CAA8B;IACtD,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,oBAAoB,CAAqB;IACjD;;iEAE6D;IAC7D,OAAO,CAAC,WAAW,CAAS;IAC5B;;;;kDAI8C;IAC9C,OAAO,CAAC,cAAc,CAAqB;IAC3C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,QAAQ,CAAC,YAAY,EAAE,sBAAsB,CAAC;IAC9C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA4C;gBAGlD,UAAU,EAAE,UAAU,EACvC,OAAO,EAAE,iCAAiC;IAO5C,IAAI,kBAAkB,IAAI,OAAO,CAEhC;IAED;;;;;;;;;OASG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAiB5B;;;;mEAI+D;IACzD,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAQhC;;2EAEuE;IACvE,MAAM,IAAI,IAAI;IAId;;;;OAIG;IACH,2BAA2B,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAW/C,KAAK,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA0BhD;;;;;;;;;;OAUG;IACG,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAwBzE;;;;;;;;;;;OAWG;IACH,aAAa,CAAC,UAAU,EAAE,OAAO,GAAG,OAAO;IAerC,MAAM,CACV,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,gBAAgB,EACxB,QAAQ,GAAE,IAAI,CAAC,yBAAyB,EAAE,SAAS,CAAM,EACzD,cAAc,UAAQ,GACrB,OAAO,CAAC,IAAI,CAAC;IA8DhB;2EACuE;IACvE,OAAO,CAAC,IAAI;IAaZ,OAAO,CAAC,IAAI;YAIE,WAAW;CAO1B;AAED,wBAAgB,qCAAqC,CAAC,eAAe,EAAE;IACrE,OAAO,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GAAG,IAAI,CAAC,yBAAyB,EAAE,SAAS,CAAC,CAW7C"}
+{"version":3,"file":"context-compaction.d.ts","sourceRoot":"","sources":["../src/context-compaction.ts"],"names":[],"mappings":"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"}