[STG-1798] feat: support Browserbase verified sessions

[shrey150]

Summary

• bump @browserbasehq/sdk to ^2.10.0 in packages/core, packages/server-v3, and packages/server-v4
• add Browserbase verified, os, and custom captcha session settings to the Stagehand Browserbase session-create schema and generated OpenAPI specs
• keep legacy advancedStealth behavior working by treating it as a compatibility alias for the new verified-mode checks in Stagehand internals

Testing

• pnpm --filter @browserbasehq/stagehand build:esm
• pnpm --filter @browserbasehq/stagehand test:core -- packages/core/dist/esm/tests/unit/browserbase-session-accessors.test.js packages/core/dist/esm/tests/unit/model-config-schema.test.js
• pnpm --filter @browserbasehq/stagehand typecheck
• pnpm --filter @browserbasehq/stagehand-server-v3 typecheck
• pnpm --filter @browserbasehq/stagehand-server-v4 typecheck
• Browserbase-backed smoke test creating a real Stagehand session with browserSettings.verified: true

Linear: https://linear.app/browserbase/issue/STG-1798/support-browserbase-verified-session-settings

---

Summary by cubic

Adds support for Browserbase Verified sessions with new session settings across Stagehand APIs and a fixed Google CUA viewport when Verified, addressing Linear STG-1798. Deprecates the isAdvancedStealth alias in favor of v3.isVerified, and fixes abort-signal handling to fail fast on already-aborted signals.

• New Features

  • Add verified, os, captchaImageSelector, and captchaInputSelector to Browserbase browser settings and generated OpenAPI (v3 and v4).
  • Introduce v3.isVerified; keep isAdvancedStealth as a deprecated, backward-compatible alias.
  • Use a 1288x711 viewport for Google CUA when Verified; otherwise use the configured viewport.

• Dependencies

  • Bump @browserbasehq/sdk to ^2.10.0 in packages/core, packages/server-v3, and packages/server-v4.

^{Written for commit c2bde33. Summary will update on new commits. Review in cubic}

[changeset-bot]

🦋 Changeset detected

Latest commit: c2bde33

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

This PR includes changesets to release 4 packages

Name	Type
@browserbasehq/stagehand	Minor
@browserbasehq/stagehand-evals	Patch
@browserbasehq/stagehand-server-v3	Patch
@browserbasehq/stagehand-server-v4	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

[github-actions]

✱ Stainless preview builds

This PR will update the stagehand SDKs with the following commit message.

feat: [STG-1798] feat: support Browserbase verified sessions

⚠️ stagehand-typescript studio · code

Your SDK build had at least one "warning" diagnostic.
generate ⚠️ → build ✅ → lint ✅ → test ✅

npm install https://pkg.stainless.com/s/stagehand-typescript/763e86ba840151dcab7c587d84842a5cafedeb67/dist.tar.gz

✅ stagehand-go studio · code

Your SDK build had at least one "note" diagnostic.
generate ✅ → build ⏭️ → lint ✅ → test ✅

go get github.com/stainless-sdks/stagehand-go@30133d320e2093815d9714e32a64ffe6242b94aa

✅ stagehand-kotlin studio · code

Your SDK build had at least one "note" diagnostic.
generate ✅ → build ✅ → lint ✅ → test ✅

✅ stagehand-openapi studio · code

Your SDK build had at least one "note" diagnostic.
generate ✅

✅ stagehand-ruby studio · code

Your SDK build had at least one "note" diagnostic.
generate ✅ → build ⏭️ → lint ✅ → test ✅

⚠️ stagehand-python studio · code

Your SDK build had at least one "warning" diagnostic.
generate ⚠️ → build ✅ → lint ✅ → test ✅

pip install https://pkg.stainless.com/s/stagehand-python/078ab5c76f13beee16e44d7eed5e3018f1cc5bd8/stagehand-3.19.5-py3-none-any.whl

⚠️ stagehand-csharp studio · code

Your SDK build had a failure in the build CI job, which is a regression from the base state.
generate ⚠️ → build ❗ → lint ❗ → test ❗

⚠️ stagehand-php studio · code

Your SDK build had at least one "warning" diagnostic.
generate ⚠️ → lint ✅ → test ✅

✅ stagehand-java studio · code

Your SDK build had at least one "note" diagnostic.
generate ✅ → build ✅ → lint ✅ → test ✅

Add the following URL as a Maven source: 'https://pkg.stainless.com/s/stagehand-java/59ee1516eb17d6b8474b12d2722ff4627fa2557c/mvn'

---

This comment is auto-generated by GitHub Actions and is automatically kept up to date as you push.
If you push custom code to the preview branch, re-run this workflow to update the comment.
Last updated: 2026-04-08 23:36:41 UTC

[cubic-dev-ai]

No issues found across 13 files

Confidence score: 5/5

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

Architecture diagram

sequenceDiagram
    participant Client
    participant API as Server (v3/v4 API)
    participant Core as V3 Core (Stagehand)
    participant Handler as V3CuaAgentHandler
    participant GoogleCUA as GoogleCUAClient
    participant BBSDK as Browserbase SDK

    Note over Client,BBSDK: Session Initialization Flow

    Client->>API: POST /session (Start Session)
    Note right of API: NEW: Validates verified, os, <br/>captcha selectors in schema
    
    API->>Core: init(browserbaseSessionCreateParams)
    
    Core->>Core: CHANGED: Check isVerified / isAdvancedStealth
    Note right of Core: Legacy advancedStealth is now <br/>treated as an alias for verified
    
    Core->>BBSDK: CHANGED: createSession() with ^2.10.0 features
    BBSDK-->>Core: Session Metadata
    Core-->>API: Session ID
    API-->>Client: 200 OK
    
    Note over Client,BBSDK: Runtime Agent Interaction (e.g., coordinate normalization)

    Client->>Handler: executeAction()
    
    Handler->>Core: get isVerified
    Core-->>Handler: boolean (verified || advancedStealth)

    alt NEW: Browserbase Managed Fingerprinting (isVerified)
        Handler->>GoogleCUA: CHANGED: setViewport(1288, 711)
        Handler->>Handler: Use STEALTH_VIEWPORT for coordinate normalization
    else Standard Mode
        Handler->>GoogleCUA: setViewport(configuredViewport)
        Handler->>Handler: Use configured dimensions for normalization
    end

    Handler->>GoogleCUA: Perform action with processed coordinates
    GoogleCUA-->>Handler: Result
    Handler-->>Client: Action Complete

Loading