4/4 Add Browserbase support to Go

[monadoid]

Finishes the Go client by wiring all three browser sources through Stagehand.Init:

• Local Chrome launches through the Go launcher and loads the bundled extension.
• Existing CDP connections preserve caller ownership and support custom headers.
• Browserbase uses a typed net/http client for extension upload, session creation, release, and cleanup.

The Browserbase client validates typed request and response structs through one shared request path, following the same pattern as Zod plus fetch in TypeScript. The public local, CDP, and Browserbase lifecycles are covered by real browser tests.

_{Stack created with GitHub Stacks CLI • Give Feedback 💬}

[changeset-bot]

⚠️ No Changeset found

Latest commit: d27ae74

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

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

[cubic-dev-ai]

All reported issues were addressed across 11 files

Architecture diagram

sequenceDiagram
    participant Client as SDK Consumer
    participant Init as Stagehand.Init
    participant Resolver as resolveBrowserSource
    participant Browserbase as Browserbase Session Client
    participant BBAPI as Browserbase HTTP API
    participant Local as Local Chrome Launcher
    participant CDP as Existing CDP Browser
    participant RPC as CDP RPC Client
    participant Extension as Extension Assets

    Note over Client,RPC: Browser Source Resolution (Init)

    Client->>Init: Init(ctx, params)
    Init->>Resolver: resolveBrowserSource(ctx, params)

    alt BrowserbaseClientBrowserSource
        Resolver->>Resolver: validate API key
        Resolver->>Browserbase: create Browserbase session client
        Browserbase->>BBAPI: uploadExtension(archive)
        BBAPI-->>Browserbase: extension ID
        Browserbase->>BBAPI: createSession(request)
        BBAPI-->>Browserbase: session ID, connect URL
        Browserbase-->>Resolver: resolvedBrowserSource
        Note over Resolver: preloadedExtension = true
    else LocalBrowserSource
        Resolver->>Extension: materializeExtension()
        Extension-->>Resolver: extension dir, cleanup
        Resolver->>Local: launchLocal(ctx, source)
        Local-->>Resolver: resolvedBrowserSource (CDP URL)
        Note over Resolver: extensionDir set, connectTimeout applied
    else CDPBrowserSource
        Resolver->>Resolver: validate CDP URL
        Resolver->>Resolver: build http.Header from map
        Resolver->>Extension: materializeExtension()
        Extension-->>Resolver: extension dir, cleanup
        Note over Resolver: keepAlive = true, close = nil (caller owns)
    end

    Resolver-->>Init: resolvedBrowserSource
    
    Init->>RPC: connectResolvedBrowser(ctx, browser, telemetry)
    RPC->>RPC: connectRPCClient with CDP options
    RPC-->>Init: protocol client
    
    alt connectProtocol fails
        Init->>Init: releaseBrowser(ctx)
        Note over Init: errors.Join(protocol err, release err)
        Init-->>Client: error
    else success
        Init-->>Client: initialized Stagehand
    end

    Note over Client,RPC: Browserbase Session Lifecycle (Close)

    Client->>Init: Close(ctx)
    Init->>Init: releaseBrowser(ctx)

    alt keepAlive = true (CDP caller-owned)
        Init->>Init: skip close, run cleanup only
    else keepAlive = false (Browserbase)
        alt close != nil (Browserbase session)
            Init->>Browserbase: browser.close(ctx)
            Browserbase->>BBAPI: releaseSession(ctx, sessionID)
            Browserbase->>BBAPI: deleteExtension(ctx, extensionID)
            Note over Browserbase: mutex protects against double-close
        end
    end
    
    opt cleanup != nil (local/CDP extension dir)
        Init->>Extension: cleanup()
    end

    Init-->>Client: errors.Join(close err, cleanup err)

Loading

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

Re-trigger cubic</sub>