Use SemVer for protocol compatibility

[monadoid]

Summary

Use full SemVer protocol versions for runtime compatibility and document how SDK, extension, and protocol packages should be versioned independently.

• Keep the SDKs at 4.0.0 and the protocol at 1.0.0
• Re-baseline the extension to 1.0.0
• Remove Changesets fixed groups so packages can be released independently

How it works

Compatibility compares the protocol versions reported by the client and extension, not their package versions.

For stable protocol versions:

• Same major + extension minor greater than or equal to client minor = compatible
• Different major or extension minor lower than client minor = incompatible
• Patch differences are compatible

Prerelease protocol versions must match exactly.

No Changeset is included because these packages have not been released yet.

Validation

• just check
• just test

---

Summary by cubic

Switch protocol compatibility to full SemVer and gate runtime negotiation on the protocol version string, not package versions. Re-baselined @browserbasehq/stagehand-extension to 1.0.0 and removed Changesets fixed groups so SDKs, extension, and protocol can release independently.

• Refactors

  • Added packages/protocol/protocol-version.ts with SemVer validation, checkProtocolCompatibility, and exported STAGEHAND_PROTOCOL_VERSION.
  • Changed JSON-RPC: protocol_version is a SemVer string with a strict pattern; malformed versions return invalid-params errors on the wire.
  • Updated SDKs (TS/Go/Python) to negotiate using SemVer strings with these rules: same major; server minor >= client minor; patch differences compatible; prereleases must match exactly. Go uses golang.org/x/mod for SemVer; Python exports PROTOCOL_SEMVER_PATTERN.
  • @browserbasehq/stagehand-extension enforces compatibility during stagehand.init, returning StagehandProtocolCompatibilityError with a structured reason; embedded bundle regenerated and preview manifest updated to 1.0.0.
  • Docs and release workflow clarify independent versioning and protocol SemVer policy; Changesets now ignore @browserbasehq/stagehand-evals; release notes include Go SDK and Protocol changelogs; Go module tags are created separately.

• Migration

  • No action for SDK users; negotiation is automatic.
  • Custom clients/servers must send and expect protocol_version as a SemVer string (e.g., "1.2.3") and enforce:
    • Same major required; server minor must be >= client minor.
    • Patch differences are compatible.
    • Prereleases must match exactly.

^{Written for commit bf97a0f. Summary will update on new commits.}

[changeset-bot]

⚠️ No Changeset found

Latest commit: bf97a0f

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[cubic-dev-ai]

5 issues found across 35 files

Confidence score: 3/5

• packages/sdk-go/models.gen.go changes the init-handshake protocol_version contract, but there’s no corresponding integration coverage under packages/server/test, so client/server negotiation regressions could reach users as failed handshakes — add an end-to-end protocol-version integration test for the breaking path.
• packages/sdk-go/internal/generator/main.go and packages/sdk-go/runtime_compatibility.go introduce new semver formatting and compatibility rules without focused Go tests, which raises the chance of subtle negotiation or validation bugs in future edits — add targeted unit tests for generation output and stable/prerelease compatibility cases.
• packages/protocol/schemas.ts and packages/sdk-python/src/stagehand/cdp_client.py each carry smaller but concrete maintainability/runtime risks: .ts specifiers may fail in emitted ESM, and duplicated semver regexes can drift between runtime and generator validation — switch to emitted .js specifiers and deduplicate the regex source.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/sdk-go/models.gen.go">

<violation number="1" location="packages/sdk-go/models.gen.go:1816">
P1: Custom agent: **Any breaking changes to Stagehand REST API client / server implementation must be covered by an integration test under packages/server/test**

This PR changes the init-handshake `protocol_version` field from `float64` to a SemVer `string`. That is a breaking wire-format change to the shared request shape and server schema. Rule 5 requires breaking REST API changes to be covered by an integration test under `packages/server/test`. Please confirm that the server-side SemVer compatibility logic and the new string-based handshake are exercised by an integration test, including major/minor compatibility and prerelease exact-match outcomes.</violation>
</file>

<file name="packages/sdk-go/internal/generator/main.go">

<violation number="1" location="packages/sdk-go/internal/generator/main.go:219">
P2: This update changes protocol version behavior (major integer to full semver string) but does not add focused tests for the new validation/output contract, so regressions can slip in unnoticed. A small test suite for generateProtocolVersionSource covering stable, prerelease, and invalid inputs would make the compatibility rules durable.

(Based on your team's feedback about adding unit tests for new behavior.) .</violation>
</file>

<file name="packages/protocol/schemas.ts">

<violation number="1" location="packages/protocol/schemas.ts:2">
P3: Runtime ESM resolution can break when relative specifiers use `.ts` instead of emitted `.js` paths. These new import/export specifiers would be safer aligned to the repo convention by referencing `./protocol-version.js`.</violation>
</file>

<file name="packages/sdk-go/runtime_compatibility.go">

<violation number="1" location="packages/sdk-go/runtime_compatibility.go:48">
P2: Runtime compatibility behavior changed substantially (major/minor negotiation plus prerelease exact-match), but the change set does not add Go unit tests to lock these cases. Adding focused tests for stable-version accept/reject paths and prerelease matching would reduce regression risk.

(Based on your team's feedback about adding unit tests for new behavior.) .</violation>
</file>

<file name="packages/sdk-python/src/stagehand/cdp_client.py">

<violation number="1" location="packages/sdk-python/src/stagehand/cdp_client.py:17">
P3: The SemVer regex pattern in `_PROTOCOL_SEMVER_PATTERN` is duplicated verbatim in `packages/sdk-python/scripts/generate.py` as `SEMVER_PATTERN`. Both files must always use the same pattern for SemVer validation — if one is updated (e.g., to refine pre-release identifier validation) and the other is not, protocol version parsing can silently diverge between codegen validation and runtime compatibility checking. Consider defining the pattern in a shared non-generated location (e.g., a constants module under `src/stagehand/`) so both the build script and the runtime module refer to the same source of truth.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 18 files (changes from recent commits).

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>