[fix]: fail fast on incompatible Stagehand runtime instead of polling to timeout

Merged
MI
2mo ago
+2055-208

Why

When the connected Stagehand extension publishes a runtime marker (globalThis.__stagehand_runtime) whose protocol version is incompatible with the SDK, the client today keeps re-polling every 100 ms until the 60 s init deadline and the user only ever sees Stagehand initialization timed out after 60000ms. The wait loops only threw when allowFallbackInstall === false, and nothing sets that flag, so the fail-fast path was dead code (Python and Go had no fail-fast path at all).

What changed

All three SDKs now share the same semantics:

  • Three-way negotiation: compatible | incompatible (marker present and parses, but the protocol rules reject it, or serverInfo.name !== "stagehand") | unknown (marker absent / not yet set / unparseable). Python and Go previously collapsed incompatible and unknown into a single false.
  • Wait loops: unknown (and Runtime.evaluate exceptions) keep polling as before. incompatible raises on the first poll that sees it, before any sleep. In the preloaded-service-worker sweep a compatible worker in the same sweep still wins; an incompatible-only sweep raises immediately.
  • allowFallbackInstall is kept (reserved for a future Browserbase preloaded-extension flow) but its default flips: the gate is now !== true instead of === false. Passing true preserves the old keep-polling behaviour. Python/Go expose it only as an internal keyword/option on the wait functions (no new public constructor surface).
  • Dedicated, catchable error carrying reason (protocol-major-mismatch / protocol-server-too-old / protocol-prerelease-mismatch / protocol-invalid-version / runtime-name-mismatch), client protocol version, reported extension protocol version, extension serverInfo name+version, and a remediation hint. Message shape is identical across SDKs:
    Incompatible Stagehand runtime (<reason>): <detail>; client protocol <client>, extension protocol <ext>, extension <name>/<version>. Upgrade the Stagehand SDK and the Stagehand extension together so their protocol majors match, or start the session with the extension bundled in this SDK.

Test plan

Per SDK: (a) incompatible marker (major = current STAGEHAND_PROTOCOL_VERSION major + 1, never hardcoded) → dedicated error on the first poll, exactly one Runtime.evaluate, zero sleeps; (b) unknown marker for N polls then compatible → succeeds; (c) allowFallbackInstall: true + incompatible → keeps polling; (d) wrong serverInfo.name → error; (e) preloaded sweep: incompatible-only sweep fails fast and detaches, unknown sweeps keep polling; (f) error type exported from the public entry.

  • pnpm --filter ./packages/sdk-ts test: 16 files passed, 1 skipped; 210 tests passed, 3 skipped
  • uv run --locked pytest (sdk-python): 469 passed, 1 skipped (pre-existing py3.12 skip)
  • go test ./... (sdk-go, excluding examples): all packages ok; go test -race on the CDP/runtime tests ok
  • just build and just check (run step-by-step) green: changesets, changelog consolidation, python version sync, pnpm check (0 lint errors), uv lock --check, generate --check, ruff format/check, ty, Go generator --check, extensionpack --check, gofmt, go vet.

Summary by cubic

Fails fast with a clear compatibility error when the connected Stagehand extension reports an incompatible protocol version, instead of polling until the 60s initialization timeout. The old behavior produced an opaque "initialization timed out" message; now all three SDKs (TypeScript, Python, Go) raise a dedicated, catchable error with the mismatch reason, both protocol versions, and a remediation hint.

Behavior changes

  • Adds a three-way runtime negotiation (compatible / incompatible / unknown); incompatible raises on the first poll, unknown keeps polling.
  • A missing, empty, or non-string serverInfo field, and an empty protocolVersion, count as unknown in all three SDKs; a non-SemVer protocol version counts as incompatible.
  • The preloaded service-worker sweep fails fast only when it saw an incompatible worker and no compatible marker, so a compatible worker still being set up keeps polling.
  • Introduces StagehandRuntimeIncompatibleError, exported from all SDK entry points, carrying reason, detail, client/extension protocol versions, extension server info, and a remediation hint; wording is identical across SDKs, including the runtime-name-mismatch message.
  • Flips allowFallbackInstall default: now fails fast unless explicitly set to true (reserved for a future preloaded-extension flow).
  • Updates the protocol package's mirrored wait-loop fixtures and the extension test fixture to the new default.