[OpenCode V2][Epic] Deliver opt-in server API V2 support in five reviewable upstream PRs #1

Goal

Deliver genuinely usable, opt-in OpenCode V2 server API support in opencode-a2a while retaining the verified OpenCode V1 path and the existing A2A 1.0 public contract. Track five small, understandable, independently reviewed upstream PRs, not a gateway rewrite.

Upstream coordination: Intelligent-Internet#550
Source baseline when planned: 5d4700204445ce658361010cbda2fd344bc60dec (fork matched upstream).
Not to be confused with: upstream A2A SDK V2 lifecycle PR Intelligent-Internet#538.

Background

The current adapter calls OpenCode V1 endpoints such as POST /session, POST /session/{sessionID}/message and GET /event; docs/compatibility.md declares V1 1.18.x, verified on 1.18.19. OpenCode V2 uses /api/* with different request/response and execution semantics. V2 POST /api/session/{sessionID}/prompt returns an admitted inbox input, not a generated assistant result. V2 GET /api/event is volatile. Its default external-directory permission is broader than V1.

References: https://opencode.ai/v2/docs/migrate-v1#server-api-and-clients and https://opencode.ai/v2/docs/api .

KISS / architectural rules

1. One A2A runtime, two thin OpenCode adapters. Keep A2A auth, task persistence, session ownership, workspace policy, output formatting, and common event rendering shared.
2. Expose a minimal typed contract for session, admission, correlated execution updates, outcome, and interventions; no universal "all agent runtimes" framework.
3. Separate accepted from completed. A task completes only on correlated terminal evidence, never solely on HTTP 200 or unrelated session.idle.
4. V1 remains the default. Explicit V2 selection; no auto-detection or silent fallback in this epic.
5. Honest capabilities throughout: any unimplemented V2 extension/model/tool behavior is hidden from discovery and rejected explicitly, starting with the first V2 PR.
6. Each PR must work independently against upstream main, or be clearly marked as a draft with documented dependency; never ask maintainers to review a giant stacked diff as one PR.
7. Preserve existing security: auth, identity-to-session ownership, location/workspace restrictions, concurrency budgets, cancellation semantics, and log redaction.

Planned upstream PR sequence (one fork issue each)

• PR 1 — Refactor V1 upstream boundary (no behavior changes). [OpenCode V2][1/5] Extract typed upstream adapter boundary without changing V1 behavior #2 — [OpenCode V2][1/5] Extract typed upstream adapter boundary without changing V1 behavior #2
• PR 2 — Add explicitly selected V2 connection/session backend; gate unimplemented execution. [OpenCode V2][2/5] Add opt-in V2 transport, session lifecycle and location mapping #3 — [OpenCode V2][2/5] Add opt-in V2 transport, session lifecycle and location mapping #3
• PR 3 — Implement correlated prompt execution, output streaming, terminal states, model/tool compatibility, and cancellation. [OpenCode V2][3/5] Complete correlated V2 prompt execution, streaming and cancellation #4 — [OpenCode V2][3/5] Complete correlated V2 prompt execution, streaming and cancellation #4
• PR 4 — Map V2 permissions/forms to secure A2A input-required interventions. [OpenCode V2][4/5] Map V2 permissions and forms to secure A2A input-required flows #5 — [OpenCode V2][4/5] Map V2 permissions and forms to secure A2A input-required flows #5
• PR 5 — Finalize truthful capability discovery, pinned V1/V2 tests, manual evidence and compatibility docs. [OpenCode V2][5/5] Finalize capability honesty, pinned V1/V2 E2E and compatibility docs #6 — [OpenCode V2][5/5] Finalize capability honesty, pinned V1/V2 E2E and compatibility docs #6

Each child issue must contain a junior-friendly implementation checklist, pitfalls, unit/HTTP tests, final manual E2E acceptance instructions, acceptance criteria, and Definition of Done. Cross-link its upstream PR and this epic. Update source paths and API details if upstream changes before implementation.

Execution plan refinement — applies to issues #4–#6 (October 25, 2026)

Work on #2 and #3 is left unchanged; this is a forward-looking refinement for implementation issues #4, #5 and #6, not a request to redo V1 extraction or V2 session transport. Issue #3 is reported as the user's current stage, not marked complete or merged (verify its actual PR/branch state before starting dependent work).

• [OpenCode V2][3/5] Complete correlated V2 prompt execution, streaming and cancellation #4 / upstream PR 3: Reuse a shared httpx.AsyncClient; prefer a bounded, shared native GET /api/event SSE subscription per authenticated upstream backend with session/input/task and owner-aware fanout, not one global SSE stream per A2A task. Open/ready the event feed before prompt admission; parse native SSE frames correctly, use V2 prompt input id and returned inbox receipt as admission, never as completion. Favor event-driven updates over polling; handle gaps with bounded targeted message/inbox reconciliation, no blind retry. Evaluate the experimental per-session durable log only if verified and justified. Distinguish queued inbox cancel from active session interrupt, verifying the latter's 200 SessionInterruptResponse payload.
• [OpenCode V2][4/5] Map V2 permissions and forms to secure A2A input-required flows #5 / upstream PR 4: Reuse [OpenCode V2][3/5] Complete correlated V2 prompt execution, streaming and cancellation #4's same event pipeline and targeted HTTP get/list reconciliation for permissions and forms; correct session/request-bound reply schemas (decision vs V1 reply) and 204 no-body behavior; no new subscription or busy polling while awaiting human input. Preserve owner/task binding and V2 external-directory policy.
• [OpenCode V2][5/5] Finalize capability honesty, pinned V1/V2 E2E and compatibility docs #6 / upstream PR 5: Release-level tests must prove connection reuse, SSE fanout isolation, bounded queues/backpressure, no normal-path hot polling, disconnect/reconciliation, exact cancellation semantics, shutdown cleanup and optional log cursor recovery only if chosen. Publish pinned real-model V1/V2 E2E evidence and sanitized HTTP/subscription counts.

KISS decision: No custom message polling daemon, no new SDK/client stack, no forced experimental-log dependency, and no speculative generalized transport framework. Do not promise seamless replay when the only active V2 source is the volatile global event feed.

Reference contracts: https://opencode.ai/v2/docs/api (session.prompt, event.subscribe, experimental session.log, session.inbox, session.interrupt, session.permission.reply, session.form.reply). Final implementation must verify these against its pinned OpenCode server build.

Epic-level pitfall gates (must not regress)

• Prompt correlation: admitted input ID vs assistant output ID vs A2A task ID. Concurrent or queued prompts and unrelated idle events must not complete another task.
• Event loss: volatile V2 events do not imply replay; reconnect must reconcile against authoritative session state or fail as uncertain, never fabricate success or blindly resubmit. Experimental /api/experimental/session/{sessionID}/log may be evaluated, but cannot be assumed supported without version-pinned evidence.
• Security: OpenCode V2 defaults external_directory to allow; test explicit upstream policy and gateway path restrictions. Reject ownership mismatches and invalid location changes before privileged calls.
• Response typing: V2 has data-wrapped JSON results and 204 No Content mutations; never assume every successful call yields a JSON object or V1-shaped payload.
• Model selection: V2 model switch is session-scoped, whereas this adapter advertises request-scoped model selection; maintain semantic isolation or reject the override.
• Tool bridge: existing a2a_call/tool-result reinjection assumes V1-style parts. Do not claim it works in V2 until proven end-to-end; gate and document unsupported behavior.
• Compatibility: SDK "V2" is not OpenCode server V2. Keep V1 live test and V2 pinned test isolated (different binaries/config HOME/XDG/workspaces), with no claims based only on mocked responses.
• Staging: after PR 2/3/4, partially supported V2 must be clearly experimental/limited; advertised features match implemented and tested features.

Detailed implementation / tracking steps (for a junior contributor)

1. Read AGENTS.md, CONTRIBUTING.md, docs/maintainer-architecture.md, docs/security-architecture.md, docs/compatibility.md and scripts/README.md.
2. Before each PR, confirm current upstream head/maintainer feedback on [Question] OpenCode V2 server API 兼容性与支持计划 Intelligent-Internet/opencode-a2a#550; branch from the latest upstream main (not from a chain of unmerged feature branches unless visibly marked stacked).
3. Implement only the child issue scope. Reuse opencode_upstream_client.py, execution/*, server/*, contracts/extensions/* and existing tests; don't reorganize unrelated modules.
4. For each PR run bash ./scripts/doctor.sh, relevant targeted tests, and the issue's manual E2E scenario. Record exact OpenCode and Python/adapter versions and command output.
5. Open a narrowly scoped upstream PR describing why, code-path changes, what is intentionally unsupported, security impact, tests, and dependencies. Link child issue and upstream [Question] OpenCode V2 server API 兼容性与支持计划 Intelligent-Internet/opencode-a2a#550.
6. Mark an epic checkbox only after the PR is reviewed/merged upstream (or record clearly if fork-only). Do not close this epic before the acceptance matrix below passes.

Final manual E2E acceptance (epic release gate)

Use real pinned V1 and V2 opencode serve installations, isolated temporary HOME/XDG state, isolated workspace dirs and ports, a configured real model, local-only upstream listeners, upstream Basic auth and separate inbound A2A credentials. Record exact versions and results:

1. Run the existing V1 bash ./scripts/live_opencode_smoke.sh and verify streaming completes with the expected assistant text; repeat with a non-streaming A2A send.
2. Switch the adapter to V2 explicitly, verify GET /api/info, create a new session, stream a prompt to a terminal A2A task, and continue the same session/context with a follow-up.
3. Repeat the central V2 request over the other supported A2A transport (REST and JSON-RPC). Verify no unsupported feature is advertised in Agent Card or extension discovery.
4. Execute a task that emits reasoning and a tool update; verify correct block metadata, final artifact snapshot and persisted terminal state.
5. Create two independent A2A tasks and queued/overlapping prompts; verify no cross-task output or premature completion. Trigger failure, cancellation and an upstream event disconnect; never get false success.
6. Trigger one human-approved permission request and one form; verify input-required, authorized reply, continued execution, rejection and cross-principal denial.
7. Try unauthorized inbound A2A calls, unauthorized upstream HTTP, cross-owner session reuse, prohibited workspace/outside-root path, and an unsupported V2 extension; all must fail safely and predictably.
8. Confirm V2 request-scoped model handling is semantically verified or explicitly unavailable. Confirm a2a_call/tool-result round trip is either proven working or explicitly not advertised.
9. Run deterministic suites and bash ./scripts/conformance.sh as well as pinned live checks. Publish the pass/fail table and known limitations in docs/compatibility.md.

If real model credentials/manual interaction are unavailable, mark the relevant gate not verified and keep the epic open: do not substitute mocks for a passed live acceptance test.

Epic acceptance criteria

• Each child PR has independent reviewable change scope and linked test evidence.
• Unchanged V1 default path passes all existing regression + live smoke tests.
• Opt-in V2 can create/continue sessions and complete real streamed + unary A2A tasks.
• V2 request correlation, terminal/failure/cancellation, and intervention workflows are tested.
• No V2 operation violates existing ownership/workspace/security boundaries.
• Capability advertisements and error behavior match actual support on both versions.
• Pinned compatibility matrix, manual E2E evidence, and upstream maintenance policy/decision are documented.

Definition of Done

• All five implementation issues resolved with upstream PR links and merged/reconciled status.
• CI/typecheck/linters/contract tests and the final manual V1/V2 E2E acceptance pass.
• No known P0/P1 semantic or security regressions; unresolved optional features explicitly gated and documented.
• Upstream maintainer decisions from [Question] OpenCode V2 server API 兼容性与支持计划 Intelligent-Internet/opencode-a2a#550 recorded; docs distinguish OpenCode API V2 from A2A SDK V2.
• Epic is closed only with a linked release/merge summary and tested upstream version numbers.

Explicitly out of scope

Automatic API-version detection, speculative multi-runtime abstraction, a general cleanup, V1 deprecation, and full parity for every OpenCode-private session/workspace extension. These may be separate non-blocking follow-ups.