Repository navigation
[Question] OpenCode V2 server API 兼容性与支持计划 #550
Description
背景与使用需求
想用标准 A2A 客户端访问 OpenCode，并复用其会话能力。当前本地安装的是 OpenCode v2.0.28，因此想先确认本项目对 OpenCode V2 的兼容性与支持计划。
这是一个讨论 / 兼容性咨询，不是已复现的 bug 报告：尚未运行本适配器对接 v2.0.28 的端到端测试。仓库未启用 GitHub Discussions，因此在这里提问。
静态阅读中看到的情况
在当前源码快照 5d4700204445ce658361010cbda2fd344bc60dec 中，上游客户端仍调用：
POST /session（L454–473）POST /session/{session_id}/message，使用parts请求体（L831–867）GET /event（L413–428）
而 OpenCode V2 的迁移文档说明 server API 已发生不兼容变更；V2 API 使用 /api/session、/api/event 及 /api/session/{sessionID}/prompt 等接口，因此看起来不仅是 base URL 的调整。
也看到了 #538，但理解其 “V2 lifecycle migration” 指的是 a2a-sdk 的 handler / task store 生命周期，并非 OpenCode V2 server API 的迁移。如有理解错误，欢迎纠正。
想请教的问题
- 当前支持或实际验证的 OpenCode server 版本范围是什么？OpenCode V2 是否已有可用的分支、PR 或兼容方式？
- 是否计划适配 OpenCode V2？如果已有相关 issue / roadmap，能否指一下入口？
- 如果尚未计划，是否愿意接受 V2 适配贡献？更倾向于 V1/V2 双栈兼容，还是在新的版本线切换到 V2？
- 能否在 README / compatibility 文档明确列出测试过的 OpenCode 版本，并区分 OpenCode V2 与 a2a-sdk V2？这样能帮助使用者在部署前判断是否适配。
范围与边界
关注的是 OpenCode 上游 API 的兼容性及版本说明，不是修改标准 A2A core，也不是新增 OpenCode 私有管理功能。暂不假定具体实施方案或要求交付时间。
已搜索相关 issues / PR，未找到明确跟踪 OpenCode V2 server API 支持的讨论；若有遗漏，请关联已有条目即可。谢谢！
English version
Background and use case
I would like to access OpenCode through a standard A2A client and reuse its session capabilities. My local installation is OpenCode v2.0.28, so I would like to clarify this project's compatibility with OpenCode V2 and any plans to support it.
This is a discussion / compatibility question, not a reproduced bug report: I have not run an end-to-end test of this adapter against v2.0.28. GitHub Discussions is not enabled for the repository, so I am asking here.
Observations from static source review
At source revision 5d4700204445ce658361010cbda2fd344bc60dec, the upstream client uses:
POST /session(lines 454–473)POST /session/{session_id}/messagewith apartsrequest body (lines 831–867)GET /event(lines 413–428)
The OpenCode V2 migration guide describes breaking server API changes. V2 uses endpoints such as /api/session, /api/event, and /api/session/{sessionID}/prompt, so adaptation appears to involve more than changing the base URL.
I also found #538, but understand its “V2 lifecycle migration” to refer to the a2a-sdk handler / task-store lifecycle, rather than migration to the OpenCode V2 server API. Please correct me if I have misunderstood.
Questions
- Which OpenCode server versions are currently supported or tested? Is there an existing branch, PR, or compatibility approach for OpenCode V2?
- Is OpenCode V2 support planned? If there is an existing tracking issue or roadmap, could you point me to it?
- If it is not planned yet, would you welcome a contribution? Would you prefer dual V1/V2 compatibility or a new release line targeting V2?
- Could the README / compatibility documentation list tested OpenCode versions and explicitly distinguish OpenCode V2 from a2a-sdk V2, to help users assess compatibility before deployment?
Scope
This concerns upstream OpenCode API compatibility and version documentation, not changes to A2A core or new OpenCode-private management features. I am not assuming a particular implementation or requesting a delivery commitment.
I searched related issues / PRs and did not find a discussion explicitly tracking OpenCode V2 server API support. If I missed one, please link the existing thread. Thank you!
Activity
tbrandenburg commentedon Oct 25, 2026
Restricted-first V2 profile：请求范围与 stack 审查
我们没有用 session idle / arrival-order 猜测解决通用 input correlation。原 2.0.28 两个 queue inputs 共用一个 terminal 的证据仍成立，通用 shared-session 后续仍未解决：
tbrandenburg#9
本轮用户授权先交付一个可证明的窄 profile：专用 private network namespace、一个 gateway/upstream pair、未共享 credential、固定 workspace、gateway-created sessions 与已提交 ownership、单飞 lease、禁用自主/background writers。成功还要求 own delivery、sequenced assistant/terminal、settlement 和 exact projections。失去证据则失败/quarantine，不重发或误报成功。
真实模型验收覆盖 V2 2.0.28 REST/JSON-RPC stream/unary、follow-up、parallel/serialized sessions、read permission、string/multiselect、授权/拒绝、取消与六个真实 transport/provider/expiry negative scenarios；positive matrix 14 admissions / 1 SSE。V1 1.18.19 expanded matrix 12/12，六个 cancellation trials 加 46 秒状态观察通过。当前 author committed gate 1021 passed，0 failed。Live reasoning 未验证。
审查顺序：#551 → #552 → #553 → #554 → #555。后续 PR 都是明确标注的 stacked Draft；exact-head regression 与相同 source tree 的 author live evidence 分开记录。
Scope / reproducible commands：
https://github.com/tbrandenburg/opencode-a2a/blob/feature/opencode-v2-exclusive/docs/v2-exclusive-execution.md
Sanitized evidence：
https://github.com/tbrandenburg/opencode-a2a/blob/feature/opencode-v2-exclusive/docs/evidence/v2-exclusive-acceptance.json
请求 maintainer 决定：是否接受这个 restricted-first profile 作为首批 V2 contribution，并按上述依赖审查？ 我们未修改 V1 默认、未宣称通用 V2 支持、未 force-push/merge 或关闭 fork epic。
a2a_call、request model overrides、attachments、rich/unary interventions、transparent replay/restart 和外部共享 writers 均不在这批范围。此更新不表示 upstream 已发布支持。tbrandenburg commentedon Oct 25, 2026
V2 default-policy follow-up 与 fork 验证状态
新增 PR #556：默认选择 V2 API，V1 需要
OPENCODE_API_VERSION=v1；V2 execution 仍默认 disabled，保留OPENCODE_V2_EXECUTION=exclusive的明确 acknowledgement 和 private deployment 前提。不增加 unrestricted shared-session 能力，不自动回退。这是 #551→#552→#553→#554→#555 之后的 stacked Draft，不是另一套实现；本次仅一个增量 commit
fab667a45bece2e79d1b531ba6ba4d8e5b2ad79c。维护者仍需决定是否接受 default-policy breaking change；没有自动 merge upstream PR。Exact head doctor 1026 passed / 0 failed，conformance 8/8；fresh pinned V1 1.18.19 opt-in real-model smoke、V2 2.0.28 omitted-selector session smoke、default V2 + explicit exclusive 的 native/A2A matrix（14 admissions / 1 SSE）和六个 real-upstream fault scenarios 通过。两个 candidate 的生产 Python source 和 live harness 内容一致；source identity 及局限见新
docs/evidence/v2-default-acceptance.json。Live reasoning 仍 NOT VERIFIED。本 fork PR：tbrandenburg#11 ，将按用户授权在本 fork CI 通过后合并。Fork delivery 不代表 upstream merge/发布。
Upstream Actions 当前为 action_required，需要 maintainer 批准 external-contribution workflow：
这不是 hosted tests 已通过的声明；本地 exact-head gates 与 live evidence 和尚未运行的 upstream hosted CI 分开报告。本 issue 保持 open。
tbrandenburg commentedon Oct 25, 2026
已合并 fork，PR 与 main hosted CI green
Fork PR tbrandenburg#11 已 normal merge，main commit
37a49bbd3d81adb777b85d9616b883009d8719a4。Merge tree 与 tested candidatef224037相同。docs/evidence/v2-default-acceptance.json匹配。现在 V2 是 API default；V1 需要
OPENCODE_API_VERSION=v1。V2 execution 仍需OPENCODE_V2_EXECUTION=exclusive，private deployment 前提和 unsupported scope 不变。没有自动 fallback，没有改写旧 prerelease/tag 或发布 PyPI。Upstream follow-up #556 保持 stacked Draft，关联 #550 ，依赖既有前置贡献。Exact upstream head
fab667a独立 doctor 1026 passed、conformance 8/8，但 hosted CI 仍为 action_required / 需要 maintainer approval，不是 green 或 upstream merge。五个既有 contribution heads 保持原样。Fork tracking tbrandenburg#10 已完成关闭；原广义 epic 和未解决的 V1 attribution / V2 unrestricted-session scope 不因此关闭。Live reasoning 仍 NOT VERIFIED。