Stagehand Updates & Release Notes

This PR was opened by the Changesets release GitHub action. When you're ready to do a release, you can merge this and the packages will be published to npm automatically. If you're not ready to do a release yet, that's fine, whenever you add more changesets to main, this PR will be updated.

Releases

@browserbasehq/[email protected]

Minor Changes

#3267
cb9a1d1
Thanks @seanmcguire12! - add extension archive getter

#3253
6bf4146
Thanks @seanmcguire12! - add optional extensionCdpUrl to localBrowser.connect to allow configuring the in-browser CDP url

#3263
ecb2a6b
Thanks @seanmcguire12! - add headers to localBrowser.connect so CDP gateways can be authenticated without credentials in the URL

#3183
901eb27
Thanks @supremeboxlogos! - Add page.waitForFunction() to wait until a predicate in the page returns a truthy value.

Patch Changes

#3229
c6b6f27
Thanks @seanmcguire12! - skip caching for request bodies larger than 25 MB.

#3198
10418f9
Thanks @seanmcguire12! - enable WebMCP by default for local chromium versions newer than 157

#3210
1c40ba7
Thanks @seanmcguire12! - Require client transport for Browserbase Model Gateway and cache requests.

#3209
17de6ea
Thanks @seanmcguire12! - Route Browserbase Model Gateway and cache requests through the connected SDK.

@browserbasehq/[email protected]

Patch Changes

Updated dependencies

@browserbasehq/[email protected]

Major Changes

#3210
1c40ba7
Thanks @seanmcguire12! - Require client transport for Browserbase Model Gateway and cache requests.

Minor Changes

#3208
4a7c637
Thanks @seanmcguire12! - Support routing Browserbase Model Gateway and cache requests through the connected SDK.

#3183
901eb27
Thanks @supremeboxlogos! - Add the page.wait_for_function method.

@browserbasehq/[email protected]

Minor Changes

#3208
4a7c637
Thanks @seanmcguire12! - Support routing Browserbase Model Gateway and cache requests through the connected SDK.

#3183
901eb27
Thanks @supremeboxlogos! - Add the page.wait_for_function method.

Patch Changes

#3229
c6b6f27
Thanks @seanmcguire12! - skip caching for request bodies larger than 25 MB.

#3257
113ad81
Thanks @seanmcguire12! - honour a changed extension CDP WS URL when creating a new Stagehand instance after closing the previous one

#3210
1c40ba7
Thanks @seanmcguire12! - Require client transport for Browserbase Model Gateway and cache requests.

@browserbasehq/[email protected]

Minor Changes

#3267
cb9a1d1
Thanks @seanmcguire12! - add extension archive getter

#3265
a31e2da
Thanks @seanmcguire12! - add Headers to LocalBrowserConnectOptions so CDP gateways can be authenticated without credentials in the URL

#3254
9eac212
Thanks @seanmcguire12! - add optional ExtensionCDPURL to LocalBrowserConnectOptions to allow configuring the in-browser CDP url.

#3183
901eb27
Thanks @supremeboxlogos! - Add Page.WaitForFunction to wait until a predicate in the page returns a truthy value.

Patch Changes

#3229
c6b6f27
Thanks @seanmcguire12! - skip caching for request bodies larger than 25 MB.

#3198
10418f9
Thanks @seanmcguire12! - enable WebMCP by default for local chromium versions newer than 157

#3210
1c40ba7
Thanks @seanmcguire12! - Require client transport for Browserbase Model Gateway and cache requests.

#3209
17de6ea
Thanks @seanmcguire12! - Route Browserbase Model Gateway and cache requests through the connected SDK.

@browserbasehq/[email protected]

Minor Changes

#3260
2859fd5
Thanks @seanmcguire12! - add headers to local_browser.connect so CDP gateways can be authenticated without credentials in the URL

#3267
cb9a1d1
Thanks @seanmcguire12! - add extension archive getter

#3252
21e0363
Thanks @seanmcguire12! - add extension_cdp_url to local_browser.connect for clients that reach Chrome through a proxy the extension cannot use

#3183
901eb27
Thanks @supremeboxlogos! - Add page.wait_for_function() to wait until a predicate in the page returns a truthy value.

Patch Changes

#3229
c6b6f27
Thanks @seanmcguire12! - skip caching for request bodies larger than 25 MB.

#3198
10418f9
Thanks @seanmcguire12! - enable WebMCP by default for local chromium versions newer than 157

#3210
1c40ba7
Thanks @seanmcguire12! - Require client transport for Browserbase Model Gateway and cache requests.

#3209
17de6ea
Thanks @seanmcguire12! - Route Browserbase Model Gateway and cache requests through the connected SDK.

@browserbasehq/[email protected]

Patch Changes

Updated dependencies

@browserbasehq/[email protected]

Patch Changes

Updated dependencies []:
@browserbasehq/[email protected]

@browserbasehq/[email protected]

Patch Changes

Updated dependencies []:
@browserbasehq/[email protected]

@browserbasehq/[email protected]

Patch Changes

Updated dependencies []:
@browserbasehq/[email protected]

@browserbasehq/[email protected]

Patch Changes

Updated dependencies

@browserbasehq/[email protected]

@browserbasehq/[email protected]

Patch Changes

Updated dependencies []:
@browserbasehq/[email protected]

@browserbasehq/[email protected]

Patch Changes

Updated dependencies []:
@browserbasehq/[email protected]

@browserbasehq/[email protected]

Patch Changes

Updated dependencies []:
@browserbasehq/[email protected]

@browserbasehq/[email protected]

Patch Changes

Updated dependencies []:
@browserbasehq/[email protected]

@browserbasehq/[email protected]

Patch Changes

Updated dependencies []:
@browserbasehq/[email protected]

@browserbasehq/[email protected]

Patch Changes

Updated dependencies

@browserbasehq/[email protected]

@browserbasehq/[email protected]

Patch Changes

Updated dependencies []:
@browserbasehq/[email protected]

@browserbasehq/[email protected]

Patch Changes

Updated dependencies []:
@browserbasehq/[email protected]

@browserbasehq/[email protected]

Patch Changes

Updated dependencies

@browserbasehq/[email protected]

@browserbasehq/[email protected]

Patch Changes

Updated dependencies []:
@browserbasehq/[email protected]

@browserbasehq/[email protected]

Patch Changes

Updated dependencies []:
@browserbasehq/[email protected]

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Original source

what changed

adds docs for getExtensionArchive(), get_extension_archive(),
ExtensionArchive()

Summary by cubic

Documents the new extension ZIP export helpers and updates the deployment guide to use them instead of the hardcoded node_modules path.

Adds a new "Exporting the Stagehand extension" section covering getExtensionArchive(), get_extension_archive(), and ExtensionArchive(), including upload and local Chrome installation examples.

Updates the deployment guide to export stagehand-extension.zip via the SDK helper before uploading.

Written for commit fd9b57b.

Summary will update on new commits.

Original source

why

Expose browser-side predicate waiting consistently across Stagehand SDKs, without transport polling.

This is PR2 of 2, stacked directly on #3179 (amel/wait-for-function-extension). Polling, navigation recovery, and cleanup live in the parent; merge it first using the repository’s stacked-PR handoff rules.

what changed

Register page.wait_for_function and connect the extension controller/runtime to the internal implementation.

Add TypeScript waitForFunction(expression, arg?, options?), Python wait_for_function(expression, *, arg, polling, timeout), and Go WaitForFunction. As in Playwright, an expression that evaluates to a function is invoked on each poll and receives the optional JSON arg.

Preserve JSON result keys through opaque wire metadata, with roundtrip coverage for own toString, constructor, and hasOwnProperty keys in nested payloads. No browser-handle API is introduced.

Provide RAF/interval polling and no deadline by default in all three SDKs; pass timeout to bound a wait. An omitted or zero timeout also drops the client response deadline.

Derive internal wait options from the canonical protocol contract. Reuse the TypeScript argument serializer. Model Go’s string-or-number polling option through its existing typed-union generator extension point.

Regenerate protocol/models/final ZIP and include docs plus minor release entries for all five packages.

Reviewed with the requested Thermo-Nuclear Code Quality Review skill, including an independent cross-review of SDK boundaries. No SDK polling loops, duplicated serializer, broad generator abstraction, or new 1,000-line file crossing.

test plan

• 9 real-Chrome tests passed, including main-world access, async predicates, custom intervals, error propagation, navigation recovery, concurrent waits, and timeout-zero closure.
• 79 extension/selector tests and 788 protocol/docs/SDK/architecture guards passed.
• 184 Python tests plus Ruff/type checks passed; Go SDK package tests passed.
• Follow-up review: 26 wire tests passed; canonical option types emit unchanged JavaScript, and the rebuilt extension ZIP remains identical.
• Extension/SDK/protocol typechecks, dependency-ordered build, generated-model/ZIP checks, formatting, lint, and git diff --check passed.

Co-authored-by: miguel [email protected]

Original source

Why

To address comments on earlier PRs in this stack.

What changed

Aligned request-header handling across SDKs. HTTP clients supply host & transfer headers; SDKs supply the Browserbase key & Gateway session header. Ordinary application headers remain supported. Malformed headers fail before HTTP dispatch, so Go no longer reports them as retryable network failures.

Preserved non-ASCII response header bytes in Python so the worker can reconstruct the response without rejecting its headers.

Cancelled pending TypeScript Browserbase requests when the browser closes, including when the socket does not deliver another close event.

Reused Python HTTP connections across requests on the same RPC connection, closing the pool after pending requests are cancelled during cleanup.

Skipped cache request bodies larger than 25 MB (25,000,000 UTF-8 bytes) before sending them over RPC. Normal execution continues. An oversized read reports payload_too_large & skips the later write; an independently oversized write is skipped without replacing the read's metadata.

Reported cache read deadlines as timeout, keeping read_failed for other failures & preserving cancellation of the user's operation.

Test plan

Shared header fixtures & local HTTP tests cover filtering, malformed input, preserved application headers, & Python response header decoding.

Lifecycle tests cover explicit browser close, cancellation, Python connection reuse, disconnects, & pool cleanup.

Cache tests cover the exact size boundary, multibyte UTF-8, skipped reads/writes, normal execution after a skip, timeouts, & caller cancellation.

Protocol & SDK tests cover valid initialization, missing browser metadata, removed init fields, & rejection before dispatch. Generator checks verify the validation survives regeneration.

Summary by cubic

Aligns Browserbase HTTP transport behavior across the Go, Python, and TypeScript SDKs so header validation, connection handling, cancellation, and cache error semantics are consistent. Malformed request headers now fail before HTTP dispatch instead of surfacing as retryable network failures, and client Browserbase init params now require browser metadata and reject api_key and api_url since the browser handle's connection supplies those.

What changed

SDKs validate request headers and strip host, content-length, hop-by-hop, and forwarding headers; they supply x-bb-api-key, and for gateway.responses also x-bb-session-id and a default Authorization.

Python preserves non-ASCII response header bytes as Latin-1 so the worker can reconstruct the response without rejecting its headers.

TypeScript cancels pending Browserbase requests when the browser or context closes, including when the socket never emits a close event; Python reuses one HTTP connection per RPC connection and closes the pool during cleanup.

Cache requests whose serialized body exceeds 25,000,000 UTF-8 bytes are skipped with payload_too_large; an independently oversized write is skipped without replacing the read metadata, and cache read timeouts are reported as timeout rather than read_failed.

Written for commit 1900e78.

Summary will update on new commits.

Original source

Why

Chromium versions newer than 157 require enable-features=WebMCP.

What changed

Added the new Chrome flag to defaults.

Summary by cubic

Adds the WebMCP flag to the default local Chrome launch flags across all SDKs so WebMCP works on Chromium versions newer than 157.

Updates the WebMCP flag from --enable-features=WebMCPTesting,DevToolsWebMCPSupport to --enable-features=WebMCP,WebMCPTesting,DevToolsWebMCPSupport in TypeScript, Python, and Go SDKs.

Updates docs and test fixtures to match the new flag.

Written for commit c75f0d9.

Summary will update on new commits.

Original source

This PR was opened by the Changesets release GitHub action. When you're ready to do a release, you can merge this and the packages will be published to npm automatically. If you're not ready to do a release yet, that's fine, whenever you add more changesets to main, this PR will be updated.

Releases

@browserbasehq/[email protected]

Patch Changes

• Updated dependencies
  [bfeda48]:
  @browserbasehq/[email protected]

@browserbasehq/[email protected]

Patch Changes

• #3157
  bfeda48
  Thanks @github-actions! -
  Accept new model IDs for supported providers without a Stagehand release. Reject empty or whitespace-containing IDs and let providers report model availability.

@browserbasehq/[email protected]

Patch Changes

• Updated dependencies
  [bfeda48]:
  @browserbasehq/[email protected]
  
  @browserbasehq/[email protected]
  @browserbasehq/[email protected]

@browserbasehq/[email protected]

Patch Changes

• Updated dependencies []:
  @browserbasehq/[email protected]
  @browserbasehq/[email protected]

@browserbasehq/[email protected]

Patch Changes

• Updated dependencies []:
  @browserbasehq/[email protected]
  @browserbasehq/[email protected]
  @browserbasehq/[email protected]

@browserbasehq/[email protected]

Patch Changes

• Updated dependencies
  [bfeda48]:
  @browserbasehq/[email protected]
  
  @browserbasehq/[email protected]

@browserbasehq/[email protected]

Patch Changes

• Updated dependencies []:
  @browserbasehq/[email protected]
  @browserbasehq/[email protected]

@browserbasehq/[email protected]

Patch Changes

• Updated dependencies []:
  @browserbasehq/[email protected]
  @browserbasehq/[email protected]

@browserbasehq/[email protected]

Patch Changes

• Updated dependencies []:
  @browserbasehq/[email protected]

@browserbasehq/[email protected]

Patch Changes

• Updated dependencies []:
  @browserbasehq/[email protected]

@browserbasehq/[email protected]

Patch Changes

• Updated dependencies []:
  @browserbasehq/[email protected]

@browserbasehq/[email protected]

Patch Changes

• Updated dependencies []:
  @browserbasehq/[email protected]

@browserbasehq/[email protected]

Patch Changes

• Updated dependencies
  [bfeda48]:
  @browserbasehq/[email protected]
  
  @browserbasehq/[email protected]

@browserbasehq/[email protected]

Patch Changes

• Updated dependencies []:
  @browserbasehq/[email protected]

@browserbasehq/[email protected]

Patch Changes

• Updated dependencies []:
  @browserbasehq/[email protected]

@browserbasehq/[email protected]

Patch Changes

• Updated dependencies
  [bfeda48]:
  @browserbasehq/[email protected]
  
  @browserbasehq/[email protected]

@browserbasehq/[email protected]

Patch Changes

• Updated dependencies []:
  @browserbasehq/[email protected]

@browserbasehq/[email protected]

Patch Changes

• Updated dependencies []:
  @browserbasehq/[email protected]

@browserbasehq/[email protected]

Patch Changes

• #3157
  bfeda48
  Thanks @github-actions! -
  Accept new model IDs for supported providers without a Stagehand release. Reject empty or whitespace-containing IDs and let providers report model availability.

@browserbasehq/[email protected]

Patch Changes

• #3157
  bfeda48
  Thanks @github-actions! -
  Accept new model IDs for supported providers without a Stagehand release. Reject empty or whitespace-containing IDs and let providers report model availability.

@browserbasehq/[email protected]

Patch Changes

• #3157
  bfeda48
  Thanks @github-actions! -
  Accept new model IDs for supported providers without a Stagehand release. Reject empty or whitespace-containing IDs and let providers report model availability.

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Original source

This PR was opened by the Changesets release GitHub action. When you're ready to do a release, you can merge this and the packages will be published to npm automatically. If you're not ready to do a release yet, that's fine, whenever you add more changesets to main, this PR will be updated.

Releases

@browserbasehq/[email protected]

Patch Changes

• Updated dependencies
  [bfeda48]:
  @browserbasehq/[email protected]

@browserbasehq/[email protected]

Patch Changes

• #3157
  bfeda48
  Thanks @github-actions! - Accept new model IDs for supported providers without a Stagehand release. Reject empty or whitespace-containing IDs and let providers report model availability.

@browserbasehq/[email protected]

Patch Changes

• Updated dependencies
  [bfeda48]:
  @browserbasehq/[email protected]
  
  @browserbasehq/[email protected]
  @browserbasehq/[email protected]

@browserbasehq/[email protected]

Patch Changes

• Updated dependencies []:
  @browserbasehq/[email protected]

@browserbasehq/[email protected]

Patch Changes

• Updated dependencies []:
  @browserbasehq/[email protected]

@browserbasehq/[email protected]

@browserbasehq/[email protected]

Patch Changes

• Updated dependencies
  [bfeda48]:
  @browserbasehq/[email protected]
  
  @browserbasehq/[email protected]

@browserbasehq/[email protected]

Patch Changes

• Updated dependencies []:
  @browserbasehq/[email protected]

@browserbasehq/[email protected]

@browserbasehq/[email protected]

Patch Changes

• Updated dependencies []:
  @browserbasehq/[email protected]

@browserbasehq/[email protected]

Patch Changes

• Updated dependencies
  [bfeda48]:
  @browserbasehq/[email protected]

@browserbasehq/[email protected]

Patch Changes

• Updated dependencies []:
  @browserbasehq/[email protected]

@browserbasehq/[email protected]

@browserbasehq/[email protected]

Patch Changes

• Updated dependencies []:
  @browserbasehq/[email protected]

@browserbasehq/[email protected]

Patch Changes

• Updated dependencies []:
  @browserbasehq/[email protected]

@browserbasehq/[email protected]

Patch Changes

• Updated dependencies []:
  @browserbasehq/[email protected]

@browserbasehq/[email protected]

Patch Changes

• Updated dependencies []:
  @browserbasehq/[email protected]

@browserbasehq/[email protected]

Patch Changes

• Updated dependencies
  [bfeda48]:
  @browserbasehq/[email protected]
  
  @browserbasehq/[email protected]

@browserbasehq/[email protected]

Patch Changes

• Updated dependencies []:
  @browserbasehq/[email protected]

@browserbasehq/[email protected]

Patch Changes

• Updated dependencies []:
  @browserbasehq/[email protected]

@browserbasehq/[email protected]

Patch Changes

• Updated dependencies
  [bfeda48]:
  @browserbasehq/[email protected]
  
  @browserbasehq/[email protected]

@browserbasehq/[email protected]

Patch Changes

• Updated dependencies []:
  @browserbasehq/[email protected]

@browserbasehq/[email protected]

Patch Changes

• Updated dependencies []:
  @browserbasehq/[email protected]

@browserbasehq/[email protected]

Patch Changes

• #3157
  bfeda48
  Thanks @github-actions! - Accept new model IDs for supported providers without a Stagehand release. Reject empty or whitespace-containing IDs and let providers report model availability.

@browserbasehq/[email protected]

Patch Changes

• #3157
  bfeda48
  Thanks @github-actions! - Accept new model IDs for supported providers without a Stagehand release. Reject empty or whitespace-containing IDs and let providers report model availability.

@browserbasehq/[email protected]

Patch Changes

• #3157
  bfeda48
  Thanks @github-actions! - Accept new model IDs for supported providers without a Stagehand release. Reject empty or whitespace-containing IDs and let providers report model availability.

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Original source

What

Internal hardening of how the browser runtime issues authenticated LLM and Model Gateway requests: they now use a fetch reference captured at startup rather than the ambient global. No public API or behavior change for callers.

Changes

• extension/llm/boundFetch.ts (new) — a fetch reference captured at module load.
• extension/llm/aiSdkClient.ts — pass boundFetch into the provider connection (OpenAI/Anthropic/Google/Groq/Cerebras).
• extension/llm/LLMProvider.ts — pass boundFetch into getAISDKLanguageModel's provider factory.
• extension/llm/gatewayClient.ts — fetchWithoutModel uses boundFetch; createGatewayLanguageModel always passes the load-time reference (previously only when no model config).

sdk-go embedded extension regenerated; gateway-client test updated to the new contract.

Draft — part of an incremental hardening series.

Original source