Skip to content

feat(server): gate external integration values by client API version - #53824

Closed
opencode-agent[bot] wants to merge 1 commit into
v2from
client-version-gating
Closed

opencode-agent[bot] wants to merge 1 commit into
v2from
client-version-gating

Conversation

@opencode-agent

@opencode-agent opencode-agent Bot commented Oct 7, 2026

Copy link
Copy Markdown
Contributor

Issue for this PR

Follow-up to #53672. A newer server breaks older clients' integration.list decoding.

Type of change

  • Bug fix
  • New feature
  • Refactor / code improvement
  • Documentation

What does this PR do?

#53672 added the external integration method, connection and credential type. Clients on v2.0.24 and earlier decode Integration.Method, Connection.CredentialInfo.method and Credential.Value as closed unions, so any external value fails the whole response. Bedrock always advertises its aws-profile method, so integration.list from a current server fails to decode for every older SDK or remote/paired client, even when no one has connected an external credential.

This adds client API-version gating:

  • @opencode/protocol/api-version defines the x-opencode-api-version header and the current version (2), with a log of what each version can decode. @opencode/client keeps its own copy because the promise client can't import protocol; a test checks that the two copies match.
  • The promise and Effect clients send the header on every request.
  • packages/server/src/api-version.ts reads the header. A missing or invalid header means version 1, which covers every already-released client. For version 1, integration.list/integration.get leave out external methods and connections, and credential.list leaves out external credentials. These are the only endpoints that return those schemas.
  • When a response gets a new value that older clients can't decode, bump API_VERSION and add the omission for lower versions in the server's api-version.ts. Once the older versions are no longer supported, delete the omission.

Version-1 clients just don't see external connections. That's correct for them, since they can't use them anyway.

This doesn't make clients tolerate unknown values; that belongs in codegen, and with it in place additive changes wouldn't need a version bump. It doesn't cover old binaries reading external rows from a shared database, or policy actions renamed in config responses.

How did you verify your code works?

  • packages/server/test/api-version.test.ts: registers an integration with key and external methods, creates an external credential and a key credential, then calls /api/integration, /api/integration/:id and /api/credential with version 2, with no header, with 1, and with a malformed header. The test fails without the handler changes.
  • Client tests check that the promise and Effect clients send the header, including when the caller passes its own headers.
  • bun run typecheck passes in server, client and protocol. Server tests api-version, provider, handler-policy, fetch and cors all pass.
  • Four client tests already fail on base v2 (46c69bc35c), with or without this PR: the stale integration/session method list assertions, the session Effect decode test, and the effect/service import-boundary check.

Checklist

  • I have tested my changes locally
  • I have not included unrelated changes in this PR

Requested by: @neriousy (Filip via Slack)

Clients now send x-opencode-api-version. Clients that send no header
(v2.0.24 and earlier) reject external integration methods, connections,
and credentials, so integration.list, integration.get, and credential.list
omit those values for them instead of failing the whole response.
@opencode-agent

opencode-agent Bot commented Oct 8, 2026

Copy link
Copy Markdown
Contributor Author

Closing: client SDKs are expected to match the server version exactly, and the HTTP protocol only gets additive changes, so the server doesn't need to hold back new values from older clients. Reopen if that changes.

@opencode-agent opencode-agent Bot closed this Oct 8, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant