feat(sdk-go): add Browserbase ClientOptions to launch and connect (#3123)

# why

Stacked on #3119 (Python), which is stacked on #3118 (TypeScript). Those
PRs add Browserbase client options to `browserbase.launch()` /
`browserbase.connect()` in TS and Python. This PR adds the Go
equivalent, so the three SDKs are at parity again and the parity test no
longer needs a Go exemption.

# what changed

- New `BrowserbaseClientOptions` struct, set as `ClientOptions
*BrowserbaseClientOptions` on both `BrowserbaseLaunchOptions` and
`BrowserbaseConnectOptions`:
- `Timeout time.Duration`: applies to each attempt; 0 keeps the 60s
default.
  - `MaxRetries *int`: nil keeps the default of 2.
- `DefaultHeaders map[string]string`, `DefaultQuery map[string]string`.
  - `HTTPClient *http.Client`: owned by the caller and never modified.
- Go talks to Browserbase over its own `net/http` client, so the
internal options it already had (HTTP client, max retries) are now
exposed, plus headers and query.
- The timeout is applied per attempt through the request context, both
for the default client and for a client the caller passes in, and it
also covers reading the response body. The default client no longer sets
`http.Client.Timeout` itself. If an attempt times out, only requests
that are safe to resend (retrieve, release, delete) are retried, each
with a new deadline. Creates fail immediately.
- Negative `Timeout` or `MaxRetries`, invalid header names, and header
values containing control characters are rejected before any request is
sent.
- `ClientOptions` is never sent in the session-create body; a test
checks the body contents.
- Removes `pendingGoBrowserFields` from the cross-language parity test.
- Docs: the client-options section is a TypeScript / Python / Go tab
group again.
- Adds a minor changeset for `@browserbasehq/stagehand-go`. This PR is
the only change in the stack that releases Go.

# header precedence

Same rule as TS and Python: `DefaultHeaders` override Stagehand's own
headers on conflict, including `X-BB-API-Key` and `User-Agent`. Both
Browserbase SDKs apply caller default headers last; this was checked in
their source (`@browserbasehq/sdk` `index.js` `defaultHeaders`, and the
Python `_base_client`). Go still rejects invalid header names or values
before sending.

# test plan

- [x] `go vet`; gofmt (prints nothing); `go test -race` on every package
except examples; generator `--check`; `scripts/check-examples.sh`
- [x] New `browserbase_client_options_test.go` uses `httptest` servers
to cover:
- options reaching requests, and later changes to the caller's maps
having no effect;
- default headers and query on POST and GET, with caller defaults
overriding Stagehand's headers (mutation-checked);
  - `MaxRetries` set to 0 and 1, and the default;
- the per-attempt timeout, including a retry getting a new deadline and
the deadline covering the response body;
  - a caller `HTTPClient` being used and left unmodified;
- invalid options failing with zero requests reaching the server, on
both launch and connect;
  - full launch and connect through the real factory.
- [x] Mutation-checked: with the per-attempt deadline removed, the
timeout test fails in about 5s with a clear message.
- [x] `rules/ast-grep` parity tests (Go exemption removed), docs tests,
the TS suite, oxfmt, oxlint, `check-changesets`
- [ ] Plain `go test ./...` fails only because
`packages/sdk-go/examples` doesn't build as a single package; that was
already the case. CI and the justfile exclude `/examples`.
- [ ] No live Browserbase session was launched

Author: miguelg719

.changeset/browserbase-client-options-go.md

@@ -0,0 +1,5 @@
+---
+"@browserbasehq/stagehand-go": minor
+---
+
+Add `ClientOptions` to `LaunchBrowserbase` and `ConnectBrowserbase`.

packages/docs/v4/configuration/browser.mdx

@@ -180,8 +180,10 @@ The Browserbase URL controls extension, session, and connection requests that `b
 
 ### Browserbase client options
 
-`browserbase.launch()` and `browserbase.connect()` create a Browserbase SDK client for session and extension requests. Pass `clientOptions` (TypeScript) or `client_options` (Python) to tune that client's timeout, retries, default headers, and default query parameters. TypeScript also accepts a custom `fetch`, and Python accepts an `httpx.AsyncClient` as `http_client`. `apiKey` and `baseUrl` stay top-level, so one key authenticates both Browserbase and Stagehand.
+`browserbase.launch()` and `browserbase.connect()` create a Browserbase client for session and extension requests. Pass `clientOptions` (TypeScript), `client_options` (Python), or `ClientOptions` (Go) to tune that client's timeout, retries, default headers, and default query parameters. TypeScript also accepts a custom `fetch`, Python accepts an `httpx.AsyncClient` as `http_client`, and Go accepts an `*http.Client` as `HTTPClient`. `apiKey` and `baseUrl` stay top-level, so one key authenticates both Browserbase and Stagehand.
 
+<Tabs>
+<Tab title="TypeScript">
 ```typescript
 const browser = await browserbase.launch({
   apiKey: process.env.BROWSERBASE_API_KEY,
@@ -192,7 +194,9 @@ const browser = await browserbase.launch({
   },
 });
 ```
+</Tab>
 
+<Tab title="Python">
 ```python
 browser = await browserbase.launch(
     api_key=os.environ["BROWSERBASE_API_KEY"],
@@ -203,8 +207,28 @@ browser = await browserbase.launch(
     },
 )
 ```
+</Tab>
+
+<Tab title="Go">
+```go
+maxRetries := 1
+browser, err := stagehand.LaunchBrowserbase(ctx, stagehand.BrowserbaseLaunchOptions{
+	APIKey: os.Getenv("BROWSERBASE_API_KEY"),
+	ClientOptions: &stagehand.BrowserbaseClientOptions{
+		Timeout:        30 * time.Second, // per attempt
+		MaxRetries:     &maxRetries,
+		DefaultHeaders: map[string]string{"X-Request-Source": "my-app"},
+		// HTTPClient: myHTTPClient, // optional caller-owned *http.Client
+	},
+})
+if err != nil {
+	return err
+}
+```
+</Tab>
+</Tabs>
 
-Units follow each Browserbase SDK: TypeScript timeouts are in milliseconds and Python timeouts are in seconds. Stagehand never closes an `http_client` you pass; keep it open until `browser.close()` returns, because releasing the session uses it.
+Units follow each SDK: TypeScript timeouts are in milliseconds, Python timeouts are in seconds, and Go uses a `time.Duration` that bounds each attempt. Stagehand never closes an `http_client` you pass; keep it open until `browser.close()` returns, because releasing the session uses it. Go never modifies an `HTTPClient` you pass, so its own `Timeout` and `Transport` still apply. In every SDK, default headers override the client's own headers on conflict, including `X-BB-API-Key` and `User-Agent`. Go rejects invalid header names or values before sending any request.
 
 ### Environment variables
 

packages/sdk-go/browser_factories.go

@@ -5,7 +5,9 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
+	"net/http"
 	"strings"
+	"time"
 
 	"github.com/browserbase/stagehand/packages/sdk-go/v4/internal/extensionassets"
 )
@@ -40,10 +42,28 @@ type LocalBrowserConnectOptions struct {
 	ExtensionID string
 }
 
+// BrowserbaseClientOptions configures the HTTP client Stagehand uses for
+// Browserbase session and extension requests.
+type BrowserbaseClientOptions struct {
+	// Timeout bounds each request attempt. Zero keeps the 60 second default.
+	Timeout time.Duration
+	// MaxRetries caps retries of replay-safe requests. Nil keeps the default of 2.
+	MaxRetries *int
+	// DefaultHeaders are added to every request and override Stagehand's own
+	// headers (including X-BB-API-Key and User-Agent) on conflict.
+	DefaultHeaders map[string]string
+	// DefaultQuery parameters are added to every request URL.
+	DefaultQuery map[string]string
+	// HTTPClient sends the requests. Stagehand never modifies it; Timeout is
+	// applied per attempt through the request context. Nil uses a default client.
+	HTTPClient *http.Client
+}
+
 // BrowserbaseLaunchOptions configures a newly launched Browserbase session.
 type BrowserbaseLaunchOptions struct {
 	APIKey          string
 	BaseURL         string
+	ClientOptions   *BrowserbaseClientOptions
 	BrowserSettings *BrowserbaseBrowserSettings
 	ExtensionID     *string
 	KeepAlive       *bool
@@ -55,10 +75,11 @@ type BrowserbaseLaunchOptions struct {
 
 // BrowserbaseConnectOptions configures a connection to an existing Browserbase session.
 type BrowserbaseConnectOptions struct {
-	APIKey      string
-	BaseURL     string
-	SessionID   string
-	ExtensionID string
+	APIKey        string
+	BaseURL       string
+	ClientOptions *BrowserbaseClientOptions
+	SessionID     string
+	ExtensionID   string
 }
 
 type browserbaseFactoryClient interface {
@@ -68,7 +89,7 @@ type browserbaseFactoryClient interface {
 
 type browserFactoryDependencies struct {
 	launchLocal             func(context.Context, LocalBrowserLaunchOptions) (resolvedBrowserSource, error)
-	createBrowserbaseClient func(string, string) (browserbaseFactoryClient, error)
+	createBrowserbaseClient func(apiKey string, baseURL string, clientOptions *BrowserbaseClientOptions) (browserbaseFactoryClient, error)
 	connectCDP              func(context.Context, cdpClientOptions) (*cdpClient, error)
 	materializeExtension    func() (string, func() error, error)
 	commandSender           func(*cdpClient) browserCommandSender
@@ -198,7 +219,7 @@ func launchBrowserbaseWithDependencies(ctx context.Context, options BrowserbaseL
 	}
 	defer cancelLifecycle()
 
-	client, err := browserbaseClientForFactory(options.APIKey, options.BaseURL, dependencies)
+	client, err := browserbaseClientForFactory(options.APIKey, options.BaseURL, options.ClientOptions, dependencies)
 	if err != nil {
 		return nil, err
 	}
@@ -232,7 +253,7 @@ func connectBrowserbaseWithDependencies(ctx context.Context, options Browserbase
 	}
 	defer cancelLifecycle()
 
-	client, err := browserbaseClientForFactory(options.APIKey, options.BaseURL, dependencies)
+	client, err := browserbaseClientForFactory(options.APIKey, options.BaseURL, options.ClientOptions, dependencies)
 	if err != nil {
 		return nil, err
 	}
@@ -249,19 +270,19 @@ func connectBrowserbaseWithDependencies(ctx context.Context, options Browserbase
 	}, dependencies)
 }
 
-func browserbaseClientForFactory(apiKey string, baseURL string, dependencies browserFactoryDependencies) (browserbaseFactoryClient, error) {
+func browserbaseClientForFactory(apiKey string, baseURL string, clientOptions *BrowserbaseClientOptions, dependencies browserFactoryDependencies) (browserbaseFactoryClient, error) {
 	if strings.TrimSpace(apiKey) == "" {
 		return nil, errors.New("stagehand Browserbase API key is required")
 	}
 	factory := dependencies.createBrowserbaseClient
 	if factory == nil {
-		factory = func(apiKey string, baseURL string) (browserbaseFactoryClient, error) {
+		factory = func(apiKey string, baseURL string, clientOptions *BrowserbaseClientOptions) (browserbaseFactoryClient, error) {
 			return newBrowserbaseSessionClient(apiKey, browserbaseSessionClientOptions{
-				http: browserbaseHTTPClientOptions{baseURL: baseURL},
+				http: browserbaseHTTPClientOptionsFor(baseURL, clientOptions),
 			})
 		}
 	}
-	client, err := factory(apiKey, baseURL)
+	client, err := factory(apiKey, baseURL, clientOptions)
 	if err != nil {
 		return nil, fmt.Errorf("create Stagehand Browserbase client: %w", err)
 	}

packages/sdk-go/browser_test.go

@@ -646,9 +646,12 @@ func TestBrowserbaseFactoryMetadataAndExtensionRouting(t *testing.T) {
 			}
 			var connected cdpClientOptions
 			var configuredBaseURL string
+			var configuredClientOptions *BrowserbaseClientOptions
+			clientOptions := &BrowserbaseClientOptions{Timeout: time.Second, MaxRetries: testPointer(0)}
 			dependencies := browserFactoryDependencies{
-				createBrowserbaseClient: func(_ string, baseURL string) (browserbaseFactoryClient, error) {
+				createBrowserbaseClient: func(_ string, baseURL string, clientOptions *BrowserbaseClientOptions) (browserbaseFactoryClient, error) {
 					configuredBaseURL = baseURL
+					configuredClientOptions = clientOptions
 					return client, nil
 				},
 				connectCDP: func(_ context.Context, options cdpClientOptions) (*cdpClient, error) {
@@ -659,10 +662,10 @@ func TestBrowserbaseFactoryMetadataAndExtensionRouting(t *testing.T) {
 			var browser *Browser
 			var err error
 			if test.connect {
-				browser, err = connectBrowserbaseWithDependencies(context.Background(), BrowserbaseConnectOptions{APIKey: "key", BaseURL: "https://api.dev.browserbase.com", SessionID: "retrieved", ExtensionID: test.extensionID}, dependencies)
+				browser, err = connectBrowserbaseWithDependencies(context.Background(), BrowserbaseConnectOptions{APIKey: "key", BaseURL: "https://api.dev.browserbase.com", ClientOptions: clientOptions, SessionID: "retrieved", ExtensionID: test.extensionID}, dependencies)
 			} else {
 				browser, err = launchBrowserbaseWithDependencies(context.Background(), BrowserbaseLaunchOptions{
-					APIKey: "key", BaseURL: "https://api.dev.browserbase.com", ExtensionID: &extensionID, KeepAlive: &keepAlive,
+					APIKey: "key", BaseURL: "https://api.dev.browserbase.com", ClientOptions: clientOptions, ExtensionID: &extensionID, KeepAlive: &keepAlive,
 					Region: &region, UserMetadata: userMetadata,
 				}, dependencies)
 			}
@@ -672,6 +675,9 @@ func TestBrowserbaseFactoryMetadataAndExtensionRouting(t *testing.T) {
 			if configuredBaseURL != "https://api.dev.browserbase.com" {
 				t.Fatalf("Browserbase base URL = %q", configuredBaseURL)
 			}
+			if configuredClientOptions != clientOptions {
+				t.Fatalf("Browserbase client options = %#v, want %#v", configuredClientOptions, clientOptions)
+			}
 			if !test.connect {
 				created := client.createOptions
 				if created.ExtensionID == nil || *created.ExtensionID != extensionID ||