[STG-1798] feat: support Browserbase verified sessions (browserbase#1980)

## 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

<!-- This is an auto-generated description by cubic. -->
---
## 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`.

<sup>Written for commit c2bde33.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1980">Review in
cubic</a></sup>

<!-- End of auto-generated description by cubic. -->

Author: shrey150

.changeset/verified-browserbase-sdk.md

@@ -0,0 +1,5 @@
+---
+"@browserbasehq/stagehand": minor
+---
+
+Support Browserbase verified session settings and bump the Browserbase SDK.

packages/core/lib/v3/agent/utils/coordinateNormalization.ts

@@ -1,6 +1,6 @@
 import type { V3 } from "../../v3.js";
 
-// Default viewport for advancedStealth mode
+// Default viewport for Browserbase managed fingerprinting mode
 const STEALTH_VIEWPORT = { width: 1288, height: 711 };
 
 export function isGoogleProvider(provider?: string): boolean {
@@ -30,10 +30,8 @@ export function processCoordinates(
   v3?: V3,
 ): { x: number; y: number } {
   if (isGoogleProvider(provider) && v3) {
-    // advancedStealth uses fixed viewport, otherwise use configured viewport
-    const viewport = v3.isAdvancedStealth
-      ? STEALTH_VIEWPORT
-      : v3.configuredViewport;
+    // Browserbase managed fingerprinting uses a fixed viewport fallback.
+    const viewport = v3.isVerified ? STEALTH_VIEWPORT : v3.configuredViewport;
     return normalizeGoogleCoordinates(x, y, viewport);
   }
   return { x, y };

packages/core/lib/v3/handlers/v3CuaAgentHandler.ts

@@ -626,9 +626,9 @@ export class V3CuaAgentHandler {
   private async updateClientViewport(): Promise<void> {
     try {
       // For Google CUA, use configured viewport for coordinate normalization
-      // advancedStealth uses fixed 1288x711, otherwise use configured viewport
+      // Browserbase managed fingerprinting uses a fixed 1288x711 fallback.
       if (this.agentClient instanceof GoogleCUAClient) {
-        const dims = this.v3.isAdvancedStealth
+        const dims = this.v3.isVerified
           ? { width: 1288, height: 711 }
           : this.v3.configuredViewport;
         this.agentClient.setViewport(dims.width, dims.height);

packages/core/lib/v3/types/public/api.ts

@@ -503,12 +503,16 @@ export const BrowserbaseBrowserSettingsSchema = z
   .object({
     advancedStealth: z.boolean().optional(),
     blockAds: z.boolean().optional(),
+    captchaImageSelector: z.string().optional(),
+    captchaInputSelector: z.string().optional(),
     context: BrowserbaseContextSchema.optional(),
     extensionId: z.string().optional(),
     fingerprint: BrowserbaseFingerprintSchema.optional(),
     logSession: z.boolean().optional(),
+    os: z.enum(["windows", "mac", "linux", "mobile", "tablet"]).optional(),
     recordSession: z.boolean().optional(),
     solveCaptchas: z.boolean().optional(),
+    verified: z.boolean().optional(),
     viewport: BrowserbaseViewportSchema.optional(),
   })
   .meta({ id: "BrowserbaseBrowserSettings" });

packages/core/lib/v3/v3.ts

@@ -198,15 +198,26 @@ export class V3 {
   }
 
   /**
-   * Returns true if advancedStealth is enabled in Browserbase settings.
+   * Returns true if Browserbase Verified mode is enabled in settings.
+   * Legacy `advancedStealth` is treated as equivalent for backwards compatibility.
    */
-  public get isAdvancedStealth(): boolean {
+  public get isVerified(): boolean {
+    const browserSettings =
+      this.opts.browserbaseSessionCreateParams?.browserSettings;
     return (
-      this.opts.browserbaseSessionCreateParams?.browserSettings
-        ?.advancedStealth === true
+      browserSettings?.verified === true ||
+      browserSettings?.advancedStealth === true
     );
   }
 
+  /**
+   * Backwards-compatible alias for Browserbase managed fingerprinting mode.
+   * @deprecated Use `isVerified` instead. This alias will be removed in a future version.
+   */
+  public get isAdvancedStealth(): boolean {
+    return this.isVerified;
+  }
+
   /**
    * Returns the configured viewport dimensions from launch options.
    * Falls back to default 1288x711 if not configured.

packages/core/package.json

@@ -69,7 +69,7 @@
   "dependencies": {
     "@ai-sdk/provider": "^2.0.0",
     "@anthropic-ai/sdk": "0.39.0",
-    "@browserbasehq/sdk": "^2.7.0",
+    "@browserbasehq/sdk": "^2.10.0",
     "@google/genai": "^1.22.0",
     "@langchain/openai": "^0.4.4",
     "@modelcontextprotocol/sdk": "^1.17.2",

packages/core/tests/unit/browserbase-session-accessors.test.ts

@@ -113,6 +113,27 @@ describe("browserbase accessors", () => {
       await v3.close().catch(() => {});
     }
   });
+
+  it("treats verified Browserbase sessions as managed fingerprinting mode", async () => {
+    const v3 = new V3({
+      env: "BROWSERBASE",
+      disableAPI: true,
+      verbose: 0,
+      browserbaseSessionCreateParams: {
+        browserSettings: {
+          verified: true,
+        },
+      },
+    });
+
+    try {
+      await v3.init();
+      expect(v3.isVerified).toBe(true);
+      expect(v3.isAdvancedStealth).toBe(true);
+    } finally {
+      await v3.close().catch(() => {});
+    }
+  });
 });
 
 describe("local accessors", () => {

packages/core/tests/unit/model-config-schema.test.ts

@@ -121,4 +121,20 @@ describe("SessionStartRequestSchema", () => {
 
     expect(result.success).toBe(true);
   });
+
+  it("accepts verified Browserbase session settings", () => {
+    const result = Api.SessionStartRequestSchema.safeParse({
+      modelName: "openai/gpt-5.4-mini",
+      browserbaseSessionCreateParams: {
+        browserSettings: {
+          verified: true,
+          os: "mac",
+          captchaImageSelector: "#captcha-image",
+          captchaInputSelector: "#captcha-input",
+        },
+      },
+    });
+
+    expect(result.success).toBe(true);
+  });
 });

packages/server-v3/openapi.v3.yaml

@@ -565,6 +565,10 @@ components:
           type: boolean
         blockAds:
           type: boolean
+        captchaImageSelector:
+          type: string
+        captchaInputSelector:
+          type: string
         context:
           $ref: "#/components/schemas/BrowserbaseContext"
         extensionId:
@@ -573,10 +577,20 @@ components:
           $ref: "#/components/schemas/BrowserbaseFingerprint"
         logSession:
           type: boolean
+        os:
+          type: string
+          enum:
+            - windows
+            - mac
+            - linux
+            - mobile
+            - tablet
         recordSession:
           type: boolean
         solveCaptchas:
           type: boolean
+        verified:
+          type: boolean
         viewport:
           $ref: "#/components/schemas/BrowserbaseViewport"
     BrowserbaseProxyGeolocation:
@@ -1545,6 +1559,10 @@ components:
           type: boolean
         blockAds:
           type: boolean
+        captchaImageSelector:
+          type: string
+        captchaInputSelector:
+          type: string
         context:
           $ref: "#/components/schemas/BrowserbaseContextOutput"
         extensionId:
@@ -1553,10 +1571,20 @@ components:
           $ref: "#/components/schemas/BrowserbaseFingerprintOutput"
         logSession:
           type: boolean
+        os:
+          type: string
+          enum:
+            - windows
+            - mac
+            - linux
+            - mobile
+            - tablet
         recordSession:
           type: boolean
         solveCaptchas:
           type: boolean
+        verified:
+          type: boolean
         viewport:
           $ref: "#/components/schemas/BrowserbaseViewportOutput"
       additionalProperties: false

packages/server-v3/package.json

@@ -22,7 +22,7 @@
     "gen:openapi": "tsx scripts/gen-openapi.ts"
   },
   "dependencies": {
-    "@browserbasehq/sdk": "^2.7.0",
+    "@browserbasehq/sdk": "^2.10.0",
     "@browserbasehq/stagehand": "workspace:*",
     "@fastify/cors": "^11.0.1",
     "@fastify/swagger": "^9.6.1",