fix(cli): stream ACP turns woken by background shells (#64262)

This commit is contained in:
Filip Hejmowski
2026-11-16 17:55:39 +01:00
committed by GitHub
Unverified
parent 887a78e280
commit 9e48e80fa5
6 changed files with 229 additions and 12 deletions
+40 -7
View File
@@ -53,6 +53,8 @@ export type TurnState = {
readonly compactions: ACPCompaction.Tracked
readonly children: ReadonlyMap<string, Child>
readonly openChildren: ReadonlySet<string>
/** Background shells that will wake their session, with the inbox ID of their notice once it is queued. */
readonly shells: ReadonlyMap<string, string | undefined>
readonly asks: ReadonlySet<string>
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<OpenCodeEvent, { type: "session.inbox.enqueued" }>) {
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 {
+6 -5
View File
@@ -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<void>()
// 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,
)
@@ -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<void>()
await using fixture = await createAcpFixture({
respond(request) {
const last = JSON.stringify(modelRequest(request).messages.at(-1))
if (last.includes("<shell") && last.includes("slow shell done")) {
woken.resolve()
return "slow shell reaction"
}
if (last.includes("<shell") && last.includes("fast shell done")) return "fast shell reaction"
if (last.includes("run the slow shell"))
return toolCallStream("call_slow", "shell", { command: releasedCommand, description: "Slow", background: true })
if (last.includes("run the fast shell"))
return toolCallStream("call_fast", "shell", { command: fastCommand, description: "Fast", background: true })
if (last.includes("follow up")) return "follow-up reply"
return "launched"
},
})
const acp = fixture.spawn()
await initialize(acp)
const { sessionId } = await newSession(acp, fixture.home)
const prompt = (text: string) =>
acp.request<PromptResponse>("session/prompt", { sessionId, prompt: [{ type: "text", text }] }).then(expectOk)
const update = (description: string, match: (update: Record<string, unknown>) => 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<string>()
+56
View File
@@ -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),
}
}
+36
View File
@@ -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 }) => [
+25
View File
@@ -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: `<shell id="${shellID}" state="completed">`,
metadata: { source: "shell", shellID, ...(options.job ? { jobID: shellID } : {}) },
},
delivery: "steer",
},
})
}
export function permissionAsked(
sessionID: string,
id: string,