[miguelg719]

Summary

• Honor browserbaseSessionCreateParams.browserSettings.solveCaptchas and waitForCaptchaSolves for local attachments. An explicit false for either option disables awareness; absent options retain Browserbase-on/local-off defaults.
• Resolve awareness from constructor options so it is available before CDP initialization, then forward it through the SDK session-start request and standalone v3 server.
• Reuse the existing waiting, solved-notice, and computer-use widget-avoidance behavior without changing CDP routing, session ownership, or shutdown behavior. No subclass or customer-specific flag.
• Update option/schema documentation, add a patch changeset, and cover the option matrix and SDK bootstrap forwarding.

Validation

• 68 focused compiled tests passed across eight suites: CAPTCHA options, agent CAPTCHA hooks, solver timing, Browserbase accessors, API default model config, API serialization, optional model API keys, and agent prompt variables.
• ESM and CommonJS builds passed.
• Package and standalone v3 server typechecks passed.
• Targeted ESLint, Prettier, and diff whitespace checks passed.
• No live hosted CAPTCHA session was tested.

---

Summary by cubic

Fixes CAPTCHA awareness for local attachments in Stagehand v3 so agents no longer interfere with Browserbase solves or stop at already-solved widgets.

Previously the waitForCaptchaSolves and browserSettings.solveCaptchas options only took effect when env: "BROWSERBASE", since awareness was gated on the environment. Now isCaptchaAutoSolveEnabled resolves from constructor options before CDP initialization, with waitForCaptchaSolves ?? solveCaptchas ?? env === "BROWSERBASE" as the default and solveCaptchas: false always disabling awareness. The resolved value is forwarded through the SDK session-start request and the standalone v3 server.

• Reuses existing waiting, solved-notice, and widget-avoidance behavior; CDP routing, session ownership, and shutdown are unchanged.
• Adds a patch changeset, updates option/schema documentation, and covers the option matrix plus API forwarding in tests.
• Targeting v3 only; the Browserbase API dependency update and package publication remain required for the hosted fix.

Rollout

• Publish the package, update the API's Orca dependency, and deploy the API forwarding change.
• This does not add a CAPTCHA solver for ordinary local attachments; solve events emitted before listeners attach remain unhandled.

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

[changeset-bot]

🦋 Changeset detected

Latest commit: 7d60cac

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-evals	Patch
@browserbasehq/stagehand-server-v3	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]

All reported issues were addressed across 8 files

Architecture diagram

sequenceDiagram
    participant Client as V3 Client Code
    participant V3 as V3 Class
    participant API as StagehandAPIClient
    participant Server as Standalone V3 Server
    participant Store as InMemorySessionStore
    participant Browser as Browserbase Session

    Note over Client,Browser: CAPTCHA Awareness Resolution Flow

    Client->>V3: Create instance(env, waitForCaptchaSolves, solveCaptchas)
    V3->>V3: Resolve isCaptchaAutoSolveEnabled
    Note over V3: waitForCaptchaSolves ?? solveCaptchas ?? (env === "BROWSERBASE")
    Note over V3: Explicit solveCaptchas: false always wins

    Client->>V3: init()
    V3->>V3: Read isCaptchaAutoSolveEnabled (before CDP init)
    V3->>API: init(waitForCaptchaSolves=resolvedValue)
    API-->>V3: sessionId, available

    V3->>Browser: Attach via CDP (env LOCAL or BROWSERBASE)

    alt Local attachment (env: "LOCAL")
        Note over V3,Browser: Same CAPTCHA awareness now applies
        Browser-->>V3: Captcha solve event
        V3->>V3: Wait for solve (if enabled)
        V3-->>Client: Continue action
    else Browserbase attachment (env: "BROWSERBASE")
        Browser-->>V3: Captcha solve event
        V3->>V3: Wait for solve (if enabled)
    end

    Note over V3,Store: Server-side forwarding (standalone)

    V3->>Server: Session start request (includes waitForCaptchaSolves)
    Server->>Store: Persist session params
    Store-->>Server: Stored session
    Server-->>V3: Session established

Loading

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 2 files (changes from recent commits).

<sub>Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 5 files (changes from recent commits).

<sub>Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 8 files (changes from recent commits).

<sub>Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>

[AzamAbdul]

not sure how much this is an actual issue, but the code looks fine to me. just a question about if this is actually a problem:

from claude

found one real bug. On plain local Chrome, setting solveCaptchas: true now turns captcha waiting on. The agent is then told not to solve captchas, but there's no solver locally, so it gets stuck. The bug is in two places: the core library check (v3.ts:203) and the server, which now passes Browserbase settings to local sessions (InMemorySessionStore.ts:251).

[miguelg719]

@AzamAbdul not an issue this fix is going out for the hosted version mainly