# why
- to enforce best practices in error handling by requiring the cause of
a given error to be included in the error that gets thrown
# what changed
- added the `preserve-caught-error` lint rule
- updated calls that were not preserving caught errors
- also bumped eslint version & typescript eslint for compatibility with
the new rule
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Adds an ESLint rule to require preserving the original error when
rethrowing, updates code to pass error causes, and fixes related linting
issues. This improves debugging by linking errors via the cause option.
- **Dependencies**
- ESLint → 10.0.2
- @eslint/js → 10.0.1
- typescript-eslint → 8.56.1
<sup>Written for commit b4cd5039b34b8156a1b55a88196d9aabc97c51d7.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1745">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
Speed up builds and tests by upgrading Turborepo, tightening cache keys,
and refactoring scripts to run from compiled dist (ESM/CJS). CI is
faster and more reliable, with ESM-first SEA builds for the server.
- **Refactors**
- Upgrade Turborepo to 2.8.10 and rewrite turbo.json with explicit
inputs/outputs for better caching.
- Stronger Turbo cache keys in CI (lockfiles + workspace + package.json
+ turbo.json + commit), workflow-scoped concurrency, and a 60s session
create timeout.
- Standardized CI via a composite setup action; build now runs before
lint.
- Build/test scripts resolve the repo root via fileURLToPath; tests run
from compiled dist; add Vitest config for CJS; CJS builds include
sourcemaps.
- Server: ESM-first SEA build and split server build into dist vs SEA
steps with a new build:server:dist script.
- Unified test scripts across packages; top-level test runs all suites,
and evals tests support source or dist CLI via --cli.
- **Migration**
- Use Node 20.19+ or 22.12+ (enforced in core).
- Run pnpm install to pick up the Turbo upgrade.
- Build before tests: pnpm -w build. For SEA tests, also run pnpm -w
--filter=@browserbasehq/stagehand-server run build:sea:esm.
<sup>Written for commit 843857c13fc4a3975c18b0e44002ae9f55e4dd66.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1712">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
---------
Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>
# why
- removes the need to append .js to all imports during esm build process
- aligns us with the default standard for esm / esbuild js projects that
also need to support cjs
- this allows us to seamlessly support ESM, CJS, and TSX with no
remapping needed
# what changed
# test plan
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Standardized all internal imports and re-exports to include .js
extensions to enable native ESM resolution, while keeping CJS and TS
working without path remapping. Updated examples to use explicit
index.js entrypoints and environment-driven config for easier local
runs.
- **Refactors**
- Appended .js to all relative imports and barrel exports across core,
v3 agent, DOM runtimes/locator scripts, caches, handlers, external
clients, and index files.
- Switched examples to ../lib/v3/index.js, fixed nested re-export paths,
and added env-based config (BROWSERBASE_API_KEY, BROWSERBASE_PROJECT_ID,
MODEL_API_KEY) passed into Stagehand/model.
- Updated dotenv to ^17.3.1 in dev deps. No public API changes.
- **Migration**
- Most users importing from package entry points: no changes.
- If importing internal files locally (e.g., examples or custom
integrations), include .js in paths and prefer index.js for directories.
<sup>Written for commit d1d0547daafca47a06a8aa9124d7081c68042270.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1700">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
# why
- so that `dotenv` is installed with `pnpm i`
# what changed
- added `dotenv` to dev dependencies
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Added dotenv 16.4.5 to devDependencies so it installs with pnpm i. This
enables .env loading in local dev scripts without manual installation.
<sup>Written for commit 53f8c54776eaefa5aab7a8c755ce37d84ae5f2e9.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1699">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
- for better code hygiene
# what changed
- added some basic security linting rules
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Added stricter ESLint security rules to block eval and dynamic Function
usage. This improves code hygiene and catches unsafe patterns early.
- **Refactors**
- Enforce no-eval, no-implied-eval, and no-new-func.
- Block Function constructors (direct, window.Function,
globalThis.Function).
- Enable security/detect-eval-with-expression.
- **Dependencies**
- Add eslint-plugin-security.
<sup>Written for commit dda6483f6d84599783f5966e94f6d675c0a40a76.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1597">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
## Summary
- Fixes import error on Node 25+ (and briefly Node 24.0.0) where `SlowBuffer` was removed.
- The `buffer-equal-constant-time` package (transitive dep via gtoken → jws → jwa) accesses `SlowBuffer.prototype` at module load time, causing immediate failure on import.
Closes#1552
## Solution
Added `jwa: "^2.0.1"` to package.json overrides. Version 2.0.1 uses `crypto.timingSafeEqual()` (available since Node 6) instead of `buffer-equal-constant-time`, avoiding the `SlowBuffer` dependency entirely.
This is cleaner than a polyfill approach because it uses the upstream fix rather than shimming deprecated APIs.
## Testing
✅ Node 25.4.0 - Stagehand imports successfully
✅ Node 24.13.0 - Works (SlowBuffer restored in 24.0.1)
✅ Node 20.19.5 - Works
✅ Bun 1.3.4 - Works
✅ Build passes
## Blast Radius
- **Affected:** Node 25+ users (SlowBuffer permanently removed)
- **Not affected:** Node ≤24.0.1, Bun (both have SlowBuffer)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Fixes import errors on Node 25+ and Bun by overriding jwa to 2.0.1, which replaces SlowBuffer usage with crypto.timingSafeEqual. Restores compatibility for the gtoken → jws → jwa chain at module load.
- **Dependencies**
- Override jwa to ^2.0.1 in package.json.
- Removes the need for a SlowBuffer shim by avoiding buffer-equal-constant-time.
<sup>Written for commit 82d075c1caa9f950c97ffc0ba7ce90d71613f3ca. Summary will update on new commits.</sup>
<!-- End of auto-generated description by cubic. -->
# why
- when transitioning to v3, we did not use the latest version of
screenshot collector
- screenshot collector currently fails due to not having page.on and
page.off support for the load, and domcontentloaded events.
# what changed
- added latest version of screenshot collector
# test plan
- ran evals in cli with additional logging to also verify everything is
working as expected
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Updated the evals CLI screenshot collector to the latest version, adding
image-diff filtering and a V3 event bus that emits agent screenshots.
This reduces duplicate screenshots and stabilizes capture on v3 pages
where navigation events are disabled.
- **New Features**
- Skip similar screenshots using MSE/SSIM thresholds with sharp.
- Event bus integration: agents emit screenshots; collector can ingest
them.
- Non-blocking initial/final captures and safer interval capture with
error handling.
- **Dependencies**
- Added sharp ^0.34.5 for image processing (evals and core).
- Patch bump via changeset for @browserbasehq/stagehand-evals.
<sup>Written for commit f4e90f85145385ba2f5a02d535a8fb0ef8406a71.
Summary will update automatically 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
These dev dependencies don't belong here. Some are no longer used, some
should go into their respective packages
# what changed
Moved dev dependencies to respective packages and removed unused ones
# test plan
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Moved dev dependencies from the workspace root into the packages that
use them and removed unused ones to cut install bloat.
- **Dependencies**
- Removed unused devDependencies from the root; moved required ones into
packages/core and packages/evals.
- Added missing dev deps to packages/core (@types/adm-zip, @types/node,
@types/ws, adm-zip, chalk, esbuild) and packages/evals (braintrust,
chalk, string-comparison).
- Cleaned pnpm-lock.yaml (large reduction in entries).
<sup>Written for commit c6f62212a3e548ec8e7c4d05685e6ca0412952fb.
Summary will update automatically on new commits.</sup>
<!-- End of auto-generated description by cubic. -->
# why
The Evals CLI has a lot of potential
# what changed
Added a simplified, cleaner version of the cli that's installable with
`pnpm build:cli`. Then, the new CLI can be run with just:
```bash
evals
```
Includes options such as:
```
evals <command> <target> [options]
Commands
run Execute evals or benchmarks
list List available evals/benchmarks
config Get/set default configuration
help Show this help message
Examples
# Run all custom evals
evals run all
# Run specific category
evals run act -e browserbase -t 5
# Run specific eval
evals run login
# Run benchmark
evals run benchmark:onlineMind2Web -l 10 -f difficulty=easy
# Configure defaults
evals config set env browserbase
evals config set trials 5
Options
-e, --env Environment: local|browserbase
-t, --trials Number of trials per eval
-c, --concurrency Max parallel sessions
-m, --model Model override
-p, --provider Provider override
--api Use Stagehand API
Benchmark-specific:
-l, --limit Max tasks to run
-s, --sample Random sample before limit
-f, --filter Benchmark filters (key=value)
```
Added a README.md within the evals directory for detailed descriptions.
# test plan
- [x] tested locally
- [x] tested on ci
*The new cli is backwards compatible and doesn't require (yet) CI
updates
# why
At the moment, Stagehand excels at browser automation but is limited in
being able to interact with third-party services. Many production use
cases require supporting these integrations. As the scope of browser
agents expand, it’s becoming increasingly important that agents adapt to
the web rather than the web adapting to them.
# what changed
Added support for integrations (MCPs) and custom tools to be passed in
to the Stagehand agent. Here are some examples:
```ts
const agent = stagehand.agent({
integrations: [
"https://www.example.com/mcp",
],
});
```
The above syntax will internally create the MCP connection. However, if
you prefer a self-managed connection, there are two more options
available. The first option is to use our built-in util to establish a
connection:
```ts
import { connectToMCPServer } from "@browserbasehq/stagehand"
const exampleClient = await connectToMCPServer("https://www.example.com/mcp")
const agent = stagehand.agent({
integrations: [exampleClient],
});
```
The alternative is to establish a connection to the MCP server with your
own client. Stagehand takes in a `Client` object from the
`@modelcontextprotocol/sdk` package. Please refer to their
[documentation](https://modelcontextprotocol.io/docs/getting-started/intro)
for more information.
# test plan
Internal agent evals.
---------
Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>
Co-authored-by: tkattkat <tkat@tkat.net>
This PR was opened by the [Changesets
release](https://github.com/changesets/action) GitHub action. When
you're ready to do a release, you can merge this and the packages will
be published to npm automatically. If you're not ready to do a release
yet, that's fine, whenever you add more changesets to main, this PR will
be updated.
# Releases
## @browserbasehq/stagehand@2.4.4
### Patch Changes
- [#1012](https://github.com/browserbase/stagehand/pull/1012)
[`9e8c173`](9e8c17374f)
Thanks [@miguelg719](https://github.com/miguelg719)! - Fix disabling api
validation whenever a customLLM client is provided
## @browserbasehq/stagehand-evals@1.0.8
### Patch Changes
- Updated dependencies
\[[`9e8c173`](9e8c17374f)]:
- @browserbasehq/stagehand@2.4.4
## @browserbasehq/stagehand-examples@1.0.8
### Patch Changes
- Updated dependencies
\[[`9e8c173`](9e8c17374f)]:
- @browserbasehq/stagehand@2.4.4
## @browserbasehq/stagehand-lib@2.4.1
### Patch Changes
- [#1027](https://github.com/browserbase/stagehand/pull/1027)
[`455b61f`](455b61fb6f)
Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - Fixed small
issue with module-level state guard for the Playwright
selectors.register call
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
# why
To enable compatibility with Zod v4
# what changed
Added v3 pathing spec and allowed zod peer dependency to be `"zod":
">=3.25.0 <4.1.0"`
# test plan
---------
Co-authored-by: miguel <miguelg71921@gmail.com>
# why
- to explain what each of the CLI args do when running evals
# what changed
- added a `buildUsage()` function in `evals/args.ts` which outputs an
explanation on how to run evals & the possible CLI args
- added a `run-evals.ts` script in the `scripts` directory to decide
whether we need to run `build` and `prettier` when running `pnpm run
evals ...`
- this is because we don't need to run `build` and `prettier` if someone
just runs `pnpm run evals -man` or `pnpm run evals -h`
## example
running `pnpm run evals -man` yeilds:
<img width="1342" alt="Screenshot 2025-06-24 at 1 12 04 PM"
src="https://github.com/user-attachments/assets/0f40bd3e-324b-4f70-9556-80fe1822bd78"
/>
# test plan
- evals
# why
- we should be using playwright, not playwright-test
# what changed
- removed playwright-test from peer deps
- replaced `playwright/test` imports with regular `playwright`
# test plan
- evals
# why
- for a better debugging experience
# what changed
- added build step `gen-version.ts` which will read the `package.json`
and expose the stagehand version number as a const globally
- included the version in the `StagehandDefaultError` message
# test plan
- regressions