76 Commits

Author SHA1 Message Date
Derek
3917df4851
Add browse get markdown command (#1907)
## 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>
2026-03-31 13:06:28 -07:00
Sam F
206fb14ac0
Recover server-v4 drizzle stack onto main (#1917)
## 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>
2026-03-30 10:06:13 -07:00
Shrey Pandya
291e66e882
STG-1671: chore: add prettier pre-commit hook via husky + lint-staged (#1888)
## 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>
2026-03-27 16:39:17 -07:00
Sean McGuire
f56befe480
[chore]: bump "langchain/core" optional dep (#1841)
# 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. -->
2026-03-17 14:52:46 -07:00
Sean McGuire
ac4539ab6b
[chore]: refactor & fix lint for browse CLI (#1821) 2026-03-12 17:44:59 -07:00
Shrey Pandya
2abf5b90f1
Make projectId optional for Browserbase sessions (#1800) 2026-03-09 19:39:05 -07:00
Shrey Pandya
e38c13b752
[feat]: add browse CLI package (#1793)
## Summary
- Adds the `@browserbasehq/browse-cli` package (`packages/cli`) to the
stagehand monorepo, open-sourcing browser automation for AI agents
- CLI provides stateful browser control via a daemon architecture —
navigation, clicking, typing, screenshots, accessibility snapshots,
multi-tab, network capture, and env switching (local/remote)
- Uses `@browserbasehq/stagehand` as a workspace dependency (bundled
into the CLI binary via tsup)
- Includes full test suite and documentation

## Changes
- `packages/cli/` — all CLI source code, config, tests, and docs
- `pnpm-workspace.yaml` — added `packages/cli` to workspace
- `.github/workflows/ci.yml` — added CLI path filters and build artifact
uploads
- `.changeset/open-source-browse-cli.md` — changeset for initial release
- `pnpm-lock.yaml` — updated lockfile

## Test plan
- [x] CLI builds successfully (`pnpm --filter @browserbasehq/browse-cli
run build`)
- [x] Full monorepo build passes (`turbo run build` — 9/9 tasks)
- [x] `browse --help` and `browse --version` output correctly
- [x] `browse status` returns valid JSON
- [x] Lint passes clean (`pnpm --filter @browserbasehq/browse-cli run
lint`)
- [x] Source verified identical to stagent-cli (only import path
changed)
- [x] Empirically tested Browserbase credential requirements match core
- [ ] Run `pnpm --filter @browserbasehq/browse-cli run test` (requires
Chrome/browser environment)

## Known issues (pre-existing from stagent-cli, not introduced by this
PR)
- Network capture `response.json` always writes `status: 0` — response
metadata from `responseReceived` CDP event is not persisted to
`loadingFinished` handler
- Ref-based `click` command silently ignores
`--button`/`--count`/`--force` flags (coordinate-based `click_xy`
handles them correctly)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-09 17:56:45 -07:00
Nick Sweeting
e36ddd6f29
[STG-1536] Split packages/stagehand/server into separate server-v3 and server-v4 dirs (#1796)
# 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. -->
2026-03-09 17:32:57 -07:00
Sean McGuire
93bbf026e9
[chore]: add error cause lint rule (#1745)
# 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. -->
2026-02-24 14:03:33 -08:00
Nick Sweeting
6329982da2
Fix typechecking for core/tests, fix SEA build for windows, speed up CI (#1721)
# 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>
2026-02-20 17:09:39 -08:00
Nick Sweeting
50a6f574a3
Speed up turbo, package.json scripts, and CI configuration (#1712)
# 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>
2026-02-19 15:35:37 -08:00
Nick Sweeting
a091affd2c
[chore]: add .js to the end of all imports (#1700)
# 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. -->
2026-02-18 12:19:15 -08:00
Sean McGuire
c815c55c35
[chore]: add dotenv to dev deps (#1699)
# 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. -->
2026-02-18 11:18:18 -08:00
Nick Sweeting
afbd08bb63
[STG-1232] Speed up PR Github Actions checks, add code coverage, fix e2e bb tests running not running in bb mode, remove tsup, generate unified re-used ESM and CJS builds with sourcemaps and types, switch CI to new Evals CLI (#1632)
# 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. -->
2026-02-17 17:45:49 -08:00
tkattkat
d334399004
bump ai sdk + google providers version (#1685)
# 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. -->
2026-02-13 17:08:41 -08:00
Sean McGuire
7584f3e92e
[fix]: extend support for xpaths containing predicates (#1683)
# 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. -->
2026-02-13 14:04:33 -08:00
Kyle Jeong
5c38f99d6d
feat: adding AI Gateway support (#1627)
# 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>
2026-02-10 11:48:07 -08:00
Nick Sweeting
fd744adbb7
add auto-bedrock support based on bedrock/provider.model-name (#1617)
# 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. -->
2026-01-27 09:40:41 -08:00
Sam F
8a3c06600a
Using 'mode' enum instead of old 'cua' boolean (#1611)
# 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>
2026-01-26 16:07:31 -07:00
Sean McGuire
90b869d3bb
[chore]: add stricter linting rules (#1597)
# 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. -->
2026-01-22 11:49:31 -08:00
Nick Sweeting
922f7ef42f
add v3 integration tests matching cloud exactly (#1583) 2026-01-20 19:03:12 -08:00
Shrey Pandya
df944e4d5d
Fix SlowBuffer compatibility for Node 25+ (#1568)
## 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. -->
2026-01-20 18:24:35 -05:00
Miguel
40e1d80776
Improve benchmark handling and add metadata (#1423)
# 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>
2026-01-20 13:30:39 -08:00
Sean McGuire
b342acfaae
[chore]: move playwright to optional deps (#1466)
# 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. -->
2025-12-23 17:36:56 -08:00
Sam F
abb3469f51
Add code to publish binaries on release (#1459)
# 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. -->
2025-12-22 18:10:38 -07:00
Sam F
cdf946b815
[STG-1053] [server] Use fastify-zod-openapi + zod v4 for openapi generation (#1420)
# 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>
2025-12-22 14:49:37 -07:00
Shrey Pandya
bd2db925f6
fix: CUA coordinating scaling issue (#1430)
# 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>
2025-12-18 21:35:47 -08:00
tkattkat
cadd192066
Update screenshot collector (#1373)
# 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>
2025-12-15 12:05:23 -08:00
Miguel
c201b15bfc
Clean workspace dev dependencies (#1340)
# 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. -->
2025-12-09 17:17:20 -08:00
Sam F
fdbb58ce7a
Add fastify server (#1384)
# 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. -->
2025-12-09 15:51:10 -08:00
Nick Sweeting
75f87f1920
[STG-1045] Add logging at all 4 levels: agent.execute, agent.act/observe/extract, CLICK/HOVER/SCROLL, and CDP (#1283)
# why

Clarify where the execution flow goes when stagehand runs by showing
more detailed logs.

<img width="1443" height="529" alt="image"
src="https://github.com/user-attachments/assets/1c85f91e-de94-46c3-8226-fe42d4c3e338"
/>


# what changed

Adds a log line printed at the beginning and end of each layer's
execution:

1. 🅰 Agent TASK: top-level user intent: when agent.execute('<intent
here>') is called (the initial entrypoint)
  2. 🆂 Stagehand STEP: any call to .act(...) .extract() or .observe()
3. 🆄 Understudy ACTION: any playwright or browser interaction api action
dispatched, e.g. CLICK, HOVER, SCROLL, etc.
4. 🧠 LLM req/resp, 🅲 CDP CALL/Event: any LLM calls or CDP websocket msgs
to/from the browser

Log lines are written to
`./.browserbase/sessions/{sessionId}/{agent,stagehand,understudy,cdp}.log`
at runtime, and can be followed in a single unified screen by doing:

`tail -f ./.browserbase/sessions/latest/*.log`

# test plan

Test by running:

```bash

# (make sure `OPENAI_API_KEY` and `ANTHROPIC_API_KEY` are both set in env too)
export BROWSERBASE_CONFIG_DIR=./.browserbase

nano packages/core/examples/flowLoggingJourney.ts  # paste in contents (it's just a basic test of the main apis)

pnpm tsx packages/core/examples/flowLoggingJourney.ts & 
tail -f ./.browserbase/sessions/latest/*
```

`flowLoggingJourney.ts`:
```typescript
import { Stagehand } from "../lib/v3";

async function run(): Promise<void> {
  const openaiKey = process.env.OPENAI_API_KEY;
  const anthropicKey = process.env.ANTHROPIC_API_KEY;

  if (!openaiKey || !anthropicKey) {
    throw new Error(
      "Set both OPENAI_API_KEY and ANTHROPIC_API_KEY before running this demo.",
    );
  }

  const stagehand = new Stagehand({
    env: "LOCAL",
    verbose: 2,
    model: { modelName: "openai/gpt-4.1-mini", apiKey: openaiKey },
    localBrowserLaunchOptions: {
      headless: true,
      args: ["--window-size=1280,720"],
    },
    disablePino: true,
  });

  try {
    await stagehand.init();

    const [page] = stagehand.context.pages();
    await page.goto("https://example.com/", { waitUntil: "load" });

    // Test standard agent path
    const agent = stagehand.agent({
      systemPrompt:
        "You are a QA assistant. Keep answers short and deterministic. Finish quickly.",
    });
    const agentResult = await agent.execute(
      "Glance at the Example Domain page and confirm that you see the hero text.",
    );
    console.log("Agent result:", agentResult);

    // Test CUA (Computer Use Agent) path
    await page.goto("https://example.com/", { waitUntil: "load" });
    const cuaAgent = stagehand.agent({
      cua: true,
      model: {
        modelName: "anthropic/claude-sonnet-4-5-20250929",
        apiKey: anthropicKey,
      },
    });
    const cuaResult = await cuaAgent.execute({
      instruction: "Click on the 'More information...' link on the page.",
      maxSteps: 3,
    });
    console.log("CUA Agent result:", cuaResult);

    const observations = await stagehand.observe("Find any links on the page");
    console.log("Observe result:", observations);

    if (observations.length > 0) {
      await stagehand.act(observations[0]);
    } else {
      await stagehand.act("click the link on the page");
    }

    const extraction = await stagehand.extract(
      "Summarize the current page title and contents in a single sentence",
    );
    console.log("Extraction result:", extraction);
  } finally {
    await stagehand.close({ force: true }).catch(() => {});
  }
}

run().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});
```

EXPECTED OUTPUT:
```bash
2025-12-08 12:20:26.23300 ⤑ ⤑ [🆄 #694a GOTO] ▷ Page.goto({args:[https://example.com/,{waitUntil:load}]})
2025-12-08 12:20:26.23401 ⤑ ⤑ [🆄 #694a GOTO] [🅲 #FE7B CDP] ⏵ Page.navigate({url:https://example.com/})
2025-12-08 12:20:26.26402 ⤑ ⤑ [🆄 #694a GOTO] [🅲 #FE7B CDP] ⏴ Page.frameStartedNavigating({frameId:8A6B…FE7B,u…rId:F41F…7B31,navigationType:differentDocument})
2025-12-08 12:20:26.26403 ⤑ ⤑ [🆄 #694a GOTO] [🅲 #FE7B CDP] ⏴ Page.frameStartedLoading({frameId:8A6B…FE7B})
2025-12-08 12:20:26.57304 ⤑ ⤑ [🆄 #694a GOTO] [🅲 #FE7B CDP] ⏵ Page.setLifecycleEventsEnabled({enabled:true})
2025-12-08 12:20:26.57605 ⤑ ⤑ [🆄 #694a GOTO] [🅲 #FE7B CDP] ⏴ Page.frameNavigated({frame:{id:8A6B…FE7B,loaderI…tIsolated,gatedAPIFeatures:[]},type:Navigation})
2025-12-08 12:20:26.57706 ⤑ ⤑ [🆄 #694a GOTO] [🅲 #FE7B CDP] ⏴ Network.policyUpdated({})
2025-12-08 12:20:26.57807 ⤑ ⤑ [🆄 #694a GOTO] [🅲 #FE7B CDP] ⏴ Runtime.consoleAPICalled({type:info,args:[{type:…ptId:5,url:",lineNumber:0,columnNumber:2837}]}})
2025-12-08 12:20:26.57908 ⤑ ⤑ [🆄 #694a GOTO] [🅲 #FE7B CDP] ⏴ Page.domContentEventFired({timestamp:545864.312948})
2025-12-08 12:20:26.58009 ⤑ ⤑ [🆄 #694a GOTO] [🅲 #FE7B CDP] ⏴ Page.loadEventFired({timestamp:545864.313355})
2025-12-08 12:20:26.58110 ⤑ ⤑ [🆄 #694a GOTO] [🅲 #FE7B CDP] ⏴ Page.frameStoppedLoading({frameId:8A6B…FE7B})
2025-12-08 12:20:26.58311 ⤑ ⤑ [🆄 #694a GOTO] [🅲 #FE7B CDP] ⏵ Runtime.evaluate({expression:document.readyState,contextId:2,returnByValue:true})
2025-12-08 12:20:26.58412 ⤑ ⤑ [🆄 #694a GOTO] ✓ GOTO completed in 0.35s
2025-12-08 12:20:26.58513 [🅰 #1d66] ▷ Agent.execute(Glance at the Example Domain page and confirm that you see the hero text.)
2025-12-08 12:20:26.59314 [🅰 #1d66] ⤑ [🧠 #21e1 LLM] gpt-4.1-mini ⏴ user: Glance at the Example Domain page and confirm that you see the hero text. +{10 tools}
2025-12-08 12:20:29.44715 [🅰 #1d66] ⤑ [🧠 #21e1 LLM] gpt-4.1-mini ↳ ꜛ688 ꜜ12 | tool call: ariaTree()
2025-12-08 12:20:29.44816 [🅰 #1d66] [🆂 #9ac4 EXTRACT] ▷ Stagehand.extract()
2025-12-08 12:20:29.45317 [🅰 #1d66] [🆂 #9ac4 EXTRACT] ⤑ [🅲 #FE7B CDP] ⏵ DOM.getDocument({depth:-1,pierce:true})
2025-12-08 12:20:29.46018 [🅰 #1d66] [🆂 #9ac4 EXTRACT] ⤑ [🅲 #FE7B CDP] ⏵ Accessibility.getFullAXTree({frameId:8A6B…FE7B})
2025-12-08 12:20:29.46419 [🅰 #1d66] [🆂 #9ac4 EXTRACT] ✓ EXTRACT completed in 0.02s
2025-12-08 12:20:29.46520 [🅰 #1d66] ⤑ [🧠 #03a1 LLM] gpt-4.1-mini ⏴ tool result: ariaTree(): Accessibility Tre…7] paragraph [0-18] link: Learn more +{10 tools}
2025-12-08 12:20:32.21321 [🅰 #1d66] ⤑ [🧠 #03a1 LLM] gpt-4.1-mini ↳ ꜛ806 ꜜ34 | tool call: close()
2025-12-08 12:20:32.21422 [🅰 #1d66] ✓ Agent.execute() DONE in 5.6s | 2 LLM calls ꜛ1494 ꜜ46 tokens | 6 CDP msgs
2025-12-08 12:20:32.21523 ⤑ ⤑ [🆄 #cb65 GOTO] ▷ Page.goto({args:[https://example.com/,{waitUntil:load}]})
2025-12-08 12:20:32.21524 ⤑ ⤑ [🆄 #cb65 GOTO] [🅲 #FE7B CDP] ⏵ Page.navigate({url:https://example.com/})
2025-12-08 12:20:32.25425 ⤑ ⤑ [🆄 #cb65 GOTO] [🅲 #FE7B CDP] ⏴ Page.frameStartedNavigating({frameId:8A6B…FE7B,u…rId:2130…4BDE,navigationType:differentDocument})
2025-12-08 12:20:32.25426 ⤑ ⤑ [🆄 #cb65 GOTO] [🅲 #FE7B CDP] ⏴ Page.frameStartedLoading({frameId:8A6B…FE7B})
2025-12-08 12:20:32.25727 ⤑ ⤑ [🆄 #cb65 GOTO] [🅲 #FE7B CDP] ⏵ Page.setLifecycleEventsEnabled({enabled:true})
2025-12-08 12:20:32.25828 ⤑ ⤑ [🆄 #cb65 GOTO] [🅲 #FE7B CDP] ⏴ DOM.scrollableFlagUpdated({nodeId:1,isScrollable:false})
2025-12-08 12:20:32.25929 ⤑ ⤑ [🆄 #cb65 GOTO] [🅲 #FE7B CDP] ⏴ Page.frameNavigated({frame:{id:8A6B…FE7B,loaderI…tIsolated,gatedAPIFeatures:[]},type:Navigation})
2025-12-08 12:20:32.26030 ⤑ ⤑ [🆄 #cb65 GOTO] [🅲 #FE7B CDP] ⏴ Network.policyUpdated({})
2025-12-08 12:20:32.26031 ⤑ ⤑ [🆄 #cb65 GOTO] [🅲 #FE7B CDP] ⏴ DOM.documentUpdated({})
2025-12-08 12:20:32.26032 ⤑ ⤑ [🆄 #cb65 GOTO] [🅲 #FE7B CDP] ⏴ Runtime.consoleAPICalled({type:info,args:[{type:…ptId:5,url:",lineNumber:0,columnNumber:2837}]}})
2025-12-08 12:20:32.26133 ⤑ ⤑ [🆄 #cb65 GOTO] [🅲 #FE7B CDP] ⏴ DOM.documentUpdated({})
2025-12-08 12:20:32.26134 ⤑ ⤑ [🆄 #cb65 GOTO] [🅲 #FE7B CDP] ⏴ Page.domContentEventFired({timestamp:545869.998129})
2025-12-08 12:20:32.26135 ⤑ ⤑ [🆄 #cb65 GOTO] [🅲 #FE7B CDP] ⏴ Page.loadEventFired({timestamp:545869.998762})
2025-12-08 12:20:32.26136 ⤑ ⤑ [🆄 #cb65 GOTO] [🅲 #FE7B CDP] ⏴ Page.frameStoppedLoading({frameId:8A6B…FE7B})
2025-12-08 12:20:32.26237 ⤑ ⤑ [🆄 #cb65 GOTO] [🅲 #FE7B CDP] ⏵ Runtime.evaluate({expression:document.readyState,contextId:3,returnByValue:true})
2025-12-08 12:20:32.26338 ⤑ ⤑ [🆄 #cb65 GOTO] ✓ GOTO completed in 0.05s
2025-12-08 12:20:32.26339 [🅰 #c756] ▷ Agent.execute({instruction:Click on the More information... link on the page.,maxSteps:3})
2025-12-08 12:20:32.26440 [🅰 #c756] ⤑ ⤑ [🅲 #FE7B CDP] ⏵ Page.addScriptToEvaluateOnNewDocument({source:(() => …ue });\n setTimeout(install, 100);\n }\n })();})
2025-12-08 12:20:32.26441 [🅰 #c756] ⤑ ⤑ [🅲 #FE7B CDP] ⏴ Accessibility.loadComplete({root:{nodeId:23,ignored:f…ds:[24],backendDOMNodeId:23,frameId:8A6B…FE7B}})
2025-12-08 12:20:32.26542 [🅰 #c756] ⤑ ⤑ [🅲 #FE7B CDP] ⏵ Runtime.evaluate({expression:({ w: window.innerWidth,…ntextId:3,awaitPromise:true,returnByValue:true})
2025-12-08 12:20:32.26543 [🅰 #c756] ⤑ ⤑ [🅲 #FE7B CDP] ⏵ Runtime.evaluate({expression:(() => {\n const ID = __… 100);\n }\n })();,includeCommandLineAPI:false})
2025-12-08 12:20:32.26744 [🅰 #c756] ⤑ [🧠 #2798 LLM] claude-sonnet-4-5-20250929 ⏴ Click on the More information... link on the page.
2025-12-08 12:20:36.15745 [🅰 #c756] ⤑ [🧠 #2798 LLM] claude-sonnet-4-5-20250929 ↳ ꜛ1875 ꜜ79 | Ill help you click on the More information... l tool_use:computer
2025-12-08 12:20:36.96146 [🅰 #c756] ⤑ [🆄 #f55d SCREENSHOT] ▷ Page.screenshot({args:[{fullPage:false}]})
2025-12-08 12:20:36.96447 [🅰 #c756] ⤑ [🆄 #f55d SCREENSHOT] [🅲 #FE7B CDP] ⏵ Runtime.evaluate({expression:(() …ntextId:3,awaitPromise:true,returnByValue:true})
2025-12-08 12:20:36.96648 [🅰 #c756] ⤑ [🆄 #f55d SCREENSHOT] [🅲 #FE7B CDP] ⏵ Page.captureScreenshot({format:png,fromSurface:true,captureBeyondViewport:false})
2025-12-08 12:20:37.01149 [🅰 #c756] ⤑ [🆄 #f55d SCREENSHOT] [🅲 #FE7B CDP] ⏵ Runtime.evaluate({expression:(() …ntextId:3,awaitPromise:true,returnByValue:true})
2025-12-08 12:20:37.01250 [🅰 #c756] ⤑ [🆄 #f55d SCREENSHOT] ✓ SCREENSHOT completed in 0.05s
2025-12-08 12:20:37.01251 [🅰 #c756] ⤑ [🆄 #cce8 SCREENSHOT] ▷ Page.screenshot({args:[{fullPage:false}]})
2025-12-08 12:20:37.01352 [🅰 #c756] ⤑ [🆄 #cce8 SCREENSHOT] [🅲 #FE7B CDP] ⏵ Runtime.evaluate({expression:(() …ntextId:3,awaitPromise:true,returnByValue:true})
2025-12-08 12:20:37.01453 [🅰 #c756] ⤑ [🆄 #cce8 SCREENSHOT] [🅲 #FE7B CDP] ⏵ Page.captureScreenshot({format:png,fromSurface:true,captureBeyondViewport:false})
2025-12-08 12:20:37.04054 [🅰 #c756] ⤑ [🆄 #cce8 SCREENSHOT] [🅲 #FE7B CDP] ⏵ Runtime.evaluate({expression:(() …ntextId:3,awaitPromise:true,returnByValue:true})
2025-12-08 12:20:37.04155 [🅰 #c756] ⤑ [🆄 #cce8 SCREENSHOT] ✓ SCREENSHOT completed in 0.03s
2025-12-08 12:20:37.04156 [🅰 #c756] ⤑ [🧠 #ce80 LLM] claude-sonnet-4-5-20250929 ⏴ Current URL: https://example.com/ +{15.8kb image}
2025-12-08 12:20:44.82757 [🅰 #c756] ⤑ [🧠 #ce80 LLM] claude-sonnet-4-5-20250929 ↳ ꜛ3192 ꜜ192 | I can see a pag…ith Example Domain as the head tool_use:computer
2025-12-08 12:20:45.12958 [🅰 #c756] ⤑ [🆄 #f8c3 V3CUA.SCROLL] ▷ v3CUA.scroll({target:(644, 400),args:[{type:sc…scroll_amount:3,pageUrl:https://example.com/}]})
2025-12-08 12:20:45.12959 [🅰 #c756] ⤑ [🆄 #3fc9 SCROLL] [🅲 #FE7B CDP] ⏵ Runtime.evaluate({expression:typeof w…"undefined\"&&window.__v3Cursor.move(644, 400)})
2025-12-08 12:20:45.12960 [🅰 #c756] ⤑ [🆄 #3fc9 SCROLL] ▷ Page.scroll({args:[644,400,0,300]})
2025-12-08 12:20:45.13061 [🅰 #c756] ⤑ [🆄 #3fc9 SCROLL] [🅲 #FE7B CDP] ⏵ Input.dispatchMouseEvent({type:mouseMoved,x:644,y:400,button:none})
2025-12-08 12:20:45.13762 [🅰 #c756] ⤑ [🆄 #3fc9 SCROLL] [🅲 #FE7B CDP] ⏵ Input.dispatchMouseEvent({type:mouseW…el,x:644,y:400,button:none,deltaX:0,deltaY:300})
2025-12-08 12:20:45.14663 [🅰 #c756] ⤑ [🆄 #3fc9 SCROLL] ✓ SCROLL completed in 0.02s
2025-12-08 12:20:45.64764 [🅰 #c756] ⤑ [🆄 #ccb0 SCREENSHOT] ▷ Page.screenshot({args:[{fullPage:false}]})
2025-12-08 12:20:45.64965 [🅰 #c756] ⤑ [🆄 #ccb0 SCREENSHOT] [🅲 #FE7B CDP] ⏵ Runtime.evaluate({expression:(() …ntextId:3,awaitPromise:true,returnByValue:true})
2025-12-08 12:20:45.65266 [🅰 #c756] ⤑ [🆄 #ccb0 SCREENSHOT] [🅲 #FE7B CDP] ⏵ Page.captureScreenshot({format:png,fromSurface:true,captureBeyondViewport:false})
2025-12-08 12:20:45.68567 [🅰 #c756] ⤑ [🆄 #ccb0 SCREENSHOT] [🅲 #FE7B CDP] ⏵ Runtime.evaluate({expression:(() …ntextId:3,awaitPromise:true,returnByValue:true})
2025-12-08 12:20:45.68668 [🅰 #c756] ⤑ [🆄 #ccb0 SCREENSHOT] ✓ SCREENSHOT completed in 0.04s
2025-12-08 12:20:45.68769 [🅰 #c756] ⤑ [🆄 #87f4 SCREENSHOT] ▷ Page.screenshot({args:[{fullPage:false}]})
2025-12-08 12:20:45.68770 [🅰 #c756] ⤑ [🆄 #87f4 SCREENSHOT] [🅲 #FE7B CDP] ⏵ Runtime.evaluate({expression:(() …ntextId:3,awaitPromise:true,returnByValue:true})
2025-12-08 12:20:45.68971 [🅰 #c756] ⤑ [🆄 #87f4 SCREENSHOT] [🅲 #FE7B CDP] ⏵ Page.captureScreenshot({format:png,fromSurface:true,captureBeyondViewport:false})
2025-12-08 12:20:45.71372 [🅰 #c756] ⤑ [🆄 #87f4 SCREENSHOT] [🅲 #FE7B CDP] ⏵ Runtime.evaluate({expression:(() …ntextId:3,awaitPromise:true,returnByValue:true})
2025-12-08 12:20:45.71473 [🅰 #c756] ⤑ [🆄 #87f4 SCREENSHOT] ✓ SCREENSHOT completed in 0.03s
2025-12-08 12:20:45.71474 [🅰 #c756] ⤑ [🧠 #ed51 LLM] claude-sonnet-4-5-20250929 ⏴ Current URL: https://example.com/ +{15.8kb image}
```

---------

Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: Nick Sweeting <pirate@users.noreply.github.com>
Co-authored-by: Miguel <36487034+miguelg719@users.noreply.github.com>
2025-12-09 15:02:34 -08:00
tkattkat
0e95cd2f67
Add support for vertex provider (#1334)
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. -->
2025-12-02 16:39:30 -08:00
Kyle Jeong
8ff7d2721a
fix: adding bufferutil as an optional dep (#1279)
# 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
2025-11-19 15:30:09 -08:00
tkattkat
f27a99c11b
add support for zod v4 (#1282)
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>
2025-11-18 17:04:38 -08:00
Sam F
ef38ccf0a2
Add minimal contract test for public api (#1255)
# 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`
2025-11-17 11:00:31 -08:00
Sean McGuire
e634539c82
rm orca pkg from evals (#1197)
# why

# what changed

# test plan
2025-10-29 12:16:22 -07:00
Miguel
f28a0a6335
Realv3docs (#1190)
# why

# what changed

# test plan

---------

Co-authored-by: Derek Meegan <derek@browserbase.com>
Co-authored-by: Sophie Chance <74380004+sophie2chance2@users.noreply.github.com>
Co-authored-by: Chris Read <rcreadii@gmail.com>
Co-authored-by: Victor Lue <vict.lue@gmail.com>
Co-authored-by: tkattkat <tkat@tkat.net>
Co-authored-by: Sameel <sameel.m.arif@gmail.com>
Co-authored-by: Kylejeong2 <kylejeong21@gmail.com>
Co-authored-by: Filip Michalsky <filip@paywithsoap.com>
2025-10-28 17:55:55 -07:00
tkattkat
231c25a0e7
ai sdk v5 migration in v3 (#1153)
# why

we need to upgrade from ai sdk v4 to v5

# what changed

migrated from v4 to v5

# test plan
2025-10-21 16:28:01 -07:00
miguel
3316274b33 fix build deps 2025-10-16 18:05:49 -07:00
Miguel
1de514741f
V3 google cua (#1135)
# why

# what changed

# test plan

---------

Co-authored-by: Sean McGuire <seanmcguire1@outlook.com>
2025-10-14 16:53:58 -07:00
Miguel
2e02bed7cd
monorepo reorg (#1120)
# why

# what changed

# test plan

---------

Co-authored-by: Sean McGuire <seanmcguire1@outlook.com>
2025-10-10 12:29:49 -07:00
Sean McGuire
1a37005f71 delete v2 code 2025-09-22 15:00:28 -07:00
Sean McGuire
b801b5b196 add patchright 2025-09-17 14:52:32 -07:00
Sean McGuire
9625bad95a Merge branch 'main' into v3
# Conflicts:
#	.changeset/pretty-jokes-own.md
#	package.json
#	pnpm-lock.yaml
2025-09-10 12:39:19 -07:00
Sean McGuire
838e1053ec move browser launch logic into separate files 2025-09-02 17:59:51 -07:00
Sameel
8244ab247c
MCP and Tool-Call Support (#981)
# 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>
2025-08-29 15:11:51 -07:00
Sophie Chance
a8aa3d72c2
Docs Revamp (#1003)
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>
2025-08-22 11:05:58 -07:00
Roaring
f18d46cba6 update understudy to use chrome-debugging-client as its cdp client 2025-08-18 16:35:54 -07:00
Sean McGuire
4c480fe7a3 v3 scaffold 2025-08-18 15:05:18 -07:00
Sean McGuire
8de7bd8635
bump zod version and add pathing spec (#944)
# 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>
2025-08-06 15:03:38 -07:00