Add Go browser transport and Browserbase session foundations

[miguelg719]

why

Ports the merged TypeScript browser-lifecycle stack (#2517–#2523) to the Go SDK. This bottom PR lands the internal plumbing the factory lifecycle needs — borrow-don't-own transports and Browserbase session connect semantics — with zero public API change.

what changed

• adds transport ownership to rpcClient: shutdown still cancels, rejects pending calls, and clears handlers, but only closes the transport when owned
• adds retrieveSession (GET /v1/sessions/{id}) to the Browserbase client with deliberately lenient validation (id required; connectUrl/region optional)
• adds internal connectSession that never takes release ownership of an existing session
• caller-supplied extension IDs suppress Stagehand extension provisioning and cleanup on every path (success, create failure, close)

intentionally not included

• no exported identifier added or changed; legacy New/Init/Close behavior is unchanged
• no factories, no Browser handle, no Create

stack

1. this PR — transport and Browserbase session foundations
2. Implement Go browser factories and stagehand.Create #2548 — browser factories and stagehand.Create
3. Remove the legacy Go Stagehand lifecycle #2549 — remove the legacy lifecycle and migrate consumers

test plan

• table tests for un-owned shutdown (transport left open, pending calls still rejected), httptest coverage for retrieveSession, fake-API cases proving caller extension IDs are never uploaded/deleted
• full package gates green: gofmt, go vet, go build, go test, generator --check, examples compile, root pnpm run test:unit, changeset check

[changeset-bot]

⚠️ No Changeset found

Latest commit: 4582c6d

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]

3 issues found across 7 files

Confidence score: 3/5

• In packages/sdk-go/browserbase_session.go and packages/sdk-go/browserbase_client.go, session create/retrieve failures currently propagate raw Browserbase response details through returned errors, which can leak upstream internals to SDK consumers and make error contracts inconsistent — map these paths to the fixed session-safe error and drop the upstream cause/body.
• In packages/sdk-go/browserbase_client.go, retrieved ConnectURL values are not validated for ws/wss and can be http, relative, or malformed, which risks runtime CDP connection failures or unsafe endpoint usage — apply the same strict WebSocket URL validation used in create-session before accepting the endpoint.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/sdk-go/browserbase_session.go">

<violation number="1" location="packages/sdk-go/browserbase_session.go:171">
P2: Failed Browserbase lookups expose upstream response details through the returned error. Return a fixed session error without retaining the upstream cause.

(Based on your team's feedback about sanitizing Browserbase session errors.) [FEEDBACK_USED]</violation>
</file>

<file name="packages/sdk-go/browserbase_client.go">

<violation number="1" location="packages/sdk-go/browserbase_client.go:183">
P2: Session retrieval failures preserve the raw Browserbase response body and message through the connect error path, so upstream details can reach SDK consumers. Convert create/retrieve failures to the session-safe error before wrapping or returning them, without retaining `BrowserbaseAPIError` as a cause.

(Based on your team's feedback about sanitizing Browserbase session errors.) [FEEDBACK_USED]</violation>

<violation number="2" location="packages/sdk-go/browserbase_client.go:827">
P2: A retrieved `connectUrl` with `http`, a relative URL, or malformed WebSocket URL passes validation and is later used as the CDP endpoint. Validate a present `ConnectURL` with the same `ws`/`wss` check as create-session responses, while still allowing it to be omitted.</violation>
</file>

Architecture diagram

sequenceDiagram
    participant Ext as External Caller
    participant SessClient as browserbaseSessionClient
    participant BBClient as browserbaseHTTPClient
    participant FakeAPI as fakeBrowserbaseAPI (test)
    participant RPC as rpcClient
    participant Transport as rpcTransport (WebSocket)

    Note over Ext,Transport: NEW: Borrow-Don't-Own Transport
    
    Ext->>RPC: newRPCClient(transport, ownsTransport)
    alt ownsTransport = true
        RPC->>RPC: Store transport ownership flag
        RPC->>RPC: Cancel context, reject pending calls
        RPC->>Transport: Close transport on shutdown
    else ownsTransport = false
        RPC->>RPC: Store transport ownership flag
        RPC->>RPC: Cancel context, reject pending calls
        RPC->>RPC: Skip transport.Close() on shutdown
    end
    Transport-->>RPC: (transport not closed)

    Note over Ext,BBClient: NEW: Browserbase Session Connect

    Ext->>SessClient: connectSession(ctx, sessionID)
    SessClient->>SessClient: Normalize & validate sessionID
    SessClient->>BBClient: retrieveSession(ctx, sessionID)
    BBClient->>BBClient: Encode GET /v1/sessions/{sessionID}
    BBClient->>BBClient: Validate session ID required
    BBClient->>External API: HTTP GET /v1/sessions/{id}
    External API-->>BBClient: browserbaseRetrieveSessionResponse
    BBClient->>BBClient: Validate response (id required, connectUrl/region optional)
    BBClient-->>SessClient: browserbaseRetrieveSessionResponse
    SessClient->>SessClient: Validate retrieved session
    SessClient->>SessClient: Extract ConnectURL (trim spaces)
    alt ConnectURL empty
        SessClient-->>Ext: Error: session not available
    else ConnectURL present
        SessClient-->>Ext: browserbaseSessionConnection{ sessionID, cdpURL, region }
    end

    Note over Ext,FakeAPI: NEW: Caller-Supplied Extension IDs

    Ext->>SessClient: createSession(ctx, params)
    SessClient->>SessClient: browserbaseCallerExtensionID(params)
    alt Caller provided ExtensionID (top-level or BrowserSettings)
        SessClient->>SessClient: Use caller's ExtensionID directly
        SessClient->>SessClient: Set request.ExtensionID = callerExtensionID
        SessClient->>SessClient: ownsExtension = false
    else No caller ExtensionID
        SessClient->>SessClient: Use pending-stagehand-extension placeholder
        SessClient->>SessClient: Upload Stagehand extension via api.uploadExtension()
        SessClient->>SessClient: Set request.ExtensionID = uploadedID
        SessClient->>SessClient: ownsExtension = true
    end
    
    SessClient->>BBClient: createSession(ctx, request)
    BBClient-->>SessClient: browserbaseCreateSessionResponse
    
    alt Create failed
        SessClient->>SessClient: deleteExtensionBestEffort(ctx, extensionID, ownsExtension)
        alt ownsExtension
            SessClient->>BBClient: deleteExtension(ctx, extensionID)
        end
        SessClient-->>Ext: Error
    else Session invalid
        SessClient->>SessClient: cleanupInvalidSession(ctx, sessionID, extensionID, ownsExtension)
        SessClient->>BBClient: releaseSession(ctx, sessionID)
        alt ownsExtension
            SessClient->>BBClient: deleteExtension(ctx, extensionID)
        end
        SessClient-->>Ext: Error
    end
    
    Note over Ext,FakeAPI: NEW: Extension cleanup respects ownership
    
    Ext->>SessClient: resources.close(ctx)
    alt ownsExtension AND not already deleted
        SessClient->>BBClient: deleteExtension(ctx, extensionID)
    end
    SessClient->>BBClient: releaseSession(ctx, sessionID)

    Note over Ext,FakeAPI: TEST: Caller extensions never uploaded/deleted
    
    Ext->>FakeAPI: createSession with caller ExtensionID
    FakeAPI->>SessClient: Handle session creation
    alt Success path
        FakeAPI-->>Ext: no uploadExtension/deleteExtension calls
    else Create failure path
        FakeAPI-->>Ext: no uploadExtension/deleteExtension calls
    else Invalid session path
        FakeAPI-->>Ext: no uploadExtension/deleteExtension calls
    end
    alt Close after success
        SessClient->>FakeAPI: releaseSession called
        FakeAPI-->>Ext: no deleteExtension calls
    end

    Note over Ext,FakeAPI: TEST: Owned extension gets uploaded/deleted
    
    Ext->>FakeAPI: createSession without caller extension
    FakeAPI->>FakeAPI: uploadExtension called
    FakeAPI->>SessClient: Handle session
    SessClient->>FakeAPI: releaseSession called
    alt Close session
        FakeAPI->>FakeAPI: deleteExtension called
    end

    Note over Ext,Transport: CHANGED: RPC transport ownership in connectRPCClient
    
    Ext->>RPC: connectRPCClient(wsURL)
    RPC->>Transport: WebSocket connect
    RPC->>RPC: newRPCClient(transport, ownsTransport=true)
    Transport-->>Ext: rpcClient with owned transport

Loading

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

Re-trigger cubic</sub>