# 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. -->
# why
Locator.click has support for both right and middle clicks, but these
are not properly piped or prompted for `act` or `observe`
# what changed
- clickElement on act handler reads the button from args (defaults to
left if undefined)
- Updated act/observe prompts to request "right" or "middle"
- Moved MouseButton type to types from locator
# test plan
- [x] Both env local & browserbase work with multiple models on
https://www.onlinemictest.com/mouse-test/
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Added right and right middle click support to act/observe so flows can
trigger context menus and middle-click behaviors. Handlers now pass the
mouse button to Locator.click.
- **New Features**
- clickElement reads the button from args and calls locator.click({
button }).
- Updated act/observe prompts to request "right" or "middle" for
non-left clicks.
- Exported MouseButton type for use across handlers.
<sup>Written for commit 10a9866089844378e50342ad3426245bec601e2c.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1631">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
---------
Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>
# why
- top‑layer UI (like `<dialog>` and popovers) is painted above the
normal document stacking context, so a mask appended to `document.body`
can never cover it. in order to mask dialog content, the overlay must be
inserted _inside_ the top‑layer container itself
- the screenshot masking logic for elements inside `<dialog>` nodes (and
other top‑layer elements) didn’t work because the overlay divs were
always appended to the document root, which renders _underneath_ the
dialog
- this PR addresses #1616
# what changed
- updated logic in `resolveMaskRect()` to detect top‑layer roots
(dialog[open], :popover-open), compute rects relative to that root, and
return a `rootToken` so the caller can target the correct container
- updated `applyMaskOverlays()` to insert mask overlays inside the
top‑layer root when a `rootToken` is present, and to restore any
temporary position changes on cleanup. `resolveMaskRectForObject()` now
passes a `maskToken` and preserves the `rootToken` output
# test plan
- added another test in `page-screenshot.spec.ts` to check whether masks
are correctly injected into the dialog node
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Fixes screenshot masking for elements inside dialog and other top‑layer
UIs by inserting overlays into the top‑layer root instead of the
document root. Masks now correctly cover dialogs and are fully cleaned
up after the screenshot.
- Bug Fixes
- Detect top‑layer roots (dialog[open], :popover-open) in
resolveMaskRect, compute rects relative to that root, and return a
rootToken.
- Insert mask overlays inside the detected top‑layer container;
temporarily adjust position when needed and restore on cleanup.
- Thread a maskToken/rootToken through masking calls to group overlays
and handle multi-frame cases safely.
- Add a test to confirm masks are injected into dialog elements.
<sup>Written for commit 4781745cf466238cecc04f9ebc093ece2d8e1126.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1624">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
# why
hybrid mode requires specific models to perform optimally
# what changed
if the models we recommend are not used, we throw an error log and link
out to the agent docs
# test plan
tested locally
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Add a runtime warning when hybrid mode is used with models that may not
perform well, linking to the docs with recommended models. This helps
catch misconfiguration early and improves agent reliability.
- **New Features**
- Log a warning in hybrid mode if the model ID isn’t “gemini-3-flash” or
“claude”, with a link to the agent docs.
- Updated hybrid mode docs to align guidance with the new warning.
<sup>Written for commit eb0dd6af3fe8ecce01d6a97014dfb2af6ecf9335.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1633">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
# why
`act` and `observe` don't fail on validation if the LLM generates an
action with a non-supported method
# what changed
- Added z.enum(supportedUnderstudyAction) to the act and observe
inference schemas
# test plan
- [x] Evals (act/observe)
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Enforces SupportedUnderstudyAction enum for the method field in act and
observe so invalid actions are rejected during schema validation.
Prevents unsupported methods from slipping through when the LLM
generates actions and supports Linear STG-1212.
- **Bug Fixes**
- Use z.enum(Object.values(SupportedUnderstudyAction)) for act/observe;
unsupported methods fail fast across Zod v3/v4.
- Added tests confirming enum validation works in both Zod v3 and v4.
- Updated method description to reference Understudy interaction methods
instead of Playwright.
- **Refactors**
- Migrated enum compatibility tests from Playwright to Vitest and moved
them to packages/core/tests.
<sup>Written for commit 4aa2573c0871d3b40874d6bc22f794dcb9592435.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1613">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
Stricter validation on LLM responses for chosen elementId to interact
with
# what changed
V3 includes **only** elementIds in the shape `number-number` to account
for iframe ordinals. This PR ensures the LLMs have stricter validation
on the elementId generation by changing the observe and act schemas to
to enforce
```typescript
z.string().regex(/^\d+-\d+$/)
```
# test plan
- [x] act evals
- [x] observe evals
- [x] combination evals
- [x] regression evals
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Enforce 'number-number' format for elementId in observe and act via
regex (^\d+-\d+$) to prevent invalid IDs. Aligns with Linear STG-675
guardrail requirements for elementId formatting.
<sup>Written for commit 3b70cc1cdbc8076ab793bfc8898943d1ad40b3e9.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1614">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
# why
- fixes issue #1585
- the `mask` param should be applied to all nodes that the locator
resolves to (unless `.nth()` is specified)
- currently, it is only being applied to the first node
# what changed
- renamed `resolveMaskRect()` to `resolveMaskRects()`, and updated
behaviour to resolve all bounding rects instead of just 1
- added `locator.resolveNodesForMask()` which is called by
`resolveMaskRects()` and resolves all nodes & object IDs so they can be
iterated through, and have masks applied to them
# test plan
- extended tests in `page-screenshot.spec.ts` to cover the case where
multiple elements match the `mask` locator
# why
Discord user reported that the `mode` property isn't typed in the Python
SDK, which was due to the OpenAPI spec being out of date
# what changed
Replaced `cua` boolean field with `mode` enum in zod objects +
regenerated openapi spec.
# test plan
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Updated agent config to use a mode enum (dom, hybrid, cua) instead of
the old cua boolean, and regenerated the OpenAPI spec. Kept cua for
backward compatibility but deprecated; mode takes precedence if both are
set.
- **Migration**
- Use agentConfig.mode; cua is deprecated but still accepted. If both
are set, mode overrides cua.
- Valid values: dom, hybrid, cua.
<sup>Written for commit 9efc0db26760b9ca3d168cb189147f34b32dd8e0.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1611">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
---------
Co-authored-by: ci-test <ci-test@example.com>
# why
Observe is failing to return `doubleClick` as the method because it has
no knowledge of the supported actions enum. Identified in #1608
# what changed
- Renamed `SupportedPlaywrightAction` to `SupportedUnderstudyAction`
- Included the list of supported actions in the observe system prompt
(similar pattern to act's)
- While testing dragAndDrop functionality realized there's no conversion
between elementId and xpath/selector for the target (specified in args
by model consistently), so added logic to replace for that specific
method
# test plan
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Make observe return only supported methods by passing
SupportedUnderstudyAction into the system prompt. Adds doubleClick and
dragAndDrop, updates handlers to use the new enum, and fixes dragAndDrop
target id-to-xpath conversion; addresses STG-1206.
- **Bug Fixes**
- Inject supportedActions into observe inference and prompt so returned
elements include a valid, supported method.
- Convert dragAndDrop target id to xpath in act/observe and skip invalid
targets while logging.
- **Refactors**
- Renamed SupportedPlaywrightAction to SupportedUnderstudyAction and
updated act/observe handlers.
- Expanded the supported actions with doubleClick and dragAndDrop.
<sup>Written for commit 3e70a5f7e1f62a0d340e8219a813a0bdfda91421.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1609">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
# why
# what changed
# test plan
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Enabled the Bedrock provider on the server by adding it to
AISDK_PROVIDERS. Clients can now select Bedrock, and the server will
route requests to Bedrock models.
<sup>Written for commit 138495917b096bb4b86a55cb4281fe91a369fea7.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1604">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
# why
Vertex is supported on local mode
# what changed
Adds vertex as a supported provider for local binary. Unlocks vertex for
canonical sdks
# test plan
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Add Vertex as a supported provider in Stagehand Server so users can
select "vertex" and run models via Vertex. Updates the AISDK provider
types to include "vertex" and includes a patch changeset.
<sup>Written for commit 0a5cd3bdffe737d73fd59ee55b7fee0a997966cb.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1602">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
# Why
The agent handler was using `usage` from `generateText()` which only
reflects the token usage of the **last step**. For multi-step agent
executions, this results in underreported token counts.
# What Changed
Updated `v3AgentHandler.ts` to use `totalUsage` instead of `usage`. The
`totalUsage` field from the AI SDK represents the sum of token usage
across all steps, providing accurate totals for:
- Input tokens
- Output tokens
- Reasoning tokens
- Cached input tokens
# Test Plan
- [x] Verify token metrics are correctly reported for multi-step agent
executions
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Fix underreported agent token metrics by using totalUsage for multi-step
executions. Token totals now reflect all steps.
- **Bug Fixes**
- Use totalUsage from the AI SDK in v3AgentHandler to compute metrics.
- Response payload includes accurate totals for input, output,
reasoning, and cached input tokens, plus inference_time_ms.
<sup>Written for commit 685a7eb8fc5dbc23376a27049a8446a851d77b0e.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1596">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
# why
- to give users a way to exclude components of the hybrid tree returned
by `page.snapshot()`
- for now, this only adds support for exclusion of iframes, but it is
designed to be extensible with the anticipation that there will be other
element/node types that users may want to exclude in the future
# what changed
- added an optional `PageSnapshotOptions` parameter with
`includeIframes?: boolean` and updated `page.snapshot()` to accept and
forward it. Internally `SnapshotOptions` now mirrors that flag
downstream in `captureHybridSnapshot()`
- the internal `captureHybridSnapshot()` function now computes
`framesInScope`, and passes that filtered list to
`buildSessionIndexes()`, `collectPerFrameMaps()`,
`computeFramePrefixes()`, and `mergeFramesIntoSnapshot()`, so each stage
only processes the intended frames while scoped snapshots
(`tryScopedSnapshot()`) still run before the filter is applied
- updated various helpers to adhere to the filtered list of frames:
- `collectPerFrameMaps()` iterates only on the provided frames
- `computeFramePrefixes()` skips any children which should be ignored
- `mergeFramesIntoSnapshot()` only merges the frames that are in scope
- `page.snapshot()` defaults to current behaviour (iframe inclusion)
# test plan
- added additional unit tests:
- `snapshot-capture-orchestration.test.ts` now asserts that
`collectPerFrameMaps()` ignores omitted frames, & scoped snapshots still
succeed with `includeIframes: false`, & the full capture path drops
iframe data when requested
- `snapshot-frame-merge.test.ts` now exercises the helper functions with
filtered frame sets to check that prefixes, merges, and per-frame
payloads are suppressed for excluded IDs
- added a new `page-snapshot.test.ts` to check that the public
`page.snapshot()` API forwards the option (both explicit false and
default true) into `captureHybridSnapshot()`
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Add an optional includeIframes flag to page.snapshot() so users can
exclude iframe subtrees from the hybrid snapshot. Defaults to current
behavior; use page.snapshot({ includeIframes: false }) to drop iframe
content. Addresses Linear STG-1190.
- **New Features**
- page.snapshot(options?: { includeIframes?: boolean }) now forwards the
flag to captureHybridSnapshot.
- SnapshotOptions gains includeIframes (default true).
- Internals compute framesInScope and only process those frames; scoped
snapshots still run before filtering.
- Updated helpers to respect filtering: collectPerFrameMaps,
computeFramePrefixes, mergeFramesIntoSnapshot.
<sup>Written for commit a61c30ba41454d2531b4bfa77dbfe55c9bdd2ec2.
Summary will update on new commits.</sup>
<!-- End of auto-generated description by cubic. -->
# why
currently actions from agent cache run too fast
# what changed
we now use waitForSelector for every cached "act" action
# test plan
created cache on semi complex workflow, re ran it
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Ensure cached actions wait for elements before executing to reduce flaky
replays and “too fast” failures. Adds a selector wait to act and
fillForm paths.
- **Bug Fixes**
- Call waitForSelector on action.selector with state: "attached" and
timeout: domSettleTimeoutMs or 15s before running cached actions.
- Log wait failures and proceed, avoiding blocked replays.
<sup>Written for commit 3fa59b25e4fb058e5509aa6d40d8d10a6939c967.
Summary will update on new commits.</sup>
<!-- End of auto-generated description by cubic. -->
# why
# what changed
# test plan
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Adds local agent caching when executing via the API. When a cacheContext
is provided, agent cache entries returned by the server are saved to
local cache for replay and faster repeats.
- **New Features**
- Extended AgentExecute (types + OpenAPI) with shouldCache and optional
cacheEntry in the response.
- API client captures cacheEntry from SSE and exposes
consumeLatestAgentCacheEntry().
- V3 persists remote cache entries to local CacheStorage when using API
mode.
- Added in-memory CacheStorage and a server agent cache handle to buffer
and transfer cache entries.
<sup>Written for commit cda468f37f2b18b928eb057a400d0428a39b3e49.
Summary will update on new commits.</sup>
<!-- End of auto-generated description by cubic. -->
---------
Co-authored-by: miguel <miguelg71921@gmail.com>
Co-authored-by: Miguel <36487034+miguelg719@users.noreply.github.com>
# why
`stagehand-api` was updated so that no request body should be send when
calling the `/end` endpoint.
# what changed
Thus, we can simplify our `stagehand-server` code so that no request
body should be sent as well, cleaning up our stainless sdks.
Also made it so that when we want to release a new github release of
`stagehand-server`, we add in a minor or major changeset - no longer
having to bump the `package.json` version manually.
# test plan
Added a minor changeset for `stagehand-server` and will confirm new
github release.
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Removed the empty JSON body requirement for POST /v1/sessions/:id/end.
The endpoint now accepts no request body, and the release workflow uses
Changesets instead of manual version bumps.
- **Refactors**
- Removed the SessionEnd request body from server route and OpenAPI; SDK
types now allow no body.
- Validate that the request body is empty; allow 0-byte JSON and return
400 for non-empty or non-object bodies. Tests assert 200 with no body or
empty JSON.
- Updated the GitHub release workflow to detect server releases via
Changesets (no package.json bump needed).
- Added port to browser launch options in the OpenAPI spec.
- **Migration**
- Call POST /v1/sessions/:id/end with no body; sending Content-Type:
application/json with an empty body is allowed.
<sup>Written for commit 975ccb6da02a782078590424a44640f1a5b01d1c.
Summary will update on new commits.</sup>
<!-- End of auto-generated description by cubic. -->
---------
Co-authored-by: ci-test <ci-test@example.com>
# why
the name "close" as a tool to end an agent run is confusing, we should
instead call it "done"
# what changed
updated all usage of the "close" tool to be "done"
# test plan
-tested locally
-updated tests
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Renamed the agent’s “close” tool to “done” for clearer task completion.
Core logic, cache, types, and tests updated; behavior remains the same.
- **Refactors**
- Replaced handleCloseToolCall with handleDoneToolCall and enforced a
final “done” call.
- Switched handler checks, action mapping, and cache replay from “close”
to “done”.
- Updated public agent types/docs to list “done” instead of “close”.
- Adjusted tests and instructions to remove “close” references.
- **Migration**
- Change any toolName === "close" checks to "done".
- Update allowed/excluded tool lists to use "done".
- Update instruction text or UI copy that tells the agent to “close” the
task; use “done”.
- If using outputSchema, read final data from the “done” tool call.
<sup>Written for commit 205d48c2352c56ec10a0dfb7c17cbdff75685fc0.
Summary will update on new commits.</sup>
<!-- End of auto-generated description by cubic. -->
…ons absent
When starting a session with browser.type="local" and only cdpUrl (no
launchOptions), the server was ignoring the cdpUrl and launching a new
browser instead of connecting to the existing one.
The condition in start.ts only constructed localBrowserLaunchOptions
when browser.launchOptions was truthy, causing cdpUrl to be lost.
Fix: Change condition from `browser?.launchOptions` to
`(browser?.launchOptions || browser?.cdpUrl)`
# why
# what changed
# test plan
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Fixes local sessions that provide only cdpUrl. The server now passes
cdpUrl into localBrowserLaunchOptions so it connects to the existing
browser instead of launching a new one.
- **Bug Fixes**
- Build localBrowserLaunchOptions when launchOptions or cdpUrl is
present.
- Added tests for cdpUrl-only and cdpUrl + launchOptions to ensure
cdpUrl is propagated.
<sup>Written for commit d2ca1b9b144f8436b2a660f168cd85e8cc7e9a8f.
Summary will update on new commits.</sup>
<!-- End of auto-generated description by cubic. -->
---------
Co-authored-by: kernel-systems-bot <p0@kernel.dev>
# why
Fixes benchmark eval runners to be more resilient and adds metadata for
filtering/grouping eval tasks
# what changed
- Exports `imageResize` utility from core
# test plan
---------
Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>