[fix]: fail fast on incompatible Stagehand runtime instead of polling to timeout
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, orserverInfo.name !== "stagehand") |unknown(marker absent / not yet set / unparseable). Python and Go previously collapsedincompatibleandunknowninto a singlefalse. - Wait loops:
unknown(andRuntime.evaluateexceptions) keep polling as before.incompatibleraises 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. allowFallbackInstallis kept (reserved for a future Browserbase preloaded-extension flow) but its default flips: the gate is now!== trueinstead of=== false. Passingtruepreserves 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, extensionserverInfoname+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 skippeduv 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 -raceon the CDP/runtime tests okjust buildandjust 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);incompatibleraises on the first poll,unknownkeeps polling. - A missing, empty, or non-string
serverInfofield, and an emptyprotocolVersion, count asunknownin all three SDKs; a non-SemVer protocol version counts asincompatible. - 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 theruntime-name-mismatchmessage. - Flips
allowFallbackInstalldefault: now fails fast unless explicitly set totrue(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.