From 9e48e80fa5a01c4c25919af38d8a58b10878e31e Mon Sep 17 00:00:00 2001 From: Filip Hejmowski <34747899+neriousy@users.noreply.github.com> Date: Mon, 16 Nov 2026 17:55:39 +0100 Subject: [PATCH] fix(cli): stream ACP turns woken by background shells (#64262) --- packages/cli/src/acp/translate.ts | 47 +++++++++++-- packages/cli/src/acp/turn.ts | 11 ++-- .../acp/background-turn.subprocess.test.ts | 66 +++++++++++++++++++ packages/cli/test/acp/translate.test.ts | 56 ++++++++++++++++ packages/cli/test/acp/turn.test.ts | 36 ++++++++++ packages/cli/test/acp/wire-fixture.ts | 25 +++++++ 6 files changed, 229 insertions(+), 12 deletions(-) diff --git a/packages/cli/src/acp/translate.ts b/packages/cli/src/acp/translate.ts index f85be8cc561..cc8a11a6609 100644 --- a/packages/cli/src/acp/translate.ts +++ b/packages/cli/src/acp/translate.ts @@ -53,6 +53,8 @@ export type TurnState = { readonly compactions: ACPCompaction.Tracked readonly children: ReadonlyMap readonly openChildren: ReadonlySet + /** Background shells that will wake their session, with the inbox ID of their notice once it is queued. */ + readonly shells: ReadonlyMap readonly asks: ReadonlySet readonly finish?: SessionMessage.Assistant["finish"] readonly usage?: { readonly turn: TokenUsage.Info; readonly last: TokenUsage.Info } @@ -89,6 +91,7 @@ export const initial: TurnState = { compactions: new Map(), children: new Map(), openChildren: new Set(), + shells: new Map(), asks: new Set(), } @@ -126,16 +129,24 @@ export function fold(state: TurnState, event: OpenCodeEvent, ctx: TurnContext): return { state: { ...state, asks }, outputs: [{ _tag: "AskSettled", id: settledID }] } } if (!sessionID || (sessionID !== ctx.sessionID && !child)) return { state, outputs: [] } - if ( - sessionID === ctx.sessionID && - event.type === "session.inbox.delivered" && - (!ctx.start || event.data.inboxID === ctx.start.id) - ) - return { state: { ...state, started: true }, outputs: [] } + if (event.type === "session.inbox.enqueued") return { state: shellNoticed(state, event), outputs: [] } + if (event.type === "session.inbox.delivered" || event.type === "session.inbox.cancelled") { + const settled = noticeSettled(state, event.data.inboxID) + const started = + sessionID === ctx.sessionID && + event.type === "session.inbox.delivered" && + (!ctx.start || event.data.inboxID === ctx.start.id) + return { state: started ? { ...settled, started: true } : settled, outputs: [] } + } if (!child && !state.started) return { state, outputs: [] } return child ? childEvent(state, event, ctx, child) : rootEvent(state, event, ctx) } +/** Whether work that outlives the turn, such as a background child or shell, can still wake the session. */ +export function pending(state: TurnState) { + return state.openChildren.size > 0 || state.shells.size > 0 +} + export function projectChild(ctx: TurnContext, child: Child) { return !ctx.childUpdates && ctx.start !== undefined && child.turnID === ctx.start.id } @@ -383,8 +394,17 @@ function sessionEvent(state: TurnState, event: OpenCodeEvent, ctx: TurnContext, case "session.tool.success": { const key = toolKey(event.data.sessionID, event.data.id) const tool = state.tools.get(key) ?? newTool(event.data.sessionID, event.data.id) + // A shell moved to the background reports its end through a notice that wakes the session. + const shellID = event.data.metadata?.status === "running" ? event.data.metadata.shellID : undefined return { - state: { ...state, tools: without(state.tools, key) }, + state: { + ...state, + tools: without(state.tools, key), + // A command that exits at once can queue its notice first; keep the notice it already has. + ...(typeof shellID === "string" && !state.shells.has(shellID) + ? { shells: new Map(state.shells).set(shellID, undefined) } + : {}), + }, outputs: send({ sessionUpdate: "tool_call_update", ...completedToolUpdate({ @@ -447,6 +467,19 @@ function childEnded(state: TurnState, ctx: TurnContext, child: ACPChild.Session, return { state: { ...state, openChildren }, outputs: childStatus(ctx, child, status) } } +// A background shell's notice wakes the session once delivered, so the shell stays pending until then. Only a job's +// notice wakes it: a user's shell command queues one without a job ID that waits for the next prompt. +function shellNoticed(state: TurnState, event: Extract) { + const metadata = event.data.item.type === "synthetic" ? event.data.item.payload.metadata : undefined + if (typeof metadata?.shellID !== "string" || typeof metadata.jobID !== "string") return state + return { ...state, shells: new Map(state.shells).set(metadata.shellID, event.data.inboxID) } +} + +function noticeSettled(state: TurnState, inboxID: string) { + const shells = new Map([...state.shells].filter(([, notice]) => notice !== inboxID)) + return shells.size === state.shells.size ? state : { ...state, shells } +} + function recordStep(state: TurnState, tokens: TokenUsage.Info): TurnState { const turn = state.usage?.turn return { diff --git a/packages/cli/src/acp/turn.ts b/packages/cli/src/acp/turn.ts index 7e5637b584a..fc84604c019 100644 --- a/packages/cli/src/acp/turn.ts +++ b/packages/cli/src/acp/turn.ts @@ -93,6 +93,7 @@ export const make = Effect.fnUntraced(function* (input: { ...ACPTranslate.initial, children: inherited.children, openChildren: inherited.openChildren, + shells: inherited.shells, }) } // Parented to the service scope; the session scope may already be closed. @@ -239,10 +240,10 @@ export const make = Effect.fnUntraced(function* (input: { } }) - const followChildren = Effect.fnUntraced(function* (turn: Turn) { + const followBackground = Effect.fnUntraced(function* (turn: Turn) { while (true) { const folded = yield* advance(turn) - if (folded.terminal && folded.state.openChildren.size === 0) return yield* asksSettled(turn.subscription) + if (folded.terminal && !ACPTranslate.pending(folded.state)) return yield* asksSettled(turn.subscription) } }) @@ -328,19 +329,19 @@ export const make = Effect.fnUntraced(function* (input: { const close = Scope.close(turn.subscription.scope, Exit.void) if (Exit.isFailure(exit) && !Cause.hasInterruptsOnly(exit.cause)) return yield* close const state = yield* Ref.get(turn.state) - if (state.openChildren.size === 0) { + if (!ACPTranslate.pending(state)) { if (state.children.size > 0) backgrounds.set(attached, { state: turn.state }) return yield* close } const responded = yield* ACPConnection.Responded const nextState = yield* Ref.make({ ...state, started: false }) const cancelled = yield* Deferred.make() - // Children outlive a cancelled turn, so their asks and report-triggered turns still reach the client. + // Children and background shells outlive a cancelled turn, so their asks and the turns they wake reach the client. const background = Effect.withFiber((fiber) => { backgrounds.set(attached, { state: nextState, fiber }) return Effect.exit(responded).pipe( Effect.andThen( - followChildren({ ...turn, ctx: { ...turn.ctx, start: undefined }, state: nextState, cancelled }), + followBackground({ ...turn, ctx: { ...turn.ctx, start: undefined }, state: nextState, cancelled }), ), Effect.interruptible, ) diff --git a/packages/cli/test/acp/background-turn.subprocess.test.ts b/packages/cli/test/acp/background-turn.subprocess.test.ts index 5894004c437..c6610f68def 100644 --- a/packages/cli/test/acp/background-turn.subprocess.test.ts +++ b/packages/cli/test/acp/background-turn.subprocess.test.ts @@ -1,9 +1,75 @@ import type { PromptResponse } from "@agentclientprotocol/sdk" import { expect, test } from "bun:test" import { Schema } from "effect" +import path from "node:path" import { createAcpFixture, expectOk, initialize, newSession, toolCallStream } from "./subprocess" const modelRequest = Schema.decodeUnknownSync(Schema.Struct({ messages: Schema.Array(Schema.Unknown) })) +const sessionUpdate = Schema.decodeUnknownSync(Schema.Struct({ update: Schema.Record(Schema.String, Schema.Unknown) })) + +const windows = process.platform === "win32" +// Runs until the test creates `release` in the session directory, so the command ends after end_turn. +const releasedCommand = windows + ? "while (!(Test-Path release)) { Start-Sleep -Milliseconds 50 }; 'slow shell done'" + : "while [ ! -f release ]; do sleep 0.05; done; echo slow shell done" +// Exits at once, so its notice can arrive before the call's result or within the turn that started it. +const fastCommand = windows ? "'fast shell done'" : "echo fast shell done" + +test("streams turns woken by background shells and keeps the session usable", async () => { + const woken = Promise.withResolvers() + await using fixture = await createAcpFixture({ + respond(request) { + const last = JSON.stringify(modelRequest(request).messages.at(-1)) + if (last.includes(" + acp.request("session/prompt", { sessionId, prompt: [{ type: "text", text }] }).then(expectOk) + const update = (description: string, match: (update: Record) => boolean) => + acp + .waitForMessage( + (message) => message.method === "session/update" && match(sessionUpdate(message.params).update), + description, + ) + .then((message) => sessionUpdate(message.params).update) + const chunk = (text: string) => + update( + `the "${text}" agent_message_chunk`, + (item) => item.sessionUpdate === "agent_message_chunk" && JSON.stringify(item).includes(text), + ) + + // The prompt ends while its shell still runs; the shell's notice later wakes a turn the client is shown. + expect((await prompt("run the slow shell")).stopReason).toBe("end_turn") + const launched = await chunk("launched") + await update( + "the slow shell's completed call", + (item) => item.toolCallId === "call_slow" && item.status === "completed", + ) + await Bun.write(path.join(fixture.home, "release"), "") + await woken.promise + const reaction = await chunk("slow shell reaction") + expect(reaction.messageId).not.toBe(launched.messageId) + + // A shell that is done before its turn is: its reaction streams whether it lands in that turn or wakes another. + expect((await prompt("run the fast shell")).stopReason).toBe("end_turn") + await chunk("fast shell reaction") + + expect((await prompt("follow up")).stopReason).toBe("end_turn") + await chunk("follow-up reply") +}, 60_000) test("streams the parent's response to a subagent report after end_turn", async () => { const child = Promise.withResolvers() diff --git a/packages/cli/test/acp/translate.test.ts b/packages/cli/test/acp/translate.test.ts index e0a24ecdda8..79bdbb15d39 100644 --- a/packages/cli/test/acp/translate.test.ts +++ b/packages/cli/test/acp/translate.test.ts @@ -8,12 +8,14 @@ import { ACPReplay } from "../../src/acp/replay" import { ACPTranslate } from "../../src/acp/translate" import { assistantMessage, + backgroundShell, childCreated, delivered, durableEvent, ephemeralEvent, failed, reasoningDelta, + shellNotice, stepEnded, succeeded, textDelta, @@ -574,6 +576,59 @@ const rows: Row[] = [ ], }, }, + { + name: "keeps a background shell pending after its turn ends", + events: live(...backgroundShell(root, "sh_bg"), succeeded(root)), + expected: { terminal: "succeeded", pending: true }, + }, + { + name: "keeps a background shell pending until its queued notice is delivered", + events: live(...backgroundShell(root, "sh_bg"), shellNotice(root, "msg_notice", "sh_bg"), succeeded(root)), + expected: { pending: true }, + }, + { + name: "settles a background shell once its notice is delivered", + events: live( + ...backgroundShell(root, "sh_bg"), + shellNotice(root, "msg_notice", "sh_bg"), + delivered(root, "msg_notice"), + ), + expected: { pending: false }, + }, + { + name: "settles a background shell whose notice is cancelled", + events: live( + ...backgroundShell(root, "sh_bg"), + shellNotice(root, "msg_notice", "sh_bg"), + durableEvent("session.inbox.cancelled", { sessionID: root, inboxID: "msg_notice" }), + ), + expected: { pending: false }, + }, + { + name: "settles a shell that exits before its call's result arrives", + events: live( + shellNotice(root, "msg_notice", "sh_fast"), + ...backgroundShell(root, "sh_fast"), + delivered(root, "msg_notice"), + ), + expected: { pending: false }, + }, + { + name: "leaves a user's shell command, whose notice waits for the next prompt, out of pending work", + events: live(shellNotice(root, "msg_user_shell", "sh_user", { job: false }), succeeded(root)), + expected: { pending: false }, + }, + { + name: "keeps a finished child's background shell pending", + events: live( + childCreated("ses_child", root, "Explore"), + durableEvent("session.execution.started", { sessionID: "ses_child" }), + ...backgroundShell("ses_child", "sh_child"), + succeeded("ses_child"), + succeeded(root), + ), + expected: { terminal: "succeeded", pending: true }, + }, { name: "replays reasoning with the same message IDs as live reasoning ordinals", messages: [ @@ -624,6 +679,7 @@ function translate(row: Row) { failure: ACPTranslate.failure(result.state)?._tag, context: result.state.usage?.last, abandoned: updates(ACPTranslate.abandon(result.state, context).outputs), + pending: ACPTranslate.pending(result.state), } } diff --git a/packages/cli/test/acp/turn.test.ts b/packages/cli/test/acp/turn.test.ts index b56e3f3b494..0d15201e0c2 100644 --- a/packages/cli/test/acp/turn.test.ts +++ b/packages/cli/test/acp/turn.test.ts @@ -2,11 +2,13 @@ import { describe, expect, test } from "bun:test" import type { SessionNotification } from "@agentclientprotocol/sdk" import { ACPElicitation } from "../../src/acp/elicitation" import { + backgroundShell, childCreated, delivered, durableEvent, ephemeralEvent, permissionAsked, + shellNotice, startSession, succeeded, textDelta, @@ -193,6 +195,40 @@ describe("acp turn events over the wire", () => { ]) }) + test("streams resumed turns after background shells finish", async () => { + await using acp = await startSession({ + onPrompt: ({ sessionID, id, text }) => + turn( + sessionID, + id, + ...backgroundShell(sessionID, `sh_${text}`), + // The second shell finishes as its turn ends: the notice is queued in it but wakes the session afterwards. + ...(text === "second" ? [shellNotice(sessionID, "msg_notice_second", "sh_second")] : []), + ), + }) + const sessionID = acp.sessionId + + expect((await acp.prompt(sessionID, "first")).stopReason).toBe("end_turn") + acp.server.send( + shellNotice(sessionID, "msg_notice_first", "sh_first"), + ...turn(sessionID, "msg_notice_first", textDelta(sessionID, "msg_reaction_1", "first reaction")), + ) + await acp.waitForUpdate(({ update }) => JSON.stringify(update).includes("first reaction")) + + expect((await acp.prompt(sessionID, "second")).stopReason).toBe("end_turn") + acp.server.send(...turn(sessionID, "msg_notice_second", textDelta(sessionID, "msg_reaction_2", "second reaction"))) + await acp.waitForUpdate(({ update }) => JSON.stringify(update).includes("second reaction")) + + expect( + turnUpdates(acp.updates) + .map(({ update }) => update) + .filter((update) => update.sessionUpdate === "agent_message_chunk"), + ).toMatchObject([ + { messageId: "msg_reaction_1", content: { text: "first reaction" } }, + { messageId: "msg_reaction_2", content: { text: "second reaction" } }, + ]) + }) + test("cancels unsupported session forms so execution can continue", async () => { await using acp = await startSession({ onPrompt: ({ sessionID, id }) => [ diff --git a/packages/cli/test/acp/wire-fixture.ts b/packages/cli/test/acp/wire-fixture.ts index 0af8843b03b..0ae53804f1e 100644 --- a/packages/cli/test/acp/wire-fixture.ts +++ b/packages/cli/test/acp/wire-fixture.ts @@ -386,6 +386,31 @@ export function toolFailed( }) } +/** The calls of a shell the model ran in the background. */ +export function backgroundShell(sessionID: string, shellID: string) { + return [ + toolStarted(sessionID, `call_${shellID}`, "shell"), + toolCalled(sessionID, `call_${shellID}`, { command: "build", background: true }), + toolSucceeded(sessionID, `call_${shellID}`, { shellID, status: "running" }, "backgrounded"), + ] +} + +/** A finished shell's notice. A background job's carries its job ID; a user's shell command's has none. */ +export function shellNotice(sessionID: string, inboxID: string, shellID: string, options = { job: true }) { + return durableEvent("session.inbox.enqueued", { + sessionID, + inboxID, + item: { + type: "synthetic", + payload: { + text: ``, + metadata: { source: "shell", shellID, ...(options.job ? { jobID: shellID } : {}) }, + }, + delivery: "steer", + }, + }) +} + export function permissionAsked( sessionID: string, id: string,