Mirrored from external contributor PR #2931 after approval by @miguelg719.

Original author: @pr1m8
Original PR: https://github.com/browserbase/stagehand/pull/2931
Approved source head SHA: 4bc630d2f04d6bf697e0903452aef7f3b6837bb3

@pr1m8, please continue any follow-up discussion on this mirrored PR. When the external PR gets new commits, this same internal PR will be marked stale until the latest external commit is approved and refreshed here.

Original description

why

Applications that centralize Browserbase setup need to reuse an existing
@browserbasehq/sdk client when launching or attaching Stagehand browsers.

Today, browserbase.launch() and browserbase.connect() always create a new
Browserbase client. This prevents callers from supplying their own configured
Browserbase management client and endpoint.

what changed

• Add an optional client?: Browserbase option to TypeScript
  browserbase.launch() and browserbase.connect().
• Reuse the supplied client for Browserbase session and extension lifecycle
  operations, including session create, retrieve, release, and extension
  provisioning/cleanup.
• Preserve existing behavior when client is omitted.
• Keep apiKey for Stagehand runtime authentication.
• Document that the supplied client controls Browserbase management requests;
  baseUrl is therefore not used for those requests.
• Add TypeScript factory, lifecycle, contract, package-consumer, and
  cross-language schema-parity coverage.
• Add a minor Changeset for @browserbasehq/stagehand.

test plan

• pnpm build
• pnpm fmt:check
• pnpm check
• pnpm test — 33 workspace tasks passed; 80 test files / 627 tests
• Focused SDK coverage — 20 test files / 282 tests
• Published-package consumer type fixture
• Cross-language schema-parity test
• Go SDK test, vet, build, generator, and example checks
• Full just Python coverage was not run because the disposable validation
  sandbox did not include uv.
• The Go extension-pack consistency check reports a pre-existing mismatch
  in the committed embedded extension archive; this PR changes neither
  artifact.

---

Summary by cubic

Adds an optional client option to browserbase.launch() and browserbase.connect() so callers can reuse an existing @browserbasehq/sdk client for session and extension lifecycle management. Previously these methods always created a new Browserbase client; now they use the supplied client, and existing behavior is unchanged when client is omitted.

• When client is provided, it determines the Browserbase management endpoint; baseUrl is ignored for those calls.
• apiKey still configures Stagehand runtime authentication.