Skip to content

Commit 5edc599

Browse files
committed
fix(opencode): bridge question tool to ACP elicitation
The question tool blocked indefinitely in ACP mode because the event handler was never wired up. question.asked events carry a QuestionV2 request ID that must be used for reply/reject — the tool call ID from message.part.updated is different and using it never unblocked the waiting Deferred. Fix: listen for question.asked and question.v2.asked events in the event subscription and forward them to a new ACPElicitation.Handler. The handler calls unstable_createElicitation when the client advertises elicitation support, and falls back to auto-reject otherwise. Fixes anomalyco#38121
1 parent 37fe5c8 commit 5edc599

6 files changed

Lines changed: 1154 additions & 2 deletions

File tree

Lines changed: 299 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,299 @@
1+
# ACP Elicitation for Questions
2+
3+
## Problem
4+
5+
The `question` tool can block indefinitely when opencode is used through ACP. The registered opencode tool currently uses the legacy question service and publishes `question.asked`; the core V2 question service publishes the equivalent `question.v2.asked` event. In both cases the tool creates a pending question request and then waits for the matching reply or reject.
6+
7+
ACP has the matching protocol concept: the agent can call `elicitation/create` on the client and wait for an accept, decline, or cancel response. The ACP adapter should bridge opencode's `QuestionV2` event to ACP elicitation and then settle the original question request.
8+
9+
## Current Shape
10+
11+
The core question path is:
12+
13+
```text
14+
LLM tool call
15+
-> question tool execute
16+
-> QuestionV2.ask(...)
17+
-> publish question.asked or question.v2.asked
18+
-> wait for reply/reject
19+
```
20+
21+
The app and desktop clients handle this by consuming question events, adapting V2 events to the existing app state shape when needed, rendering `SessionQuestionDock`, then calling the question HTTP API with the real request ID.
22+
23+
ACP already does a similar bridge for permissions:
24+
25+
```text
26+
permission.asked
27+
-> connection.requestPermission(...)
28+
-> sdk.permission.reply(...)
29+
```
30+
31+
Questions should follow the same pattern:
32+
33+
```text
34+
question.asked / question.v2.asked
35+
-> connection.unstable_createElicitation(...)
36+
-> sdk.question.reply(...) or sdk.question.reject(...)
37+
```
38+
39+
## Design
40+
41+
`packages/opencode/src/acp/event.ts` should treat `question.asked` as the current source of truth for ACP elicitation and should also handle `question.v2.asked` defensively for the core V2 path.
42+
43+
Do not derive elicitation from `message.part.updated` question tool parts. Tool parts describe projected transcript state; they do not carry the `QuestionV2` request ID needed to unblock the pending question. A tool part's `callID` is the model/tool call ID, not the question request ID.
44+
45+
The event contains both identities needed by the bridge:
46+
47+
- `event.properties.id`: the real question request ID. Use this for `sdk.question.reply` and `sdk.question.reject`.
48+
- `event.properties.tool?.callID`: the originating tool call ID. Use this as ACP `toolCallId` when present.
49+
50+
The ACP event subscription should add handlers for both `question.asked` and `question.v2.asked`:
51+
52+
```text
53+
on question.asked or question.v2.asked:
54+
find ACP session by event.properties.sessionID
55+
if session is unknown:
56+
return
57+
58+
if the client did not advertise elicitation support:
59+
reject event.properties.id
60+
return
61+
62+
if connection.unstable_createElicitation is unavailable:
63+
reject event.properties.id
64+
return
65+
66+
call unstable_createElicitation({
67+
mode: "form",
68+
sessionId: event.properties.sessionID,
69+
toolCallId: event.properties.tool?.callID,
70+
message,
71+
requestedSchema,
72+
})
73+
74+
if response.action is "accept":
75+
convert response.content to QuestionV2 answers
76+
reply event.properties.id
77+
return
78+
79+
reject event.properties.id
80+
```
81+
82+
`initialize` should record whether the ACP client advertised elicitation support. The bridge should not infer support only from method presence because the ACP SDK type may expose optional methods that a client did not negotiate.
83+
84+
## Schema Mapping
85+
86+
Each `QuestionV2.Info` should become one property in the ACP form schema.
87+
88+
Single-select question:
89+
90+
```text
91+
type: "string"
92+
title: question.header
93+
description: question.question
94+
enum: question.options[].label
95+
```
96+
97+
Multi-select question:
98+
99+
```text
100+
type: "array"
101+
title: question.header
102+
description: question.question
103+
items.anyOf: question.options[].label as const/title entries
104+
```
105+
106+
Use `question.header` as the property key because it is the short user-facing label already used by the question tool. Duplicate headers are ambiguous; the first implementation may preserve current behavior, but production code should either disambiguate duplicate keys or reject the elicitation safely.
107+
108+
On accept, convert ACP response content back into `QuestionV2.Reply.answers` in the original question order:
109+
110+
- string value -> single selected label
111+
- array value -> selected labels
112+
- missing or empty value -> empty answer array
113+
114+
## Capability Behavior
115+
116+
If a client does not advertise `clientCapabilities.elicitation`, opencode should not leave the tool blocked.
117+
118+
The conservative behavior is to reject the pending question request. This matches the existing issue goal: clients that cannot answer questions should not hang the session. A rejection becomes a `QuestionV2.RejectedError`, which the runner can treat as a declined user interaction.
119+
120+
## Event Ordering
121+
122+
`question.asked` and `question.v2.asked` are emitted before the corresponding question service waits on its Deferred. The question event is the earliest reliable point where ACP can ask the user and settle the request.
123+
124+
`message.part.updated` may arrive before, after, or not in time for this bridge depending on projection and stream timing. It is still useful for ACP `session_update` tool-call display, but it should not own question elicitation.
125+
126+
## Implementation Plan
127+
128+
### Production Code Changes
129+
130+
`packages/opencode/src/acp/elicitation.ts`
131+
132+
- Replace the current `QuestionToolPart` input type with a question request input type:
133+
134+
```ts
135+
type QuestionRequest = {
136+
readonly id: string
137+
readonly sessionID: string
138+
readonly questions: ReadonlyArray<QuestionInfo>
139+
readonly tool?: { readonly messageID: string; readonly callID: string }
140+
}
141+
```
142+
143+
- `Handler.handle(...)` should accept this question request shape, not a `ToolPart`.
144+
- `Handler.process(...)` should:
145+
- look up the ACP session by `request.sessionID`
146+
- return without action if the session is unknown
147+
- reject `request.id` if the request has no questions
148+
- reject `request.id` if elicitation is unsupported or unavailable
149+
- call `unstable_createElicitation(buildRequest(request))` when supported
150+
- reply `request.id` on `accept`
151+
- reject `request.id` on `decline`, `cancel`, missing response, or client call failure
152+
- `buildRequest(...)` should set:
153+
- `sessionId: request.sessionID`
154+
- `toolCallId: request.tool?.callID`
155+
- `requestedSchema` from `request.questions`
156+
- Remove every use of `part.callID` as a question request ID.
157+
158+
`packages/opencode/src/acp/event.ts`
159+
160+
- Add `question.asked` and `question.v2.asked` to the event switch in `Subscription.handle(...)`.
161+
- Route that event to `this.elicitation.handle(event.properties)`.
162+
- Do not invoke `this.elicitation.handle(...)` from the `message.part.updated` / `handleToolPart(...)` path.
163+
- Keep existing `toolStart(...)`, `runningTool(...)`, completed, and error updates for tool display. The question tool can still appear in ACP `session_update`; it just must not own the elicitation/reply flow.
164+
- Keep `enableElicitation()` as the capability toggle if the implementation keeps negotiation state inside `ACPElicitation.Handler`.
165+
166+
`packages/opencode/src/acp/service.ts`
167+
168+
- Keep the `initialize(...)` capability hook, but remove debug logging.
169+
- On initialize, call `events?.enableElicitation()` only when `params.clientCapabilities?.elicitation` is present.
170+
- Do not advertise or enable the question tool from ACP initialization as part of this bridge. Tool availability should remain controlled by the existing registry logic and tests should opt in explicitly when needed.
171+
172+
### Cleanup Required Before Fixing Behavior
173+
174+
Remove all temporary debug code from production files:
175+
176+
- `packages/opencode/src/acp/elicitation.ts`
177+
- remove dynamic `import("fs")`
178+
- remove `/tmp/acp-debug.log` writes
179+
- `packages/opencode/src/acp/event.ts`
180+
- remove dynamic `import("fs")`
181+
- remove `/tmp/acp-debug.log` writes in `handle(...)` and `handleToolPart(...)`
182+
- `packages/opencode/src/acp/service.ts`
183+
- remove dynamic `import("fs")`
184+
- remove `/tmp/acp-debug.log` writes in `initialize(...)`
185+
- Delete the ad hoc debug entrypoint:
186+
- `packages/opencode/debug_acp.ts`
187+
188+
Do this before evaluating test results. The debug writes can hide timing problems, leave noisy side effects, and should not ship.
189+
190+
### Hanging Prevention Rules
191+
192+
Every code path that observes a `question.asked` or `question.v2.asked` event for a known ACP session must eventually settle the pending question unless the process is interrupted.
193+
194+
The handler must call exactly one of:
195+
196+
```ts
197+
sdk.question.reply({ requestID: request.id, directory: session.cwd, answers })
198+
sdk.question.reject({ requestID: request.id, directory: session.cwd })
199+
```
200+
201+
for these cases:
202+
203+
- client does not advertise elicitation support: reject
204+
- `connection.unstable_createElicitation` is missing: reject
205+
- question request contains no questions: reject
206+
- `unstable_createElicitation(...)` throws/rejects: reject
207+
- client returns `{ action: "accept" }`: reply
208+
- client returns `{ action: "decline" }`: reject
209+
- client returns `{ action: "cancel" }`: reject
210+
- client returns no response or an invalid response: reject
211+
212+
The handler should catch reply/reject failures so ACP event processing does not crash, but tests should make those failures visible through assertions where possible.
213+
214+
Do not use `tool.callID` or `part.callID` for `sdk.question.reply(...)` or `sdk.question.reject(...)`. That is the hanging bug. The only valid unblock ID is the question request ID from the question event.
215+
216+
### Testing Changes
217+
218+
`packages/opencode/test/acp/elicitation.test.ts`
219+
220+
- Change the tests to emit `question.asked`, not synthetic `message.part.updated` tool parts.
221+
- Test data must use different IDs:
222+
223+
```text
224+
question request id: que_test
225+
tool call id: call_test
226+
```
227+
228+
- Assertions must verify:
229+
- `unstable_createElicitation(...)` receives `toolCallId: "call_test"`
230+
- `sdk.question.reply(...)` receives `requestID: "que_test"`
231+
- `sdk.question.reject(...)` receives `requestID: "que_test"`
232+
- Keep coverage for:
233+
- accept maps answers and replies
234+
- decline rejects
235+
- cancel rejects
236+
- unsupported client auto-rejects
237+
- `unstable_createElicitation` failure rejects
238+
- multiple questions
239+
- multi-select questions
240+
- unknown ACP session does not call elicitation or reply/reject
241+
- Add a regression test that would fail if `tool.callID` is used as `requestID`.
242+
243+
`packages/opencode/test/cli/acp/elicitation.test.ts`
244+
245+
- Keep this as subprocess coverage, but make the test harness fail faster.
246+
- The test must explicitly enable the question tool for ACP. Normal ACP does not expose the question tool because `OPENCODE_CLIENT=acp`; the registry only includes it when `enableQuestionTool` is true.
247+
- Add one happy-path test:
248+
- initialize with `clientCapabilities.elicitation`
249+
- create a session
250+
- model calls `question`
251+
- test client receives `elicitation/create`
252+
- test client returns `accept`
253+
- `session/prompt` returns `stopReason: "end_turn"`
254+
- Add one unsupported-client test:
255+
- initialize without elicitation support
256+
- model calls `question`
257+
- no `elicitation/create` is observed
258+
- `session/prompt` still returns instead of timing out
259+
- Add one decline test if runtime cost is acceptable:
260+
- client returns `decline`
261+
- prompt returns instead of timing out
262+
- The per-test infrastructure timeout can remain high, but the harness should include shorter intent-specific waits. For example, after the model emits the question tool, fail within a few seconds if the expected `elicitation/create` request is not observed.
263+
- The JSON-RPC driver must keep serving inbound requests while `session/prompt` is pending. Do not use a receive loop that can be monopolized by the outbound prompt response wait.
264+
265+
### Expected Diff Shape
266+
267+
The final implementation should primarily touch:
268+
269+
- `packages/opencode/src/acp/elicitation.ts`
270+
- `packages/opencode/src/acp/event.ts`
271+
- `packages/opencode/src/acp/service.ts`
272+
- `packages/opencode/test/acp/elicitation.test.ts`
273+
- `packages/opencode/test/cli/acp/elicitation.test.ts`
274+
275+
It should delete:
276+
277+
- `packages/opencode/debug_acp.ts`
278+
279+
It should not require changes to:
280+
281+
- `packages/core/src/question.ts`
282+
- `packages/core/src/tool/question.ts`
283+
- `packages/opencode/src/tool/registry.ts`
284+
- generated SDK files
285+
- Protocol or Server `HttpApi`
286+
287+
## Non-Goals
288+
289+
Do not teach ACP clients to call opencode's HTTP question API directly. That leaks opencode-specific control flow through the ACP boundary.
290+
291+
Do not use a plugin to bridge question events to ACP. The ACP adapter already has the connection and the opencode SDK; this belongs in the adapter.
292+
293+
Do not make `message.part.updated` the source of truth for replying to questions. It does not contain the request ID that `QuestionV2` requires.
294+
295+
## Open Questions
296+
297+
- Should duplicate question headers be rejected, disambiguated, or encoded under generated stable keys?
298+
- Should ACP advertise an agent capability for elicitation support in `initialize`, or is client capability negotiation sufficient for now?
299+
- Should the question tool remain disabled by default for ACP and only be enabled when the client advertises elicitation support, or should existing `enableQuestionTool` remain the only override?

0 commit comments

Comments
 (0)