## Summary
- Adds `browse get markdown [selector]` to convert page HTML to clean
markdown
- Defaults to body content when no selector given, accepts optional
CSS/XPath/ref selector
- Uses `node-html-markdown` for quality conversion (links, tables, code
blocks preserved)
- Useful for agents that need readable page content without HTML noise
## Usage
```bash
browse get markdown # full page body as markdown
browse get markdown .article # specific element
browse get markdown @0-5 # ref from snapshot
```
## Test results
| Test | Local | Remote (Browserbase) |
|------|-------|---------------------|
| `get markdown` (body default) | HN full page markdown | HN full page
markdown |
| `get markdown .titleline` (selector) | Clean link with title | Clean
link with title |
## Test plan
- [x] Test locally with no selector (full body)
- [x] Test locally with CSS selector
- [x] Test on remote Browserbase session (no selector)
- [x] Test on remote Browserbase session (with selector)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
## Why
The original server-v4 stacked PRs merged into each other after
`STG-1614` had already merged into `main`, so the env/test-harness work,
Drizzle foundation, and Drizzle schema/controller flow never actually
reached `main`.
This PR recovers that full stack onto current `main` in one branch.
## What Changed
- cherry-picked the three stacked squash-merge commits from `#1896`,
`#1897`, and `#1898` onto fresh `main`
- preserved the full `server-v4` env/test harness cleanup, Drizzle
foundation, DB smoke tests, schema/migration work, and `/v4/llms`
controller/service/repo flow
- added one small follow-up commit to normalize `pnpm-lock.yaml` against
current `main` after applying the recovered stack
## Test Plan
- `pnpm install`
- `pnpm --filter @browserbasehq/stagehand-server-v4 run lint`
- `pnpm --filter @browserbasehq/stagehand-server-v4 run test:unit`
- `pnpm --filter @browserbasehq/stagehand-server-v4 run build`
- `pnpm --filter @browserbasehq/stagehand-server-v4 run gen:openapi`
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Recovers the server‑v4 Drizzle stack onto `main`, restoring DB‑backed
`/v4/llms` and switching the public `LLMId` to UUID. Adds a typed env,
clean app bootstrap, and a local `pglite`/Postgres runtime with
migrations, tests, and a simpler source‑based test harness.
- **New Features**
- Drizzle foundation with `pglite` default and Postgres option; new
`db:*` scripts via `drizzle-kit`.
- Fastify `databasePlugin` and unified DB client; `app.ts` bootstrap
with health/readiness and Swagger/OpenAPI; env via `@t3-oss/env-core`.
- Tables/relations for LLMs and Stagehand; DB‑derived Zod schemas; first
migration; OpenAPI updated for UUID `LLMId` with strict format and
pattern.
- LLM module (repo/service/controller) backing `/v4/llms`; routes now
delegate to the controller; browser session create uses the service and
auto‑creates a system default LLM when `llmId` is missing.
- Tests run from source via `tsx`; test server script simplified;
`turbo` tasks cleaned up; schema cleanup (`z.url()`).
- **Migration**
- Run: `pnpm --filter @browserbasehq/stagehand-server-v4 db:migrate`.
- Local dev uses `pglite` at `~/.stagehand/db/stagehand-v4`. For
Postgres set `STAGEHAND_DB_MODE=postgres` and `DATABASE_URL`.
- Update clients to treat `LLMId` as a UUID and regenerate from
`openapi.v4.yaml` if needed.
<sup>Written for commit 1fb861ed27739ad2330a4a0a6daf6e2c4951a575.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1917">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
---------
Co-authored-by: Nick Sweeting <github@sweeting.me>
Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>
## Summary
- Adds a pre-commit hook that runs prettier on staged files to catch
formatting issues before CI
- Uses `husky` for git hooks and `lint-staged` to scope prettier to only
staged files
- Preserves the existing `prepare` script behavior (`node
packages/core/scripts/prepare.js`)
## Changes
- Added `husky` and `lint-staged` as root devDependencies
- Created `.husky/pre-commit` hook that runs `pnpm exec lint-staged`
- Configured lint-staged: `{ "*": "prettier --write --ignore-unknown" }`
(respects `.prettierignore`)
## Test plan
- [x] Hook runs on commit — verified: badly formatted file auto-fixed
during commit
- [x] `pnpm install` sets up hooks correctly via `prepare` script
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
# why
- there is a vulnerability in `"langchain/core"` for versions lower than
`0.3.80` (more info
[here](https://www.cve.org/CVERecord?id=CVE-2025-68665))
- we have this package as an optional dep
# what changed
- bumps the optional `"langchain/core"` dep to `^0.3.80`
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Bumps optional `@langchain/core` to ^0.3.80 to resolve a vulnerability
in earlier versions. Lockfile refreshed; no runtime changes.
<sup>Written for commit 5e5d812cea51bd495beeed091f7d03d28f204940.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1841">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
# Follow-up Tasks
- [ ] Update stainless SDK custom code for all languages to pull new
`stagehand-server-v3-darwin-x64` binary names (`-v3-` added)
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Split the Stagehand API into `packages/server-v3` and
`packages/server-v4`, each with its own builds, tests, SEA binaries, and
release workflows. Delivers STG-1536 and lets us keep v3 stable while
iterating on v4; CI/test discovery and OpenAPI artifacts are versioned.
- **Refactors**
- Renamed the original server to `packages/server-v3`
(`@browserbasehq/stagehand-server-v3`); updated docs and runtime path
helpers (now synced across core/docs/evals and both servers), ESLint
globs/ignores, scripts/Turbo filters, tests, and Stainless to read
`packages/server-v3/openapi.v3.yaml`; v3 SEA binaries use
`stagehand-server-v3-*`.
- Added `packages/server-v4` (`@browserbasehq/stagehand-server-v4`) with
`/v4/**` routes, SSE streaming via `x-stream-response`, LRU/TTL
in-memory session store, health/readiness, logging/metrics,
`openapi.v4.yaml` + generator, SEA tooling, and v4 integration tests.
- CI: path filters, test discovery, and artifacts cover both versions;
added `stagehand-server-v4-release.yml` and
`stagehand-server-v4-sea-build.yml`; renamed v3 workflows; artifacts
include `packages/server-v3/**` and `packages/server-v4/**` dists and
OAS.
- **Migration**
- Replace `packages/server/**` refs with `packages/server-v3/**` or
`packages/server-v4/**`.
- Use new package filters and binary names:
`@browserbasehq/stagehand-server-v3` /
`@browserbasehq/stagehand-server-v4`; `stagehand-server-v3-*` /
`stagehand-server-v4-*`.
- Update OpenAPI consumers to `packages/server-v3/openapi.v3.yaml` or
`packages/server-v4/openapi.v4.yaml`.
<sup>Written for commit 2b9114ca8097d28ac1567fc67062b24f789a5c2e.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1796">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
# 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
Fixes TypeScript across core tests/scripts, finalizes the default
export/CLI, and makes the SEA build reliable on Windows. CI splits build
and lint, OpenAPI generation no longer runs Prettier, and builds run in
parallel across packages for faster pipelines.
- **Bug Fixes**
- Stricter TS across tests/scripts (tsconfig includes tests + CLI, added
@types/jsdom, switched to playwright-core); tightened types (child-frame
probes, DocumentReadyState, model utils, source-map Raw types); fixed
OpenAPI typing; removed cross-package imports in server tests; added
default-export parity test.
- Default export and CLI fixed: introduced StagehandDefault mirroring
named exports; ESM/CJS indices now export default; corrected
package.json CLI paths/types.
- SEA build works on Windows: build scripts use pnpm.cmd with better
spawn error handling.
- List parsing now works from raw source across core/server/evals and
maps cleanly to dist outputs.
- **Refactors**
- CI split into separate Build and Lint jobs; lint cancels the workflow
on failure; optional Turbo cache restore; discovery/runner steps no
longer depend on the build job.
- Parallelized builds: DOM script generators run concurrently; ESM/CJS
builds and server/evals build tasks run in parallel; tuned Turbo inputs
to reduce noisy rebuilds and improve caching.
<sup>Written for commit a25e17c2411b374e8d35c39f6120d242102ff8dc.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1721">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
# 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
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
- 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. -->
# why
New open source models are released, and don't necessarily have a great
inference provider at all times. Seeing as we're already using the
AI-SDK, it makes sense to add support for the AI Gateway.
# what changed
Added Vercel AI Gateway as a provider to the llm providers list.
# test plan
Testing with Evals
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Adds Vercel AI Gateway as a provider to route model calls across vendors
with a single API key; docs now cover gateway/{provider}/{model} usage,
AI_GATEWAY_API_KEY setup, examples for Anthropic/Google, and optional
baseURL config.
Also enforces JSON outputs for Kimi and DeepSeek, sets Kimi
temperature=1, and fixes eval parsing by using the first slash in
provider/model strings.
<sup>Written for commit 514142f8364e4b15f0ec77c2329e6fd2467982fb.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1627">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
---------
Co-authored-by: Miguel <36487034+miguelg719@users.noreply.github.com>
# why
Fixes: https://github.com/browserbase/stagehand-go/issues/43
Adds automatic bedrock AI SDK client support when `modelName ~=
'bedrock/...'`
# what changed
# test plan
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Adds automatic Amazon Bedrock support by routing models named
bedrock/{provider}.{model} to the Bedrock client. This enables
zero-API-key setup using your AWS credentials.
- **New Features**
- Route bedrock/... model names to @ai-sdk/amazon-bedrock.
- Treat Bedrock as no-API-key provider (uses AWS IAM/default
credentials).
- Example usage: bedrock/anthropic.claude-3.
- **Dependencies**
- Added @ai-sdk/amazon-bedrock as an optional dependency.
<sup>Written for commit e1d7c4c14e14b57120b10735cd8b4f898a987342.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1617">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
# 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
- 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
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>
# why
- stagehand no longer depends on playwright
- addresses #1463
# what changed
- moved `playwright` from dependencies to optional dependencies in
package.json
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Make Playwright optional so Stagehand installs cleanly without it. This
reduces install size and avoids Playwright install issues; aligns with
removing the hard dependency (issue #1463).
- **Dependencies**
- Removed Playwright from dependencies; added Playwright and Playwright
Core to optionalDependencies.
- Added Playwright and Playwright Core to devDependencies for local
development.
- Updated pnpm-lock.yaml and added a changeset for a patch release.
<sup>Written for commit 1264d716fa21b98b93b0889e6ac138d37e82580f.
Summary will update automatically on new commits.</sup>
<!-- End of auto-generated description by cubic. -->
# why
Stagehand-python needs a stable, versioned place to fetch the exact
stagehand/server SEA binaries for packaging into wheels. Today our
stagehand-server/v* GitHub Releases only include the OpenAPI spec, so
the binary handoff isn’t automatic.
# what changed
`stagehand-server/v*` releases now build a cross-platform SEA binary
matrix (linux/macOS/windows) and attach the resulting binaries (plus
checksums) to the same GitHub Release. The release still includes the
versioned OpenAPI spec asset as before.
# test plan
Binaries should build on merge to main
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Publish cross-platform stagehand-server SEA binaries on each versioned
GitHub Release, with SHA-256 checksums. This makes it easy for
stagehand-python to fetch exact, versioned server binaries.
- **New Features**
- CI builds SEA binaries for linux-x64, linux-arm64, darwin-arm64,
darwin-x64, win32-x64, and win32-arm64.
- Binaries and checksums are attached to the stagehand/server v* GitHub
Release alongside the OpenAPI spec.
- Added build scripts (build-binary.sh, create-binary.sh) and
sea-config.json; local cross-compiling is not supported.
- Artifacts are produced per-OS via a matrix job and collected in the
release.
- **Dependencies**
- Added esbuild and postject to support bundling and SEA blob injection.
<sup>Written for commit acc3bf5433fde74d3a589e69079e949b6eafbbdb.
Summary will update automatically on new commits.</sup>
<!-- End of auto-generated description by cubic. -->
# why
- Our OpenAPI file was stale and hand-maintained; routes and shapes
diverged from reality (e.g., /act and /start payloads).
- Validation had been disabled; we lacked consistent request/response
enforcement and clear error reporting.
- We were on Zod v3 plus zod-to-json-schema
- We need generated docs that match the live Zod schemas and a path to
stricter, type-safe responses.
# what changed
- Upgraded to zod v4 and removed zod-to-json-schema; we now rely on
Zod’s native schemas directly with fastify-zod-openapi.
- Integrated fastify-zod-openapi + @fastify/swagger/UI
- Added pnpm gen:openapi (scripts/gen-openapi.ts) to write
openapi.v3.yaml from the live app.
- Added Zod response schemas that mirror our actual envelope ({ success,
data: ... }) for start/act/agentExecute/navigate/observe/extract/end so
response validation is strict without breaking the API.
- Improved error handling:
- Schema formatter + error handler now surface Zod issues (422 for
requests, 500 for response serialization) with structured logs
### Future stuff:
- Remove healthz and readiness endpoints
- Tighten up request / response schemas
# test plan
Ran eval suite - passing
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Generates an OpenAPI 3.1 spec from live Zod v4 schemas with strict
request/response validation. /v1/sessions/start now accepts browser.type
and can return connectUrl; cdpUrl is removed. Addresses STG-1053.
- **New Features**
- Switched to Zod v4 + fastify-zod-openapi with Swagger UI; OpenAPI is
generated from runtime schemas.
- Added pnpm gen:openapi to write packages/server/openapi.v3.yaml.
- Centralized API request/response schemas in the client and exported
under Stagehand.Api; server routes use these directly.
- /v1/sessions/start accepts browser.type ("local" | "browserbase") and
returns { sessionId, available, connectUrl? }.
- Standardized { success, data } responses; improved errors (422 on
request validation, 500 on response serialization).
- Health endpoints moved to /healthz and readiness to /readyz.
- Added /v1/sessions/:id/replay stub.
- Added SSE streaming via the x-stream-response header.
- **Migration**
- Do not expect cdpUrl from /v1/sessions/start; use connectUrl when
present. For Browserbase, pass browserbaseSessionID.
- Rename localBrowserLaunchOptions.cdpUrl to connectUrl.
- Expect the { success, data } envelope on all responses.
- Use /healthz and /readyz instead of the old paths.
- Run pnpm gen:openapi to refresh the spec.
<sup>Written for commit 2ae58ab477997cc279a94f1c7904dcba9ca40efe.
Summary will update automatically on new commits.</sup>
<!-- End of auto-generated description by cubic. -->
---------
Co-authored-by: Nick Sweeting <git@sweeting.me>
Co-authored-by: Nick Sweeting <github@sweeting.me>
Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>
# why
- Google, Microsoft, and OpenAI CUA clicks miss targets when using
advanced stealth mode with Browserbase
- Advanced stealth scales screenshots to 1288×711 but browser reports
2560×1305 viewport
- GoogleCUAClient (and others) was scaling coordinates directly from
Google's 0-1000 range to viewport dimensions without accounting for the
screenshot→viewport size mismatch.
_This forced users to disable advanced stealth mode (losing bot
protection) to get accurate clicks._
# what changed
CUA Clients:
- Added `actualScreenshotSize` field to track screenshot dimensions
- Added `setScreenshotSize()` method to update dimensions
- Fixed `normalizeCoordinates()` with two-step scaling:
1. Convert 0-1000 range → screenshot space
2. Scale screenshot space → viewport space (handles different X/Y
scales)
**v3CuaAgentHandler.ts:**
- Added `getPNGDimensions()` helper to read PNG dimensions from buffer
(header-only, no decode)
- Updated screenshot provider to detect actual screenshot size and call
`setScreenshotSize()`
- Applied same logic to `captureAndSendScreenshot()`
- Graceful fallback if dimension reading fails
# test plan
Wrote test scripts locally and ensured that coordinate positioning is
now correct
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Fixes mis-scaled CUA clicks in advanced stealth by mapping model
coordinates through the actual screenshot size to the viewport, and
prevents corrupted images by encoding screenshots correctly.
- **Bug Fixes**
- Track screenshot dimensions and add setScreenshotSize() in
GoogleCUAClient, OpenAICUAClient, and MicrosoftCUAClient.
- Scale coordinates screenshot → viewport (Google: 0–1000 → screenshot →
viewport; OpenAI/Microsoft: screenshot → viewport with separate X/Y).
- Read PNG width/height from the buffer header; set screenshot size when
available with safe fallback, and pass base64 to captureScreenshot() to
avoid corrupted images.
- Fix event name to agent_screenshot_taken_event and emit the screenshot
buffer via the bus.
<sup>Written for commit cabead973dc1afb2d66956ecf459d4da4d91fd86.
Summary will update automatically on new commits.</sup>
<!-- End of auto-generated description by cubic. -->
---------
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
# 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
Stand up a Fastify Stagehand server we can reuse for thin-client SDKs
across multiple languages.
# what changed
created new fastify server
# test Plan
- Start the Fastify server (pnpm --filter server dev or your usual
command).
- Local browser smoke: MODEL_API_KEY=... ./scripts/test_local_browser.sh
- Browserbase smoke: MODEL_API_KEY=... BROWSERBASE_API_KEY=...
BROWSERBASE_PROJECT_ID=... ./scripts/test_remote_browser.sh.
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Adds a new Fastify-based Stagehand API server exposing V3 browser
automation over REST with streaming responses and session management.
Supports both local Chrome and Browserbase, includes health/readiness
endpoints, and ships an OpenAPI spec.
- **New Features**
- New packages/server with REST routes: start, navigate, observe, act,
extract, agentExecute, end (streaming logs/results)
- In-memory LRU session store with TTL, lazy V3 init, and cleanup on end
- Local and Browserbase browsers; credentials passed via headers
- Health (/healthz) and readiness (/readyz), metrics, and structured
request logging
- OpenAPI v3 spec and README
- Removed v2 code and DB dependency; auth currently disabled
- **Migration**
- Run: pnpm --filter @browserbasehq/stagehand-server dev
- Required header: x-model-api-key; for Browserbase also x-bb-api-key
and x-bb-project-id
<sup>Written for commit ed1089bae65c7ea337e2012eb64efc664b36141c.
Summary will update automatically on new commits.</sup>
<!-- End of auto-generated description by cubic. -->
Why
Adding Vertex AI support to Stagehand.
What changed
- Added GoogleVertexProviderSettings from @ai-sdk/google-vertex to
ClientOptions type
- Kept consistent with how we import types from @anthropic-ai/sdk and
openai packages
- Fixed typing in model utils
-
Test plan
- tested locally
- ested existing model format on api
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Adds Google Vertex AI as a model provider (behind an experimental gate)
and unifies clientOptions across providers, supporting API key or
service account auth. Tightens typings and fixes the Anthropic baseURL
key.
## Why:
- Support Vertex AI users.
- Standardize provider configuration.
- Gate Vertex behind experimental while stabilizing.
## What:
- Add Vertex provider via @ai-sdk/google-vertex; register in AISDK maps.
- Extend ClientOptions with GoogleVertexProviderSettings and service
account credentials (googleAuthOptions.credentials).
- Unify AISDK model creation to accept ClientOptions.
- Gate Vertex: throw ExperimentalNotConfiguredError unless experimental
or disableAPI is set; plumb options through V3 -> LLMProvider.
- Map vertex to GOOGLE_VERTEX_AI_API_KEY.
- Fix Anthropic baseURL key; update agents to use typed ClientOptions;
minor example cleanup.
- package.json: add @ai-sdk/google-vertex; relax zod ranges; add
changeset.
## Test Plan:
- [ ] Enable Vertex:
- [ ] Set experimental=true or disableAPI=true.
- [ ] Configure Vertex auth:
- [ ] Set GOOGLE_VERTEX_AI_API_KEY or pass
googleAuthOptions.credentials.
- [ ] Provide project and location in clientOptions.
- [ ] Run a flow with "aisdk:vertex/<model-name>" and verify responses.
- [ ] Verify OpenAI and Anthropic still work with apiKey/baseURL in
clientOptions.
- [ ] Type-check (tsc) and build examples without errors.
<sup>Written for commit 8e0a105f8447d24fedae133e44144ceac1617dc0.
Summary will update automatically on new commits.</sup>
<!-- End of auto-generated description by cubic. -->
# why
there was an issue with the alex ai endpoint deploying to vercel, where
while using stagehand v3 the scripts would correctly deploy and build,
but we weren't able to use them due to some bug where ws (websocket)
library would need bufferutil library to run any stagehand code
properly.
# what changed
added bufferutil library as an optional dep:
https://www.npmjs.com/package/bufferutil
# test plan
ci
Why
Adds support for zod 4 while maintaining backwards compatibility with
zod 3
What changed
- Introduced a zodCompat layer so Stagehand speaks both Zod v3 and v4
natively. Every place that used to import zod/v3, zod-to-json-schema, or
poke at schema internals now routes through the same helpers
(StagehandZodSchema, InferStagehandSchema, toJsonSchema, etc.). That
keeps existing apps on v3 working while letting us upgrade to the v4
ecosystem.
- Swapped all examples, eval tasks, tests, and LLM clients over to
standard zod imports, updated dependencies to accept 3.25.76 || 4.1.8,
and dropped zod-to-json-schema. Tool plumbing (Anthropic/Google CUA) and
custom clients now produce the right JSON Schema regardless of which Zod
flavor the user passes in.
- Tightened typings so structured LLM calls return { data, usage }
directly no more as casts throughout inference or the samples.
Manual testing
To make sure nothing regressed, I ran:
Custom OpenAI client example (schema conversion + structured output).
Standard extract (including URL injection path).
Google computer-use agent with a custom tool.
Anthropic computer-use agent with a custom tool.
All behaved as before
---------
Co-authored-by: miguel <miguelg71921@gmail.com>
# why
We want to be able to see what the public API shape looks like - which
top level functions are exported.
# what changed
Added vitest and a minimal test file that checks which functions are
exported at the root level. If new functions are exported or removed,
this test will catch that. I also added one example of drilling down and
testing the parameters of StagehandMetrics — in the future we might want
to do this for all exports.
Curious if this surfaces and exports that don't need to be exported or
not.
# test plan
Just added tests. They run in the CI pipeline or can be run with `pnpm
--filter @browserbasehq/stagehand run test:vitest`
# 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>
Complete overhaul of the Stagehand Documentation. Changes made at the
Browserbase Docsite.
---------
Co-authored-by: Kyle Jeong <77771518+Kylejeong2@users.noreply.github.com>
Co-authored-by: Derek <75138022+derekmeegan@users.noreply.github.com>
Co-authored-by: miguel <miguelg71921@gmail.com>
Co-authored-by: tkattkat <48974763+tkattkat@users.noreply.github.com>
Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>
Co-authored-by: Miguel <36487034+miguelg719@users.noreply.github.com>
Co-authored-by: Sean McGuire <seanmcguire1@outlook.com>
Co-authored-by: Sean McGuire <75873287+seanmcguire12@users.noreply.github.com>
Co-authored-by: tkattkat <tkat@tkat.net>
Co-authored-by: Paul Klein <paulleoklein@gmail.com>
Co-authored-by: Copilot <175728472+Copilot@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>