Repository navigation
[FEATURE]: V2 session.command invocation identity and result correlation #49690
Description
Feature hasn't been suggested before.
- I have verified this feature I'm about to request hasn't been suggested before.
Describe the enhancement you want to request
Please expose a stable invocation identity and result correlation for V2 session.command, or document an existing supported way to obtain them.
While adding V2 support to an MCP bridge, I found that @opencode/client@2.0.6 accepts sessionID, name, text, attachments and delivery, but no caller-assigned ID. Its result is void; the HTTP endpoint returns 204. The current V2 branch still has this contract:
This makes it difficult for an external client to associate a command with inputs it admits and their eventual output/error. For example, if a command enqueues a prompt while another client submits work to the same session, selecting the latest message or waiting for session inactivity cannot reliably identify the command's result. A lost HTTP response also leaves the caller without an invocation handle to inspect.
The desired contract would provide:
- A caller-assigned invocation ID, or another recoverable identity.
- A receipt linking the invocation to any admitted input IDs, plus documented status/log correlation.
- Explicit semantics for callback completion versus completion of admitted agent work, including commands that admit no input.
session.prompt already accepts an ID and returns an inbox receipt. An equivalent correlation path for commands would let bridges observe results without guessing or replaying uncertain mutations.
This is a contract inspection and integration requirement, not a claim that command execution itself is broken or that a live concurrency race was reproduced. Related: the completed implementation in #34429 / #34849; this request concerns its externally observable invocation/result identity.
Activity
AlaeddineMessadi commentedon Oct 18, 2026
Follow-up: I checked the published
@opencode/client@2.0.32package, andSessionCommandInputstill has no caller-assigned invocation ID whileSessionCommandOutputremainsvoid. The invocation/result correlation described above is therefore still missing from that published contract.Our draft MCP bridge PR is here: AlaeddineMessadi/opencode-mcp#29
For now, we explicitly reject V2
opencode_command_executebefore dispatch rather than infer completion from session inactivity or risk attributing another client's output to the command. Other supported V2 operations can proceed independently.Is there an existing supported mechanism for recovering command invocation identity and correlating admitted inputs with their eventual results that we have missed?
opencodejr commentedon Oct 28, 2026
Thanks for the detailed write-up, @AlaeddineMessadi!
You're asking for V2
session.commandto accept a caller-assigned invocation ID (or another recoverable identity) and return a receipt linking that invocation to any inputs it admits. You'd also like documented semantics for when a command counts as complete. That would let external clients match commands to their results the same waysession.promptalready allows with itsidand inbox receipt.The current
devbranch matches what you describe: the endpoint takesname, the prompt fields and an optionaldelivery, and returns 204 with no body. Maintainers will consider this request.Related: #34429 / #34849 (the original command implementation).
AlaeddineMessadi commentedon Oct 29, 2026
Following up after 2.2.0: the
session.commandcontract is unchanged. It still returns 204 with no invocation id and nothing linking the call to the inputs the command admits, so clients still can't match a command to its result. Is a design planned for this? For example, it could accept a caller-suppliedidthe waysession.promptdoes, or return receipts for the inputs it admits to the inbox. Happy to test a draft.