Skip to content

Commit cc57c7e

Browse files
authored
feat: show async Codex questions as elicitations (#707)
## Problem Codex's `request_user_input_async` tool asks questions without waiting: it emits an `agentMessage` with `delivery: "async"` and `questions`, and the turn continues. The adapter dropped these messages, so Air showed nothing and the agent went on with its defaults (IJAI-4999). ## Fix - Show agent messages that arrive whole, without deltas, so the question text appears live. - Send async questions as a non-blocking form elicitation. On ACP v2 the session state stays `running` while the form is open. - Steer an accepted answer into the turn that asked, in the reply envelope Codex clients use. Declining or cancelling sends nothing. - Cancel open elicitations with `$/cancel_request` when their turn ends, the session closes or the app-server is lost. - Drop an answer that arrives after its turn ended, as the Codex TUI does, and send a warning notice where the client supports notices. - On replay, show a stored answer as the quoted question followed by the answer, instead of the raw envelope. Behaviour is documented in `docs/async-questions.md`. Tests cover ACP v1 and v2.
1 parent 34e0897 commit cc57c7e

22 files changed

Lines changed: 1097 additions & 130 deletions

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ Use [OpenAI Codex](https://github.com/openai/codex) from [Agent Client Protocol]
1717
- For AIR, one tool call shape with each fact in one field, as the [tool call contract](docs/air-extensions.md#tool-call-contract) defines. Other clients keep the earlier fields.
1818
- [Native ACP subagent sessions](docs/subagent-sessions.md) (after capability negotiation) with separate child histories and root-routed permissions; a legacy tool-call fallback otherwise.
1919
- Mid-turn input through the [_session/steering extension](docs/steering.md), with an opt-in host-owned fallback when no turn can accept it.
20+
- [Async Codex questions](docs/async-questions.md) as non-blocking form elicitations, with answers steered into the turn that asked them.
2021
- [Background terminal tasks](docs/air-extensions.md#async-tasks) in AIR, with task status and targeted stop support after capability negotiation.
2122
- Session-scoped long-running goals in AIR through the [goal extension](docs/air-extensions.md#goal).
2223
- Typed warnings and errors through the opt-in [AIR session failure extension](docs/air-extensions.md#session-failure).

‎docs/async-questions.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# Async questions
2+
3+
Codex's `request_user_input_async` tool lets the agent ask the user questions without waiting for
4+
an answer. Unlike the blocking `request_user_input` of Plan mode, it is not an app-server request:
5+
Codex emits an `agentMessage` item with `delivery: "async"` and `questions`, tells the model that
6+
the questions were accepted, and the turn goes on.
7+
8+
## What the client sees
9+
10+
- The message text (the questions and their options) is sent as an ordinary agent message.
11+
- If the client supports form elicitation, the adapter also sends a session-scoped
12+
`elicitation/create` with one field per question. A question with options offers them, plus an
13+
own answer the way Plan mode questions do. Fields are optional, since each question can be
14+
answered on its own. The request carries `_meta.codex.delivery: "async"`.
15+
- The adapter does not wait for the elicitation. On ACP v2 it does not count as a user action, so
16+
the session state stays `running` while the form is open.
17+
18+
## Answers
19+
20+
- An accepted answer is steered into the turn that asked the question (`turn/steer` with that
21+
turn as `expectedTurnId`). It is not echoed as a live user message.
22+
- Declining or cancelling sends nothing; the agent keeps its own default.
23+
- When the turn ends, its open elicitations are cancelled with `$/cancel_request`. The same happens
24+
when the session closes or its app-server is lost.
25+
- An answer that arrives after its turn ended is dropped, as in the Codex TUI. This includes an
26+
answer to a cancelled elicitation, and one that Codex rejects because a new turn has started. The
27+
adapter then sends a `warning` notice, where the client supports notices.
28+
29+
## Reply format and replay
30+
31+
Answers use the envelope that the Codex TUI and desktop app send, so Codex reads them the same way:
32+
33+
```
34+
<send_user_message_question_reply>
35+
[{"answer":"Staging","question":"Which environment?","questionItemId":"[\"request_user_input_async\",\"call_1\",0]"}]
36+
</send_user_message_question_reply>
37+
```
38+
39+
Codex stores this text as an ordinary user message. On `session/load` and `session/resume`, a user
40+
message that is exactly one such envelope is replayed as each question in a quote followed by its
41+
answer:
42+
43+
```
44+
> Which environment?
45+
46+
Staging
47+
```
48+
49+
The format follows Codex's `codex-rs/context-fragments/src/answered_question.rs`, and its parsing
50+
follows `codex-rs/tui/src/async_question_reply.rs`.

‎src/ACPSessionConnection.ts‎

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -138,11 +138,23 @@ export class AcpV2Connection {
138138
}, options?.cancellationSignal);
139139
}
140140

141-
/** Request-scoped login elicitations and idle background elicitations never change state. */
141+
/**
142+
* Sends `elicitation/create`. Request-scoped login elicitations and idle background elicitations never change
143+
* the session state.
144+
*
145+
* @param request The elicitation to show.
146+
* @param options Request options, such as the signal that cancels the request.
147+
* @param interaction.userAction Whether the agent waits for the answer, `true` by default. While such an
148+
* elicitation is open in a running turn, the session reports `requires_action` whenever none of its items
149+
* is in progress. Pass `false` for a question the agent keeps working through, so the session state is left
150+
* as it is.
151+
*/
142152
async createElicitation(
143153
request: acp.CreateElicitationRequest,
144154
options?: acp.SendRequestOptions,
155+
interaction: {userAction?: boolean} = {},
145156
): Promise<acp.CreateElicitationResponse> {
157+
const userAction = interaction.userAction ?? true;
146158
const sendRequest = async () => {
147159
const response = await this.client.request(
148160
acpV2.methods.client.elicitation.create,
@@ -152,7 +164,7 @@ export class AcpV2Connection {
152164
return toV1CreateElicitationResponse(response);
153165
};
154166
const sessionId = elicitationSessionId(request);
155-
if (sessionId === undefined) {
167+
if (sessionId === undefined || !userAction) {
156168
return sendRequest();
157169
}
158170
const toolCallId = "toolCallId" in request && typeof request.toolCallId === "string" ? request.toolCallId : undefined;

‎src/CodexAcpServer.ts‎

Lines changed: 26 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -158,6 +158,7 @@ import {
158158
import packageJson from "../package.json";
159159
import {isJetBrains2026_1Client} from "./JBUtils";
160160
import {clientSupportsNotices} from "./SessionNotice";
161+
import {AsyncQuestionClient, AsyncQuestionElicitations, renderAsyncQuestionReply} from "./CodexAsyncQuestions";
161162
import {
162163
createAgentTextMessageChunk,
163164
createAgentTextThoughtChunk,
@@ -524,6 +525,8 @@ export class CodexAcpServer {
524525
/** Tail of the per-session turn-start FIFO; see `acquireTurnStartReservation`. */
525526
private readonly turnStartQueueTail: Map<string, {promise: Promise<void>; settled: boolean}>;
526527
private readonly steeringQueues: Map<string, SteeringQueue>;
528+
/** The async questions of each session, shown while the turn that asked them runs. */
529+
private readonly asyncQuestions = new Map<string, AsyncQuestionElicitations>();
527530
/**
528531
* Steers awaiting their `userMessage` landing, keyed by the minted `clientUserMessageId`
529532
* passed to `turn/steer`. Used only to show a v2 live `user_message` when a steer injected
@@ -2025,6 +2028,8 @@ export class CodexAcpServer {
20252028
} finally {
20262029
if (this.getSessionGeneration(params.sessionId) === closeGeneration) {
20272030
this.sessions.delete(params.sessionId);
2031+
this.asyncQuestions.get(params.sessionId)?.dispose();
2032+
this.asyncQuestions.delete(params.sessionId);
20282033
if (!this.v2PromptsInFlight.has(params.sessionId)) {
20292034
AcpV2Connection.of(this.connection)?.forgetSession(params.sessionId);
20302035
}
@@ -4067,9 +4072,12 @@ export class CodexAcpServer {
40674072

40684073
private userInputToContentBlocks(input: UserInput): acp.ContentBlock[] {
40694074
switch (input.type) {
4070-
case "text":
4075+
case "text": {
4076+
const asyncQuestionReply = renderAsyncQuestionReply(input.text);
4077+
if (asyncQuestionReply !== null) return [{type: "text", text: asyncQuestionReply}];
40714078
return desktopAttachmentHistory(input.text)
40724079
?? (input.text.length > 0 ? [{ type: "text", text: input.text }] : []);
4080+
}
40734081
case "image":
40744082
return [{
40754083
type: "text",
@@ -4898,13 +4906,16 @@ export class CodexAcpServer {
48984906
await observeInteraction(event);
48994907
if (!promptNotificationsActive) {
49004908
await promptEventHandler.handleSessionScopedNotification(event);
4909+
this.asyncQuestionsFor(sessionState).handleNotification(event);
49014910
await this.trackCodexTurnCompletion(sessionState, event, promptEventHandler);
49024911
return;
49034912
}
49044913
const completesActiveTurn = event.method === "turn/completed"
49054914
&& event.params.threadId === sessionState.sessionId
49064915
&& event.params.turn.id === sessionState.currentTurnId;
49074916
await promptEventHandler.handleNotification(event);
4917+
// After the question text is shown.
4918+
this.asyncQuestionsFor(sessionState).handleNotification(event);
49084919
if (completesActiveTurn) {
49094920
// The prompt may remain open for plan approval after its turn has ended. Switch at
49104921
// the causal boundary so a queued late error cannot enter the completed turn's buffer.
@@ -5420,6 +5431,19 @@ export class CodexAcpServer {
54205431
throw this.recovery.errorForGeneration(generation);
54215432
}
54225433

5434+
/** The async questions of a session, created on first use. */
5435+
private asyncQuestionsFor(sessionState: SessionState): AsyncQuestionElicitations {
5436+
const sessionId = sessionState.sessionId;
5437+
let questions = this.asyncQuestions.get(sessionId);
5438+
if (questions === undefined) {
5439+
questions = new AsyncQuestionElicitations(sessionId, this.clientCapabilities, new AsyncQuestionClient(
5440+
sessionId, this.connection, this.clientCapabilities, () => this.codexAcpClient,
5441+
));
5442+
this.asyncQuestions.set(sessionId, questions);
5443+
}
5444+
return questions;
5445+
}
5446+
54235447
/**
54245448
* Ends what a prompt showed as running when its app-server died: open tool calls of the session and of its native
54255449
* subagent sessions, the subagent sessions themselves and compactions. Nothing will ever complete them.
@@ -5432,6 +5456,7 @@ export class CodexAcpServer {
54325456
state: "failed" | "cancelled",
54335457
): Promise<void> {
54345458
try {
5459+
this.asyncQuestions.get(sessionState.sessionId)?.dispose();
54355460
await elicitations?.completeAllUrlElicitations();
54365461
const sessionIds = new Set([sessionState.sessionId, ...sessionState.subagents.childSessionIds()]);
54375462
await this.failUnfinishedToolCalls(sessionIds);

0 commit comments

Comments
 (0)