Skip to content

Commit 84bfbe8

Browse files
jimjim
authored andcommitted
fix: keep idle steering fallback host-owned
1 parent 2b48e98 commit 84bfbe8

4 files changed

Lines changed: 100 additions & 9 deletions

File tree

‎src/AcpExtensions.ts‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -99,11 +99,17 @@ export async function legacySetSessionModel(
9999
export type SessionSteerRequest = {
100100
sessionId: SessionId;
101101
prompt: ContentBlock[];
102+
_meta?: {
103+
steering?: {
104+
/** Leave idle input unconsumed so the host can own a normal prompt lifecycle. */
105+
idleBehavior?: "promptRequired";
106+
};
107+
};
102108
}
103109

104-
export type SessionSteeringResponse = {
105-
outcome: "injected" | "startedNewTurn" | "failed";
106-
}
110+
export type SessionSteeringResponse =
111+
| {outcome: "injected" | "startedNewTurn" | "failed"}
112+
| {outcome: "promptRequired", reason: "noRunningTurn"}
107113

108114
export type SessionSteeringExtRequest = {
109115
method: typeof SESSION_STEERING_METHOD;

‎src/CodexAcpServer.ts‎

Lines changed: 27 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@ import * as acp from "@agentclientprotocol/sdk";
22
import {RequestError, type SessionId, type SessionModeState} from "@agentclientprotocol/sdk";
33
import {CodexEventHandler, type CompletedPlan} from "./CodexEventHandler";
44
import {CodexApprovalHandler} from "./permissions/CodexApprovalHandler";
5+
import {isRecord} from "./permissions/json";
56
import {PermissionLifecycleContext} from "./permissions/lifecycle";
67
import {
78
planImplementationApproved,
@@ -1195,8 +1196,9 @@ export class CodexAcpServer {
11951196
* check guards against deleting a queue a later request has since reused).
11961197
*
11971198
* @param params The target session id and the prompt to steer with.
1198-
* @returns Whether the prompt joined the active turn ("injected"), started a
1199-
* new one ("startedNewTurn"), or could not be applied ("failed"); see
1199+
* @returns Whether the prompt joined the active turn ("injected"), needs a
1200+
* host-owned prompt ("promptRequired"), started a new one
1201+
* ("startedNewTurn"), or could not be applied ("failed"); see
12001202
* {@link performSteeringRequest}.
12011203
*/
12021204
async executeOrQueueSteeringRequest(params: SessionSteerRequest): Promise<SessionSteeringResponse> {
@@ -1234,11 +1236,13 @@ export class CodexAcpServer {
12341236

12351237
/**
12361238
* Delivers a steering prompt to the session: injects it into the live turn
1237-
* when there is one, otherwise starts a new turn.
1239+
* when there is one. On an idle race, an opted-in host keeps ownership of
1240+
* the content; legacy clients retain the adapter-started turn behavior.
12381241
*
12391242
* @param params The target session id and the prompt to steer with.
1240-
* @returns "injected" when the prompt joined an existing turn, otherwise the
1241-
* outcome of starting a new turn.
1243+
* @returns "injected" when the prompt joined an existing turn,
1244+
* "promptRequired" when the host requested an owned idle fallback, or
1245+
* the outcome of starting a legacy fallback turn.
12421246
*/
12431247
private async performSteeringRequest(params: SessionSteerRequest): Promise<SessionSteeringResponse> {
12441248
logger.log("Steering session requested", {
@@ -1256,6 +1260,9 @@ export class CodexAcpServer {
12561260
return {outcome: "injected"};
12571261
}
12581262
}
1263+
if (params._meta?.steering?.idleBehavior === "promptRequired") {
1264+
return {outcome: "promptRequired", reason: "noRunningTurn"};
1265+
}
12591266
return await this.startNewTurnFromSteering(params);
12601267
}
12611268

@@ -1436,9 +1443,24 @@ export class CodexAcpServer {
14361443
if (typeof sessionId !== "string" || !Array.isArray(prompt)) {
14371444
throw RequestError.invalidParams();
14381445
}
1446+
const meta = params["_meta"];
1447+
if (meta !== undefined && !isRecord(meta)) {
1448+
throw RequestError.invalidParams(undefined, "steering _meta must be an object");
1449+
}
1450+
const steering = meta?.["steering"];
1451+
if (steering !== undefined && !isRecord(steering)) {
1452+
throw RequestError.invalidParams(undefined, "steering _meta.steering must be an object");
1453+
}
1454+
const idleBehavior = steering?.["idleBehavior"];
1455+
if (idleBehavior !== undefined && idleBehavior !== "promptRequired") {
1456+
throw RequestError.invalidParams(undefined, "unsupported steering idleBehavior");
1457+
}
14391458
return {
14401459
sessionId: sessionId,
14411460
prompt: prompt as acp.ContentBlock[],
1461+
...(idleBehavior === "promptRequired" ? {
1462+
_meta: {steering: {idleBehavior}},
1463+
} : {}),
14421464
};
14431465
}
14441466

‎src/__tests__/CodexACPAgent/steer-events.test.ts‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -109,6 +109,23 @@ describe('_session/steering', () => {
109109
});
110110
});
111111

112+
it('leaves idle input unconsumed when the host requests an owned prompt fallback', async () => {
113+
const mockFixture = createCodexMockTestFixture();
114+
const sessionState = createTestSessionState();
115+
vi.spyOn(mockFixture.getCodexAcpAgent(), "getSessionState").mockReturnValue(sessionState);
116+
const turnStartSpy = vi.spyOn(mockFixture.getCodexAppServerClient(), "turnStart");
117+
const turnSteerSpy = vi.spyOn(mockFixture.getCodexAppServerClient(), "turnSteer");
118+
119+
await expect(mockFixture.getCodexAcpAgent().extMethod(SESSION_STEERING_METHOD, {
120+
sessionId: "session-id",
121+
prompt: [{type: "text", text: "host-owned follow-up"}],
122+
_meta: {steering: {idleBehavior: "promptRequired"}},
123+
})).resolves.toEqual({outcome: "promptRequired", reason: "noRunningTurn"});
124+
125+
expect(turnStartSpy).not.toHaveBeenCalled();
126+
expect(turnSteerSpy).not.toHaveBeenCalled();
127+
});
128+
112129
it('starts a new turn when Codex reports that the tracked turn is no longer active', async () => {
113130
const {mockFixture, sessionState, turnCompleted} = startActiveTurn();
114131
const nextTurnCompleted = deferred<TurnCompletedNotification>();
@@ -152,6 +169,38 @@ describe('_session/steering', () => {
152169
});
153170
});
154171

172+
it('returns the host-owned fallback when the tracked turn wins the idle race', async () => {
173+
const {mockFixture, sessionState, turnCompleted} = startActiveTurn();
174+
const turnStartSpy = vi.spyOn(mockFixture.getCodexAppServerClient(), "turnStart");
175+
vi.spyOn(mockFixture.getCodexAppServerClient(), "turnSteer").mockImplementation(async () => {
176+
turnCompleted.resolve({
177+
threadId: "session-id",
178+
turn: createTurn("turn-id", "completed"),
179+
});
180+
throw Object.assign(new Error("Internal error"), {
181+
data: {details: "no active turn to steer"},
182+
});
183+
});
184+
185+
const promptPromise = mockFixture.getCodexAcpAgent().prompt({
186+
sessionId: "session-id",
187+
prompt: [{type: "text", text: "long running prompt"}],
188+
});
189+
await vi.waitFor(() => {
190+
expect(sessionState.currentTurnId).toBe("turn-id");
191+
});
192+
193+
await expect(mockFixture.getCodexAcpAgent().extMethod(SESSION_STEERING_METHOD, {
194+
sessionId: "session-id",
195+
prompt: [{type: "text", text: "racing follow-up"}],
196+
_meta: {steering: {idleBehavior: "promptRequired"}},
197+
})).resolves.toEqual({outcome: "promptRequired", reason: "noRunningTurn"});
198+
199+
await expect(promptPromise).resolves.toMatchObject({stopReason: "end_turn"});
200+
expect(turnStartSpy).toHaveBeenCalledTimes(1);
201+
expect(sessionState.currentTurnId).toBeNull();
202+
});
203+
155204
it('serializes concurrent late steering requests without dropping either prompt', async () => {
156205
const mockFixture = createCodexMockTestFixture();
157206
const sessionState = createTestSessionState();
@@ -212,6 +261,16 @@ describe('_session/steering', () => {
212261
})).rejects.toThrow(RequestError);
213262
});
214263

264+
it('rejects an unsupported idle behavior', async () => {
265+
const mockFixture = createCodexMockTestFixture();
266+
267+
await expect(mockFixture.getCodexAcpAgent().extMethod(SESSION_STEERING_METHOD, {
268+
sessionId: "session-id",
269+
prompt: [{type: "text", text: "follow-up"}],
270+
_meta: {steering: {idleBehavior: "startDetachedTurn"}},
271+
})).rejects.toThrow("unsupported steering idleBehavior");
272+
});
273+
215274
it('rejects image input when the model does not support it', async () => {
216275
const {mockFixture} = startActiveTurn({supportedInputModalities: ["text"]});
217276
const turnSteerSpy = vi.spyOn(mockFixture.getCodexAppServerClient(), "turnSteer");

‎src/__tests__/SteeringQueue.test.ts‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -58,7 +58,11 @@ describe("SteeringQueue", () => {
5858
});
5959

6060
it("delivers each handler result to its own caller", async () => {
61-
const outcomes: SessionSteeringResponse["outcome"][] = ["injected", "startedNewTurn", "injected"];
61+
const outcomes: Array<Exclude<SessionSteeringResponse["outcome"], "promptRequired">> = [
62+
"injected",
63+
"startedNewTurn",
64+
"injected",
65+
];
6266
let call = 0;
6367
const queue = new SteeringQueue(async () => ({outcome: outcomes[call++]!}));
6468

0 commit comments

Comments
 (0)