[fix]: close parity gaps across SDKs for local browser launching

[seanmcguire12]

why

this PR addresses parity gaps in local launch behaviour:

• the TypeScript and Go SDKs already waited for a newly launched Chrome process to expose a usable CDP endpoint, detected early process exit, & cleaned up owned resources when launch failed.
• the Python SDK returned immediately after spawning Chrome & had narrower executable discovery, profile setup, cancellation, & process-tree shutdown behavior

Go & Python also accepted an explicit debugging port without first proving it was available. that could let launch continue toward a browser endpoint the SDK did not own

what changed

• added a default Chrome flag fixture & made all three SDK test suites compare their local flag lists against it
• added cross SDK contract coverage for launch argument ordering, about:blank, viewport behavior, & profile ownership
• refactored the Python local launcher into focused validation, executable discovery, profile, readiness, & shutdown helpers
• aligned Python Chrome discovery with TypeScript & Go:
  • explicit executable then CHROME_PATH then platform candidates
  • Chrome Canary, Stable, Beta, & Chromium on macOS
  • Canary & Stable across the standard Windows roots
  • the shared Chrome & Chromium executable order on Linux
• validate Python launch options & explicit executables before creating a profile or spawning Chrome
• create caller-provided Python profile directories recursively while preserving caller ownership
• wait for a successful /json/version response with a non-empty webSocketDebuggerUrl before a Python launch resolves
• race Python readiness against browser exit & initialization cancellation, then terminate the owned process & remove its temporary profile when launch does not complete
• added explicit loopback port availability checks to the Python & Go launchers before profile creation or process spawn
• return a focused occupied-port error instead of adopting or continuing toward an existing browser, while preserving other socket failures
• aligned Python shutdown with the TypeScript & Go launchers:
  • automatically disable the Chromium sandbox for Linux root
  • terminate Unix process groups with graceful then forced signals
  • terminate Windows process trees with taskkill /T then /F
  • share one close task across concurrent callers
  • continue profile cleanup after shutdown failures & preserve combined errors

test plan

• Verify all three SDKs use the same static default Chrome flags, argument ordering, starting URL, viewport behavior, & profile ownership contract.
• Verify Python option validation, explicit executable precedence, CHROME_PATH, complete platform discovery order, unsupported platforms, & caller profile creation.
• Verify Python waits for a valid CDP version response, rejects malformed readiness responses, detects early browser exit, & cleans up after spawn failure or cancellation.
• Verify Python & Go automatic port selection, occupied explicit-port rejection before resource creation, & preservation of non-occupancy socket errors.
• Verify Python Linux-root sandbox behavior, Unix graceful & forced process-group termination, Windows tree termination, already-exited processes, concurrent close, & combined cleanup errors

---

Summary by cubic

Closes local browser-launching parity gaps across the Python, Go, and TypeScript SDKs. Python previously returned after spawning Chrome and could leave failed launches behind; it now waits for a usable CDP endpoint, while Python and Go reject occupied debugging ports and all SDKs treat empty profile paths as omitted.

Bug Fixes

• Python validates launch options, executable paths, and explicit ports before creating profiles or spawning Chrome; explicit ports must be between 1 and 65535.
• Python Chrome discovery now follows the same precedence and platform candidate order as Go and TypeScript.
• Caller-owned Python profiles are created recursively and preserved, while SDK-owned temporary profiles are removed after failures, cancellation, or close.
• Python disables the Chromium sandbox for Linux root and shuts down process groups or Windows process trees with graceful-then-forced termination.
• Concurrent Python closes share one cleanup task, and shutdown continues profile cleanup while reporting combined errors.
• Go checks loopback port availability before profile creation and preserves non-occupancy socket errors.

Tests

• Shared fixtures and cross-SDK contract tests cover default flags, argument ordering, startup URL, viewport behavior, port handling, and profile ownership.

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

[changeset-bot]

🦋 Changeset detected

Latest commit: a7bccfa

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

This PR includes changesets to release 2 packages

Name	Type
@browserbasehq/stagehand-python	Patch
@browserbasehq/stagehand-go	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 7 files

Architecture diagram

sequenceDiagram
    participant App as SDK Consumer
    participant SDK as Python / Go / TypeScript SDK
    participant Launch as Local Chrome Launcher
    participant Env as Environment and Platform
    participant Port as Loopback Port
    participant Profile as Chrome Profile
    participant Chrome as Chrome Process
    participant CDP as Chrome CDP Endpoint

    Note over App,CDP: Local browser launch runtime flow shared across SDKs

    App->>SDK: Launch local browser(options)
    SDK->>Launch: Validate viewport, scale factor, proxy, and launch options
    alt Invalid options
        Launch-->>SDK: Validation error
        SDK-->>App: Reject launch before resource creation
    else Valid options
        Launch->>Env: Resolve executable
        alt Explicit executable is configured
            Env-->>Launch: Use explicit executable
        else CHROME_PATH is configured
            Env-->>Launch: Use CHROME_PATH executable
        else No explicit path
            Env-->>Launch: Search platform candidates in shared order
        end

        Launch->>Port: Inspect requested loopback port
        alt Automatic port
            Port-->>Launch: Available ephemeral port
        else Explicit port available
            Port-->>Launch: Confirm requested port
        else Explicit port occupied
            Port-->>Launch: Address-in-use error
            Launch-->>SDK: Focused occupied-port error
            SDK-->>App: Reject before profile creation or process spawn
        end

        Launch->>Profile: Resolve profile ownership
        alt Caller-provided profile
            Profile->>Profile: Create directory recursively
            Profile-->>Launch: Preserve caller-owned profile
        else SDK-created temporary profile
            Profile-->>Launch: SDK-owned profile marked for cleanup
        end

        Launch->>Launch: Build ordered shared Chrome flags
        Note over Launch,Chrome: Includes viewport, remote debugging port, profile path, and about:blank
        opt Linux process runs as root
            Launch->>Launch: Disable Chromium sandbox
        end

        Launch->>Chrome: Spawn executable with flags
        alt Spawn fails
            Chrome-->>Launch: Process creation error
            Launch->>Profile: Remove SDK-owned profile
            Launch-->>SDK: Combined launch and cleanup error if cleanup fails
            SDK-->>App: Reject launch
        else Spawn succeeds
            loop Until CDP is ready
                Launch->>CDP: GET /json/version
                alt Valid response with non-empty webSocketDebuggerUrl
                    CDP-->>Launch: CDP readiness
                else Not ready or malformed response
                    CDP-->>Launch: Retry after polling interval
                end
                Chrome-->>Launch: Process exit status
            end

            alt Chrome exits or initialization is cancelled before readiness
                Launch->>Chrome: Terminate owned process
                Launch->>Profile: Remove SDK-owned profile
                Launch-->>SDK: Launch failure and cleanup result
                SDK-->>App: Reject launch
            else Ready
                Launch-->>SDK: Resolved browser with CDP URL and close callback
                SDK-->>App: Return local browser
            end
        end
    end

    App->>SDK: Close local browser
    SDK->>Launch: Run shared close task
    alt Unix platform
        Launch->>Chrome: Graceful process-group termination
        opt Process group does not exit in time
            Launch->>Chrome: Forced process-group termination
        end
    else Windows platform
        Launch->>Chrome: taskkill /T
        opt Process tree remains
            Launch->>Chrome: taskkill /T /F
        end
    end
    Launch->>Profile: Remove SDK-owned profile
    Profile-->>Launch: Cleanup result
    Launch-->>SDK: Preserve caller profile and report combined errors
    SDK-->>App: Close complete

Loading

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

Re-trigger cubic</sub>

[miguelg719]

port=0 used to mean "auto-pick" here but now only None takes the auto path, that's great but passing 0 can cause a hang (_inspect_chrome_port(0) binds fine)

TS rejects this in validateLocalBrowserOptions ("Chrome port must be an integer between 1 and 65535"), should we do the same here?

[seanmcguire12]

passing 0 in the public upstream API would fail pydantic validation, but i can add an extra check here in the internal fn