Skip to content

Commit ced4c34

Browse files
authored
fix: wait for the compact turn to finish (#654)
## Summary Fix the `/compact` completion race observed while implementing client system prompts. Compaction item completion is a progress/lifecycle signal, not proof that Codex has released the turn. The command now waits for the matching terminal `turn/completed` notification before completing foreground work. It returns the real turn result through the existing success, cancellation, and failure handling. - V1 holds the prompt response until the compact turn ends. - V2 still accepts the prompt early, but holds idle and the next queued prompt until the turn ends. - Compaction progress updates, including legacy `thread/compacted` rendering, are unchanged. - Existing close/dispose/process-exit handling still rejects pending waits and releases observers. - Remove the runtime-log wait from the real-process system-prompt integration fixture: it now starts the next probe immediately after ACP completion. Standard subagent support remains a separate work package. ## Validation - Added a regression assertion that failed on the original implementation: item completion resolved the command before turn completion. - Added v1/v2 wire-order snapshots proving the next prompt cannot start in that gap. - Cover early success/failure/cancellation before acknowledgement, unrelated turn completion, and failure/cancellation after item completion; retain rejection, cancellation, and connection/process-exit coverage. - `npm run typecheck` — passed, including examples. - `npm test` — **1,867 passed**, 36 skipped. - `npm run build` — passed. - `npm run test:integration` — **7 passed**, including immediate compact-to-prompt transitions through ACP v1/v2 against real Codex app-server with a local mock model, without runtime-log synchronization. - `npm run codex-test -- -p '/compact' ... -o summary` — passed against real Codex; ended with `end_turn` and observed both item and turn completion. - `git diff --check` — passed. The full live-model E2E suite and local cross-platform binary bundles were not run; CI runs binary bundling.
1 parent 5993a12 commit ced4c34

11 files changed

Lines changed: 150 additions & 32 deletions

‎readme-dev.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -176,6 +176,13 @@ through app-server recovery and provider restarts. After closing a session or re
176176
adapter, clients should resend their prompt on load/resume/fork; without it, Codex's retained
177177
context and configured defaults determine the instructions.
178178

179+
#### Manual compaction
180+
181+
`/compact` finishes foreground work only after Codex reports `turn/completed` for the compact
182+
turn. Item completion still reports compaction progress, but does not release the next prompt.
183+
The v1 prompt response and v2 idle state wait for the turn to finish; v2's early prompt-acceptance
184+
response is unchanged.
185+
179186
#### AIR v2 client contract
180187

181188
These are behaviors the AIR (JetBrains) ACP client relies on that aren't obvious from the wire

‎src/CodexAcpClient.ts‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1005,9 +1005,8 @@ export class CodexAcpClient {
10051005
sessionId: string,
10061006
onTurnStarted?: (turnId: string) => void,
10071007
onAccepted?: () => void,
1008-
): Promise<TurnCompletedNotification | undefined> {
1009-
const completed = await this.codexClient.runCompact({threadId: sessionId}, onTurnStarted, onAccepted);
1010-
return completed.method === "turn/completed" ? completed.params : undefined;
1008+
): Promise<TurnCompletedNotification> {
1009+
return await this.codexClient.runCompact({threadId: sessionId}, onTurnStarted, onAccepted);
10111010
}
10121011

10131012
async getGoal(sessionId: string): Promise<ThreadGoal | null> {

‎src/CodexAppServerClient.ts‎

Lines changed: 5 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -602,12 +602,11 @@ export class CodexAppServerClient {
602602
params: ThreadCompactStartParams,
603603
onTurnStarted?: (turnId: string) => void,
604604
onAccepted?: () => void,
605-
): Promise<CompactionCompletedNotification | Extract<ServerNotification, {method: "turn/completed"}>> {
606-
type Result = CompactionCompletedNotification | Extract<ServerNotification, {method: "turn/completed"}>;
605+
): Promise<TurnCompletedNotification> {
607606
let compactTurnId: string | null = null;
608-
let resolveCompleted: (event: Result) => void = () => {};
607+
let resolveCompleted: (event: TurnCompletedNotification) => void = () => {};
609608
let rejectCompleted: (error: Error) => void = () => {};
610-
const completed = new Promise<Result>((resolve, reject) => {
609+
const completed = new Promise<TurnCompletedNotification>((resolve, reject) => {
611610
resolveCompleted = resolve;
612611
rejectCompleted = reject;
613612
});
@@ -617,15 +616,11 @@ export class CodexAppServerClient {
617616
const rejectClosed = () => rejectCompleted(new Error("Codex connection closed during compaction."));
618617
const closed = this.connection.onClose?.(rejectClosed);
619618
const disposed = this.connection.onDispose?.(rejectClosed);
620-
const completeCompaction = (event: CompactionCompletedNotification) => {
621-
if (compactTurnId !== null && event.params.turnId !== compactTurnId) return;
622-
resolveCompleted(event);
623-
};
624-
const releaseCompactionCapture = this.captureCompactionCompletions(params.threadId, completeCompaction);
619+
// Item completion reports progress, but Codex still owns the turn until turn/completed.
625620
const releaseTurnCapture = this.captureTurnCompletions(params.threadId, (event) => {
626621
if (compactTurnId === null || event.turn.id !== compactTurnId) return;
627622
if (event.turn.status !== "inProgress") {
628-
resolveCompleted({method: "turn/completed", params: event});
623+
resolveCompleted(event);
629624
}
630625
});
631626
const releaseRoutingCapture = this.captureTurnRoutings(params.threadId, (turnId, notification) => {
@@ -644,7 +639,6 @@ export class CodexAppServerClient {
644639
} finally {
645640
releaseTurnCapture();
646641
releaseRoutingCapture();
647-
releaseCompactionCapture();
648642
closed?.dispose();
649643
disposed?.dispose();
650644
}

‎src/CodexCommands.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -383,7 +383,7 @@ export class CodexCommands {
383383
(turnId) => options.onTurnStarted?.(turnId, sessionId),
384384
options.onCommandAccepted,
385385
));
386-
return { handled: true, ...(turnCompleted === undefined ? {} : {turnCompleted}) };
386+
return { handled: true, turnCompleted };
387387
}
388388
case "goal": {
389389
return await this.runGoalCommand(sessionState, command.rest, options);

‎src/__tests__/CodexACPAgent/CodexAcpClient.test.ts‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2294,10 +2294,17 @@ describe('ACP server test', { timeout: 40_000 }, () => {
22942294
await Promise.resolve();
22952295
expect(promptResolved).toBe(false);
22962296

2297+
mockFixture.sendServerNotification({
2298+
method: "turn/started",
2299+
params: {threadId: "session-id", turn: createTurn("compact-turn-id", "inProgress")},
2300+
});
22972301
mockFixture.sendServerNotification({
22982302
method: "thread/compacted",
22992303
params: { threadId: "session-id", turnId: "compact-turn-id" },
23002304
});
2305+
await flushAsyncWork();
2306+
expect(promptResolved).toBe(false);
2307+
mockFixture.sendServerNotification(createTurnCompletedNotification("session-id", "compact-turn-id"));
23012308

23022309
await expect(promptPromise).resolves.toEqual(expect.objectContaining({
23032310
stopReason: "end_turn",
@@ -3725,10 +3732,15 @@ describe('ACP server test', { timeout: 40_000 }, () => {
37253732
controller.abort();
37263733
await expect(promptPromise).resolves.toMatchObject({stopReason: "cancelled"});
37273734

3735+
mockFixture.sendServerNotification({
3736+
method: "turn/started",
3737+
params: {threadId: "session-id", turn: createTurn("compact-turn-id", "inProgress")},
3738+
});
37283739
mockFixture.sendServerNotification({
37293740
method: "thread/compacted",
37303741
params: { threadId: "session-id", turnId: "compact-turn-id" },
37313742
});
3743+
mockFixture.sendServerNotification(createTurnCompletedNotification("session-id", "compact-turn-id"));
37323744
await flushAsyncWork();
37333745
});
37343746

‎src/__tests__/CodexACPAgent/compact-command-lifecycle.test.ts‎

Lines changed: 31 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ const sessionId = "compact-command-session";
1212
const turnId = "compact-command-turn";
1313

1414
describe("compact command lifecycle", () => {
15-
it.each(["interrupted", "failed"] as const)("captures an early %s turn before compact acknowledgement", async (status) => {
15+
it.each(["completed", "interrupted", "failed"] as const)("captures an early %s turn before compact acknowledgement", async (status) => {
1616
const fixture = createCodexMockTestFixture();
1717
const appServer = fixture.getCodexAppServerClient();
1818
const completed = turnCompleted(status);
@@ -23,7 +23,7 @@ describe("compact command lifecycle", () => {
2323
});
2424
const onTurnStarted = vi.fn();
2525

26-
await expect(appServer.runCompact({threadId: sessionId}, onTurnStarted)).resolves.toEqual(completed);
26+
await expect(appServer.runCompact({threadId: sessionId}, onTurnStarted)).resolves.toEqual(completed.params);
2727
expect(onTurnStarted).toHaveBeenCalledExactlyOnceWith(turnId);
2828
});
2929

@@ -36,8 +36,7 @@ describe("compact command lifecycle", () => {
3636
settled = true;
3737
return result;
3838
});
39-
// The preceding compact prompt may resolve on item/completed before this
40-
// previous turn/completed reaches the next compact request.
39+
// A preceding turn's terminal notification cannot finish this compaction.
4140
fixture.sendServerNotification({
4241
method: "turn/completed",
4342
params: {threadId: sessionId, turn: {...turn("completed"), id: "previous-turn"}},
@@ -67,7 +66,12 @@ describe("compact command lifecycle", () => {
6766
},
6867
};
6968
fixture.sendServerNotification(completed);
70-
await expect(pending).resolves.toEqual(completed);
69+
await new Promise(resolve => setImmediate(resolve));
70+
expect(settled).toBe(false);
71+
72+
const finished = turnCompleted("completed");
73+
fixture.sendServerNotification(finished);
74+
await expect(pending).resolves.toEqual(finished.params);
7175
});
7276

7377
it("releases compact observation after the request is rejected", async () => {
@@ -82,9 +86,28 @@ describe("compact command lifecycle", () => {
8286

8387
start.mockResolvedValue({});
8488
const retry = appServer.runCompact({threadId: sessionId});
85-
const completed: ServerNotification = {method: "thread/compacted", params: {threadId: sessionId, turnId}};
89+
fixture.sendServerNotification({method: "turn/started", params: {threadId: sessionId, turn: turn("inProgress")}});
90+
const completed = turnCompleted("completed");
91+
fixture.sendServerNotification(completed);
92+
await expect(retry).resolves.toEqual(completed.params);
93+
});
94+
95+
it.each(["failed", "interrupted"] as const)("preserves a %s turn after the compaction item completes", async status => {
96+
const fixture = createCodexMockTestFixture();
97+
const appServer = fixture.getCodexAppServerClient();
98+
vi.spyOn(appServer, "threadCompactStart").mockResolvedValue({});
99+
const pending = appServer.runCompact({threadId: sessionId});
100+
startCompaction(fixture);
101+
fixture.sendServerNotification({
102+
method: "item/completed",
103+
params: {
104+
threadId: sessionId, turnId, completedAtMs: 1,
105+
item: {type: "contextCompaction", id: "compaction-item"},
106+
},
107+
});
108+
const completed = turnCompleted(status);
86109
fixture.sendServerNotification(completed);
87-
await expect(retry).resolves.toEqual(completed);
110+
await expect(pending).resolves.toEqual(completed.params);
88111
});
89112

90113
it("rejects a compact wait when the Codex connection closes", async () => {
@@ -196,7 +219,7 @@ function startCompaction(fixture: ReturnType<typeof createCodexMockTestFixture>)
196219
});
197220
}
198221

199-
function turnCompleted(status: "failed" | "interrupted"): Extract<ServerNotification, {method: "turn/completed"}> {
222+
function turnCompleted(status: "completed" | "failed" | "interrupted"): Extract<ServerNotification, {method: "turn/completed"}> {
200223
return {method: "turn/completed", params: {threadId: sessionId, turn: turn(status)}};
201224
}
202225

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
import {afterEach, describe, expect, it, vi} from "vitest";
2+
import {
3+
connectSession, dump, itemCompleted, itemStarted, settle, stateUpdates,
4+
turnCompleted, turnStarted, userMessageItem, type PromptSession,
5+
} from "./v2-prompt-harness";
6+
7+
describe.each([1, 2] as const)("/compact completion over ACP v%s", version => {
8+
let client: PromptSession;
9+
afterEach(() => client?.connection.close());
10+
11+
it("holds the next prompt until the compact turn ends, not just its item", async () => {
12+
client = await connectSession(version);
13+
const start = vi.fn(async () => ({}));
14+
client.setCodexResponse("thread/compact/start", start);
15+
const compact = client.sendPrompt([{type: "text", text: "/compact"}]);
16+
await vi.waitFor(() => expect(start).toHaveBeenCalledOnce());
17+
// V2 accepts the command early, but its foreground work must remain running.
18+
if (version === 2) await compact;
19+
let finished = false;
20+
const compactFinished = client.promptRunFinished().then(() => { finished = true; });
21+
const item = {type: "contextCompaction" as const, id: "compaction-item"};
22+
client.emit(turnStarted("compact-turn"));
23+
client.emit(itemStarted(item, "compact-turn"));
24+
client.emit(itemCompleted(item, "compact-turn"));
25+
await settle();
26+
expect(finished).toBe(false);
27+
expect(stateUpdates(client.transcript).some(update => update.state === "idle")).toBe(false);
28+
29+
const next = client.sendPrompt([{type: "text", text: "Next prompt"}]);
30+
await settle();
31+
expect(client.turnStartParams).toEqual([]);
32+
33+
client.emit(turnCompleted("compact-turn"));
34+
await compactFinished;
35+
await compact;
36+
await vi.waitFor(() => expect(client.turnStartParams).toHaveLength(1));
37+
const messageId = client.turnStartParams[0]!["clientUserMessageId"];
38+
client.emit(turnStarted());
39+
client.emit(itemCompleted(userMessageItem(typeof messageId === "string" ? messageId : null, "Next prompt")));
40+
if (version === 2) await next;
41+
client.emit(turnCompleted());
42+
await next;
43+
await client.promptRunFinished(1);
44+
await settle();
45+
46+
const timeline = client.transcript.flatMap(entry => {
47+
if ("codexNotification" in entry) return [entry.codexNotification];
48+
if ("codexRequest" in entry) return [entry.codexRequest];
49+
if ("promptResponse" in entry) return ["prompt_response"];
50+
if ("sessionUpdate" in entry && entry.sessionUpdate.sessionUpdate === "state_update") {
51+
return [`state:${entry.sessionUpdate.state}`];
52+
}
53+
return [];
54+
});
55+
await expect(dump(timeline)).toMatchFileSnapshot(`data/compact-command-v${version}-ordering.json`);
56+
});
57+
});
Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
[
2+
"turn/started",
3+
"item/started",
4+
"item/completed",
5+
"turn/completed",
6+
"turn/start",
7+
"prompt_response",
8+
"turn/started",
9+
"item/completed",
10+
"turn/completed",
11+
"prompt_response"
12+
]
Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
[
2+
"prompt_response",
3+
"state:running",
4+
"turn/started",
5+
"item/started",
6+
"item/completed",
7+
"turn/completed",
8+
"state:idle",
9+
"turn/start",
10+
"state:running",
11+
"turn/started",
12+
"item/completed",
13+
"prompt_response",
14+
"turn/completed",
15+
"state:idle"
16+
]

‎src/__tests__/CodexACPAgent/session-compaction.test.ts‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -131,7 +131,11 @@ describe("session compaction", () => {
131131
const compactStart = vi.spyOn(fixture.getCodexAppServerClient(), "threadCompactStart");
132132
const prompt = fixture.getCodexAcpAgent().prompt({sessionId, prompt: [{type: "text", text: "/compact"}]});
133133
await vi.waitFor(() => expect(compactStart).toHaveBeenCalledWith({threadId: sessionId}));
134-
await sendNotifications(fixture, [compactionStarted(), compactionCompleted()]);
134+
await sendNotifications(fixture, [
135+
compactionStarted(),
136+
compactionCompleted(),
137+
{method: "turn/completed", params: {threadId: sessionId, turn: createTurn("completed")}},
138+
]);
135139
await expect(prompt).resolves.toMatchObject({stopReason: "end_turn"});
136140

137141
await expect(fixture.getAcpConnectionDump([])).toMatchFileSnapshot(

0 commit comments

Comments
 (0)