# why
Browserbase can solve captchas asynchronously, but agents were still
trying to interact with the page while the solver was active. That led
to CUA and DOM/hybrid flows clicking solved captcha widgets again,
pausing on confirmation questions, or resuming with stale assumptions
instead of continuing the original task cleanly.
This PR pauses agent execution while Browserbase's captcha solver is
active and hardens the post-solve resume path so the agent keeps working
on the original task after Browserbase finishes.
# what changed
- added a shared `CaptchaSolver` utility that listens for Browserbase
`browserbase-solving-started/finished/errored` console events, supports
concurrent waiters, and disposes listeners cleanly
- paused DOM/hybrid `prepareStep` execution and CUA `prepareStep` /
action execution while Browserbase is solving a captcha
- enabled Browserbase captcha solving by default unless
`browserSettings.solveCaptchas: false`
- updated agent prompts and follow-up messages to tell the model that
captchas are handled automatically and should not be clicked again after
they are solved
- added OpenAI CUA recovery behavior so it can:
- carry one-shot context notes into the next model turn
- auto-continue when the model asks for confirmation instead of acting
- guard post-solve clicks that target the solved captcha widget and
restate the original instruction so the model re-anchors on the task
- added focused unit coverage for solver state, Browserbase session
accessors, CUA/regular agent hooks, and OpenAI CUA confirmation handling
# test plan
- `pnpm --filter @browserbasehq/stagehand lint`
- `pnpm --filter @browserbasehq/stagehand build:esm`
- `cd packages/core && pnpm exec vitest run --config
vitest.esm.config.mjs dist/esm/tests/unit/openai-cua-client.test.js
dist/esm/tests/unit/captcha-solver.test.js
dist/esm/tests/unit/agent-captcha-hooks.test.js
dist/esm/tests/unit/browserbase-session-accessors.test.js`
Browserbase smoke:
- OpenAI CUA + reCAPTCHA demo: strict pass on `Verification Success`
- Anthropic CUA + reCAPTCHA demo: strict pass on `Verification Success`
- Hybrid Gemini + reCAPTCHA demo: strict pass on `Verification Success`
- OpenAI CUA + `solveCaptchas: false`: solver stays disabled, no
wait/resume path is triggered, and the agent stops at the captcha
instead of bypassing it
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: Shrey Pandya <shrey@browserbase.com>
# why
Monarch Money reported a bug in the Python SDK (stagehand-python
v3.6.0).
In src/stagehand/_streaming.py, both the sync Stream.__stream__() (line
62-63) and async AsyncStream.__stream__() (line 147-148) have:
```
python
if sse.data.startswith('{"data":{"status":"finished"'):
break # ← drops the event without yielding it
```
When the server sends the finished SSE event (which contains success,
message, actions, usage, and messages), the SDK immediately breaks out
of the loop without yielding the event to the caller. This means the
final result payload is silently dropped.
# what changed
The streaming on_event config had `handle: done` for the
`{"data":{"status":"finished"...}}` event. Stainless generates this as a
bare break, which exits the SSE loop without yielding the event –
silently dropping the final result payload (success status, message,
actions, usage, and messages) from every streaming response.
Fix – Changed to `handle: yield` so the finished event is delivered to
callers before the stream terminates. This is safe because the server
explicitly calls `reply.raw.end()` immediately after sending the
finished event (packages/server-v3/src/lib/stream.ts), so the SSE
connection closes right after the yield and the loop exits naturally on
EOF – no hang risk.
# test plan
Regenerate SDKs and confirm fix
# Why
Add Browserbase Search API as the primary search tool for agents (`POST
/v1/search`), leveraging the Browserbase API key users already have
configured. Brave Search remains fully supported as a backwards
compatible fallback for existing users with `BRAVE_API_KEY` set.
# What Changed
- **Browserbase Search tool**: New search tool powered by the
Browserbase Search API, enabled via `useSearch: true` in
`agent.execute()`.
- **Brave Search (backwards-compatible)**: Existing users with
`BRAVE_API_KEY` in their environment continue to get the search tool
automatically with no code changes required.
- **Priority**: `useSearch: true` with a Browserbase API key takes
precedence. If not set, falls back to Brave if `BRAVE_API_KEY` is
present.
- **Validation**: If `useSearch: true` is set without a valid
Browserbase API key, a clear error is thrown at preparation time (before
the agent loop starts).
- **Separate files**: `browserbaseSearch.ts` and `braveSearch.ts` keep
the implementations cleanly isolated.
```typescript
const agent = stagehand.agent({ mode: "hybrid" });
const result = await agent.execute({
instruction: "use the search tool to find me the capital of france",
useSearch: true,
});
```
# Test Plan
- [x] Run agent with `useSearch: true` and a valid `BROWSERBASE_API_KEY`
— Browserbase search tool should return results
- [x] Run agent with `useSearch: true` and no Browserbase API key —
should throw `MissingEnvironmentVariableError`
# why
Allow users to pass custom headers in their LLM calls
# what changed
Add headers to the model.ts types
# test plan
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Adds `headers` support to `ClientOptions` so clients can send custom
HTTP headers with every provider request. Useful for auth tokens or
routing hints without changing global config.
- **New Features**
- Added `headers?: Record<string, string>` to `ClientOptions` in
`packages/core/lib/v3/types/public/model.ts`; headers are sent with each
request.
- No breaking changes; default behavior is unchanged.
<sup>Written for commit 424dc1af74da82364f752f3976182f8aafc3f6ed.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1817">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
## Summary
- Adds `--context-id <id>` and `--persist` flags to `browse open` so
agents can load/persist browser state (cookies, localStorage, etc.)
across Browserbase sessions using Contexts
- Validates edge cases: `--persist` requires `--context-id`,
`--context-id` requires remote mode, context change triggers daemon
restart
## Usage
```bash
# Load a context (read-only — state not saved back)
browse open https://app.com --context-id ctx_abc123
# Load and persist changes back on session end
browse open https://app.com --context-id ctx_abc123 --persist
```
## How it works
1. `browse open --context-id` writes context config to
`/tmp/browse-{session}.context`
2. The daemon reads this file during browser initialization and passes
it through as `browserbaseSessionCreateParams.browserSettings.context`
3. If a second `browse open` is called with a different context ID, the
daemon is restarted (context is baked into the BB session at creation
time)
Context config uses a temp file (same pattern as `.mode`) because it's
needed at Browserbase session creation time, before the daemon's command
socket is up.
## Test plan
- [x] `browse open https://example.com --context-id <known-id>
--persist` on remote mode — verify session created with context in BB
dashboard
- [x] `browse stop` then reopen with same context — verify state
persists
- [x] Verify context mismatch triggers daemon restart (open with context
A, then open with context B)
- [x] Same context, second open — verify no unnecessary restart
- [x] `browse open https://example.com --context-id <id>` on local mode
— verify clear error
- [x] `browse open https://example.com --persist` without `--context-id`
— verify clear error
- [x] Plain `browse open` (no context flags) — verify no regression
- [x] `cleanupStaleFiles` removes `.context` file on shutdown
- [x] Stale `.context` file from crashed daemon is cleared on next
`browse open` without `--context-id`
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
# Why
OpenAI organizations with Zero Data Retention (ZDR) rejects stored
responses from the Responses API (`store: true` is the default when the
AI SDK auto selects it). This causes agent runs to fail
# What Changed
- Set `openai: { store: false }` in `providerOptions` across
`generateText` / `streamText` calls: `v3AgentHandler.ts` (execute +
stream), `handleDoneToolCall.ts`,
- Simplified the existing Gemini `providerOptions` — removed the
conditional `modelId.includes("gemini-3")` check and always pass
`google: { mediaResolution: "MEDIA_RESOLUTION_HIGH" }` since non-Google
providers ignore it.
# Test Plan
- [ ] Run agent in mode with an OpenAI model to confirm no breaking
changes
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Defaulted agent calls to OpenAI to not store responses, preventing
failures for Zero Data Retention orgs. Also simplified Gemini options by
always sending high media resolution.
- **Bug Fixes**
- Set `providerOptions.openai.store` to `false` for agent `generateText`
and `streamText` calls in `v3AgentHandler` (execute + stream) and
`handleDoneToolCall`, avoiding Responses API rejections in ZDR orgs.
- **Refactors**
- Always pass `google: { mediaResolution: "MEDIA_RESOLUTION_HIGH" }` in
`providerOptions`; non-Google providers ignore it. Added a changeset for
a patch release of `@browserbasehq/stagehand`.
<sup>Written for commit a01d8c07fb15080c264aad2998bf047941113920.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1814">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
## Summary
- `browse env` showed stale "local" mode after `browse env remote`
- Root cause: `.mode` file was only written during lazy browser init
(`ensureBrowserInitialized`), not at daemon startup. Between daemon
start and first command, `readCurrentMode()` returned `null` and fell
back to hardcoded `"local"`
- Write `.mode` eagerly in `runDaemon()` at startup so it's immediately
available
- Fall back to `desiredMode` instead of `"local"` in the `env` display
handler as a safety net
## Test plan
- [x] Reproduced bug: `browse env remote` → `browse env` showed
`"mode":"local"`
- [x] Verified fix: `browse env remote` → `browse env` now shows
`"mode":"remote"`
- [x] `mode.test.ts` passes (3/3)
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Fixes `browse env` showing stale "local" after `browse env remote`
(STG-1547). The daemon now writes `.mode` at startup, the display falls
back to `desiredMode` until mode is written, and a patch changeset is
added for `@browserbasehq/browse-cli`.
<sup>Written for commit 9661d92de26f60383a1d77c6c636f43aa95089e4.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1806">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
# why
# what changed
# test plan
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Corrects the changeset package reference from
`@browserbasehq/stagehand-server` to
`@browserbasehq/stagehand-server-v3` to unblock CI and ensure the
correct package receives the patch release.
<sup>Written for commit 177bc48b84a442ad4e0d9f85c7dffcfc338720de.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1801">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
## Summary
- Adds support for CDP (Chrome DevTools Protocol) extra HTTP headers
when connecting to browser sessions
- Passes `extraHTTPHeaders` from the Stagehand config through to the CDP
connection layer
- Warns when `cdpHeaders` provided without `cdpUrl`
- Includes integration test for the new functionality
Related: #1737
Co-authored-by: aditya-silna <aditya@silnahealth.com>
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: aditya-silna <aditya@silnahealth.com>
# why
- to allow for setting HTTP headers at the page level
# what changed
- added new function `page.setExtraHTTPHeaders()` , which sets HTTP
headers for the CDP session of the page, and all of its child sessions
(eg, iframes)
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Adds page.setExtraHTTPHeaders() to set per-page HTTP headers on all
requests from the page and its iframes. Applies to pipeline sessions
immediately and replays on newly adopted child sessions. Addresses ST
LaurensG- NB: STG-1316.
<sup>Written for commit cf677c219f48302427af40921f02ce90c2399692.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1774">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
## Summary
- expose `headers` on `GoogleVertexProviderSettings` in Stagehand public model types
- add a public API type test proving model configs with headers are accepted for google/openai/anthropic
- add a patch changeset
## Context
Runtime already forwards provider options to `createVertex()`, but TypeScript rejected `headers` in model config. This aligns public types with runtime behavior.
## Validation
- `pnpm -C packages/core run typecheck`
- `pnpm -C packages/core run build:esm`
- `pnpm -C packages/core run test:core -- packages/core/dist/esm/tests/unit/public-api/llm-and-agents.test.js`
- `pnpm -C packages/core run test:core -- packages/core/dist/esm/tests/unit/llm-provider.test.js`
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Expose the headers field on GoogleVertexProviderSettings in the public model config types so custom provider headers (e.g., X-Goog-Priority) are accepted without TypeScript errors. Updated the public API type test to cover Vertex headers and align the model config check with the public API style, keeping types consistent with runtime behavior.
<sup>Written for commit bf4907dcf6ee3e1ec2991527a74d554c72867cc9. Summary will update on new commits. <a href="https://cubic.dev/pr/browserbase/stagehand/pull/1764">Review in cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
# why
- this function was from legacy stagehand which only operated on one
page
- presently, it was only being used to produce a log which:
- at best, misinformed users on whether the page had actually navigated,
and,
- at worst, resulted in a noisy error log
- the error log would happen if `clickElement()` triggered page closure.
this means that the frame.evaluate() to get the URL would attempt
`.evaluate()` on a frame that no longer existed
# what changed
- removed `handlePossibleNavigation()`
# test plan
- existing tests are fine here
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Removed the legacy handlePossibleNavigation() that tried to detect
navigation by URL and produced misleading logs. This also prevents
errors when clicks close the page and evaluate runs on a non-existent
frame, reducing log noise.
<sup>Written for commit 1d2c3d68280d8a686e806a3b55bbbbb766a1ea25.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1761">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
## Summary
- Adds `"bedrock"` to the `provider` enum in `ModelConfigObjectSchema` and `AgentConfigSchema` (Zod schemas in `packages/core/lib/v3/types/public/api.ts`)
- Regenerates `packages/server/openapi.v3.yaml` via `pnpm gen:openapi`
## Context
Bedrock was added to `AISDK_PROVIDERS` and `LLMProvider` in PRs #1604 and #1617, but the Zod schemas that feed the OpenAPI spec (and ultimately the Stainless-generated SDKs) were never updated. This means the Python/Go/etc. SDK type definitions don't include `"bedrock"` as a valid provider option.
Companion PR in bb/core: https://github.com/browserbase/core/pull/7668
## Test plan
- [x] `pnpm gen:openapi` produces updated spec with `bedrock` in all 4 provider enum locations
- [ ] Stainless picks up the OpenAPI change and regenerates SDKs with `bedrock` in the `provider` literal type
🤖 Generated with [Claude Code](https://claude.com/claude-code)
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Add "bedrock" to provider enums in ModelConfigObjectSchema/AgentConfigSchema and regenerate the OpenAPI spec so SDKs accept it and stay in sync with AISDK_PROVIDERS/LLMProvider. Also update AgentType to include "bedrock" to fix a server build type mismatch, and add a patch changeset to publish and unblock Python/Go SDK type generation.
<sup>Written for commit 88e33724c8a08af594dafb86d90fd3fced952520. Summary will update on new commits. <a href="https://cubic.dev/pr/browserbase/stagehand/pull/1759">Review in cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
# why
Stagehand API failures were caused on all routes `/act`, `/observe`,
etc. when session init failed because a page was closed. This adds a
fallback to open about:blank so at least the session remains usable
instead of just crashing on init.
# what changed
# test plan
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Fixes session init when connecting to a browser with zero pages by
auto-creating an about:blank tab. Keeps Stagehand routes working after
the last page closes and surfaces lint failures via a dedicated
cancellation job. Addresses STG-1450.
- **Bug Fixes**
- Replace waitForFirstTopLevelPage with ensureFirstTopLevelPage: check
for an existing page, wait with timeout, then create about:blank if
none.
- Simplify errors to a TimeoutError with clearer context; improve
logging and add an integration test for zero-page init.
- **CI**
- Run cancellation in a separate job only when lint fails, so failures
are visible instead of marked skipped.
<sup>Written for commit 45ed6dc059d44f07c338dc8f36e72eb0702a2cfd.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1749">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
<!-- mintlify-editor-comments:start -->
Mintlify
---
0 threads from 0 users in Mintlify
- No unresolved comments
<!-- mintlify-editor-comments:end -->
<!-- mintlify-comment-->
<a
href="https://dashboard.mintlify.com/browserbase/stagehand/editor/session-init-fixes?source=pr_comment"
target="_blank" rel="noopener noreferrer"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://d3gk2c5xim1je2.cloudfront.net/assets/open-mintlify-editor-dark.svg"><source
media="(prefers-color-scheme: light)"
srcset="https://d3gk2c5xim1je2.cloudfront.net/assets/open-mintlify-editor-light.svg"><img
src="https://d3gk2c5xim1je2.cloudfront.net/assets/open-mintlify-editor-light.svg"
alt="Open in Mintlify Editor"></picture></a>
<!-- /mintlify-comment -->
# why
Once API-side caching is deployed, the feature will be opt-out. Users
should have a way to disable the cache from the client.
# what changed
Added a `serverCache` parameter to the constructor which adds the
`x-bb-skip-cache` header to all outbound API requests. This parameter is
also present on act, extract, and observe functions to allow for further
configuration.
# test plan
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Adds global and per-request control of server-side caching for
act/extract/observe in Browserbase mode. Caching is on by default; you
can opt out. HIT/MISS is logged, and results include cacheStatus (Linear
STG-1182).
- **New Features**
- Added serverCache to V3Options and act/extract/observe options
(default true). Sends browserbase-cache-bypass when false, reads
browserbase-cache-status and SSE cacheHit, logs HIT/MISS, and sets
cacheStatus on ActResult/ExtractResult/ObserveResult. Observe now
returns ObserveResult (Action[] with optional cacheStatus).
- Updated public types and docs. Expanded tests with server integration
checks for bypass header behavior and cache-status semantics (including
HIT on repeated identical requests), plus ActCache variable-key
handling/replay.
- **Bug Fixes**
- Fixed cache miss logging when variables are missing during ActCache
replay, and suppressed cache status logging when a request explicitly
bypasses the cache.
<sup>Written for commit b35d29ea042f1314e7a9cc0366b87ceb9aa29118.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1581">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
<!-- CURSOR_SUMMARY -->
---
> [!NOTE]
> **Medium Risk**
> Touches the Browserbase API request/response path (new headers, SSE
parsing behavior, and result type shape), which could affect caching
behavior or backwards compatibility for consumers relying on exact
response objects.
>
> **Overview**
> Adds **server-side caching support for Browserbase API mode** with a
new `serverCache` flag on `V3Options` (instance default) and per-call
overrides in `act()`, `extract()`, and `observe()`.
>
> `StagehandAPIClient` now sends `browserbase-cache-bypass: true` when
caching is disabled, reads `browserbase-cache-status` (and SSE
`cacheHit`) to log HIT/MISS, and attaches `cacheStatus?: "HIT" | "MISS"`
onto `ActResult` and `ExtractResult`.
>
> Updates public types/tests, adds new unit tests for `ActCache`
variable-key behavior, and refreshes docs + changeset to announce
server-side caching and the opt-out mechanism.
>
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
b5ce9172a3c6e8c1adfcddceb42fea628852388f. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->
# why
From [1690](https://github.com/browserbase/stagehand/pull/1690/changes)
shoutout @huuyafwww !
This enables agent to connect to MCP servers that require Authorization
headers.
# what changed
connectToMCPServer was modified to accept options for
StreamableHTTPClientTransport as arguments.
# test plan
A public api test was added
<!-- CURSOR_SUMMARY -->
---
> [!NOTE]
> **Low Risk**
> Small additive API change that only affects MCP HTTP connection setup;
minimal behavior change unless callers opt into `requestOptions`.
>
> **Overview**
> `connectToMCPServer` now accepts `requestOptions` and forwards them to
`StreamableHTTPClientTransport`, enabling HTTP connections to MCP
servers that require request-header auth (e.g., `Authorization`).
>
> Updates the public API type test to include `requestOptions`, adds
docs showing a header-authenticated connection example, and publishes
patch changesets for `@browserbasehq/stagehand` and
`@browserbasehq/stagehand-docs`.
>
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
657b7d5fb2350ec2d171175b366b72b671a7315e. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Enable header-based auth for MCP HTTP connections. connectToMCPServer
now accepts requestOptions and forwards them to
StreamableHTTPClientTransport.
- **New Features**
- Added requestOptions to connectToMCPServer for HTTP transports to pass
headers like Authorization.
- Updated docs with an authenticated MCP server example, expanded the
public API type test, and limited the changeset bump to
@browserbasehq/stagehand (docs package bump removed).
<sup>Written for commit 6cee1df669b8011ebd54a164e3c7d5aee2b16dcd.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1735">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
---------
Co-authored-by: huuyafwww <huuya.yamauchi@3-shake.com>
Co-authored-by: ci-test <ci-test@example.com>
## Summary
- `IFRAME_STEP_RE` regex only matched `iframe` steps, causing `act()` to
fail on legacy `<frameset>` pages where `observe()` returns XPaths
containing `frame[N]` (e.g.
`/html[1]/frameset[1]/frame[4]/html[1]/body[1]/...`)
- Changed regex from `/^iframe(?:\[\d+])?$/i` to
`/^i?frame(?:\[\d+])?$/i` so both `<iframe>` and `<frame>` are
recognized as frame boundaries
- Consolidated the duplicate `IFRAME_STEP_RE` constant (was defined in
both `deepLocator.ts` and `focusSelectors.ts`) into a single shared
export
## Test plan
- [x] Scratchpad repro confirms current regex misses `frame`,
`frame[4]`, `FRAME` — all pass with fix
- [x] 10 new unit tests added to
`snapshot-focus-selectors-utils.test.ts` covering:
- Regex matches `iframe`, `iframe[N]`, `frame`, `frame[N]`
(case-insensitive)
- Regex rejects `frameset`, `frameset[N]`, `div`, `body`, `html`
- Full XPath parse + walk for frameset page XPaths detects correct frame
boundary
- Standard iframe XPaths still detected correctly
- `frameset` is not false-positive detected as a frame boundary
- [x] All 15 tests pass, build + typecheck pass
🤖 Generated with [Claude Code](https://claude.com/claude-code)
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Adds support for <frame> in XPath frame boundary detection so navigation
works on legacy <frameset> pages. iframe and frame steps are treated as
frame boundaries.
- **Bug Fixes**
- Updated regex from /^iframe(?:\[\d+])?$/i to /^i?frame(?:\[\d+])?$/i
to match iframe and frame (case-insensitive) without matching frameset.
- Added focused tests for iframe/frame and frameset XPaths, including
parse + boundary detection; trimmed low-value cases.
- Added a changeset for a patch release.
- **Refactors**
- Consolidated IFRAME_STEP_RE into a shared export from focusSelectors
and used it in deepLocator.
<sup>Written for commit 4d09b02364a0b4f4bb745c3423fb210b5e0a733a.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1697">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
## Summary
- Claude Opus 4.6 and Sonnet 4.6 require the newer `computer_20251124`
tool type and `computer-use-2025-11-24` beta header for CUA mode
- The previous hardcoded `computer_20250124` is rejected by the
Anthropic API for these models
- Adds conditional tool version selection in
`AnthropicCUAClient.getAction()` — older models are unaffected
- Adds `claude-sonnet-4-6` to model maps (Opus 4.6 was already present)
## Test plan
- [x] Direct Anthropic API calls confirmed both Opus 4.6 and Sonnet 4.6
work with `computer_20251124`
- [x] Stagehand `env: "LOCAL"` CUA mode tested — both models
successfully completed tasks
- [x] Unit tests pass (18/18 in `llm-and-agents.test.ts`)
- [ ] Verify older models (Sonnet 4, Sonnet 4.5, Haiku 4.5) still work
with `computer_20250124`
🤖 Generated with [Claude Code](https://claude.com/claude-code)
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Adds CUA support for Claude Opus 4.6 and Sonnet 4.6 by switching to the
computer_20251124 tool and computer-use-2025-11-24 beta. Older models
continue using computer_20250124 to avoid API rejections.
- **Bug Fixes**
- Select tool/beta per model in AnthropicCUAClient.getAction(),
including prefixed names.
- Use new tool/beta for claude-opus-4-6, claude-sonnet-4-6, and
claude-opus-4-5-20251101.
- Add claude-sonnet-4-6 to modelToAgentProviderMap and
AVAILABLE_CUA_MODELS; update unit tests.
<sup>Written for commit 7c0a52c8021a4cffaefa523e72c8a6071abdb5be.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1729">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
# why
when running evals at high concurrency (~30) with the stagehand API
enabled in a region far from the client machine, browser sessions die
and the entire eval run hangs indefinitely. the process never exits
because `v3.close()` awaits a promise that never resolves.
the root cause is a race in the shutdown path between:
- the HTTP round-trip of `apiClient.end()` (client → API → client), and
- the CDP websocket close event arriving from the browser
race sequence:
1. `v3.close()` awaits `apiClient.end()` (HTTP request/response)
2. the API requests release immediately, and the browser closes the CDP
websocket
3. the websocket `"close"` event can reach the client before the HTTP
response returns
4. only after the HTTP response returns do we call `ctx.close()` →
`CdpConnection.close()`
if the close event wins the race and fires before step (4), then
`CdpConnection.close()` attaches its one-shot
`"close"` listener too late (the event already happened), so the promise
never resolves.
far regions make this more likely because the HTTP RTT is longer,
increasing the window where the close event can
beat the response.
two additional issues were found in the same shutdown path:
- inflight CDP calls are never rejected when the websocket closes
unexpectedly. pending `send()` promises hang forever alongside
`close()`, which compounds the original hang
- the `_onCdpClosed` transport handler was still registered when
`apiClient.end()` was called. the server-side websocket close would fire
`_onCdpClosed` -> `_immediateShutdown()` -> `close({ force: true })`,
re-entering the close path while the original `close()` was still in
progress
this bug only reproduced reliably with regions that are far away from
the client machine because:
- `apiClient.end()` awaits a full request/response to the hosted API;
higher client-region latency makes that await longer
- during that longer window, the server-side websocket close can arrive
and be processed before `CdpConnection.close()` is called
- if the client machine is close to the region, the timing often works
out and `close()` registers the `"close"` listener in time
# what changed
in`packages/core/lib/v3/understudy/cdp.ts`:
- updated `close()` to have an early return when `this.ws.readyState ===
WebSocket.CLOSED` so that calling `close()` on an already-closed
websocket resolves immediately instead of hanging.
- added `rejectAllInflight(why)`, which is a private method that
iterates the `inflight` map and rejects every pending CDP call with a
`CdpConnectionClosedError`, then clears the entry. this is called from
both the websocket `"close"` and `"error"` handlers in the constructor
- updated the `"close"` and `"error"` handlers to call
`this.rejectAllInflight(why)` before `this.emitTransportClosed(why)` to
make sure all pending promises are rejected when the ws dies
in `packages/core/lib/v3/v3.ts`:
- updated `v3.close()` such that `offTransportClosed` runs _before_
`apiClient.end()`
- this prevents `_onCdpClosed` from firing during the API teardown and
re-entering `close({ force: true })`
# test plan
- added unit tests in `cdp-connection-close.test.ts` which check that:
- `CdpConnection.close()` resolves when the websocket is already closed
- inflight `send()` calls reject when the websocket is terminated
- added an e2e test in `cdp-connection-close.spec.ts` which:
- terminates the underlying websocket, then calls `v3.close()` and
asserts it resolves
- terminates the websocket with an inflight CDP call and asserts the
pending promise rejects
- added another e2e test in `cdp-close-api-region.spec.ts` which:
- reproduces the full production trigger chain by creating a stagehand
instance with `disableAPI: false` and `region: "ap-southeast-1"`,
- calls `v3.close()` and asserts it resolves within 30 seconds
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Fixes a shutdown race that caused eval runs to hang when using the
Stagehand API in non-us-west-2 regions. v3.close() now resolves reliably
and inflight CDP requests reject on socket shutdown, addressing Linear
STG-1422.
- **Bug Fixes**
- CdpConnection.close(): return immediately if the WebSocket is already
CLOSED.
- Reject inflight CDP calls on "close"/"error" via new
CdpConnectionClosedError (exported in public error types).
- Unhook transport-close handler before apiClient.end() to prevent
double-close during API teardown.
- Added unit and e2e tests (incl. ap-southeast-1) verifying close
resolves and inflight requests reject.
<sup>Written for commit 699b48a8a75d0b7d33da83d11f7b133ef5673195.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1728">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
# Why
Users need a way to pass sensitive data (passwords, API keys, personal
info) to agent executions without exposing the actual values to the LLM.
This also enables reusable agent scripts where variable values can
change without invalidating cached executions.
## Usage
```typescript
const agent = stagehand.agent({
model: "google/gemini-3-flash-preview",
mode: "hybrid"
});
await agent.execute({
instruction: "Log in to the dashboard",
variables: {
username: { value: "john@example.com", description: "The user's email address" },
password: { value: process.env.USER_PASSWORD, description: "The user's password" },
},
});
```
# What Changed
- Added `variables` option to `agent.execute()` accepting
`Record<string, { value: string | number | boolean; description: string
}>`
- LLM sees variable names and descriptions in system prompt, uses
`%variableName%` syntax in tool calls
- Variable substitution implemented in `act`, `type`, `fillForm`, and
`fillFormVision` tools
- Sensitive values never returned to LLM in tool outputs
- Cache keys use variable names only (not values) - changing values
won't invalidate cache
- Feature requires `experimental: true`, not supported in CUA mode
- Shared utilities in `agent/utils/variables.ts`
# Test Plan
- [x] Test agent execution with variables for login flow
(username/password)
- [x] Verify LLM correctly uses `%variableName%` syntax in tool calls
- [x] Confirm sensitive values don't appear in LLM responses/tool
outputs
- [x] Test cache hit when variable values change but names stay same
- [x] Verify error thrown when `variables` used without `experimental:
true`
- [x] Verify error thrown when `variables` used with CUA mode
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Add first-class variables to agent.execute and act with a single
VariableValue type. Use %name% placeholders that are swapped at runtime,
never shown to the LLM, and cached by variable names only.
- **New Features**
- Unified API: Variables = Record<string, VariableValue> where
VariableValue = string | number | boolean | { value; description? };
shared utils: resolveVariableValue, substituteVariables,
flattenVariables.
- Prompt/tool UX: System prompt adds a variables section (names,
optional descriptions, usage and example); tool inputs list available
variables; %name% supported in act, type, fillForm, and fillFormVision
(hybrid included).
- Runtime safety: Substitution only during execution; logs/replay keep
original %tokens%; tool outputs never include sensitive values.
- Cache: Keys include variable names only; replay substitutes current
values across act/fillForm steps.
- Guardrails/docs: Requires experimental: true; blocked in CUA mode with
clear errors; docs updated for agent variables and act reference.
<sup>Written for commit 02a9cd584d37dabe20d2f8a624eae88ed044c282.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1580">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
---------
Co-authored-by: Shrey Pandya <shrey@browserbase.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
# why
- to enable users to set headers to be included in every request created
by every page within the `context`
# what changed
- added a new function `context.setExtraHTTPHeaders()` which calls the
`Network.setExtraHTTPHeaders` CDP command on all existing sessions
- we also call `Network.setExtraHTTPHeaders` with the user defined
headers whenever we attach to a new target (via `onAttachedToTarget`)
- if there is a rejected promise when headers are being set, a
`StagehandSetExtraHTTPHeadersError` will be thrown
# test plan
- added an e2e test to confirm that headers are being correctly set by
listening to `Network.requestWillBeSent` and inspecting headers
- also added unit tests to confirm that the custom error is being thrown
correctly when promises reject
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Adds context.setExtraHTTPHeaders() to set default HTTP headers on every
request from all pages in a context. Implements STG-1411; applies to
current sessions and newly attached targets after Network.enable.
- **New Features**
- New API: context.setExtraHTTPHeaders(headers) sends Network.enable
then Network.setExtraHTTPHeaders to each active session; repeats on
attach for new targets.
- Public error: StagehandSetExtraHTTPHeadersError with per-session
failure details.
- Tests: e2e verifies navigation headers; unit tests cover multi-session
send and error reporting; public error type is exported.
<sup>Written for commit 21606892ebf693f7798d3d4fea695c1563caa16f.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1708">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
# Why
Browser automation workflows frequently need to manage authentication
state, persist sessions across runs, and handle cookie-based features.
Currently, users have no direct API to read, write, or clear cookies in
Stagehand, forcing workarounds through raw CDP commands or page-level
JavaScript injection.
# What Changed
## Cookie Management APIs
Added cookie management methods that mirror the familiar Playwright
BrowserContext API:
**On `context` instance:**
- `context.cookies(urls?)` — Get all browser cookies, optionally
filtered by URL(s)
- `context.addCookies(cookies)` — Set one or more cookies in the browser
context
- `context.clearCookies(options?)` — Clear all cookies or selectively by
name/domain/path (supports RegExp)
### Types Added
- `Cookie` — Cookie object returned by the browser
- `CookieParam` — Parameters for setting a cookie (supports `url` OR
`domain`+`path`)
- `ClearCookieOptions` — Filter options for selective cookie clearing
# Test Plan
## Cookie Management
- [ ] `context.cookies()` returns all cookies when no URLs provided
- [ ] `context.cookies(url)` filters cookies by single URL
- [ ] `context.cookies([url1, url2])` filters cookies by multiple URLs
- [ ] `context.addCookies([...])` successfully sets cookies
- [ ] `context.addCookies()` validates cookie params (requires url OR
domain+path)
- [ ] `context.addCookies()` rejects `sameSite: "None"` without `secure:
true`
- [ ] `context.addCookies()` throws on browser rejection (checks CDP
success flag)
- [ ] `context.clearCookies()` clears all cookies atomically via single
CDP call
- [ ] `context.clearCookies({ name: "session" })` clears by exact name
- [ ] `context.clearCookies({ domain: /\.example\.com/ })` clears by
regex
- [ ] Selective clear only deletes matching cookies, leaves others
untouched
---------
Co-authored-by: Sean McGuire <seanmcguire1@outlook.com>
## Summary
Navigating to a PDF URL crashes Chrome's built-in PDF viewer because the piercer script gets injected into the PDF viewer's `chrome-extension://` target.
The fix adds an `isNonWebTarget()` predicate (alongside existing `isTopLevelPage()`) that uses an **allowlist** — only `"page"` and `"iframe"` targets receive piercer injection. All other target types (workers, background pages, browser, webviews, worklets, etc.) are resumed but skipped. Additionally, `chrome-extension://` and `chrome://` URLs are always skipped even if the type is `"page"`, since Chrome's PDF viewer reports as `type: "page"` with a `chrome-extension://` URL.
This is future-proof: Chrome currently has [14 target types](https://chromium.googlesource.com/chromium/src/+/main/content/browser/devtools/devtools_agent_host_impl.cc) and adding new ones won't require updating a blocklist.
## Root Cause
`onAttachedToTarget()` only filtered out worker targets. Chrome's PDF viewer (`chrome-extension://mhjfbmdgcfjbbpaeojofohoefgiehjai`) gets auto-attached as a `type: "page"` target — the piercer script patches `Element.prototype.attachShadow` and walks the DOM inside this extension, corrupting the viewer.
## Test plan
- [x] Open a PDF URL (e.g. `https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf`) with Stagehand — verify it loads without error
- [x] Verify normal page navigation still works after viewing a PDF
- [x] Verify OOPIF (cross-origin iframe) targets still get piercer injection
- [x] Verify shadow DOM piercing works (open + closed shadow roots tracked and accessible)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
# why
Server-side multi-region support enabled for all Browserbase regions:
- `us-west-2` (default)
- `us-east-1`
- `eu-central-1`
- `ap-southeast-1`
# what changed
Added multi-region routing to the Stagehand API client so requests use
the endpoint that matches the Browserbase session’s region. Updates
OpenAPI and docs, adds tests, and fixes STAGEHAND_API_URL handling.
### **New Features**
- Route API calls by session region via
REGION_API_URLS/getApiUrlForRegion; supports us‑west‑2 (default),
us‑east‑1, eu‑central‑1, ap‑southeast‑1.
- Store the session region in the client; remove the non–us‑west‑2
restriction.
- Add BrowserbaseRegion schema/type; unit tests for region→URL and /v1
suffix; integration tests verify non‑default regions return available:
true.
- OpenAPI adds regional servers and shared BrowserbaseRegion schema.
- Docs: add region/endpoint table, setup examples, mismatch error
guidance, and the disableAPI option.
### **Bug Fixes**
- Ensure STAGEHAND_API_URL resolves to exactly one /v1.
- Update SDK error messages to reference disableAPI.
- Fix OpenAPI table rendering by removing blank lines between markdown
table rows.
# test plan
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Adds multi-region routing to the Stagehand API client so requests use
the API that matches the Browserbase session’s region. Updates v3
OpenAPI/docs and tests; honors and normalizes STAGEHAND_API_URL; v2 docs
changes remain reverted.
- New Features
- Route API calls by session region (us-west-2 default, us-east-1,
eu-central-1, ap-southeast-1); removed the us‑west‑2‑only restriction.
- Add REGION_API_URLS/getApiUrlForRegion and store session region; v3
OpenAPI adds regional servers and a shared BrowserbaseRegion schema;
docs add region table, mismatch guidance, and disableAPI examples.
- Bug Fixes
- Normalize STAGEHAND_API_URL to include exactly one /v1;
getApiUrlForRegion always returns a /v1 URL; SDK error text references
disableAPI.
- Fix OpenAPI rendering (literal scalar description, quoted versions)
and preserve table formatting in generated YAML.
- Tests: add unit and integration coverage for regions; use try/finally
to prevent session leaks; remove unused env scaffolding; use
LOCAL_BROWSER_BODY in multiRegion tests for CI stability.
<sup>Written for commit cbdaf178fb35d1658b56a00697c2b06cb953a295.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1673">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
---------
Co-authored-by: Chromie <miguel@browserbase.com>
Co-authored-by: Chromie Bot <chromie@browserbase.com>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
GLM-4-Flash (Zhipu AI) doesn't support OpenAI's native structured
outputs, causing 500s on extract. Refactors the per-model boolean checks
into an extensible pattern list and adds "glm" to it.
# why
# what changed
# test plan
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Added GLM models to the prompt-based JSON fallback for structured
outputs to prevent 500s on extract for GLM-4-Flash. Addresses STG-1470
and includes a changeset for a patch release.
- **Refactors**
- Replace per-model flags with an extensible pattern list (deepseek,
kimi, glm) to trigger prompt-based JSON fallback when response_model is
used.
<sup>Written for commit 9ac8d7f991575e0d1a4bbea85b40dd86d621ff4b.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1706">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
# why
- to make the error more informative & actionable
# what changed
- moved `UnderstudyCommandException` into `sdkErrors.ts`
- added `cause` param
- updated callsites in `actHandlerUtils.ts` to include cause
# test plan
- added unit tests in `understudy-command-exception.test.ts`
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Expose the original error as the cause in UnderstudyCommandException to
preserve stack traces and context during Understudy actions, with
type-safe handling for non-Error values. Addresses Linear STG-1310.
- **Bug Fixes**
- Add cause to UnderstudyCommandException (extends StagehandError).
- Pass original error as cause across handlers; safely compute
message/stack for non-Error values.
- Prevent double-wrapping by rethrowing existing
UnderstudyCommandException in performUnderstudyMethod.
- Expose UnderstudyCommandException in the public API and add unit tests
for name, message, cause, and stack.
<sup>Written for commit e2047d6456c6f07dcbbf5816a11da5f0c687ab6c.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1705">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
# why
There is currently a bug isolated specifically to people using zod
pinned to v3 with structured output in agent resulting in a zod error
"undefined def"
# what changed
We now ensure any output schema passed in is correctly normalized to v3
or v4 depending on what version is being used through our zodcompat
factory
# test plan
tested the failing scenario to make sure it is addressed
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Fixes the “undefined def” error when agents use structured outputs with
Zod pinned to v3 by building the “done” tool schema with the same Zod
version as the user’s schema.
- **Bug Fixes**
- Use getZFactory to create schemas with the user’s Zod version (v3 or
v4).
- Build the base done schema via the factory and safely extend with
outputSchema.
- Generate output instructions using StagehandZodSchema types to avoid
v3/v4 mixing.
- Add changeset to publish a patch release.
<sup>Written for commit 07538ad15225c307cd64b257af81605dd23a4e5c.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1695">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
# why
- unit tests, e2e integration tests, and evals were taking 10~15 minutes
per pr
- finding the specific failing eval or test was tedious and required
reading tons of log output
- we weren't leveraging pnpm or turbo caches or github action's native
chromium install
- tests were flaky because CDP would randomly fail to connect when
github actions runner was overloaded
- e2e bb tests were not actually running against bb, so it was
previously just double-running e2e:local and reporting it as bb
- tsup has been deprecated for a while and should be replaced by esbuild
# what changed
- parallelized all CI tests and broke out evals and tests into
individual matrix jobs
- created unified node+pnpm+turbo setup action that all other actions
call
- verified vanilla chromium is able to launch inside all the e2e local
jobs before running any of our own code to catch resource contention
flakyness
- add proper esm and csj builds with sourcemaps and types for aligned
coverage
- remove tsup dependency
- switch to new evals cli
- add coverage reporting
- fix some flaky tests needed to get everything passing reliably
<img width="1635" height="609" alt="Screenshot 2026-01-26 at 1 04 04 PM"
src="https://github.com/user-attachments/assets/24bb2ea9-e182-4cb3-9856-6a77efe921b7"
/>
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Speeds up CI and makes tests stable by running Vitest/Playwright/Evals
on the built ESM dist with cached artifacts, verified runner Chromium,
weighted Browserbase routing, and merged coverage. Publishes a unified
ESM+CJS SDK with sourcemaps/types and SEA binaries from ESM; fixes
Browserbase e2e, switches to the new Evals CLI, and adds flaky‑test
reporting, addressing Linear STG‑1232.
- **New Features**
- CI: split pnpm/Turbo caches; composite actions (setup/caches, Chromium
launch check, region selection, CTRF/V8 uploads); reuse artifacts; use
Actions Chromium via CHROME_PATH with --no-sandbox; unique CTRF reports;
V8 coverage normalization/merge with cancellation safety; push triggers
enabled.
- Tests: run from dist/esm; env reporter; true Browserbase runs with
weighted/randomized regions; hard timeouts for LLM and session
create/CDP connect; faster multi‑click dispatch; higher timeouts and
targeted skips; cleanup helpers; fixes for init‑script,
wait‑for‑selector, and screenshot reliability.
- Build/SDK/SEA: export map (ESM import + CJS require) with
sourcemaps/types; SEA binaries built from ESM with sourcemaps and plain
logs in CI; removed tsup and dotenv; AISdk/CustomOpenAI moved to lib and
exported; getAISDKLanguageModel added; replay metrics now include
method/parameters/result/timestamps/cost.
- **Migration**
- Set STAGEHAND_BROWSER_TARGET=local|browserbase, STAGEHAND_ENV
(replaces TEST_ENV), CHROME_PATH; tune LLM_MAX_MS,
BROWSERBASE_SESSION_CREATE_MAX_MS, BROWSERBASE_CDP_CONNECT_MAX_MS;
optionally set BROWSERBASE_REGION_DISTRIBUTION.
- Remove dotenv; set env vars directly and import
@browserbasehq/stagehand via the export map (avoid dist paths).
<sup>Written for commit 5c76fecf6b9016f4ad5273d4143c3fe747b5d06f.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1632">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Ships an ESM‑first SDK with a CJS entry, unified sourcemaps, and types.
CI runs Vitest/Playwright and the new Evals CLI against the built ESM
dist using the runner’s Chromium (launch‑verified), with region‑weighted
Browserbase routing, normalized V8 coverage, unique CTRF artifacts, and
more stable tests (timeouts, Browserbase skips, understudy click/API
fixes).
Speed up CI by running Vitest and Playwright tests in parallel matrices,
add V8/CTRF coverage, and stabilize Browserbase/LLM flows with hard
timeouts and better cleanup. Server integration tests now use the
runner’s Chromium for reliability and are folded into the main CI.
- **Refactors**
- Parallelized core unit tests via discover-core-tests/core-unit-tests
(Vitest matrix, fail-fast).
- Parallelized E2E via discover-e2e-tests (Playwright local +
Browserbase) gated on core changes; weighted Browserbase region
selection; verify Chromium/CDP before tests; local uses runner Chromium
via CHROME_PATH and --no-sandbox; Playwright can emit JUnit when
CTRF_JUNIT_PATH is set.
- Unified Lint & Build with Turbo caching and shared artifacts;
tests/evals download and reuse; prepare script skips build in CI; SEA
builds support sourcemaps.
- Enforced configurable timeouts and parallelism via env (LLM_MAX_MS,
BROWSERBASE_CDP_CONNECT_MAX_MS, BROWSERBASE_SESSION_CREATE_MAX_MS,
LOCAL_SESSION_LIMIT_PER_E2E_TEST,
BROWSERBASE_SESSION_LIMIT_PER_E2E_TEST, EVAL_*); added LLM and
Browserbase hard timeouts; improved click event dispatch to reduce
remote flakiness.
- Explicitly close Browserbase sessions in tests and evals to free
capacity.
- Added composite actions: setup-node-pnpm-turbo,
verify-chromium-launch, select-browserbase-region, publish-ctrf-report
(JUnit→CTRF and evals), upload-v8-coverage.
- Renamed TEST_ENV to STAGEHAND_ENV across E2E; added an env reporter
for CI logs; removed the standalone stagehand-server tests workflow and
ran server tests in the unified CI with Node’s test runner and GitHub
Actions Chromium.
- **New Features**
- Build/Exports: ESM in dist/esm and CJS in dist/cjs via export map;
types from ESM; SEA binaries built from dist with sourcemaps; server SEA
job targets CJS; new build/test/coverage scripts; Node loader maps
package imports to dist/esm; ESM‑safe pathing (fileURLToPath);
ESLint/Prettier tweaks; dotenv removed.
- CI: Composite actions (setup-node-pnpm-turbo, verify-chromium-launch,
select-browserbase-region, upload-ctrf-report, upload-v8-coverage); uses
runner Chromium via CHROME_PATH with --no-sandbox and launch checks;
weighted Browserbase region selection; unique CTRF artifacts; V8
coverage normalized/merged with debug logs and graceful cancellation;
Playwright/Vitest discover tests in dist/esm; push/PR triggers enabled.
- Tests & API: Vitest/Playwright run on dist/esm; new env reporter and
closeV3 helper; tighter multi‑click CDP dispatch; higher timeouts and
targeted skips (e.g., console on Browserbase) reduce flakiness; local
launches honor CHROME_PATH; replay metrics now include
parameters/result/timestamps/cost with parser fixes; AISdk/CustomOpenAI
clients moved to lib/v3/external_clients and exported; env‑driven hard
timeouts for LLM ops and Browserbase session create/CDP connect;
understudy API usage fixes.
- **Migration**
- Set STAGEHAND_BROWSER_TARGET=local|browserbase and CHROME_PATH; tune
LLM_MAX_MS, BROWSERBASE_SESSION_CREATE_MAX_MS, and
BROWSERBASE_CDP_CONNECT_MAX_MS; optionally set
BROWSERBASE_REGION_DISTRIBUTION.
- dotenv support is removed; set env vars explicitly in dev and CI.
- Import @browserbasehq/stagehand via the export map; do not reference
dist paths or prior tsup outputs.
<sup>Written for commit 8119145426a4e6e5cb614dee5b3f2d8fe41a65e9.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1632">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
# why
- to give users the freedom to decide whether the browser should be kept
open or "alive" when their stagehand instance is killed
- to follow best practices by avoiding usage of global signal handlers
inside library code
# what changed
new `keepAlive` option:
- added an optional, boolean `keepAlive` parameter in the stagehand
constructor params. `keepAlive` defaults to `false`
- `keepAlive` on the constructor overrides
`browserbaseSessionCreateParams.keepAlive` when both are provided
out-of-process shutdown supervisor (`packages/core/lib/v3/shutdown/`):
- replaced the old in-process global signal handlers
(process.once("SIGINT"), etc.) with a detached supervisor process that
watches a lifeline (stdin pipe + IPC channel) to the parent
- when `keepAlive` is set to `false`, the supervisor is spawned during
`init()` and performs best-effort cleanup if the parent dies
unexpectedly:
- if `env` is `"LOCAL"` the supervisor kills the Chrome PID (with
SIGTERM → SIGKILL escalation) and removes any temp user-data directory
- if `env` is `"BROWSERBASE"` & using the stagehand API, the supervisor
sends `REQUEST_RELEASE` to the browserbase API
- the supervisor also includes PID polling to guard against process
reuse (killing a recycled PID
- when `keepAlive` is set to `true`, no supervisor is spawned, & the
browser is left running
- when `disableAPI` is set to `true` (direct WS to Browserbase), no
supervisor is spawned since the browser will auto release when the WS is
dropped
refactored `close()` into helpers:
- pulled browser teardown logic into `shutdown/shutdownBrowser.ts`
(`shutdownBrowserSession`, `shutdownLocalBrowser`)
- pulled stagehand internal state cleanup into
`shutdown/shutdownStagehand.ts` (`shutdownStagehandResources`,
`finalizeStagehandShutdown`)
-`.close()` now skips `apiClient.end()` when `keepAlive: true`
local browser launch changes:
- updated local launch to pass chrome launcher’s `handleSIGINT` based on
`keepAlive` in `packages/core/lib/v3/v3.ts` and
`packages/core/lib/v3/launch/local.ts`. this prevents chrome from
getting killed on Ctrl+C when `keepAlive: true`
- updated local launch so that we `unref()` the chrome child process
after launch so Node can exit while chrome stays open
(`packages/core/lib/v3/v3.ts`)
### behaviour notes:
- setting `keepAlive: true` will keep the browser alive in the following
scenarios:
- stagehand instance gets killed because of an uncaught error (eg,
`unhandledRejection`, `unhandledException`)
- stagehand instance gets killed because of a `SIGTERM` or `SIGINT`
- stagehand instance gets killed with an explicit call to
`stagehand.close()`
# test plan
- added tests in `keep-alive.spec.ts` that validate expected behaviour
across the following scenarios:
- `unhandledRejection`/`unhandledException`,
- `SIGTERM`/`SIGINT`,
- `stagehand.close()`
- each scenario is validated in each of the following browser
configurations:
- using a local browser launched by stagehand
- using a browserbase browser, connected directly over the WS
- using a browserbase browser + the stagehand API
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Adds a keepAlive option to Stagehand V3 so you control whether the
browser/session stays up after stagehand.close(), signals, or uncaught
errors. Replaces global process handlers with a per‑instance crash‑only
supervisor with a ready handshake and PID polling to avoid race
conditions (STG‑1338).
- **New Features**
- keepAlive?: boolean (default false) on the V3 constructor; overrides
browserbaseSessionCreateParams.keepAlive when set.
- Local: set handleSIGINT based on keepAlive and unref Chrome when true;
when false, a detached supervisor watches a stdin/IPC lifeline and on
parent crash/error SIGTERM→SIGKILLs Chrome and removes the temp profile
(with PID polling). A shared cleanup helper is used by both close() and
the supervisor for consistent local teardown.
- Browserbase: propagate keepAlive to session creation; when keepAlive
is true, close() skips apiClient.end() so the session stays RUNNING;
when false (and API enabled), the supervisor requests REQUEST_RELEASE on
crash/error; when disableAPI is true (direct WS), no supervisor is
spawned and the session ends when the WS drops.
- **Migration**
- Set keepAlive: true in the V3 constructor to keep the browser/session
open on errors, signals, or stagehand.close(); this overrides any value
in browserbaseSessionCreateParams.
- When keepAlive is true, close resources yourself when done (Local:
send Browser.close; Browserbase: request release/end the session).
<sup>Written for commit 3887d8f373d27afca6560c9436132fbfbcbb9845.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1672">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
# why
fix 1/2 ai sdk google thought signature buts
The version of google provider + ai sdk we currently use has a bug
resulting in errors with google thought signatures
They are in the process of releasing a fix for bug #2 but it is not yet
released - w ewill need to bump again when that is live
# what changed
bumped ai sdk + google providers versions
# test plan
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Bumped AI SDK and @ai-sdk/google to pick up the fix for Google “thought
signature” errors. A second upstream fix is pending and will require
another bump later.
- **Dependencies**
- ai: ^5.0.0 -> ^5.0.133 (core, evals)
- @ai-sdk/google: ^2.0.23 -> ^2.0.53 (core)
- Updated lockfile and added changeset for @browserbasehq/stagehand
(patch)
<sup>Written for commit b6c94cb86a264fbbbfb820ca50bd0007ed08115b.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1685">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
# why
people want to try codex models in Stagehand (also see benchmarks)
# what changed
Codex needs a text verbosity and reasoning effort of medium (not low) so
we set this using a conditional operator.
# test plan
Ran evals
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Enable Codex models in Stagehand via the AI SDK with the right OpenAI
provider options. Addresses STG-1324: Codex uses medium text verbosity
and reasoning effort; non-Codex gpt-5 defaults stay the same.
- **New Features**
- Detects Codex models (modelId includes "codex") and sets
textVerbosity: "medium" and reasoningEffort: "medium".
- Updates AISdkClient and AISdkClientWrapped to apply low/minimal
reasoning defaults to gpt-5.1/5.2 only when not Codex.
<sup>Written for commit 1115d9be156d93b53ed1019b57f6b82ceba98f1b.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1666">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
---------
Co-authored-by: Sean McGuire <seanmcguire1@outlook.com>
# why
- to make sure `.count()`/`.nth()` include shadow DOM matches
- make sure common predicates work in shadow DOM selectors (beyond just
attribute predicates)
- also to unify xpath resolution into one shared resolver, building off
of [this](https://github.com/browserbase/stagehand/pull/1679) PR
# what changed
- added shared resolver policy in
`packages/core/lib/v3/dom/locatorScripts/xpathResolver.ts`
- expanded composed predicate parsing/evaluation in
`packages/core/lib/v3/dom/locatorScripts/xpathParser.ts` (attr
existence, contains/starts-with, text(), normalize-space, and/or/not)
- routed xpath entrypoints through the resolver:
- `packages/core/lib/v3/dom/locatorScripts/selectors.ts`
(`resolveXPathMainWorld`)
- `packages/core/lib/v3/dom/locatorScripts/counts.ts`
(`countXPathMatchesMainWorld`)
- `packages/core/lib/v3/dom/locatorScripts/waitForSelector.ts` (xpath
path now uses resolver)
- also removed unused injected helper `resolveSimpleXPath` from
`packages/core/lib/v3/dom/piercer.runtime.ts` & updated
`packages/core/lib/v3/dom/global.d.ts`
# test plan
- `packages/core/tests/xpath-parser.test.ts` (expanded predicate parsing
+ evaluation coverage)
- `packages/core/tests/xpath-resolver.test.ts` (shadow-inclusive
count/nth ordering across composed tree)
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Extended XPath support for predicates and shadow DOM, unified behind a
shared resolver. Fixes .count() and .nth() with document-order DFS
across light and shadow DOM, aligning with Linear STG-1373.
- **New Features**
- Predicate support: attr exists/equals/contains/starts-with;
text()/normalize-space; and/or/not; positional [n].
- Shadow-piercing resolution for selectors, count, and waitForSelector
with native document.evaluate fallback and DFS indexing.
- **Refactors**
- Routed all XPath entry points to the shared resolver; removed legacy
traversal and the piercer’s resolveSimpleXPath backdoor.
- Expanded parser/resolver tests and added jsdom; cleaned dead code in
selectors/counts/waitForSelector.
<sup>Written for commit 57f38186d2ada80fac32558928bad51c48c85f61.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1683">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
## Summary
- Fix `locator.count()` returning 0 for XPath selectors containing attribute predicates (e.g. `//img[@alt='Stagehand']`)
- Consolidate all four copies of the XPath step parser into a single shared module with unit tests
## Root Cause
Stagehand has two ways to evaluate XPath expressions:
1. **Native browser XPath** (`document.evaluate()`) — understands the full XPath spec, including attribute filters like `[@alt='Stagehand']`, but cannot see into shadow DOM
2. **Custom XPath parser** — a hand-written DOM traversal that walks the composed tree (including shadow roots), but only understood simple patterns like `//div` or `//div[2]`, not attribute predicates
The `isVisible()` code path (via `resolveXPathMainWorld`) tried native browser XPath first and fell back to the custom parser. But the `count()` code path (`countXPathMatchesMainWorld`) went straight to the custom parser. The custom parser's regex only recognized numeric positional indices (`[1]`, `[2]`), so `[@alt='Stagehand']` was treated as part of the tag name, matching nothing.
## Fix
### 1. Extract shared parser (`xpathParser.ts`)
The XPath step parser was duplicated four times across `counts.ts`, `selectors.ts`, `piercer.runtime.ts`, and `waitForSelector.ts`. All four are consolidated into a single `xpathParser.ts` module exporting `parseXPathSteps()` and `elementMatchesStep()`.
### 2. Add attribute predicate parsing
The parser now handles `[@attr='value']` predicates (single and double quotes, multiple predicates, combined with positional indices). Attribute predicate XPaths work correctly **including inside shadow DOM**.
### 3. Fix forward slash splitting in predicates
The step splitter now tracks bracket depth so `/` inside attribute values (e.g. `[@href='/api/endpoint']`) no longer incorrectly splits the step. This was a pre-existing bug in three of the four copies; `waitForSelector.ts` had independently fixed it.
### 4. Document supported XPath subset
The parser docstring explicitly lists what's supported and what isn't, so future contributors know the scope.
## Files changed
- `xpathParser.ts` (new) — shared parser with `parseXPathSteps()` and `elementMatchesStep()`
- `counts.ts` — uses shared parser (removed ~40 lines of inline parser)
- `selectors.ts` — uses shared parser (removed ~40 lines of inline parser)
- `piercer.runtime.ts` — uses shared parser (removed ~40 lines of inline parser)
- `waitForSelector.ts` — uses shared parser (removed ~50 lines of inline parser + matching)
- `global.d.ts` — updated docstring
- `xpath-parser.test.ts` (new) — 25 vitest unit tests
## Test plan
### Unit tests (25 vitest tests in `xpath-parser.test.ts`)
- [x] Basic tag parsing and case normalization
- [x] Child vs descendant axes
- [x] Positional indices (including clamping)
- [x] Attribute predicates: single quotes, double quotes, multiple predicates, combined with index, hyphenated names, empty values
- [x] Multi-step paths with mixed predicates
- [x] Forward slashes inside attribute values (`[@href='/api/endpoint']`)
- [x] URL attribute values (`[@data-url='http://example.com/path/to/page']`)
- [x] Edge cases: empty input, `xpath=` prefix, whitespace
- [x] Element matching: tag name, wildcard, attribute filtering, multiple attributes, tag+attribute combination
### Integration tests (verified manually)
- [x] `page.locator("//img[@alt='Stagehand']").count()` returns correct count (was 0, now 3) on https://www.stagehand.dev/
- [x] `page.locator("//img[@alt='Stagehand']").isVisible()` still returns `true`
- [x] Simple XPath `//div` returns correct count
- [x] CSS selectors unaffected
- [x] Non-existent XPath returns 0
- [x] `//div` on page with shadow DOM counts all elements (light + shadow = 6)
- [x] `//div[@class='test-item']` on page with shadow DOM counts all elements (light + shadow = 5)
Fixes#1668🤖 Generated with [Claude Code](https://claude.com/claude-code)
# why
For observability into stagehand sessions
# what changed
- Added a custom `Stagehand/<version>` user agent header to CDP
connections.
# test plan
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Set a custom User-Agent on CDP WebSocket connections:
Stagehand/<version> using STAGEHAND_VERSION. This helps servers identify
the client for logging and compatibility.
<sup>Written for commit 4a0c58de5d8edfbe8b9cadb037511a4c0010e9db.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1646">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
---------
Co-authored-by: Chromie <miguel@browserbase.com>
Co-authored-by: Chromie Bot <chromie@browserbase.com>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
# why
Gemini models now support CU tools
# what changed
- Added support for `google/gemini-3-flash-preview` and
`google/gemini-3-pro-preview` with access to computer use tools for both
hybrid and CUA agent modes
- Updated types accordingly
- Updated tests
- Updated `cua-example.ts` to default to the new gen
# test plan
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Adds Gemini 3 Flash and Pro support to hybrid and CUA agents, enabling
Computer Use tools with these models. Also updates types, provider
mapping, tests, and sets the CUA example default to
gemini-3-flash-preview.
- **New Features**
- Enable google/gemini-3-flash-preview and google/gemini-3-pro-preview
for CU tools in hybrid and CUA modes.
- Map both models to the Google provider and include them in
AVAILABLE_CUA_MODELS.
- Update tests and switch cua-example.ts to gemini-3-flash-preview by
default.
<sup>Written for commit 25e37215d30ec8e584ab99eace59bdbb1254526b.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1652">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
# why
There is currently a bug that occasionally happens when using agent
specifically in dom mode, and passing messages from one run to another.
The error `Invalid prompt: The messages must be a ModelMessage[]` is
thrown due to two issues:
1. `processMessages` was modifying tool outputs without verifying they
conform to the expected `type: "content"` schema format
2. The `act` tool was returning `undefined` values in its result object,
which is not valid JSON
# what changed
1. **`packages/core/lib/v3/agent/tools/scroll.ts`**: Added
`toModelOutput` method to `scrollTool` (DOM mode) to ensure it returns
the `{ type: "content", value: [...] }` format consistent with other
vision tools.
2. **`packages/core/lib/v3/agent/utils/messageProcessing.ts`**: Added
`isContentTypeOutput` check before modifying any tool output. This
ensures we only compress outputs that have `type: "content"`
(array-based values), preventing corruption of `type: "text"` or `type:
"json"` outputs.
3. **`packages/core/lib/v3/agent/tools/act.ts`**: Fixed
`playwrightArguments` being set to `undefined` when no actions exist.
Now the field is omitted entirely instead, since `undefined` is not
valid JSON and breaks AI SDK validation.
4. **`packages/core/lib/v3/types/public/agent.ts`**: Added
`ScrollToolResult` interface and updated `ScrollVisionToolResult` to
extend it.
# test plan
- [x] Run agent in DOM mode with multiple steps on a task that
previously caused the error
- [x] Verify no `Invalid prompt: The messages must be a ModelMessage[]`
error occurs
- [x] Verify message compression still works correctly for
screenshot/ariaTree/vision tools
- [x] Run agent in hybrid mode to ensure no regression
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Fixes intermittent “Invalid prompt: The messages must be a
ModelMessage[]” in DOM mode by enforcing a consistent tool output schema
and safer message compression. Stabilizes multi-step runs and keeps
vision-tool compression intact.
- **Bug Fixes**
- scrollTool (DOM): added toModelOutput to emit { type: "json", value: {
success, message, scrolledPixels } }.
- Message processing: added isContentTypeOutput; only compress outputs
with type "content" and replace the whole output; leave "text"/"json"
untouched; keep vision action text and drop media; use safe placeholders
for screenshots/ARIA trees.
- act tool: omit playwrightArguments when no actions to avoid undefined
in JSON.
- Types: introduced ScrollToolResult and made ScrollVisionToolResult
extend it for a unified result shape.
<sup>Written for commit 41e94581bbd009ae61f38c38db10d1ce0f3798e4.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1647">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
# why
- to fix release
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Removed the docs-only changeset (.changeset/crazy-lions-wear.md) so it
no longer triggers a patch release of @browserbasehq/stagehand-docs.
This unblocks the release pipeline.
<sup>Written for commit 2f1195eee05cc8a6807605fc2cf724bface3f314.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1648">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
# why
- fixes#1628
- scripts injected via`context.addInitScript()` were not reliably
applied to pages that were created via a popup (eg, clicking a link that
opens a new page), or, when a new page was created via
`context.newPage(url)`.
- when a target was created directly at a URL, navigation often started
before attaching to the target & installing the init script. this means
that the script would either run too late or not run at all.
# what changed
- enabled `waitForDebuggerOnStart` in `Target.setAutoAttach` in
`cdp.ts`, so that new targets pause until we explicitly resume them
- in `understudy/context.ts`:
- `onAttachedToTarget()` now installs context init scripts on the
**session** before resuming, then resumes with
`Runtime.runIfWaitingForDebugger`. this guarantees scripts are
registered before the first real document executes.
- worker targets are resumed immediately. we still are not attaching to
them, but they need to be resumed since we are now telling everything to
wait for the debugger.
- added `seedOnly` to `applyInitScriptsToPage()` so the `page` object
records scripts without re‑installing them
- `newPage()` first creates targets at `about:blank` and then navigates
after attach (fire‑and‑forget). this avoids the race where the first
document loads before init scripts are installed
- in`understudy/page.ts`, i added `seedInitScript()` so the `page` can
track scripts that were already installed on the session
# test plan
- added additional tests to `tests/context-addInitScript.spec.ts` which
explicitly covers `context.newPage(url)` and popup pages to ensure init
scripts run on the initial document
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Fixes a race where context.addInitScript() didn’t run on the first
document for new pages opened via popups or context.newPage(url). New
targets now pause until init scripts are registered, ensuring scripts
run reliably.
- **Bug Fixes**
- Paused new targets with waitForDebuggerOnStart; resume after script
install.
- Installed init scripts on the CDP session before first document
executes.
- Resumed worker targets immediately so they don’t stay paused.
- Created newPage() at about:blank, attach, then navigate
(fire-and-forget).
- Seeded scripts/URL on Page to avoid double installs and timing issues.
- Added tests for newPage(url) and popup pages to verify scripts run on
initial load.
<sup>Written for commit 21193c2084408619a2a2e5f0d86c7126310e5e2a.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1642">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
# why
- We saw worker crashes caused by `unhandledRejection: Error("CDP
session detached")` when a Playwright‑connected page closed while
Stagehand had inflight CDP calls.
- Root cause: `Page.sendCDP` was async, which wraps the underlying CDP
promise. The detach rejection hit the inner promise before the outer
wrapper was awaited, so Node treated it as unhandled.
# what changed
- Fix by making Page.sendCDP return the original promise (remove async)
so callers receive the same promise that is already handled internally.
This eliminates the unhandled rejection race without changing semantics.
# test plan
- The new regression test reproduces this by starting a long‑running CDP
command and closing the page; it failed on main with an unhandled
rejection.
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Fixes worker crashes from unhandled CDP session detaches when a page
closes during in‑flight calls. Addresses STG-1240 by returning the
original sendCDP promise and guarding internal CDP promises.
- **Bug Fixes**
- Page.sendCDP now returns the original promise (removed async) so
rejections are handled by callers.
- Added catch guards in CdpConnection to prevent early
unhandledRejection on detach.
- New regression test: long Runtime.evaluate + page close rejects
cleanly with no unhandledRejection.
- Patch changeset for @browserbasehq/stagehand.
<sup>Written for commit d5e86daee16826ef10ac12573606a8abcded27b5.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1644">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
Co-authored-by: ci-test <ci-test@example.com>
# why
Was missing in mintlify docs
# what changed
# test plan
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Added the GET /v1/sessions/{id}/replay endpoint to the API docs so users
can fetch session replays.
<sup>Written for commit 193b983c24a7f73be14c4bce6fdec82ad1f6c44b.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1643">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
---------
Co-authored-by: ci-test <ci-test@example.com>
# why
The legacy model format is getting deprecated. Encouraging the model
definition as:
```typescript
model: "{provider}/{model}"
// or
model: {
modelName:"{provider}/{model}",
apiKey: "sk-tortilla-...."
}
```
# what changed
- Always log a deprecation warning for legacy model names; suggest
provider/model format (e.g., "openai/gpt-5",
"anthropic/claude-sonnet-4").
- Preserve legacy model routing to OpenAI/Anthropic clients; provide
clearer errors for invalid providers.
# test plan
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Add a level-0 deprecation warning for legacy model names without a
provider (e.g., "gpt-4o") while keeping them functional. Improve error
messages to guide users to the provider/model format with examples, and
add tests for the new behavior.
- **New Features**
- Always log a deprecation warning for legacy model names; suggest
provider/model format (e.g., "openai/gpt-5",
"anthropic/claude-sonnet-4").
- Update UnsupportedModelError to list supported models and include
provider/model guidance with examples.
- Preserve legacy model routing to OpenAI/Anthropic clients; provide
clearer errors for invalid providers.
- **Migration**
- Use provider/model strings going forward (e.g., "openai/gpt-4o",
"anthropic/claude-sonnet-4").
- No breaking changes; legacy names still work for now.
<sup>Written for commit 39a1e120462e13e747f0b9951b2d3c764429a32a.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1637">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
---------
Co-authored-by: Chromie <miguel@browserbase.com>
Co-authored-by: Chromie Bot <chromie@browserbase.com>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>
# why
`executionModel` is not properly propagated to api
# what changed
Serialize and send AgentConfig.executionModel to the API
# test plan
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Serialize and send AgentConfig.executionModel to the API, and document
it in schemas so tool execution uses the intended model. Addresses
Linear STG-1229 (execution model not reaching the API).
- **Bug Fixes**
- Serialize executionModel in StagehandAPIClient requests using
prepareModelConfig when provided.
- Add executionModel to AgentConfigSchema (Zod) and OpenAPI
(input/output) as ModelConfig or string with clear description.
<sup>Written for commit 0372c3848cc13e287c349ecc6da0c9bdfd16e9fb.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1636">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->