From f73408dc33abe8d571c9eaf8ab42cb4eb0c97106 Mon Sep 17 00:00:00 2001 From: Mohamed Boudra Date: Fri, 20 Nov 2026 17:27:46 +0100 Subject: [PATCH] fix(acp): track post-end_turn wire order and preserve settled reply across tool completion --- .../src/server/acp-internal/connection.ts | 141 ++++++++---- packages/plugin/src/server/acp.test.ts | 215 ++++++++++++++++++ 2 files changed, 313 insertions(+), 43 deletions(-) diff --git a/packages/plugin/src/server/acp-internal/connection.ts b/packages/plugin/src/server/acp-internal/connection.ts index d3ed1a2097..b0d9db1b70 100644 --- a/packages/plugin/src/server/acp-internal/connection.ts +++ b/packages/plugin/src/server/acp-internal/connection.ts @@ -389,8 +389,6 @@ type DeferredTurnOutcome = | { type: "fail"; error: { message: string } }; interface DeferredTurnState { - replyOpen: boolean; - replySettled: boolean; timer: ReturnType | null; resolve(outcome: DeferredTurnOutcome): void; } @@ -401,6 +399,10 @@ interface ActivePrompt { cancelling: boolean; wirePromptsInFlight: number; wirePromptLane: Promise; + endTurnWireSeq: number | null; + crossedEndTurn: boolean; + replyOpen: boolean; + replySettled: boolean; deferred: DeferredTurnState | null; } @@ -449,6 +451,8 @@ class AcpRuntime { private stagedTransformerConfig: ProviderConfigState | null = null; private readonly closeConnector: () => Promise; private notificationLane: Promise = Promise.resolve(); + private incomingWireSeq = 0; + private readonly sessionUpdateWireSeqs: number[] = []; private autoAccept = false; private activePrompt: ActivePrompt | null = null; private lastUsage: ProviderUsage = {}; @@ -517,12 +521,18 @@ class AcpRuntime { this.transformers = options.options.transformers ?? []; const client: Client = { requestPermission: (request) => this.requestPermission(request), - sessionUpdate: (notification) => - this.enqueueNotification(() => this.sessionUpdate(notification)), + sessionUpdate: (notification) => { + const wireSeq = this.sessionUpdateWireSeqs.shift() ?? ++this.incomingWireSeq; + return this.enqueueNotification(() => this.sessionUpdate(notification, wireSeq)); + }, }; this.connection = new ClientSideConnection( () => client, - routeVendorNotifications(stream, (method, params) => this.vendorNotification(method, params)), + routeIncomingMessages( + stream, + (method, params) => this.vendorNotification(method, params), + (message) => this.observeWireMessage(message), + ), ); if (!child) void this.connection.closed.then(() => this.handleUnexpectedTransportClose()); child?.on("error", (error) => { @@ -714,6 +724,10 @@ class AcpRuntime { cancelling: false, wirePromptsInFlight: 1, wirePromptLane: Promise.resolve(), + endTurnWireSeq: null, + crossedEndTurn: false, + replyOpen: false, + replySettled: false, deferred: null, }; // The SDK dispatches notifications without awaiting them, so the prompt response can resolve @@ -1176,7 +1190,35 @@ class AcpRuntime { }); } - private sessionUpdate(notification: SessionNotification): void { + private observeWireMessage(message: unknown): void { + if (typeof message !== "object" || message === null) return; + const record = message as Record; + if (record.method === "session/update") { + this.sessionUpdateWireSeqs.push(++this.incomingWireSeq); + return; + } + if ( + !("method" in record) && + "id" in record && + typeof record.result === "object" && + record.result !== null && + (record.result as Record).stopReason === "end_turn" && + this.activePrompt && + !this.activePrompt.deferred && + this.activePrompt.endTurnWireSeq === null + ) { + this.activePrompt.endTurnWireSeq = ++this.incomingWireSeq; + } + } + + private isPostEndTurn(active: ActivePrompt, wireSeq: number): boolean { + return ( + active.deferred !== null || + (active.endTurnWireSeq !== null && wireSeq > active.endTurnWireSeq) + ); + } + + private sessionUpdate(notification: SessionNotification, wireSeq: number): void { if (notification.sessionId !== this.nativeSessionId) return; if (this.replayWindow) this.lastLoadUpdateAt = performance.now(); if (this.replayWindow === "skip") { @@ -1187,7 +1229,7 @@ class AcpRuntime { update.sessionUpdate === "current_mode_update" || update.sessionUpdate === "usage_update" ) { - this.reduceStateUpdate(update); + this.reduceStateUpdate(update, wireSeq); } return; } @@ -1198,10 +1240,10 @@ class AcpRuntime { this.reduceUserMessageChunk(notification.update); return; } - this.reduceUpdate(notification.update); + this.reduceUpdate(notification.update, wireSeq); } - private reduceUpdate(update: SessionUpdate): void { + private reduceUpdate(update: SessionUpdate, wireSeq: number): void { if ( update.sessionUpdate === "agent_message_chunk" || update.sessionUpdate === "agent_thought_chunk" || @@ -1235,25 +1277,16 @@ class AcpRuntime { : {}), }, }); - if (this.activePrompt?.deferred) { - if ( - update.sessionUpdate === "agent_message_chunk" && - this.activePrompt.wirePromptsInFlight === 0 - ) { - this.activePrompt.deferred.replyOpen = true; - } - this.activePrompt.deferred.replySettled = false; - this.scheduleDeferredSettle(); - } + this.noteDeferredChunk(update.sessionUpdate, wireSeq); return; } if (update.sessionUpdate === "tool_call" || update.sessionUpdate === "tool_call_update") { if (update.sessionUpdate === "tool_call") this.fallbackChunkIds.clear(); - this.reduceToolCall(update); + this.reduceToolCall(update, wireSeq); return; } if (update.sessionUpdate === "plan") this.fallbackChunkIds.clear(); - this.reduceStateUpdate(update); + this.reduceStateUpdate(update, wireSeq); } // Historical user messages arrive only as replayed chunks; a live prompt @@ -1297,7 +1330,7 @@ class AcpRuntime { return id; } - private reduceStateUpdate(update: SessionUpdate): void { + private reduceStateUpdate(update: SessionUpdate, wireSeq: number): void { if (update.sessionUpdate === "plan") { this.emit({ type: "timeline.item", @@ -1354,7 +1387,7 @@ class AcpRuntime { sessionId: this.options.boundarySessionId, usage: this.lastUsage, }); - this.noteDeferredUsageUpdate(); + this.noteDeferredUsageUpdate(wireSeq); return; } if (update.sessionUpdate === "compaction_update") { @@ -1414,6 +1447,7 @@ class AcpRuntime { private reduceToolCall( update: Extract, + wireSeq: number, ): void { if ( update.sessionUpdate === "tool_call_update" && @@ -1446,10 +1480,14 @@ class AcpRuntime { }); const isOpenQualifying = this.liveOpenToolIds.has(snapshot.id) && this.toolKeepsTurnOpen(snapshot); - if (this.activePrompt?.deferred && wasOpenQualifying !== isOpenQualifying) { - if (isOpenQualifying) this.activePrompt.deferred.replyOpen = false; - this.activePrompt.deferred.replySettled = false; - this.scheduleDeferredSettle(); + const active = this.activePrompt; + if (active && this.isPostEndTurn(active, wireSeq) && wasOpenQualifying !== isOpenQualifying) { + if (wasOpenQualifying) active.crossedEndTurn = true; + if (isOpenQualifying) { + active.replyOpen = false; + active.replySettled = false; + } + if (active.deferred) this.scheduleDeferredSettle(); } } @@ -1588,8 +1626,8 @@ class AcpRuntime { } const prompt = toAcpPrompt(input.prompt); active.wirePromptsInFlight += 1; - deferred.replyOpen = false; - deferred.replySettled = false; + active.replyOpen = false; + active.replySettled = false; this.scheduleDeferredSettle(); this.replayWindow = null; this.fallbackChunkIds.clear(); @@ -1682,7 +1720,8 @@ class AcpRuntime { private async settleDeferredPrompt(active: ActivePrompt): Promise { this.fallbackChunkIds.clear(); const outcome = await new Promise((resolve) => { - active.deferred = { replyOpen: false, replySettled: false, timer: null, resolve }; + active.deferred = { timer: null, resolve }; + this.scheduleDeferredSettle(); }); if (this.closing) return; if (outcome.type === "fail") { @@ -1726,7 +1765,7 @@ class AcpRuntime { private shouldDeferTurn(active: ActivePrompt): boolean { if (!this.options.options.acpOptions?.deferTurnOnRunningTools) return false; if (active.cancelling || this.closing || this.processFailed) return false; - return this.hasQualifyingOpenTools(); + return this.hasQualifyingOpenTools() || active.crossedEndTurn; } private finishDeferredTurn(active: ActivePrompt, outcome: DeferredTurnOutcome): void { @@ -1737,14 +1776,26 @@ class AcpRuntime { deferred.resolve(outcome); } - private noteDeferredUsageUpdate(): void { + private noteDeferredChunk( + kind: "agent_message_chunk" | "agent_thought_chunk", + wireSeq: number, + ): void { const active = this.activePrompt; - const deferred = active?.deferred; - if (!active || !deferred || active.wirePromptsInFlight > 0 || !deferred.replyOpen) return; - deferred.replyOpen = false; - if (this.hasDeferredBlockers()) return; - deferred.replySettled = true; - this.scheduleDeferredSettle(); + if (!active || !this.isPostEndTurn(active, wireSeq)) return; + const inWireSteer = active.deferred !== null && active.wirePromptsInFlight > 0; + if (kind === "agent_message_chunk" && !inWireSteer) active.replyOpen = true; + active.replySettled = false; + if (active.deferred) this.scheduleDeferredSettle(); + } + + private noteDeferredUsageUpdate(wireSeq: number): void { + const active = this.activePrompt; + if (!active || !this.isPostEndTurn(active, wireSeq)) return; + const inWireSteer = active.deferred !== null && active.wirePromptsInFlight > 0; + if (inWireSteer || !active.replyOpen) return; + active.replyOpen = false; + active.replySettled = true; + if (active.deferred) this.scheduleDeferredSettle(); } private scheduleDeferredSettle(): void { @@ -1757,7 +1808,7 @@ class AcpRuntime { deferred.timer = null; } if (this.hasDeferredBlockers()) return; - const delayMs = deferred.replySettled + const delayMs = active.replySettled ? (config.settleDelayMs ?? DEFAULT_DEFERRED_SETTLE_DELAY_MS) : (config.quietLimitMs ?? DEFAULT_DEFERRED_QUIET_LIMIT_MS); deferred.timer = setTimeout(() => { @@ -1810,9 +1861,10 @@ class AcpRuntime { } } -function routeVendorNotifications( +function routeIncomingMessages( stream: Stream, - receive: (method: string, params: unknown) => void, + receiveVendor: (method: string, params: unknown) => void, + observeWire: (message: unknown) => void, ): Stream { const clientMethods = new Set(Object.values(CLIENT_METHODS)); return { @@ -1824,11 +1876,14 @@ function routeVendorNotifications( // The SDK dispatches extensions asynchronously and can resolve a later response first. // Run synchronous vendor transforms in wire order, inside the configuration transaction. try { - receive(message.method, message.params); + receiveVendor(message.method, message.params); } catch (error) { console.error("Error handling ACP vendor notification", error); } - } else controller.enqueue(message); + } else { + observeWire(message); + controller.enqueue(message); + } }, }), ), diff --git a/packages/plugin/src/server/acp.test.ts b/packages/plugin/src/server/acp.test.ts index a065b73f7e..696f8821c3 100644 --- a/packages/plugin/src/server/acp.test.ts +++ b/packages/plugin/src/server/acp.test.ts @@ -4905,4 +4905,219 @@ describe("deferTurnOnRunningTools", () => { await connection.close(); } }); + + it("settles on the reply timer when reply usage arrives before the final background tool completes", async () => { + const { connector, instances } = connectorHarness({ + handleRequest(instance, request) { + if (request.method !== "session/prompt") return false; + instance.notify("session/update", { + sessionId: "connector-session", + update: { + sessionUpdate: "tool_call", + toolCallId: "bg-u1", + name: "run_command", + title: "Job 1", + status: "in_progress", + }, + }); + instance.notify("session/update", { + sessionId: "connector-session", + update: { + sessionUpdate: "tool_call", + toolCallId: "bg-u2", + name: "run_command", + title: "Job 2", + status: "in_progress", + }, + }); + instance.respond(request, { stopReason: "end_turn" }); + return true; + }, + }); + const registration = runAcpProvider({ + id: "deferred-usage-before-tool", + label: "Deferred Usage Before Tool", + connector, + acpOptions: { + deferTurnOnRunningTools: { + settleDelayMs: 30, + quietLimitMs: 1_500, + }, + }, + }); + const connection = await registration.connect({ + versions: [1], + capabilities: ["prompt.message"], + }); + const events: ProviderEvent[] = []; + connection.onEvent((event) => events.push(event)); + try { + await connection.send(openInput()); + await waitForEvent(events, (event) => event.type === "session.ready"); + await connection.send({ + type: "session.prompt", + sessionId: "session-1", + prompt: { + clientMessageId: "usage-first-turn", + delivery: "auto", + input: { type: "message", content: [{ type: "text", text: "run jobs" }] }, + }, + }); + await waitForEvent( + events, + (event) => + event.type === "timeline.item" && + event.item.type === "tool_call" && + event.item.id === "bg-u2", + ); + await new Promise((resolve) => setTimeout(resolve, 20)); + + // Job 1 finishes, reply + usage_update arrive while Job 2 is still running. + instances[1].notify("session/update", { + sessionId: "connector-session", + update: { sessionUpdate: "tool_call_update", toolCallId: "bg-u1", status: "completed" }, + }); + instances[1].notify("session/update", { + sessionId: "connector-session", + update: textChunk("All done."), + }); + instances[1].notify("session/update", { + sessionId: "connector-session", + update: { sessionUpdate: "usage_update", used: 300, size: 1000 }, + }); + await new Promise((resolve) => setTimeout(resolve, 50)); + // Still running because Job 2 has not completed yet. + expect( + events.some( + (event) => + event.type === "session.turn" && + event.turnId === "acp:usage-first-turn" && + event.state !== "started", + ), + ).toBe(false); + + // Job 2 completes -> should settle via settleDelayMs, not quietLimitMs. + const startedAt = Date.now(); + instances[1].notify("session/update", { + sessionId: "connector-session", + update: { sessionUpdate: "tool_call_update", toolCallId: "bg-u2", status: "completed" }, + }); + await waitForEvent( + events, + (event) => + event.type === "session.turn" && + event.turnId === "acp:usage-first-turn" && + event.state === "completed", + 400, + ); + expect(Date.now() - startedAt).toBeLessThan(400); + } finally { + await connection.close(); + } + }); + + it("defers the turn when a running tool completes immediately after end_turn in the same batch", async () => { + const { connector, instances } = connectorHarness({ + handleRequest(instance, request) { + if (request.method !== "session/prompt") return false; + instance.notify("session/update", { + sessionId: "connector-session", + update: { + sessionUpdate: "tool_call", + toolCallId: "bg-race", + name: "run_command", + title: "Fast background job", + status: "in_progress", + }, + }); + instance.respond(request, { stopReason: "end_turn" }); + // Completion arrives right after end_turn in the same wire batch. + instance.notify("session/update", { + sessionId: "connector-session", + update: { + sessionUpdate: "tool_call_update", + toolCallId: "bg-race", + status: "completed", + }, + }); + return true; + }, + }); + const registration = runAcpProvider({ + id: "deferred-post-end-turn-race", + label: "Deferred Post End Turn Race", + connector, + acpOptions: { + deferTurnOnRunningTools: { + settleDelayMs: 30, + quietLimitMs: 1_500, + }, + }, + }); + const connection = await registration.connect({ + versions: [1], + capabilities: ["prompt.message"], + }); + const events: ProviderEvent[] = []; + connection.onEvent((event) => events.push(event)); + try { + await connection.send(openInput()); + await waitForEvent(events, (event) => event.type === "session.ready"); + await connection.send({ + type: "session.prompt", + sessionId: "session-1", + prompt: { + clientMessageId: "race-turn", + delivery: "auto", + input: { type: "message", content: [{ type: "text", text: "run fast bg job" }] }, + }, + }); + await waitForEvent( + events, + (event) => + event.type === "timeline.item" && + event.item.type === "tool_call" && + event.item.id === "bg-race" && + event.item.status === "completed", + ); + await new Promise((resolve) => setTimeout(resolve, 60)); + // Turn must still be open waiting for the post-tool reply. + expect( + events.some( + (event) => + event.type === "session.turn" && + event.turnId === "acp:race-turn" && + event.state !== "started", + ), + ).toBe(false); + + // Post-tool reply + usage_update arrive and settle the deferred turn. + instances[1].notify("session/update", { + sessionId: "connector-session", + update: textChunk("Background job finished."), + }); + instances[1].notify("session/update", { + sessionId: "connector-session", + update: { sessionUpdate: "usage_update", used: 250, size: 1000 }, + }); + await waitForEvent( + events, + (event) => + event.type === "session.turn" && + event.turnId === "acp:race-turn" && + event.state === "completed", + 400, + ); + expect( + events.some( + (event) => + event.type === "timeline.item" && + event.item.type === "assistant_message" && + event.item.text === "Background job finished.", + ), + ).toBe(true); + } finally { + await connection.close(); + } + }); });