fix: track SDK language in v4 metadata

[shrey150]

Summary

• tag Browserbase sessions created by the TypeScript SDK with authoritative stagehand and stagehand_sdk_language user metadata
• preserve caller-provided session metadata while preventing attribution fields from being spoofed
• send the Python SDK name and installed package version through the existing runtime.configure.clientInfo metadata field
• add patch changesets for the TypeScript and Python SDKs

Why

Stagehand v3 identifies its SDK language with the x-language request header. V4 no longer routes SDK work through the hosted Stagehand API, so Browserbase session metadata is the durable, queryable equivalent for cloud sessions. The existing cross-language clientInfo handshake remains the right metadata path for runtime connections.

v4-spike currently creates Browserbase sessions from the TypeScript SDK. Python session creation is not implemented on this branch yet, while the in-flight Go SDK already sends its language and version through clientInfo. Future Python and Go Browserbase session creators should stamp stagehand_sdk_language with their respective language values.

E2E Test Matrix

Command / flow	Observed output	Confidence / sufficiency
Local TypeScript build → create a real Browserbase session with spoofed attribution → retrieve the session through the Browserbase API	Retrieved stagehand: "true", stagehand_sdk_language: "typescript", and preserved the custom suite field	Proves the exact code under review writes durable Browserbase session metadata and keeps Stagehand attribution authoritative
vitest run --root . packages/sdk-ts/tests	134 passed, 1 skipped	Covers the TypeScript SDK, including session creation, packaging, and metadata merge behavior
uv run --locked pytest	196 passed	Covers the full Python SDK, including the serialized runtime.configure.client_info payload
Build the local Python wheel → uv run --isolated --no-project --with dist/*.whl python scripts/smoke.py	Installed wheel completed stagehand.init and stagehand.close against the built extension	Proves the published Python artifact can complete the real runtime handshake with the new metadata
Workspace formatting, linting, protocol/evals type checking, Python formatting/linting/type checking, and changeset checks	All commands exited successfully; workspace lint reported pre-existing warnings only	Supporting static validation across every changed package

Linear

STG-2714

---

Summary by cubic

Track SDK language in v4 metadata to meet Linear STG-2714. TypeScript sessions now set authoritative Browserbase user metadata, and Python sends SDK name and version via client_info during runtime configuration.

• New Features
  • TypeScript SDK: stamp Browserbase sessions with stagehand: "true" and stagehand_sdk_language: "typescript", merging other userMetadata and preventing spoofing using centralized SDK identity.
  • Python SDK: send client_info with name: "stagehand-sdk-python" and installed package version in runtime.configure.

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

[changeset-bot]

🦋 Changeset detected

Latest commit: f9ff170

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@browserbasehq/stagehand	Patch
@browserbasehq/stagehand-python	Patch
@browserbasehq/stagehand-evals	Patch

Not sure what this means? Click here to learn what changesets are.

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

[cubic-dev-ai]

No issues found across 5 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

Architecture diagram

sequenceDiagram
    participant TSClient as TypeScript SDK Client
    participant TSBrowserbase as Browserbase Session Client
    participant BrowserbaseAPI as Browserbase API
    participant PythonClient as Python SDK Client
    participant PythonRPC as RPC Client
    participant StagehandExt as Stagehand Extension

    Note over TSClient,StagehandExt: TypeScript SDK: Session Creation with Metadata

    TSClient->>TSBrowserbase: createSession({ userMetadata, ...params })
    TSBrowserbase->>TSBrowserbase: Merge userMetadata with authoritative STAGEHAND_SESSION_METADATA
    Note over TSBrowserbase: stagehand: "true", stagehand_sdk_language: "typescript"
    alt Caller provides spoofed stagehand keys
        Note over TSBrowserbase: Caller keys are overridden by authoritative metadata
    end
    TSBrowserbase->>BrowserbaseAPI: createSession({ userMetadata, extensionId, ...params })
    BrowserbaseAPI-->>TSBrowserbase: Session with cdpUrl, sessionId
    TSBrowserbase-->>TSClient: Session connection details

    Note over PythonClient,StagehandExt: Python SDK: Runtime Configuration with Client Info

    PythonClient->>PythonRPC: connect_rpc_client(cdp, ...)
    PythonRPC->>PythonRPC: Construct _STAGEHAND_SDK_CLIENT_INFO
    Note over PythonRPC: name: "stagehand-sdk-python", version: from importlib.metadata
    PythonRPC->>StagehandExt: runtime.configure({ client_info, cdp_url, log_level, telemetry })
    Note over PythonRPC,StagehandExt: client_info sent as ImplementationInfo payload
    StagehandExt-->>PythonRPC: Configuration acknowledged
    PythonRPC-->>PythonClient: Connected RPC client

    Note over TSClient,StagehandExt: Future: Go SDK would follow same pattern for session metadata

Loading

_{Re-trigger cubic}