481 Commits

Author SHA1 Message Date
github-actions[bot]
9b07e99420
Version Packages (#2067)
This PR was opened by the [Changesets
release](https://github.com/changesets/action) GitHub action. When
you're ready to do a release, you can merge this and the packages will
be published to npm automatically. If you're not ready to do a release
yet, that's fine, whenever you add more changesets to main, this PR will
be updated.


# Releases
## @browserbasehq/stagehand@3.4.0

### Minor Changes

- [#2084](https://github.com/browserbase/stagehand/pull/2084)
[`0641d44`](0641d44a84)
Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - add
ignoreSelectors param to extract()

- [#2096](https://github.com/browserbase/stagehand/pull/2096)
[`a11603d`](a11603d09d)
Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - add
ignoreSelectors to observe()

### Patch Changes

- [#2080](https://github.com/browserbase/stagehand/pull/2080)
[`21c78b3`](21c78b3a50)
Thanks [@miguelg719](https://github.com/miguelg719)! - Add variables
support to v3 agentExecute API schema and remove experimental
requirement

- [#2077](https://github.com/browserbase/stagehand/pull/2077)
[`f437f73`](f437f738d2)
Thanks [@monadoid](https://github.com/monadoid)! - Fix frame registry
handling for OOPIF pages

- [#2098](https://github.com/browserbase/stagehand/pull/2098)
[`a783b99`](a783b99fb9)
Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - bump
transitive deps to patched versions

- [#2089](https://github.com/browserbase/stagehand/pull/2089)
[`8d2f354`](8d2f354142)
Thanks [@shrey150](https://github.com/shrey150)! - Strengthen observe
prompts so LLMs return complete encoded element IDs.

- [#2047](https://github.com/browserbase/stagehand/pull/2047)
[`a87c1fc`](a87c1fc435)
Thanks [@tkattkat](https://github.com/tkattkat)! - Set default agent
mode to hybrid with auto routing to dom for non compatible models

- [#2101](https://github.com/browserbase/stagehand/pull/2101)
[`26e6c96`](26e6c960ca)
Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - move
playwright-core, puppeteer-core, patchright-core from optional
dependencies to peer dependencies

- [#2068](https://github.com/browserbase/stagehand/pull/2068)
[`1d176c4`](1d176c466e)
Thanks [@filip-michalsky](https://github.com/filip-michalsky)! - Remove
the default temperature setting from v3 agent AI SDK calls so reasoning
models that do not support temperature run without provider warnings.

- [#2040](https://github.com/browserbase/stagehand/pull/2040)
[`1fa9613`](1fa96130ab)
Thanks [@monadoid](https://github.com/monadoid)! - Prefer
`STAGEHAND_API_URL` for Stagehand API overrides while retaining
`STAGEHAND_BASE_URL` as a deprecated fallback.

- [#2065](https://github.com/browserbase/stagehand/pull/2065)
[`9ff70dd`](9ff70dd26c)
Thanks [@miguelg719](https://github.com/miguelg719)! - Add support for
CUA models: openai/gpt-5.4-mini, openai/gpt-5.5, and
anthropic/claude-haiku-4-5

- [#2039](https://github.com/browserbase/stagehand/pull/2039)
[`7640381`](76403819b8)
Thanks [@monadoid](https://github.com/monadoid)! - Deprecate Browserbase
project ID configuration.

## @browserbasehq/stagehand-evals@2.0.1

### Patch Changes

- Updated dependencies
\[[`21c78b3`](21c78b3a50),
[`0641d44`](0641d44a84),
[`f437f73`](f437f738d2),
[`a783b99`](a783b99fb9),
[`8d2f354`](8d2f354142),
[`a11603d`](a11603d09d),
[`a87c1fc`](a87c1fc435),
[`26e6c96`](26e6c960ca),
[`1d176c4`](1d176c466e),
[`1fa9613`](1fa96130ab),
[`9ff70dd`](9ff70dd26c),
[`7640381`](76403819b8)]:
    -   @browserbasehq/stagehand@3.4.0

## @browserbasehq/stagehand-server-v3@3.6.4

### Patch Changes

- [#2098](https://github.com/browserbase/stagehand/pull/2098)
[`a783b99`](a783b99fb9)
Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - bump
transitive deps to patched versions

- [#2091](https://github.com/browserbase/stagehand/pull/2091)
[`de132bc`](de132bc6f2)
Thanks [@pirate](https://github.com/pirate)! - Default the v3 server
listener to localhost, respect explicit HOST values, and warn when
HOST=0.0.0.0 exposes all interfaces.

- [#2040](https://github.com/browserbase/stagehand/pull/2040)
[`1fa9613`](1fa96130ab)
Thanks [@monadoid](https://github.com/monadoid)! - Prefer
`STAGEHAND_API_URL` for Stagehand API overrides while retaining
`STAGEHAND_BASE_URL` as a deprecated fallback.

- [#2094](https://github.com/browserbase/stagehand/pull/2094)
[`4a808c4`](4a808c4378)
Thanks [@monadoid](https://github.com/monadoid)! - Make the model API
key optional in the v3 OpenAPI security requirements.

- [#2039](https://github.com/browserbase/stagehand/pull/2039)
[`7640381`](76403819b8)
Thanks [@monadoid](https://github.com/monadoid)! - Deprecate Browserbase
project ID configuration.

- Updated dependencies
\[[`21c78b3`](21c78b3a50),
[`0641d44`](0641d44a84),
[`f437f73`](f437f738d2),
[`a783b99`](a783b99fb9),
[`8d2f354`](8d2f354142),
[`a11603d`](a11603d09d),
[`a87c1fc`](a87c1fc435),
[`26e6c96`](26e6c960ca),
[`1d176c4`](1d176c466e),
[`1fa9613`](1fa96130ab),
[`9ff70dd`](9ff70dd26c),
[`7640381`](76403819b8)]:
    -   @browserbasehq/stagehand@3.4.0

## @browserbasehq/stagehand-server-v4@3.6.4

### Patch Changes

- [#2098](https://github.com/browserbase/stagehand/pull/2098)
[`a783b99`](a783b99fb9)
Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - bump
transitive deps to patched versions

- Updated dependencies
\[[`21c78b3`](21c78b3a50),
[`0641d44`](0641d44a84),
[`f437f73`](f437f738d2),
[`a783b99`](a783b99fb9),
[`8d2f354`](8d2f354142),
[`a11603d`](a11603d09d),
[`a87c1fc`](a87c1fc435),
[`26e6c96`](26e6c960ca),
[`1d176c4`](1d176c466e),
[`1fa9613`](1fa96130ab),
[`9ff70dd`](9ff70dd26c),
[`7640381`](76403819b8)]:
    -   @browserbasehq/stagehand@3.4.0

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
2026-05-11 14:17:14 -07:00
Sean McGuire
26e6c960ca
[chore]: move integration libs into peer deps (#2101)
# why
- pnpm installs optional deps by default, which meant installing
`stagehand` would also pull in `playwright-core`, `patchright-core`, &
`puppeteer-core`
- these packages should be supplied by the consumer **_only if_** they
want to use `stagehand` with an existing browser automation framework.
they are otherwise not required
- moving them into peer dependencies prevents unnecessary installs, &
reflects a more accurate dependency graph

# what changed
- moved `playwright-core`, `patchright-core`, & `puppeteer-core` in
`packages/core` from optional deps to optional peer deps


<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Moved `playwright-core`, `patchright-core`, and `puppeteer-core` to
optional peer dependencies in `@browserbasehq/stagehand` to stop
automatic installs and let consumers opt in only if needed. Also aligned
`playwright` version ranges across packages.

- **Dependencies**
- In `packages/core`: moved `playwright-core`, `patchright-core`,
`puppeteer-core` from optional deps to optional peer deps (all marked
optional).
- Updated internal dev deps to keep tests working: `playwright`,
`playwright-core`, `puppeteer-core`, `patchright-core`.
- Aligned `playwright` ranges: `packages/evals` uses `>=1.55.1 <1.57.0`;
`packages/server-v3` and `packages/server-v4` use `^1.55.1`.

- **Migration**
  - If you use Stagehand with Playwright, add `playwright-core@^1.55.1`.
  - If you use Puppeteer, add `puppeteer-core@^24.43.0`.
  - If you use Patchright, add `patchright-core@^1.55.2`.

<sup>Written for commit dc726fc12933305106cb7936eb6a18310cfb7c53.
Summary will update on new commits.</sup>

<!-- End of auto-generated description by cubic. -->
2026-05-11 10:00:45 -07:00
Sean McGuire
8e5a4606e8
[docs]: rm lockfile from docs package (#2099)
# why
- lockfile was unused, leftover from monorepo reorg 
# what changed
- removed `packages/docs/pnpm-lock.yaml`


<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Removed the unused docs lockfile left over from the monorepo reorg.
Deleting `packages/docs/pnpm-lock.yaml` reduces noise and avoids
confusion about dependency state.

<sup>Written for commit d8a5c2b1da751e3edf2c2271382bb7984278e364.
Summary will update on new commits.</sup>

<!-- End of auto-generated description by cubic. -->
2026-05-08 16:22:24 -07:00
Miguel
84bfc8426f
Evals man help (#2092)
# Why

Help discovery was inconsistent across the evals CLI.

- `--help` / `-h` worked everywhere.
- The bare word `help` only worked at the top level and on three
dispatcher commands.
- `config core` had no dedicated help page at all — `evals config core
--help` was intercepted upstream and printed the parent `config` help
instead.

# What Changed

- Added `printConfigCoreHelp` documenting:
  - `evals config core`
  - `path`
  - `set`
  - `reset`
  - `setup`

- Standardized `help` as a positional alias for `--help` at every level:
  - Top-level dispatchers:
    - `run`
    - `list`
    - `new`
    - `config`
    - `experiments`
  - Nested dispatchers:
    - `config core`
  - Leaf verbs:
    - `set`
    - `reset`
    - `path`
    - `setup`
    - `list`
    - `show`
    - `open`
    - `compare`

- Removed the early `wantsHelp → printConfigHelp()` interception in:
  - `cli.ts`
  - `repl.ts`

This allows `config core --help` to correctly reach the core-specific
help page.

- Cleaned up:
  - unused imports
  - dead experiments help branch

- Help interception now only occurs when `help` appears as the first
argument to a verb, so legitimate values such as `evals config set
provider help` continue to work properly.

# Tests

- [x] Added 35 parameterized `it.each` cases in `tests/cli.test.ts`
covering:
  - `help`
  - `--help`
  - `-h`
across every command and subcommand level.

- [x] Full evals unit suite:
  - `251 / 251` passing

- [x] Verified built CLI prints correct help for:
  - `config core help`
  - `experiments compare help`
  - `run help`
2026-05-08 16:00:56 -07:00
Sean McGuire
a783b99fb9
[chore]: bump various transitive deps across monorepo (#2098)
# why
- to bump a small set of direct and transitive dependencies to pick up
patched upstream releases
# what changed
- bumped `playwright` to 1.55.1 across workspace all workspace packages
- bumped `@playwright/test` in `packages/core` to 1.55.1
- bumped `playwright-core` in `packages/core` to 1.55.1
- bumped `puppeteer-core` in `packages/core` to 24.43.0
- bumped `jsdom` in `packages/core` to 29.1.1.
- bumped `@browserbasehq/sdk` where needed to pick up a patched
transitive dependency tree
# test plan
- existing test suite + pnpm audit

<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Bumps key direct and transitive dependencies across the monorepo to pick
up patched upstream releases and align browser tooling. Ships patch
releases for Stagehand packages.

- **Dependencies**
- `packages/core`: `playwright` → `^1.59.1`, `playwright-core` →
`^1.59.1`, `@playwright/test` → `^1.59.1`, `puppeteer-core` →
`^24.43.0`, `jsdom` → `^29.1.1`, `openai` → `^4.104.0`,
`@langchain/openai` → `^0.4.9`.
- `packages/server-v3` and `packages/server-v4`: `playwright` →
`1.55.1`.
- `packages/evals`: `openai` → `^4.104.0`, `playwright` → `^1.55.1`,
`braintrust` → `^0.4.10`, added `@types/node` and `types: ["node"]` in
`tsconfig`.
  - Updated `pnpm-lock.yaml`.
- Patch releases: `@browserbasehq/stagehand`,
`@browserbasehq/stagehand-evals`, `@browserbasehq/stagehand-server-v3`,
`@browserbasehq/stagehand-server-v4`.

- **Migration**
  - Reinstall deps: `pnpm install`.
  - Reinstall Playwright browsers if needed: `npx playwright install`.

<sup>Written for commit db96e496ead3c081d74484784763aa86b6d096a9.
Summary will update on new commits.</sup>

<!-- End of auto-generated description by cubic. -->
2026-05-08 13:37:14 -07:00
Nick Sweeting
de132bc6f2
Default SEA binary server-v3 to only bind to localhost (#2091)
## Summary
- default the v3 server listener to localhost unless HOST is explicitly
set
- warn when HOST=0.0.0.0 opts into all-interface binding
- make the v4 SEA build choose a Node binary that contains the SEA fuse

## Validation
- pnpm --filter @browserbasehq/stagehand-server-v3 run build:esm-tests
- pnpm --filter @browserbasehq/stagehand-server-v3 run typecheck
- pnpm --filter @browserbasehq/stagehand-server-v4 run typecheck
- pnpm --filter @browserbasehq/stagehand-server-v3 run test:unit --
packages/server-v3/dist/tests/unit/listenHost.test.js
- pnpm --filter @browserbasehq/stagehand-server-v4 run build:sea:esm --
--binary-name=stagehand-server-v4-localhost-binding-test

Leaving the full suite to CI.

<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Default `@browserbasehq/stagehand-server-v3` to listen on localhost
unless `HOST` is set, and warn on `HOST=0.0.0.0` to prevent accidental
exposure. Also make the `@browserbasehq/stagehand-server-v4` SEA build
use a Node binary that includes the SEA fuse for reliable builds.

- New Features
- Default listen host to `localhost` when `HOST` is unset or blank;
respect explicit values.
  - Warn when `HOST=0.0.0.0` to make all-interface binding explicit.

- Migration
- If you need external access, set `HOST=0.0.0.0` (or a specific
interface).

<sup>Written for commit 3cecdce8251f43aa3853ca56f8924eb0dda9dff7.
Summary will update on new commits.</sup>

<!-- End of auto-generated description by cubic. -->
2026-05-07 14:06:34 -07:00
Sean McGuire
a11603d09d
[feat]: add ignoreSelectors to observe() (#2096)
# why
- to let users exclude parts of the page from the snapshot that
`observe()` sends to the model, the same way they can with `extract()`

# what changed
- this PR is just wiring the added param through observe & updating
types. it uses the same underlying functionality that was added in #2084
when adding `ignoreSelectors` to `extract()`
- `packages/core/lib/v3/types/public/methods.ts`,
`packages/core/lib/v3/types/private/handlers.ts`, &
`packages/core/lib/v3/types/public/api.ts`:
- added the `ignoreSelectors` option to the public api, internal handler
params, & request schema
- `packages/core/lib/v3/v3.ts` &
`packages/core/lib/v3/handlers/observeHandler.ts`:
- passed `ignoreSelectors` through the observe path into
`captureHybridSnapshot()`

# test plan
- updated `packages/core/tests/unit/public-api/public-types.test.ts` to
cover the new `ignoreSelectors` param
- updated `packages/core/tests/unit/api-variables-schema.test.ts` &
`packages/core/tests/unit/api-client-observe-variables.test.ts` to cover
request validation and serialization for `observe({ ignoreSelectors })`
- updated `packages/core/tests/unit/timeout-handlers.test.ts` to cover
`ObserveHandler` passing `ignoreSelectors` into
`captureHybridSnapshot()`

### notes
- the test file placement is a little weird right now: 
- `timeout-handlers.test.ts` already contains broader parameter
threading tests, so this was the smallest change for now
  - this can be cleaned up in a later refactor


<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Add `ignoreSelectors` to `observe()` so you can exclude elements from
the snapshot sent to the model. Brings `observe()` to parity with
`extract()`.

- **New Features**
- Support `observe({ ignoreSelectors: ["nav", ".cookie-banner"] })` to
skip elements and subtrees during snapshot capture.
- Plumbed through public types, internal handler params, and
`captureHybridSnapshot()` call path.
- Request schema and `packages/server-v3/openapi.v3.yaml` updated;
client serialization and validation covered by tests.
  - Published as a minor for `@browserbasehq/stagehand`.

<sup>Written for commit c7b538c04d439b13d28db843a12344529171219b.
Summary will update on new commits.</sup>

<!-- End of auto-generated description by cubic. -->
2026-05-07 11:24:56 -07:00
Sam F
4a808c4378
STG-1806 Make model API key optional in OpenAPI (#2094)
## Summary
- remove ModelApiKey from the server-v3 OpenAPI global security
requirement
- update the checked-in v3 OpenAPI spec so Stainless no longer treats
model API key as required client auth

## Verification
- pnpm --filter @browserbasehq/stagehand-server-v3 run lint
- pnpm --filter @browserbasehq/stagehand-server-v3 run build

<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Make the model API key optional by removing `ModelApiKey` from server v3
OpenAPI global security (STG-1806). Update the spec/generator in
`@browserbasehq/stagehand-server-v3` and add a patch changeset so
Stainless clients no longer require a model key.

- **Migration**
- Regenerate clients from the v3 OpenAPI (e.g., Stainless) to drop
`ModelApiKey` as required auth.

<sup>Written for commit 3c74893febe6a3501f26eaa700ba2290c02cad56.
Summary will update on new commits.</sup>

<!-- End of auto-generated description by cubic. -->

---------

Co-authored-by: samfinton <samfinton@samLaptopm5.galaxus.box>
2026-05-07 20:22:09 +02:00
Sean McGuire
86d3ec070e
[chore]: commit updated spec (#2095)
# why
- schema descriptions changed which means spec yaml files need to be
regenerated
- the regenerated yaml files were uncommitted
# what changed
- added the regenerated yaml files


<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Regenerated OpenAPI specs for `packages/server-v3` and
`packages/server-v4` to align with schema description updates. In v4,
the `x-bb-project-id` header and related `projectId` fields are now
deprecated since API keys are project-scoped.

- **Migration**
  - Stop sending the `x-bb-project-id` header.
  - Omit `projectId` in v4 session payloads and ignore it in responses.

<sup>Written for commit 8dd382e1833337e8ea52021f8ca66f9284e01061.
Summary will update on new commits.</sup>

<!-- End of auto-generated description by cubic. -->
2026-05-07 10:44:46 -07:00
Shrey Pandya
8d2f354142
[STG-1935] fix: strengthen observe element ID prompting (#2089)
Linear:
https://linear.app/browserbase/issue/STG-1935/strengthen-observe-element-id-prompting

## Summary

- keep the strict `number-number` observe element ID schema intact
- strengthen the observe system prompt to tell the model to copy the
full bracketed tree ID, including frame ordinal and hyphen
- strengthen the schema description with the concrete `[0-18372] ->
"0-18372", not "18372"` example
- add prompt regression coverage, main-frame `0-...` observe integration
coverage, and a patch changeset
- add `observe/observe_main_frame_element_ids` as a regression eval for
multiple main-frame targets

## Eval Coverage

Current bench eval count after this PR:

```text
146 total bench evals
12 observe bench evals
```

This PR adds one observe regression eval:
`observe/observe_main_frame_element_ids`.

## Validation

- `pnpm --filter @browserbasehq/stagehand run build`
- `pnpm --filter @browserbasehq/stagehand run test:core --
packages/core/dist/esm/tests/unit/prompt-observe-variables.test.js`
- `pnpm --filter @browserbasehq/stagehand run test:e2e --
packages/core/dist/esm/tests/integration/observe-element-id-format.spec.js`
- `pnpm --filter @browserbasehq/stagehand run lint`
- `pnpm --filter @browserbasehq/stagehand-evals run typecheck`
- `pnpm --filter @browserbasehq/stagehand-evals run test:unit --
tests/taskConfig.test.ts`
- `pnpm --filter @browserbasehq/stagehand-evals run lint`
- `env STAGEHAND_E2E_TARGET=BROWSERBASE pnpm exec tsx
/Users/shrey/Developer/scratchpad/stagehand-observe-bare-id-e2e/index.ts`
- `pnpm --filter @browserbasehq/stagehand-evals exec tsx cli.ts run
observe_main_frame_element_ids -e browserbase -t 1 -c 1 -m
anthropic/claude-sonnet-4-6`

Real Browserbase E2E used `anthropic/claude-sonnet-4-6` and verified raw
model IDs plus click success:

```text
Attempt 1 raw model elementId: 0-5011
Attempt 1 act success: true
Attempt 1 DOM clicked marker: yes
Attempt 2 raw model elementId: 0-5011
Attempt 2 act success: true
Attempt 2 DOM clicked marker: yes
Attempt 3 raw model elementId: 0-5011
Attempt 3 act success: true
Attempt 3 DOM clicked marker: yes
```

The new Browserbase bench eval also passed with
`anthropic/claude-sonnet-4-6`:

```text
observe/observe_main_frame_element_ids  anthropic/claude-sonnet-4-6  passed
Results: 1 passed, 0 failed (1 total)
Pass rate: 100%
```
2026-05-07 08:49:55 -07:00
Filip Michalsky
c4da2e2286
remove default temp (#2076)
# why

Stagehand v3 was setting hard-coded temperature defaults for standard
act, extract, and observe inference calls. This forced provider
  behavior instead of letting model/provider defaults apply.

  # what changed

Removed the hard-coded temperature: isGPT5 ? 1 : 0.1 defaults from
shared act, extract, and observe inference.

  Removed the unused GPT-5 temperature branching in that path.

Updated Groq and Cerebras clients to pass through options.temperature
directly instead of defaulting missing values to 0.7, while preserving
  explicit temperature: 0.

  Added regression tests covering:

  - act, extract, and observe no longer pass temperature by default
  - Groq/Cerebras do not inject default temperature
  - Groq/Cerebras preserve explicit zero temperature

  # test plan

  - pnpm --filter @browserbasehq/stagehand run typecheck
- pnpm --filter @browserbasehq/stagehand exec prettier --check
lib/inference.ts lib/v3/llm/GroqClient.ts lib/v3/llm/CerebrasClient.ts
tests/
unit/inference-temperature.test.ts
tests/unit/openai-compatible-temperature.test.ts
  - pnpm --filter @browserbasehq/stagehand run build:esm
- pnpm --filter @browserbasehq/stagehand run test:core --
packages/core/dist/esm/tests/unit/inference-temperature.test.js
packages/core/
dist/esm/tests/unit/openai-compatible-temperature.test.js
packages/core/dist/esm/tests/unit/aisdk-clients.test.js
packages/core/dist/esm/
    tests/unit/anthropic-cua-adaptive-thinking.test.js

---------

Co-authored-by: Filip Michalsky <filip-michalsky@users.noreply.github.com>
Co-authored-by: Miguel <36487034+miguelg719@users.noreply.github.com>
Co-authored-by: Chromie <miguel@browserbase.com>
Co-authored-by: Claude <noreply@anthropic.com>
2026-05-06 17:17:16 -07:00
Miguel
21c78b3a50
remove experimental requirement on agent variables (#2079) (#2080)
# why
`experimental: true` is no longer required for agent variable support

# what changed
- Removed the experimental gate on agent variables: dropped the
variables check in `validateExperimentalFeatures.ts` and the
@experimental JSDoc on `AgentExecuteOptionsBase.variables`.
- Added a variables field to the AgentExecuteOptions API schema
(`packages/core/lib/v3/types/public/api.ts`) and reflected it in the
generated `openapi.v3.yaml` (both request and output components).
- Updated docs to drop `experimental: true` from the Variables Note and
Basic Usage example (kept the "Non-CUA agents only" caveat).
- Added unit tests covering the new surface
- Added integration coverage on the login eval site: new variables
describe blocks in `act.test.ts` and `agentExecute.test.ts` (simple and
rich { value, description } forms, verified via CDP), and updated
`observe.test.ts`'s existing variables tests to use the same scenario.

# test plan
- [x] pnpm --filter @browserbasehq/stagehand-server-v3 typecheck —
passes.
- [x] pnpm exec prettier --check on the three test files — passes.
- [x] pnpm exec eslint on the three test files — passes. 

<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Enable variables in v3 `agentExecute` without experimental mode, with
end-to-end substitution across `act`, `observe`, and agent tools.
Tightened `fillFormVision` so secrets are only substituted at type-time
and never leak via logs, replays, or tool outputs.

- **New Features**
- Added `variables` to `AgentExecuteOptionsSchema` and server OpenAPI
(`Variables`).
- Removed experimental gating for variables; CUA-mode rejection remains.
  - Updated JSDoc and docs to drop the experimental requirement.
- Added tests: unit (validation, client serialization, schema) and
integration for substitution in `act`, `observe`, and `agentExecute`
(simple and rich forms).

- **Bug Fixes**
- Updated `fillFormVision` to substitute variables only when typing and
keep placeholders in action logs, replays, and returned arguments.

<sup>Written for commit a6e9d621d396cab397bd5348c814629373693cf0.
Summary will update on new commits.</sup>

<!-- End of auto-generated description by cubic. -->

---------

Co-authored-by: Chromie <miguel@browserbase.com>
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: tkattkat <tkat@tkat.net>
2026-05-06 11:51:41 -07:00
Sam F
76403819b8
[STG-1808] Deprecate Browserbase project ID (#2039)
# why
Browserbase API keys are project-scoped, so Stagehand should keep
accepting project IDs without requiring them.

# what changed
- Mark `browserbaseSessionCreateParams.projectId` deprecated in
Zod/OpenAPI.
- Make `BROWSERBASE_PROJECT_ID` nullable/deprecated in Stainless config.
- Use Browserbase-returned `projectId` in the local server instead of
`x-bb-project-id`.

```ts
projectId: z.string().optional().meta({ deprecated: true })
```

# test plan
- `pnpm --filter @browserbasehq/stagehand run lint`
- `pnpm --filter @browserbasehq/stagehand-server-v3 run lint`

<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Deprecate Browserbase project ID per STG-1808; Stagehand now relies on
project-scoped API keys and the project ID returned by Browserbase. The
`x-bb-project-id` header, session `projectId` param, and
`BROWSERBASE_PROJECT_ID` config are deprecated but remain optional for
now.

- **Refactors**
- Marked `projectId` in session create params as deprecated in
Zod/OpenAPI; updated security scheme descriptions to reflect deprecation
of `x-bb-project-id`.
- Made `BROWSERBASE_PROJECT_ID` nullable and marked deprecated in
`stainless.yml`.
- Server now resolves `projectId` from the retrieved/created Browserbase
session; stops reading `x-bb-project-id` and adjusts validation
messages.

- **Migration**
- Stop sending `x-bb-project-id` and remove `BROWSERBASE_PROJECT_ID`;
they’re no longer needed.
- Avoid passing `projectId` in session creation; it’s accepted but
deprecated.

<sup>Written for commit 5ee90b860105739405927eec695060a1d1a066fc.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/2039">Review in
cubic</a></sup>

<!-- End of auto-generated description by cubic. -->
2026-05-06 19:11:05 +02:00
Sean McGuire
0641d44a84
[feat]: add ignoreSelectors to extract() (#2084)
# why
- to allow users to specify selectors whose content should be omitted
from the LLM request inside of `extract()`
# what changed
- added `ignoreSelectors` to `extract()` so callers can exclude parts of
the page from the extraction snapshot
- `packages/core/lib/v3/understudy/a11y/snapshot/capture.ts`:
- added `resolveIgnoreSelectorRoots()` to resolve ignore selectors into
`frameId + backendNodeId`
- added `buildFrameExclusionIntervals()` to turn those roots into
per-frame subtree ranges
- updated `collectPerFrameMaps()` / `tryScopedSnapshot()` to skip
ignored nodes when building snapshot data
- `packages/core/lib/v3/understudy/a11y/snapshot/domTree.ts`:
- updated `buildSessionDomIndex()` to record dfs entry/exit positions
for each backend node so ignored subtrees can be filtered by interval
membership instead of having to re-traverse the tree
- `packages/core/lib/v3/understudy/a11y/snapshot/a11yTree.ts`: 
- updated `a11yForFrame()` to accept an ignore predicate and remove
ignored nodes from the outline (the stringified tree) and `urlMap`
- `packages/core/lib/v3/handlers/extractHandler.ts` and
`packages/core/lib/v3/v3.ts`:
- passed `ignoreSelectors` down through the extract path into
`captureHybridSnapshot()`
- kept `xpathMap` values based on the original dom structure and only
skipped ignored entries, so surviving selectors do not get renumbered

# test plan
- updated `packages/core/tests/unit/public-api/public-types.test.ts` to
cover the new `ignoreSelectors` option on `extract()`
- updated `packages/core/tests/unit/snapshot-a11y-resolvers.test.ts` to
cover ignored backend nodes being removed from the a11y outline and
`urlMap`, and to cover scoped snapshots dropping ignored xpath entries
- updated
`packages/core/tests/unit/snapshot-capture-orchestration.test.ts` to
cover the new capture flow, including filtered per-frame maps and merged
snapshot output when `ignoreSelectors` is used

<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Adds `ignoreSelectors` to `extract()` so callers can exclude elements
and their subtrees from snapshots and the LLM input. Supports CSS and
XPath (with iframe hops) across shadow DOM and iframes, without
renumbering existing XPaths; also adds a fast path for scoped snapshots
and excludes child frame subtrees when an iframe host is ignored.

- **New Features**
- `extract({ ignoreSelectors: string[] })`: drops matching nodes and
descendants from DOM maps, a11y outline, and `urlMap`; `xpathMap` keeps
original values but omits ignored entries.
- Applies to full-page and scoped snapshots; filters resolved per frame,
excludes child frames when their iframe host is ignored, and enforces
DFS enter/exit intervals for speed.
- A11y tree accepts an ignore predicate and filters before building the
outline and links.
- Scoped snapshots return early when only `selector` is provided (no
`ignoreSelectors`) for faster capture.
- Plumbed through `extractHandler`, `v3`, and `captureHybridSnapshot()`;
public types and OpenAPI updated in `@browserbasehq/stagehand`; unit
tests added.

<sup>Written for commit 0ad2f67d8fe81d15945599c60351ac45f66f1277.
Summary will update on new commits.</sup>

<!-- End of auto-generated description by cubic. -->
2026-05-06 10:05:31 -07:00
Filip Michalsky
1d176c466e
remove hardcoded agent temp (#2068)
# why                                                                
Reasoning models (e.g. `openai/gpt-5-mini`) emit `AI SDK Warning: The
"temperature" setting is not supported by this model` whenever the v3
agent
runs against them, because `V3AgentHandler` hardcoded `temperature: 1`
on every `generateText`/`streamText` call. There was no constructor or
agent-config option to override it, so users running reasoning models
with `experimental: true` had no way to silence the warning.
  # what changed                                                       
- Removed the hardcoded `temperature: 1` from both the non-streaming and
streaming agent paths in
`packages/core/lib/v3/handlers/v3AgentHandler.ts`.
- Agent calls now omit `temperature` entirely, so the AI SDK no longer
flags it as user-set on models that don't accept it. Models that do
accept
temperature still default to the AI SDK provider's own default.
- Added unit coverage in
`packages/core/tests/unit/agent-temperature.test.ts` asserting neither
code path passes a `temperature` to the LLM
client.
- Added a patch changeset
(`.changeset/remove-agent-temperature-default.md`).
  # test plan
- [ ] `pnpm --filter @browserbasehq/stagehand test agent-temperature` —
new unit tests pass
- [ ] Existing v3 agent unit suite stays green
- [ ] Manual: `agent.execute(...)` against `openai/gpt-5-mini` with
`experimental: true` — confirm no `"temperature" setting is not
supported`
warning in stderr
- [ ] Manual: same call against a non-reasoning model (e.g.
`openai/gpt-4.1-mini`) — confirm agent still completes a multi-step task
end-to-end
- [ ] Manual: hybrid-mode agent run on a reasoning model — verify
streaming path is also clean

---------

Co-authored-by: Filip Michalsky <filip-michalsky@users.noreply.github.com>
2026-05-06 06:09:32 -07:00
Sam F
f437f738d2
fix: preserve OOPIF frame registry parent edge (#2077)
# why

Stagehand could lose a known parent-child frame relationship after
adopting an OOPIF child session. In practice, that meant the registry
could forget that a child frame still belonged under the top-level page,
leaving later iframe resolution with an incomplete frame tree.

# what changed

Added a deterministic FrameRegistry unit test for the OOPIF adoption
ordering. Updated `seedFromFrameTree()` to preserve an already-known
parent when a child frame tree snapshot does not include parent
metadata.

# test plan

Before the fix, the new test failed with `expected null to be
'root-frame'`. After the fix, this passes:

`pnpm --dir packages/core run build:esm && pnpm --dir packages/core run
test:core --
packages/core/dist/esm/tests/unit/frame-registry-oopif-adoption.test.js`

<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Fixes a bug where the frame registry could lose a known parent-child
link after adopting an OOPIF child session. Preserves the parent edge
when seeding from a child frame tree that lacks parent metadata to keep
the iframe tree complete.

- Bug Fixes
- Updated `FrameRegistry.seedFromFrameTree()` to retain an existing
parent when `parentId` is missing and to sync child sets accordingly.
- Added a unit test for OOPIF adoption ordering and seeding to prevent
regressions, and a changeset for `@browserbasehq/stagehand` patch
release.

<sup>Written for commit 1e50e9c3ed4d56c158c1b694bbd04d2aac55821c.
Summary will update on new commits.</sup>

<!-- End of auto-generated description by cubic. -->

---------

Co-authored-by: samfinton <samfinton@samLaptopm5.galaxus.box>
2026-05-05 18:12:02 +02:00
Sam F
1fa96130ab
[STG-1808] Use STAGEHAND_API_URL for Stagehand API client (#2040)
# why
Stagehand should standardize public docs and runtime overrides on
`STAGEHAND_API_URL` without breaking users who still export
`STAGEHAND_BASE_URL`.

# what changed
- Prefer `STAGEHAND_API_URL`, with `STAGEHAND_BASE_URL` as a deprecated
legacy fallback.
- Emit a one-time deprecation warning when the legacy fallback is used.
- Update server-v3 test env plumbing, CI, and docs to use
`STAGEHAND_API_URL`.
- Add patch changesets for core and server-v3.

```ts
const configuredBaseUrl =
  process.env.STAGEHAND_API_URL ?? process.env.STAGEHAND_BASE_URL;
```

# test plan
- `pnpm --filter @browserbasehq/stagehand run build:esm`
- `pnpm --filter @browserbasehq/stagehand run test:core --
packages/core/dist/esm/tests/unit/api-optional-model-api-key.test.js`
- `pnpm --filter @browserbasehq/stagehand run typecheck`
- `pnpm --filter @browserbasehq/stagehand-server-v3 run typecheck`
- `pnpm --filter @browserbasehq/stagehand run lint`
- `pnpm --filter @browserbasehq/stagehand-server-v3 run lint`
- `pnpm exec prettier --check .changeset/rude-tips-check.md
.github/workflows/ci.yml packages/docs/v3/sdk/java.mdx
packages/docs/v3/sdk/python.mdx turbo.json`
- `pnpm changeset status --since origin/main --verbose`
2026-05-04 10:32:27 -07:00
Miguel
2eb9416470
Evals v2 (#2011)
# why
### **Evals CLI v2.0**
<img width="813" height="450" alt="Screenshot 2026-04-28 at 3 34 44 PM"
src="https://github.com/user-attachments/assets/69ef8dd4-b717-4548-9798-b1639febe753"
/>

# what changed

You can find this diagram in `ARCHITECTURE.md`
```mermaid
flowchart TB
    subgraph Entrypoints["Entrypoints and Distribution"]
        CLI["cli.ts<br/>single-shot argv"]
        REPL["tui/repl.ts<br/>interactive shell<br/>Esc abort support"]
        BuildCLI["scripts/build-cli.ts<br/>bundled dist/cli bin"]
        BuildESM["scripts/build-esm.ts<br/>dist/esm + assets + datasets"]
        LegacyCLI["cli-legacy.ts / index.eval.ts<br/>--legacy escape hatch"]
    end

    subgraph TUI["TUI Command Layer"]
        Help["help<br/>usage text"]
        List["list<br/>registry views"]
        ConfigCmd["config<br/>defaults + core tool setup"]
        NewTask["new<br/>task scaffold"]
        Experiments["experiments<br/>Braintrust inspect/compare"]
        RunCmd["run<br/>progress + dry-run plan"]
        Parse["parse.ts<br/>flag validation<br/>target shorthand<br/>env override scope"]
        ConfigFile[("evals.config.json<br/>defaults, core config,<br/>benchmark metadata")]
    end

    subgraph Registry["Task Registry and Target Resolution"]
        RuntimePaths["runtimePaths.ts<br/>source vs dist roots"]
        Discovery["framework/discovery.ts<br/>filesystem scan<br/>category overrides<br/>lazy/eager metadata"]
        Resolver["resolveTarget()<br/>tier, category, task,<br/>partial name"]
        CoreTasks[("core/tasks/*<br/>deterministic tool tasks")]
        BenchTasks[("tasks/bench/*<br/>act, extract, observe,<br/>agent, combination, suites")]
        DefineTask["framework/defineTask.ts<br/>defineCoreTask<br/>defineBenchTask"]
    end

    subgraph Planning["Run Planning"]
        ResolvedOptions["ResolvedRunOptions<br/>env, trials, concurrency,<br/>model, provider, api,<br/>harness, agent mode"]
        BenchPlanner["framework/benchPlanner.ts<br/>model matrix<br/>suite expansion<br/>metadata/tags"]
        TaskConfig["taskConfig.ts<br/>default models<br/>agent model entries"]
        Datasets[("datasets/*<br/>WebVoyager<br/>OnlineMind2Web<br/>WebTailBench")]
        DryRun["dry-run JSON<br/>tasks, skippedTasks,<br/>envOverrides, runOptions"]
    end

    subgraph Runner["Unified Runner"]
        RunEvals["framework/runner.ts<br/>generate testcases<br/>Braintrust Eval wrapper<br/>progress callbacks"]
        BraintrustAdapter["framework/braintrust.ts<br/>lazy import<br/>traced spans"]
        Cleanup["activeRunCleanup.ts<br/>signal cleanup<br/>registered session cleanup"]
        Scoring["scoring.ts<br/>passRate<br/>exactMatch<br/>errorMatch"]
        Summary["summary.ts<br/>local run summary"]
    end

    subgraph CoreTier["Core Tier Execution"]
        CoreContext["framework/context.ts<br/>buildCoreContext"]
        FixtureServer["core/fixtures<br/>local deterministic pages"]
        CoreTargets["core/targets<br/>local Chrome<br/>Browserbase CDP"]
        CoreTools["core/tools registry<br/>understudy_code<br/>playwright_code<br/>cdp_code<br/>MCP + browse_cli"]
        CoreAssertions["assertions + metrics<br/>adapter-backed results"]
    end

    subgraph BenchTier["Bench Tier Execution"]
        BenchRunner["framework/benchRunner.ts<br/>load task module<br/>execute bench task"]
        TaskLoader["framework/taskLoader.ts<br/>defineBenchTask + legacy<br/>module loader"]
        HarnessRegistry["framework/benchHarness.ts<br/>stagehand + claude_code<br/>(codex slot pending)"]
        InitV3["initV3.ts<br/>V3 session + agent"]
        AISDK["AISdkClientWrapped<br/>provider/model client"]
        ClaudeCodeRunner["framework/claudeCodeRunner.ts<br/>Claude Code SDK adapter<br/>prompt + result parse"]
        ClaudeCodeToolAdapter["framework/claudeCodeToolAdapter.ts<br/>tool-surface handoff<br/>browse_cli wrapper"]
        ExternalHarnessPlan["framework/externalHarnessPlan.ts<br/>webvoyager / onlineMind2Web /<br/>webtailbench task plan"]
        BenchSuites["suites/*<br/>dataset-backed suite cases"]
        BenchTaskDefs["bench task modules<br/>defineBenchTask or legacy fn"]
    end

    subgraph Reporting["Reporting and Inspection"]
        Progress["tui/progress.ts<br/>live task table"]
        ResultsView["tui/results.ts<br/>model summary<br/>results table"]
        ReportLib["lib/braintrust-report.ts<br/>experiment fetch<br/>comparison data"]
        RenderReport["scripts/render-braintrust-core-report.ts<br/>core report rendering"]
    end

    subgraph External["External Systems"]
        Braintrust["Braintrust<br/>experiments, spans,<br/>scores, comparisons"]
        Browserbase["Browserbase<br/>remote browser sessions"]
        LocalBrowser["Local Chromium<br/>fixture-backed sessions"]
        Providers["LLM Providers<br/>OpenAI, Anthropic,<br/>Google, others"]
        Stagehand["Stagehand package<br/>V3, AgentProvider,<br/>available models"]
        ClaudeCodeSDK["@anthropic-ai/claude-agent-sdk<br/>external Claude Code agent<br/>headless run"]
    end

    %% Entrypoints
    CLI --> Parse
    CLI --> RunCmd
    CLI --> List
    CLI --> ConfigCmd
    CLI --> Experiments
    CLI --> NewTask
    CLI --> Help
    REPL --> Parse
    REPL --> RunCmd
    BuildCLI --> CLI
    BuildESM --> RuntimePaths
    LegacyCLI --> LegacyRunner["legacy runner path<br/>pre-refactor behavior"]

    %% TUI and config
    ConfigCmd <--> ConfigFile
    Parse --> ConfigFile
    Parse --> ResolvedOptions
    Parse --> DryRun
    RunCmd --> ResolvedOptions
    RunCmd --> RuntimePaths
    RunCmd --> Discovery
    List --> Discovery
    NewTask --> CoreTasks
    NewTask --> BenchTasks
    Experiments --> ReportLib

    %% Registry
    RuntimePaths --> CoreTasks
    RuntimePaths --> BenchTasks
    CoreTasks --> Discovery
    BenchTasks --> Discovery
    DefineTask --> CoreTasks
    DefineTask --> BenchTasks
    Discovery --> Resolver
    Resolver --> RunCmd

    %% Planning
    RunCmd --> BenchPlanner
    RunCmd --> DryRun
    ResolvedOptions --> BenchPlanner
    TaskConfig --> BenchPlanner
    Datasets --> BenchSuites
    BenchSuites --> BenchPlanner
    BenchPlanner --> RunEvals
    Resolver --> RunEvals

    %% Runner
    RunCmd --> RunEvals
    RunEvals --> BraintrustAdapter
    RunEvals --> Cleanup
    RunEvals --> Scoring
    RunEvals --> Summary
    RunEvals --> CoreContext
    RunEvals --> BenchRunner
    RunEvals --> Progress
    Progress --> ResultsView

    %% Core path
    CoreContext --> FixtureServer
    CoreContext --> CoreTargets
    CoreContext --> CoreTools
    CoreContext --> CoreAssertions
    CoreTargets --> LocalBrowser
    CoreTargets --> Browserbase
    CoreTools --> LocalBrowser
    CoreTools --> Browserbase

    %% Bench path
    BenchRunner --> HarnessRegistry
    BenchRunner --> TaskLoader
    TaskLoader --> BenchTaskDefs
    HarnessRegistry --> InitV3
    InitV3 --> Stagehand
    InitV3 --> Browserbase
    InitV3 --> LocalBrowser
    HarnessRegistry --> AISDK
    AISDK --> Providers
    BenchRunner --> BenchTaskDefs
    BenchTaskDefs --> Stagehand
    BenchSuites --> Datasets

    %% Claude Code external harness path
    HarnessRegistry --> ClaudeCodeRunner
    HarnessRegistry --> ClaudeCodeToolAdapter
    HarnessRegistry --> ExternalHarnessPlan
    ClaudeCodeToolAdapter --> CoreTools
    ClaudeCodeToolAdapter --> CoreTargets
    ClaudeCodeRunner --> ClaudeCodeSDK
    ClaudeCodeSDK --> Providers

    %% Reporting and external
    BraintrustAdapter --> Braintrust
    ReportLib --> Braintrust
    RenderReport --> ReportLib
    Summary --> Braintrust
    Stagehand --> Providers

    %% Styling
    style Entrypoints fill:#263238,stroke:#111111,stroke-width:3px,color:#ffffff
    style TUI fill:#0d47a1,stroke:#082d69,stroke-width:3px,color:#ffffff
    style Registry fill:#1b5e20,stroke:#0d3010,stroke-width:3px,color:#ffffff
    style Planning fill:#6a1b9a,stroke:#4a148c,stroke-width:3px,color:#ffffff
    style Runner fill:#004d40,stroke:#00251f,stroke-width:3px,color:#ffffff
    style CoreTier fill:#bf360c,stroke:#7f2207,stroke-width:3px,color:#ffffff
    style BenchTier fill:#1565c0,stroke:#0d47a1,stroke-width:3px,color:#ffffff
    style Reporting fill:#4e342e,stroke:#2d1b17,stroke-width:3px,color:#ffffff
    style External fill:#7f0000,stroke:#4d0000,stroke-width:3px,color:#ffffff

    style CLI fill:#eceff1,stroke:#263238,stroke-width:2px,color:#000000
    style REPL fill:#eceff1,stroke:#263238,stroke-width:2px,color:#000000
    style BuildCLI fill:#cfd8dc,stroke:#263238,stroke-width:2px,color:#000000
    style BuildESM fill:#cfd8dc,stroke:#263238,stroke-width:2px,color:#000000
    style LegacyCLI fill:#ffcdd2,stroke:#b71c1c,stroke-width:2px,color:#000000
    style LegacyRunner fill:#ffcdd2,stroke:#b71c1c,stroke-width:2px,color:#000000

    style Parse fill:#bbdefb,stroke:#0d47a1,stroke-width:2px,color:#000000
    style RunCmd fill:#bbdefb,stroke:#0d47a1,stroke-width:2px,color:#000000
    style ConfigFile fill:#e3f2fd,stroke:#0d47a1,stroke-width:2px,color:#000000
    style Discovery fill:#c8e6c9,stroke:#1b5e20,stroke-width:2px,color:#000000
    style Resolver fill:#a5d6a7,stroke:#1b5e20,stroke-width:2px,color:#000000
    style CoreTasks fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px,color:#000000
    style BenchTasks fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px,color:#000000

    style BenchPlanner fill:#e1bee7,stroke:#6a1b9a,stroke-width:2px,color:#000000
    style Datasets fill:#f3e5f5,stroke:#6a1b9a,stroke-width:2px,color:#000000
    style RunEvals fill:#b2dfdb,stroke:#004d40,stroke-width:2px,color:#000000
    style BraintrustAdapter fill:#e0f2f1,stroke:#004d40,stroke-width:2px,color:#000000
    style Cleanup fill:#e0f2f1,stroke:#004d40,stroke-width:2px,color:#000000

    style CoreContext fill:#ffe0b2,stroke:#bf360c,stroke-width:2px,color:#000000
    style CoreTargets fill:#ffcc80,stroke:#bf360c,stroke-width:2px,color:#000000
    style CoreTools fill:#ffcc80,stroke:#bf360c,stroke-width:2px,color:#000000
    style BenchRunner fill:#bbdefb,stroke:#1565c0,stroke-width:2px,color:#000000
    style HarnessRegistry fill:#90caf9,stroke:#1565c0,stroke-width:2px,color:#000000
    style InitV3 fill:#90caf9,stroke:#1565c0,stroke-width:2px,color:#000000
    style TaskLoader fill:#bbdefb,stroke:#1565c0,stroke-width:2px,color:#000000
    style ClaudeCodeRunner fill:#90caf9,stroke:#1565c0,stroke-width:2px,color:#000000
    style ClaudeCodeToolAdapter fill:#90caf9,stroke:#1565c0,stroke-width:2px,color:#000000
    style ExternalHarnessPlan fill:#bbdefb,stroke:#1565c0,stroke-width:2px,color:#000000

    style Braintrust fill:#ffcdd2,stroke:#7f0000,stroke-width:2px,color:#000000
    style Browserbase fill:#ffcdd2,stroke:#7f0000,stroke-width:2px,color:#000000
    style Providers fill:#ffcdd2,stroke:#7f0000,stroke-width:2px,color:#000000
    style Stagehand fill:#ffcdd2,stroke:#7f0000,stroke-width:2px,color:#000000
    style ClaudeCodeSDK fill:#ffcdd2,stroke:#7f0000,stroke-width:2px,color:#000000

```

# test plan


<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Evals v2 rebuilds the suite into a core + bench system with
auto-discovered tasks, adapter-backed tools, a unified Braintrust
runner, and a stable CLI/TUI. It now stabilizes the `playwright_code`
and `cdp_code` tool surfaces, adds `browse_cli` and MCP adapters, ships
a Braintrust comparison report, fixes `simple_google_search`, guards
file-upload evals with cleanup-on-failure, and removes outdated planning
docs.

- **New Features**
- Core: deterministic tasks under `packages/evals/core/tasks/**`, shared
contracts/assertions/metrics, local fixture server, lazy `getEnv()`,
runner-provided Chrome targets (local, Browserbase) with
artifacts/cleanup and a shared cleanup registry.
- Tools: stable `playwright_code` and `cdp_code`; plus
`understudy_code`, `playwright_mcp`, `chrome_devtools_mcp`,
`browse_cli`.
- Bench: matrix planner and external-suite support (WebVoyager,
OnlineMind2Web, WebTailBench); harness registry with `stagehand` and
`claude_code`, Claude Code SDK boundary, and a `browse_cli` tool
handoff; bench runner propagates `sessionUrl`/`debugUrl`.
- CLI/TUI: stable `dist/cli` (`pnpm evals ...`) with `bin/evals`,
`experiments` command, startup warning suppression, quieter logs via
`EvalLogger` echo toggle; legacy CLI via `pnpm evals:old`.
- Reporting: Braintrust data layer (`lib/braintrust-report.ts`),
`report:core` script, and summaries that include the experiment URL and
scores.
- CI/Deps/Docs: defaults updated (`EVAL_AGENT_MODELS=
openai/gpt-5.4-mini, anthropic/claude-haiku-4-5,
google/gemini-3-flash-preview`; `EVAL_CATEGORIES` includes
`regression`); `.gitignore` ignores Playwright/MCP artifacts; version
bumped to `2.0.0`; add `playwright`, `@anthropic-ai/claude-agent-sdk`,
and `vitest`; updated README, architecture diagram, and `skills/browser`
guide.

- **Migration**
- Tasks are auto-discovered; remove task lists from `evals.config.json`.
- Bench tasks must default-export `defineBenchTask({ name })` under
`packages/evals/tasks/bench/**`; core tasks live under
`packages/evals/core/tasks/**` via `defineCoreTask`.
- Use the new CLI (`pnpm evals ...` or the `evals` bin); the legacy
interface remains via `pnpm evals:old`.
- Set `BROWSERBASE_API_KEY` (and optionally `BROWSERBASE_PROJECT_ID`);
set `CHROME_PATH` if auto-detect fails; `EVAL_ENV` is chosen at runtime.
- Filters/categories changed; remove `webbench` references — use
`b:webvoyager` or `b:onlineMind2Web`.

<sup>Written for commit 5a0056d5aba49219bd80c3b65032164ce0ca6611.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/2011?utm_source=github">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-05-01 15:32:24 -07:00
tkattkat
a87c1fc435
default agent to hybrid mode (#2047)
# why

Dom mode has been deprecated for a while, and is now being replaced with
hybrid as a default

# what changed

- When a hybrid capable model is provided, it is used with hybrid mode
by default
- When a non hybrid capable model is provided, it is used with dom mode 
- if dom or hybrid is explicitly provided, it will use the provided mode

# test plan
tested locally + wrote tests 

<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Set the default v3 agent mode to hybrid, with automatic routing to dom
for models that aren’t hybrid-capable. Explicit mode settings are always
respected; CUA behavior is unchanged.

- **New Features**
- Auto-selects "hybrid" for models matching
`HYBRID_CAPABLE_MODEL_PATTERNS` (`gemini-3`, `claude`, `gpt-5.4`,
`gpt-5.5`); otherwise uses "dom".
- Routes using the provided agent model (string or config), or falls
back to the Stagehand-level model when undefined.
- Honors explicit `mode` (`dom`, `hybrid`, `cua`); if `mode` is unset,
deprecated `cua: true` enables CUA.
- Logs the resolved mode and warns when "hybrid" is used with
non-hybrid-capable models.
  - Adds unit tests for routing and handler fallbacks.

<sup>Written for commit 01e7d69945369cca735dff9ba088538420e344c9.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/2047">Review in
cubic</a></sup>

<!-- End of auto-generated description by cubic. -->
2026-04-30 14:40:25 -07:00
Miguel
9ff70dd26c
[chore] update supported CUA models (#2064) (#2065)
## What Changed

Adds three new models to the list of supported CUA (Computer Use Agent)
models:

- `openai/gpt-5.4-mini`
- `openai/gpt-5.5`
- `anthropic/claude-haiku-4-5`

---

## Files Changed

### `packages/core/lib/v3/types/public/agent.ts`

- Added the three models to the `AVAILABLE_CUA_MODELS` const array  
- This drives:
  - The `AvailableCuaModel` type
  - The runtime CUA model check in `resolveModel()`

### `packages/core/lib/v3/agent/AgentProvider.ts`

- Added model → provider mappings in `modelToAgentProviderMap`:
  - `gpt-5.4-mini` → `openai`
  - `gpt-5.5` → `openai`
  - `claude-haiku-4-5` → `anthropic`
- Ensures `AgentProvider.getAgentProvider()` resolves them correctly

### `packages/core/tests/unit/public-api/llm-and-agents.test.ts`

- Updated the `expectedModels` list in the type-level test to stay in
sync with the source of truth

---

## How It Was Tested

- ✅ Build passes (`pnpm turbo run build`)
- ✅ All **204 public-api unit tests** pass
- ✅ All **608 unit tests** pass
- ⚠️ 4 pre-existing failures in `flowlogger-eventstore.test.js`
(confirmed on base branch)

<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Adds support for three new Computer Use Agent models and maps them to
the right providers. Apps can now use `openai/gpt-5.4-mini`,
`openai/gpt-5.5`, and `anthropic/claude-haiku-4-5` via the public API.

- **New Features**
- Registered the models in `AVAILABLE_CUA_MODELS` and mapped providers:
`gpt-5.4-mini` → `openai`, `gpt-5.5` → `openai`, `claude-haiku-4-5` →
`anthropic`.
  - Updated public API tests to include the new models.
- Added a changeset to release these additions as a patch in
`@browserbasehq/stagehand`.

<sup>Written for commit ec5b691fdf9e469e11b4d025a11a7ac32dbba0c5.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/2065?utm_source=github">Review
in cubic</a></sup>

<!-- End of auto-generated description by cubic. -->

---------

Co-authored-by: Chromie <miguel@browserbase.com>
Co-authored-by: Claude <noreply@anthropic.com>
2026-04-29 13:20:27 -07:00
github-actions[bot]
98cdd20cc5
Release @browserbasehq/browse-cli@0.6.0 (#1948)
Prepare the next browse-cli release by versioning the package on `main`.

What this PR does:
- bumps `packages/cli/package.json` to `0.6.0`
- updates the browse-cli changelog
- consumes the pending browse-cli changesets

After this PR merges, the `Release` workflow on `main` will publish
`@browserbasehq/browse-cli@0.6.0` from that exact commit using `pnpm
pack` + `npm publish --provenance`.

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
2026-04-27 15:16:50 -07:00
Sam F
0382005a1b
Remove docs changeset release metadata (#2057)
# why
The docs-only changeset from PR #2017 created release metadata for a
docs workspace package that should not be published to npm.

# what changed
Reverted the generated docs package changelog and version bump while
keeping the actual MCP documentation updates intact.


<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Removed accidental release metadata for the docs workspace so it isn’t
treated as a publishable package. Keeps the MCP docs from #2017 intact.
Aligns with Linear STG-1869.

- **Bug Fixes**
  - Deleted `packages/docs/CHANGELOG.md`.
  - Reset `@browserbasehq/stagehand-docs` version to 1.0.0.

<sup>Written for commit ff9c8eb5122903c20745ebf5237137ea8797499c.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/2057?utm_source=github">Review
in cubic</a></sup>

<!-- End of auto-generated description by cubic. -->
2026-04-27 13:22:07 -07:00
Derek
e87f167d68
feat(cli): emit Page.lifecycleEvent in browse cdp (#2056)
## Summary

`browse cdp` enables the Page domain via `Page.enable`, but
`Page.enable` does not by itself emit `Page.lifecycleEvent` — that
requires a separate `Page.setLifecycleEventsEnabled` opt-in. As a
result, consumers of `browse cdp` today see only `Page.frameNavigated`
and miss the granular lifecycle milestones (`init`, `commit`,
`DOMContentLoaded`, `load`, `firstPaint`, `firstContentfulPaint`,
`firstMeaningfulPaint`, `networkAlmostIdle`, `networkIdle`).

This PR enables lifecycle events whenever the Page domain is enabled (so
it covers both the default-domain set and explicit `--domain Page`), and
adds a `--pretty` formatter case that prints the milestone name.

## Why

These events are exactly what observability/perf tools want from the
firehose:

- approximate page-ready timing (`DOMContentLoaded` / `load`)
- network-settled signal (`networkIdle`)
- paint timing (`firstPaint` / `firstContentfulPaint` /
`firstMeaningfulPaint`)

Without the opt-in, all of those have to be approximated from
`Page.frameNavigated` + `Network.loadingFinished`, which loses the
per-milestone resolution.

## Verification

Built locally with `pnpm exec tsx src/index.ts cdp 9333` against a
debuggable Chrome and triggered an `example.com` navigation. Before this
patch, no `Page.lifecycleEvent` lines. After:

```
[Page.lifecycleEvent] init
[Page.lifecycleEvent] commit
[Page.lifecycleEvent] DOMContentLoaded
[Page.lifecycleEvent] firstPaint
[Page.lifecycleEvent] firstContentfulPaint
[Page.lifecycleEvent] firstMeaningfulPaint
[Page.lifecycleEvent] load
[Page.lifecycleEvent] networkAlmostIdle
[Page.lifecycleEvent] networkIdle
```

Default mode (NDJSON) emits the same events with full params:

```json
{"sessionId":"…","method":"Page.lifecycleEvent","params":{"frameId":"…","loaderId":"…","name":"DOMContentLoaded","timestamp":468107.080156}}
```

## Test plan

- [ ] `pnpm --filter @browserbasehq/browse-cli typecheck` passes
- [ ] `pnpm --filter @browserbasehq/browse-cli eslint` passes
- [ ] `pnpm --filter @browserbasehq/browse-cli test` — no new failures
(pre-existing failures in `cli.test.ts` / `mode.test.ts` reproduce on
`main` and are unrelated to this change)
- [ ] Manual: `browse cdp <port>` against a debuggable Chrome shows
`Page.lifecycleEvent` lines after a navigation
- [ ] Manual: `browse cdp <port> --pretty` formats
`[Page.lifecycleEvent] <name>`
- [ ] Manual: `browse cdp <port> --domain Network --domain Console` (no
Page) emits no lifecycle events — the opt-in is gated correctly

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

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-27 11:24:40 -07:00
Shrey Pandya
ed4db535c3
[STG-1859] fix(cli): use exact DevToolsActivePort websocket path (#2049)
## Summary

- move local CDP discovery into a dedicated module so the
DevToolsActivePort behavior is directly testable
- reuse the exact `DevToolsActivePort` websocket path for `browse env
local --auto-connect`
- reuse the same exact-path lookup for bare numeric CDP targets in
`resolveWsTarget`
- avoid the extra speculative websocket verification pass on the
file-backed discovery path
- add regression coverage for exact-path resolution, stale file cleanup,
ambiguity, and fallback port probing

## Root Cause

The CLI was reading `DevToolsActivePort` but then discarding the exact
websocket path and probing generic endpoints first. On Chrome's
remote-debugging approval flow that could trigger extra preflight
requests before the real attach.

## Validation

- `pnpm --filter @browserbasehq/stagehand gen-version`
- `pnpm --filter @browserbasehq/stagehand build-dom-scripts`
- `pnpm --filter @browserbasehq/stagehand build`
- `pnpm --filter @browserbasehq/browse-cli build`
- `pnpm --filter @browserbasehq/browse-cli typecheck`
- `pnpm --filter @browserbasehq/browse-cli test`

Linear:
https://linear.app/browserbase/issue/STG-1859/use-exact-devtoolsactiveport-websocket-path-for-browse-cli-auto

<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Fixes local CDP auto-connect by using the exact websocket path from
DevToolsActivePort to avoid extra probes and speed up attach in Chrome’s
approval flow. Addresses Linear STG-1859 and improves
`@browserbasehq/browse-cli` for `browse env local --auto-connect` and
bare port targets.

- **Bug Fixes**
- Reuse the exact DevToolsActivePort websocket path for local
auto-connect.
- Prefer exact-path resolution for bare numeric ports in
`resolveWsTarget`, then fall back to `/json/version`, then
`/devtools/browser`.
- Skip speculative websocket verification when a file provides the exact
path.
- Clean up stale DevToolsActivePort files and return null on ambiguity.

- **Refactors**
- Extracted local CDP discovery to `local-cdp-discovery.ts` with tests
for exact-path resolution, stale cleanup, ambiguity, and fallback
probing.

<sup>Written for commit 440eee4c562a71775cf3e413d5e929a0881837de.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/2049">Review in
cubic</a></sup>

<!-- End of auto-generated description by cubic. -->
2026-04-27 09:08:34 -07:00
github-actions[bot]
04765c11ef
Version Packages (#1979)
This PR was opened by the [Changesets
release](https://github.com/changesets/action) GitHub action. When
you're ready to do a release, you can merge this and the packages will
be published to npm automatically. If you're not ready to do a release
yet, that's fine, whenever you add more changesets to main, this PR will
be updated.


# Releases
## @browserbasehq/stagehand@3.3.0

### Minor Changes

- [#1980](https://github.com/browserbase/stagehand/pull/1980)
[`e471d2e`](e471d2e89d)
Thanks [@shrey150](https://github.com/shrey150)! - Support Browserbase
verified session settings and bump the Browserbase SDK.

### Patch Changes

- [#1954](https://github.com/browserbase/stagehand/pull/1954)
[`732b384`](732b3840f1)
Thanks [@github-actions](https://github.com/apps/github-actions)! -
Update Anthropic CUA to use adaptive thinking

- [#2001](https://github.com/browserbase/stagehand/pull/2001)
[`20b601d`](20b601dc87)
Thanks [@shrey150](https://github.com/shrey150)! - Include
`agent.execute()` usage in `stagehand.metrics` for API-backed sessions.

- [#1983](https://github.com/browserbase/stagehand/pull/1983)
[`8543c11`](8543c11f6b)
Thanks [@github-actions](https://github.com/apps/github-actions)! - Add
variable substitution to the keys tool in both live execution and cache
replay paths. When keys steps with `method="type"` contain
`%variableName%` tokens, they are now resolved against the provided
variables. This brings the keys tool to parity with the type tool's
variable handling.

- [#1973](https://github.com/browserbase/stagehand/pull/1973)
[`14b64ec`](14b64ec7d2)
Thanks [@monadoid](https://github.com/monadoid)! - Enable strict
structured outputs for supported model paths.

- [#2028](https://github.com/browserbase/stagehand/pull/2028)
[`a500de1`](a500de15cc)
Thanks [@tkattkat](https://github.com/tkattkat)! - Remove deprecated
provider option

- [#1975](https://github.com/browserbase/stagehand/pull/1975)
[`8f7192c`](8f7192cee9)
Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - make file
upload elements more explicit in page snapshot

## @browserbasehq/stagehand-docs@1.0.1

### Patch Changes

- [#2017](https://github.com/browserbase/stagehand/pull/2017)
[`6b9b46d`](6b9b46d81e)
Thanks [@monadoid](https://github.com/monadoid)! - Document the optional
MCP `start` `sessionId` parameter for attaching to an existing
Browserbase session.

## @browserbasehq/stagehand-evals@1.1.11

### Patch Changes

- Updated dependencies
\[[`732b384`](732b3840f1),
[`20b601d`](20b601dc87),
[`8543c11`](8543c11f6b),
[`14b64ec`](14b64ec7d2),
[`a500de1`](a500de15cc),
[`e471d2e`](e471d2e89d),
[`8f7192c`](8f7192cee9)]:
    -   @browserbasehq/stagehand@3.3.0

## @browserbasehq/stagehand-server-v3@3.6.3

### Patch Changes

- Updated dependencies
\[[`732b384`](732b3840f1),
[`20b601d`](20b601dc87),
[`8543c11`](8543c11f6b),
[`14b64ec`](14b64ec7d2),
[`a500de1`](a500de15cc),
[`e471d2e`](e471d2e89d),
[`8f7192c`](8f7192cee9)]:
    -   @browserbasehq/stagehand@3.3.0

## @browserbasehq/stagehand-server-v4@3.6.3

### Patch Changes

- Updated dependencies
\[[`732b384`](732b3840f1),
[`20b601d`](20b601dc87),
[`8543c11`](8543c11f6b),
[`14b64ec`](14b64ec7d2),
[`a500de1`](a500de15cc),
[`e471d2e`](e471d2e89d),
[`8f7192c`](8f7192cee9)]:
    -   @browserbasehq/stagehand@3.3.0

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
2026-04-27 08:47:22 -07:00
Sam F
6b9b46d81e
[STG-1837] Document MCP start sessionId support (#2017)
# why

The v3 MCP docs now need to describe the hosted server behavior where
`start` can attach to an existing Browserbase session via an optional
`sessionId`.

# what changed

- Updated the MCP setup and tools docs to document optional
`start.sessionId`.
- Clarified that omitting `sessionId` creates a new Browserbase session.
- Added a patch changeset for `@browserbasehq/stagehand-docs`.

# test plan

- `pnpm exec prettier --check
packages/docs/v3/integrations/mcp/setup.mdx
packages/docs/v3/integrations/mcp/tools.mdx`


<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Added docs for optional `sessionId` on MCP `start` to attach to an
existing Browserbase session; omitting it creates a new session.
Addresses STG-1837 and publishes a patch to
`@browserbasehq/stagehand-docs`.

<sup>Written for commit edc7cbdef0ce712d369699589e1b24b426bffdd6.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/2017">Review in
cubic</a></sup>

<!-- End of auto-generated description by cubic. -->
2026-04-24 19:45:43 +02:00
Sean McGuire
8f7192cee9
[fix]: make file upload elements more explicit in page snapshot (#1975)
# why
- file upload elements sometimes have a 'button' AX role 
- this causes issues when users prompt `.observe()` to find "file upload
elements", since the model sees them as a 'button'
- addresses #972 
# what changed
- this PR preserves the semantics of file upload elements by using the
actual DOM tag name and 'type'
- eg, instead of `[0-12] button: Choose File`, we now use `[0-12] input,
file: Choose File`
# test plan
- added a unit test for the replacement logic
- added an `observe()` eval which checks that hidden file upload
elements are correctly found by the LLM


<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Make file upload inputs explicit in the page snapshot so `.observe()`
can reliably find them. Addresses Linear STG-934 by preventing file
inputs from being misclassified as buttons.

- **Bug Fixes**
- Enrich DOM tag names to include input type (e.g., `input, file`) and
use them in DOM maps.
- Force file inputs to appear as `input, file` in the a11y outline
instead of AX `button`.
- Add unit test and fix/register the `observe_file_uploads` eval in
`evals.config.json`.
  - Publish patch for `@browserbasehq/stagehand`.

<sup>Written for commit 2fad86f408ebb3d990935575a839bcb3e67d0eca.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1975">Review in
cubic</a></sup>

<!-- End of auto-generated description by cubic. -->
2026-04-22 16:41:09 -07:00
Miguel
68d767a02f
Remove default from twoStep schema requirement (#2029)
# why
`z.boolean().default(false)` on line 448 is incompatible with OpenAI's
strict structured-output mode.

OpenAI's error:

> 'required' is required to be supplied and to be an array including
every key in properties. Missing 'twoStep'.


# what changed

# test plan


<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Made `twoStep` a required boolean in the `act` schema (no default). This
removes the silent `false` default and forces callers to be explicit
about two-step actions.

- **Migration**
  - Always pass `twoStep: true | false` when calling `act`.
  - `tsconfig.json` change is formatting-only; no runtime impact.

<sup>Written for commit ca56e780634eacba7aab77ef1222bb4bcbf0a766.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/2029">Review in
cubic</a></sup>

<!-- End of auto-generated description by cubic. -->
2026-04-22 14:56:22 -07:00
tkattkat
a500de15cc
remove strictJson schema (#2028)
# why

Structured output mode is deprecated 

# what changed

removed usage of anthropic structured output mode 

# test plan

Ran tests locally + CI tests 


<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Removed the deprecated `anthropic.structuredOutputMode` option from
AISdk provider options to align with Anthropic’s deprecation and avoid
sending unsupported flags. Updated unit tests and added a changeset;
behavior for other providers is unchanged.

<sup>Written for commit 64daca7b23c0d19e6281fffc7a1d30350477eabd.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/2028">Review in
cubic</a></sup>

<!-- End of auto-generated description by cubic. -->
2026-04-22 14:31:57 -07:00
Miguel
21ba2defa8
Remove error thrown on no action taken (#2027)
# why

After adding regex schema validation for element ids in `act`, the
models were left with no choice to say 'no candidate found/no action to
be taken' since an empty string on element id would fail validation.
This PR corrects the regressed behavior

# what changed
`act()` no longer throws when the model can't find a target. Callers get
the structured `success: false` result, matching the behavior
`observe()` already has ([]) when nothing matches.
- `packages/core/lib/inference.ts` — wrap the act fields (elementId,
description, method, arguments, twoStep) under action: {...}.nullable().
When the model returns action: null, inference returns element:
undefined and the existing handler branch returns { success: false,
actions: [], message: "Failed to perform act: No action found" }.
- Lift `twoStep` out of the nullable action object and back to the top
level of the act schema — small models (gpt-4.1-nano) flatten booleans
out of anyOf variants during structured output, causing spurious
AI_NoObjectGeneratedError on otherwise-valid responses.
- `packages/core/lib/prompt.ts` — update buildActSystemPrompt,
buildActPrompt, and buildStepTwoPrompt to instruct the model to set
action: null when no element matches, with an explicit ban on empty
strings / placeholder values.
- `packages/core/lib/v3/handlers/actHandler.ts` — no logic change; the
existing no-action branch is now reachable.

Act will return the following on these cases:
<img width="586" height="343" alt="Screenshot 2026-04-22 at 1 19 33 PM"
src="https://github.com/user-attachments/assets/34efa7dd-7e80-4c6e-916f-de29d4e28083"
/>

# test plan


<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Stops `act` from throwing when no element matches by making the response
`action` nullable and updating prompts/parsing to treat “no action” as
valid. Fixes the regression where empty element IDs failed validation.
Aligns with Linear STG-1849.

- **Bug Fixes**
- Changed `act` schema to `{ action: { elementId, description, method,
arguments } | null, twoStep: boolean }` with the element ID regex;
`twoStep` is top‑level and defaults to `false`.
- Updated prompts to set `action: null` when no element matches and to
not fabricate elements or use empty/placeholder values.
- Adjusted parsing to handle `action === null` and return `element:
undefined`, letting the existing no‑action path return `success: false`.
- Updated integration tests and test utils to use the new `action` shape
and top‑level `twoStep`.

<sup>Written for commit 1cb51fa47ffefe7b7b931eb011ca6c468aa0bf97.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/2027">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-04-22 13:35:45 -07:00
github-actions[bot]
732b3840f1
[Claimed #1912] Feat: Add Anthropic CUA adaptive thinking (#1954)
Mirrored from external contributor PR #1912 after approval by
@miguelg719.

Original author: @chromiebot
Original PR: https://github.com/browserbase/stagehand/pull/1912
Approved source head SHA: `0ea0332c525017c727743d11a68b8eb74f76b646`

@chromiebot, please continue any follow-up discussion on this mirrored
PR. When the external PR gets new commits, this same internal PR will be
marked stale until the latest external commit is approved and refreshed
here.

## Original description
# why

# what changed

# test plan

<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Add adaptive thinking for Anthropic Claude 4.6 models in the `CUA`
client with effort controls and automatic `temperature=1`. Keeps legacy
`thinkingBudget` for older models and improves model detection and tool
versioning.

- **New Features**
- Detects 4.6 models (e.g., `claude-opus-4-6*`, `claude-sonnet-4-6*`,
incl. provider-prefixed) and sends `thinking: { type: "adaptive" }` with
`output_config.effort` (defaults to `"medium"`).
- Adds `ThinkingEffort` and `thinkingEffort` in `ClientOptions` (`"none"
| "low" | "medium" | "high" | "max"`); `"none"` disables adaptive
thinking.
- Forces `temperature: 1` with adaptive thinking and logs when
overriding a user value; logs when `thinkingBudget` is provided on 4.6
models.
- Uses `computer_20251124` for 4.6 and `claude-opus-4-5-20251101`; older
models continue with `thinking: { type: "enabled", budget_tokens }`.

- **Migration**
  - For 4.6 models, set `thinkingEffort`; `thinkingBudget` is ignored.
- Adaptive thinking forces `temperature: 1`; set `thinkingEffort:
"none"` to disable.

<sup>Written for commit ebe95e77418c755ecc4b3d03235cb3d3cb2e03cc.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1954">Review in
cubic</a></sup>

<!-- End of auto-generated description by cubic. -->

<!-- external-contributor-pr:owned source-pr=1912
source-sha=0ea0332c525017c727743d11a68b8eb74f76b646 claimer=miguelg719
-->

---------

Co-authored-by: Chromie Bot <chromie@browserbase.com>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Co-authored-by: miguel <miguelg71921@gmail.com>
2026-04-22 09:50:25 -07:00
github-actions[bot]
ff16d88754
[Claimed #2010] fix: respect connectTimeoutMs when waiting for first top-level page (#2025)
Mirrored from external contributor PR #2010 after approval by @pirate.

Original author: @octo-patch
Original PR: https://github.com/browserbase/stagehand/pull/2010
Approved source head SHA: `fd9ed12d2499c022b45ba30703c75082dc743a78`

@octo-patch, please continue any follow-up discussion on this mirrored
PR. When the external PR gets new commits, this same internal PR will be
marked stale until the latest external commit is approved and refreshed
here.

## Original description
Fixes #1287

## Problem

On slow machines, Chrome may still be setting up the first tab by the
time
the CDP WebSocket handshake completes. `V3Context.create()` previously
waited a fixed 5 seconds (`DEFAULT_FIRST_TOP_LEVEL_PAGE_TIMEOUT_MS`) for
the first top-level page to register, regardless of any user-supplied
timeout, causing a `TimeoutError: waitForFirstTopLevelPage (no top-level
Page) timed out after 5000ms` on slow hardware.

## Solution

Take the *maximum* of `localBrowserLaunchOptions.connectTimeoutMs` and
the
existing env-var / CI-derived default. This means users who already bump
`connectTimeoutMs` to accommodate a slow environment automatically get
the
same patience when waiting for the initial page—no new API surface
needed.

```ts
// Before
await ctx.ensureFirstTopLevelPage(getFirstTopLevelPageTimeoutMs());

// After
const firstPageTimeoutMs = Math.max(
  opts?.localBrowserLaunchOptions?.connectTimeoutMs ?? 0,
  getFirstTopLevelPageTimeoutMs(),
);
await ctx.ensureFirstTopLevelPage(firstPageTimeoutMs);
```

Existing escape hatches (`STAGEHAND_FIRST_TOP_LEVEL_PAGE_TIMEOUT_MS` env
var, `CI` auto-bump to 30 s) are unchanged—this change only applies a
floor when the user has explicitly set a higher `connectTimeoutMs`.

## Testing

- Existing unit and integration tests continue to pass (no change to
default behaviour).
- Users on slow machines / WSL2 can now set `connectTimeoutMs: 30000` in
`localBrowserLaunchOptions` and the first-page wait will scale with it.

<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Respect `connectTimeoutMs` when waiting for the first top‑level page to
avoid startup timeouts on slow machines. Fixes #1287.

- **Bug Fixes**
- `V3Context.create()` now waits up to
`max(localBrowserLaunchOptions.connectTimeoutMs,
getFirstTopLevelPageTimeoutMs())` for the first page.
- Keeps `STAGEHAND_FIRST_TOP_LEVEL_PAGE_TIMEOUT_MS` and CI defaults
unchanged; no API changes.

<sup>Written for commit 0998c755700d9ea9f4671c8543fa375a8d789feb.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/2025">Review in
cubic</a></sup>

<!-- End of auto-generated description by cubic. -->

<!-- external-contributor-pr:owned source-pr=2010
source-sha=fd9ed12d2499c022b45ba30703c75082dc743a78 claimer=pirate -->

---------

Co-authored-by: octo-patch <octo-patch@users.noreply.github.com>
Co-authored-by: Nick Sweeting <git@sweeting.me>
2026-04-21 22:57:44 -04:00
github-actions[bot]
0ce782bc4b
[Claimed #1892] Support gpt 5.4 cua upd (#2022) 2026-04-21 19:47:06 -07:00
Filip Michalsky
8b0ef02cab
attempt 2 without accuracy degradation (#2018)
# why

# what changed

# test plan

---------

Co-authored-by: Filip Michalsky <filip-michalsky@users.noreply.github.com>
Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>
2026-04-21 17:01:05 -07:00
github-actions[bot]
ad766ad865
[Claimed #2019] fix(core): add FlowLogger parity for Microsoft CUA (#2023)
Mirrored from external contributor PR #2019 after approval by @pirate.

Original author: @BABTUNA
Original PR: https://github.com/browserbase/stagehand/pull/2019
Approved source head SHA: `54b258b01fa9e29ea5e044f50c7dbe159364690b`

@BABTUNA, please continue any follow-up discussion on this mirrored PR.
When the external PR gets new commits, this same internal PR will be
marked stale until the latest external commit is approved and refreshed
here.

## Original description
Title
  fix(core): add FlowLogger parity for Microsoft CUA

  Description

  # why

`MicrosoftCUAClient` was the only CUA provider not emitting FlowLogger
LLM
  request/response events.
  OpenAI, Google, and Anthropic clients already emit these events, so
  Microsoft CUA lacked observability parity.

  # what changed

  - Added FlowLogger imports and request/response logging to
  `MicrosoftCUAClient`:
    - `FlowLogger.logLlmRequest(...)` before the model call
    - `FlowLogger.logLlmResponse(...)` after a successful response
  - Added request ID correlation via `uuidv7` so request/response pair
  correctly in logs.
  - Kept existing execution behavior unchanged (logging-only change).
  - Added unit tests for Microsoft CUA logging behavior:
    - emits request + response on success
    - emits only request when the model call fails

  # test plan

  - `prettier --check` on touched files
  - `eslint` on touched files
  - `tsc -p packages/core/tsconfig.json --noEmit`
  - Added unit test file:
    - `packages/core/tests/unit/microsoft-cua-client.test.ts`

<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Add LLM request/response logging to `MicrosoftCUAClient` to match other
providers and improve observability. This brings Microsoft CUA to parity
with OpenAI, Google, and Anthropic clients.

- **Bug Fixes**
- Emit `FlowLogger.logLlmRequest` before the model call and
`FlowLogger.logLlmResponse` after success.
  - Correlate events with a `requestId` using `uuid` v7.
  - No behavior changes to execution; logging-only.
- Added unit tests for success (request + response) and failure (request
only).

<sup>Written for commit 221e83a7b56b115504c09d3154dcc9690fe0cee8.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/2023">Review in
cubic</a></sup>

<!-- End of auto-generated description by cubic. -->

<!-- external-contributor-pr:owned source-pr=2019
source-sha=54b258b01fa9e29ea5e044f50c7dbe159364690b claimer=pirate -->

---------

Co-authored-by: Benjamin Barrera-Altuna <benbarrera13@gmail.com>
Co-authored-by: Nick Sweeting <git@sweeting.me>
2026-04-21 16:37:58 -07:00
Miguel
715580571e
Update default gemini model for evals (#2024)
# why

# what changed

# test plan

<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Updated the default Gemini eval model to `google/gemini-2.5-flash` and
updated CI `EVAL_MODELS` to use it, so evals run against the latest
flash model both by default and in CI.

<sup>Written for commit 87f421eea7d9e5160e9b3c97ce2b95ecf945eb34.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/2024">Review in
cubic</a></sup>

<!-- End of auto-generated description by cubic. -->
2026-04-21 16:30:41 -07:00
tkattkat
593a71fa1b
When cdp url is set, but browser type is not set throw a 400 (#1744)
# why

Currently, if a cdp url is set, but browser.type is not set to local a
session is created on api

# what changed

We now warn people that they need to set the browser.type to local to
properly use their own custom cdp url

# test plan

tested locally with http requests + from go client + added tests

<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Return 400 on POST /v1/sessions/start when `browser.cdpUrl` is provided
but `browser.type` is not "local", preventing unintended session
creation and guiding correct local CDP usage.

- **Bug Fixes**
- Reject requests with `cdpUrl` when `browser.type` is missing or not
"local"; respond 400 with a clear message to set `browser.type` to
"local".
- Keep local validation: when `browser.type` is "local", require
`cdpUrl` or `launchOptions`.
- Add integration tests for missing type and `type="browserbase"` with
`cdpUrl`.

<sup>Written for commit 58a6c551387d168ceb0f5273e4bb95965771eead.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1744">Review in
cubic</a></sup>

<!-- End of auto-generated description by cubic. -->
2026-04-21 15:25:17 -07:00
Shrey Pandya
20b601dc87
[STG-1825] fix: include agent.execute usage in metrics (#2001) 2026-04-17 12:18:51 -07:00
Sameel
91a4385992
[STG-1823] docs: add server-side caching best practices (#1994) 2026-04-10 17:08:16 -04:00
Sean McGuire
66f6dbf981
[chore]: simplify build for browser-side scripts (#1988)
# why

# what changed

# test plan

<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Unifies the build for browser-injected DOM scripts by replacing four
generators with a single builder. Simplifies the pipeline and removes
redundant file copying, with no runtime changes expected.

- **Refactors**
- Added `scripts/build-dom-scripts.ts` to build all DOM-injected assets:
IIFE strings for `piercer.entry.ts` and
`rerenderMissingShadows.entry.ts`; bootstrap + per-function sources for
`locator` (`__stagehandLocatorScripts`) and `a11y`
(`__stagehandA11yScripts`); sources-only for `screenshot` scripts.
- Removed `genDomScripts.ts`, `genLocatorScripts.ts`,
`genScreenshotScripts.ts`, `genA11yScripts.ts`.
- Updated `packages/core/package.json` to a single `build-dom-scripts`
command and simplified `turbo.json` to one task with
`lib/v3/dom/build/**` outputs.
- Removed JS copy steps from `scripts/build-cjs.ts` and
`scripts/build-esm.ts`; generated TS emits compile with the rest of the
package.
- Updated `tsconfig.json` to include generated files (removed old
`gen*.ts` exclude).

- **Migration**
- Use `pnpm run build-dom-scripts`; the old `build-dom-scripts:*`
scripts are removed.

<sup>Written for commit ac3839794447064bb865a0b6070decb2f2518169.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1988">Review in
cubic</a></sup>

<!-- End of auto-generated description by cubic. -->
2026-04-10 11:11:06 -07:00
github-actions[bot]
8543c11f6b
[Claimed #1978] fix: add variable substitution to keys step during cache replay (#1983)
Mirrored from external contributor PR #1978 after approval by @pirate.

Original author: @a7med3liamin
Original PR: https://github.com/browserbase/stagehand/pull/1978
Approved source head SHA: `2149aa265a04dc37154d5a84411f3ab4d1045897`

@a7med3liamin, please continue any follow-up discussion on this mirrored
PR. When the external PR gets new commits, this same internal PR will be
marked stale until the latest external commit is approved and refreshed
here.

## Original description
- [x] Check the [documentation](https://docs.stagehand.dev/) for
relevant information
- [x] Search existing
[issues](https://github.com/browserbase/stagehand/issues) to avoid
duplicates

Fixes #1776

## Problem

The `keys` tool has no variable substitution in either the live
execution or cache replay paths. When the agent uses `%variableName%`
tokens with the keys tool, the literal token string gets typed instead
of the resolved value.

## Fix

This PR combines two fixes into one:

### 1. Live execution (original fix by @trillville from #1777)
- Accept `variables` parameter in `keysTool` (matching `typeTool`)
- Call `substituteVariables()` before `page.type()` in the `method ===
"type"` branch
- Pass `variables` to `keysTool` in `createAgentTools`
- Update schema description to advertise available variables to the LLM
- Return original token in result to avoid exposing sensitive values to
LLM

### 2. Cache replay (new fix)
- Import `substituteVariables` in `AgentCache.ts`
- Pass `variables` through to `replayAgentKeysStep`
- Call `substituteVariables(text, variables)` before `page.type()` in
the replay path

Without fix #2, cached `keys` steps with `method="type"` replay by
typing literal `%variableName%` tokens even when variables are provided,
since `replayAgentKeysStep` had no access to the variables map.

## Credit

The live execution fix (part 1) is from @trillville's work in
#1777/#1813. We merged it here with the cache replay fix per @pirate's
request to consolidate into a single PR.

<!-- external-contributor-pr:owned source-pr=1978
source-sha=2149aa265a04dc37154d5a84411f3ab4d1045897 claimer=pirate -->

<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Add variable substitution to the `keys` tool for both live execution and
cache replay so `%variableName%` tokens are resolved before typing. This
fixes cases where literal tokens were typed and brings parity with the
`type` tool.

- **Bug Fixes**
- Pass `variables` into `keys` and call `substituteVariables()` before
`page.type()`; update the input schema to list available variables.
- In cache replay, forward `variables` to `replayAgentKeysStep` and
substitute before typing to avoid replaying literal tokens.
- Record and return the original tokenized value (not the resolved
value) to avoid leaking sensitive data.

<sup>Written for commit abb3905cd9563609b01e78bf190a21a5998b9bb4.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1983">Review in
cubic</a></sup>

<!-- End of auto-generated description by cubic. -->

---------

Co-authored-by: Ahmed Ali <a7med3liamin@gmail.com>
Co-authored-by: trillville <trillville@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: Nick Sweeting <git@sweeting.me>
2026-04-09 14:29:48 -07:00
tkattkat
c76beebe79
Revert "[STG-1573] Add providerOptions for extensible model auth (#1822)" (#1987)
## Summary

- Reverts PR #1822 which added `providerOptions` for extensible model
auth (Bedrock/Vertex)
- Removes `providerOptions` bag from model config schema, Bedrock
examples, provider config, and server-side `modelClientOptions`
storage/passthrough

## Note

- One test from PR #1980 (`accepts verified Browserbase session
settings` in `model-config-schema.test.ts`) was removed as part of this
revert since the test file was originally created by #1822. That test
may need to be re-added in a separate file.


Made with [Cursor](https://cursor.com)

<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Reverts the `providerOptions`-based model auth from #1822 (STG-1573) and
restores the previous auth flow: no provider options passthrough; model
auth is via the `x-model-api-key` header.

- **Refactors**
- Removed `providerOptions` and server-side `modelClientOptions`
passthrough from core and server.
- Deleted Bedrock examples and provider config; pruned related schemas
and tests.
- Simplified OpenAPI: removed ProviderOptions/ModelClientOptions
components and helpers extracting model config from request bodies.

- **Migration**
  - Remove `providerOptions` from all model configs and requests.
- Do not send `modelClientOptions` in session start; the server ignores
it.
- Send model API keys via the `x-model-api-key` header; remove any
`skipApiKeyFallback` usage.
  - If you adopted `vertex/*` names from #1822, switch to `google/*`.

<sup>Written for commit 1a3bbcb39c9831d4b0fa0e754fe57a255c392ab8.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1987">Review in
cubic</a></sup>

<!-- End of auto-generated description by cubic. -->
2026-04-09 13:31:38 -07:00
Shrey Pandya
e471d2e89d
[STG-1798] feat: support Browserbase verified sessions (#1980)
## Summary

- bump `@browserbasehq/sdk` to `^2.10.0` in `packages/core`,
`packages/server-v3`, and `packages/server-v4`
- add Browserbase `verified`, `os`, and custom captcha session settings
to the Stagehand Browserbase session-create schema and generated OpenAPI
specs
- keep legacy `advancedStealth` behavior working by treating it as a
compatibility alias for the new verified-mode checks in Stagehand
internals

## Testing

- `pnpm --filter @browserbasehq/stagehand build:esm`
- `pnpm --filter @browserbasehq/stagehand test:core --
packages/core/dist/esm/tests/unit/browserbase-session-accessors.test.js
packages/core/dist/esm/tests/unit/model-config-schema.test.js`
- `pnpm --filter @browserbasehq/stagehand typecheck`
- `pnpm --filter @browserbasehq/stagehand-server-v3 typecheck`
- `pnpm --filter @browserbasehq/stagehand-server-v4 typecheck`
- Browserbase-backed smoke test creating a real Stagehand session with
`browserSettings.verified: true`

Linear:
https://linear.app/browserbase/issue/STG-1798/support-browserbase-verified-session-settings

<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Adds support for Browserbase Verified sessions with new session settings
across Stagehand APIs and a fixed Google CUA viewport when Verified,
addressing Linear STG-1798. Deprecates the `isAdvancedStealth` alias in
favor of `v3.isVerified`, and fixes abort-signal handling to fail fast
on already-aborted signals.

- New Features
- Add `verified`, `os`, `captchaImageSelector`, and
`captchaInputSelector` to Browserbase browser settings and generated
OpenAPI (v3 and v4).
- Introduce `v3.isVerified`; keep `isAdvancedStealth` as a deprecated,
backward-compatible alias.
- Use a 1288x711 viewport for Google CUA when Verified; otherwise use
the configured viewport.

- Dependencies
- Bump `@browserbasehq/sdk` to `^2.10.0` in `packages/core`,
`packages/server-v3`, and `packages/server-v4`.

<sup>Written for commit c2bde3337fbbb9b8143dc6ce2d0a6203282d8055.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1980">Review in
cubic</a></sup>

<!-- End of auto-generated description by cubic. -->
2026-04-08 23:32:19 +00:00
Miguel
ead2d0e34a
Bump drizzle version (#1981)
# why

# what changed

# test plan


<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Bumped `drizzle-orm` to `1.0.0-beta.20` to patch a security
vulnerability in `server-v4`. Addresses Linear STG-1801.

<sup>Written for commit 76ec8a0ea3ec184425b3d34823cae69e35df3864.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1981">Review in
cubic</a></sup>

<!-- End of auto-generated description by cubic. -->
2026-04-08 15:04:48 -07:00
Sam F
14b64ec7d2
Fix local browser startup ECONNREFUSED in CI (#1973)
## Why
Local Chromium startup in CI intermittently fails with `ECONNREFUSED`
before tests ever reach their real assertions. The failures reproduce on
a clean branch off `main`, so this PR is focused only on hardening local
browser/session startup.

## What changed
- retries the full local `V3.init()` launch-and-connect path for
transient startup failures instead of failing immediately on the first
refused connection
- adds failure-only launch diagnostics so if the flake returns we
capture Chrome stdout/stderr plus devtools endpoint state
- limits the retry logic to local browser startup so Browserbase-backed
sessions are unaffected

<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Hardens CI by retrying and verifying local Chromium startup to reduce
ECONNREFUSED flakes. Enables strict structured outputs across supported
AI SDK providers.

- **Bug Fixes**
- Retries local browser init once in CI on ECONNREFUSED/ECONNRESET and
CDP-connect errors; waits and cleans up between attempts.
- Installs stable Chrome via `browser-actions/setup-chrome` and runs a
preflight launch check before server-v3 integration and local E2E tests,
passing `CHROME_PATH` to the verifier.

- **New Features**
- Enables strict structured outputs: sets `strict: true` in
`OpenAIClient` `json_schema` and adds provider options for `openai`,
`azure`, `google`, `vertex`, `anthropic`, `groq`, `cerebras`, and
`mistral`.
- Adds unit tests for AI SDK provider options; publishes a patch to
`@browserbasehq/stagehand`.

<sup>Written for commit 134e98d3895b76f72fe0cd82132835f7bdf7b0da.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1973">Review in
cubic</a></sup>

<!-- End of auto-generated description by cubic. -->
2026-04-08 21:07:46 +02:00
bb
4fe9a7200b
[STG-1573] Add providerOptions for extensible model auth (#1822)
## Summary

- Add `providerOptions` bag to model config schema for provider-specific
auth (Bedrock, Vertex, future providers) without polluting the shared
schema with vendor-specific fields
- Make `modelApiKey` optional so providers with non-API-key auth (e.g.
AWS SigV4) can work without it
- Server stores `modelClientOptions` from session start and reuses them
on subsequent act/observe/extract/execute calls — SDKs don't need to
reimplement this logic
- Send `modelClientOptions` (including `providerOptions`) in the session
start request body; server merges stored + per-request config

## What this enables

- **Bedrock**: pass `region`, `accessKeyId`, `secretAccessKey`,
`sessionToken` via `providerOptions`
- **Vertex**: pass `project`, `location`, `googleAuthOptions` via
`providerOptions`
- **Future providers**: any provider with non-standard auth just adds
fields to `providerOptions` — zero schema or server changes needed

## Architecture

```
SDK                          Server                       AI SDK
─────────────────────────    ─────────────────────────    ──────────────
modelClientOptions: {        Stores in session,           createAmazonBedrock({
  apiKey?,                   merges on each request,        apiKey,
  providerOptions: {    ──►  passes to V3 constructor ──►   region,
    region,                                                 accessKeyId,
    accessKeyId,             Server is vendor-agnostic:     secretAccessKey,
    ...                      just passes providerOptions    ...
  }                          through unchanged            })
}
```

## Linked PRs

- core: https://github.com/browserbase/core/pull/8004

## Testing

<img width="694" height="945" alt="image"
src="https://github.com/user-attachments/assets/39dc4bd2-4008-4776-bcdb-cf3b5eefc726"
/>

<img width="748" height="641" alt="image"
src="https://github.com/user-attachments/assets/ab1c6bcf-322b-4e78-9a96-9dbc5045ba02"
/>

---------

Co-authored-by: Shrey Pandya <shrey@browserbase.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: ci-test <ci-test@example.com>
Co-authored-by: monadoid <sam.finton@gmail.com>
2026-04-08 18:22:10 +00:00
github-actions[bot]
f70e7d51b9
Version Packages (#1853)
This PR was opened by the [Changesets
release](https://github.com/changesets/action) GitHub action. When
you're ready to do a release, you can merge this and the packages will
be published to npm automatically. If you're not ready to do a release
yet, that's fine, whenever you add more changesets to main, this PR will
be updated.


# Releases
## @browserbasehq/stagehand@3.2.1

### Patch Changes

- [#1843](https://github.com/browserbase/stagehand/pull/1843)
[`144e18e`](144e18e9e0)
Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - apply user
defined toolTimeout to all agent tools (other than wait & think tools)

- [#1872](https://github.com/browserbase/stagehand/pull/1872)
[`d3c3736`](d3c3736c57)
Thanks [@tkattkat](https://github.com/tkattkat)! - Add support for LLM
provider middleware

- [#1953](https://github.com/browserbase/stagehand/pull/1953)
[`5c889df`](5c889dfef9)
Thanks [@github-actions](https://github.com/apps/github-actions)! -
(NEW) Model Gateway: make model api key optional on API

- [#1924](https://github.com/browserbase/stagehand/pull/1924)
[`a1ab39e`](a1ab39e7aa)
Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - fix issue
where stagehand could not attach to new tabs that were created manually.

- [#1874](https://github.com/browserbase/stagehand/pull/1874)
[`f3fe7ce`](f3fe7ce597)
Thanks [@miguelg719](https://github.com/miguelg719)! - Add headers (LLM)
to ModelConfig

- [#1964](https://github.com/browserbase/stagehand/pull/1964)
[`5fb9785`](5fb9785357)
Thanks [@github-actions](https://github.com/apps/github-actions)! -
chore: update examples

- [#1901](https://github.com/browserbase/stagehand/pull/1901)
[`f5d1f1f`](f5d1f1ff80)
Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - pass
timeout as timeoutMs in goto()

- [#1858](https://github.com/browserbase/stagehand/pull/1858)
[`8bf5db8`](8bf5db8eb8)
Thanks [@monadoid](https://github.com/monadoid)! - Add explicit SSE
event names for local v3 streaming and update the generated SDK contract
to match.

- [#1899](https://github.com/browserbase/stagehand/pull/1899)
[`6dc2276`](6dc2276144)
Thanks [@tkattkat](https://github.com/tkattkat)! - fix: include
screenshot in openai cua agents first message

## @browserbasehq/stagehand-evals@1.1.10

### Patch Changes

- Updated dependencies
\[[`144e18e`](144e18e9e0),
[`d3c3736`](d3c3736c57),
[`5c889df`](5c889dfef9),
[`a1ab39e`](a1ab39e7aa),
[`f3fe7ce`](f3fe7ce597),
[`5fb9785`](5fb9785357),
[`f5d1f1f`](f5d1f1ff80),
[`8bf5db8`](8bf5db8eb8),
[`6dc2276`](6dc2276144)]:
    -   @browserbasehq/stagehand@3.2.1

## @browserbasehq/stagehand-server-v3@3.6.2

### Patch Changes

- [#1901](https://github.com/browserbase/stagehand/pull/1901)
[`f5d1f1f`](f5d1f1ff80)
Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - pass
timeout as timeoutMs in goto()

- [#1873](https://github.com/browserbase/stagehand/pull/1873)
[`a98801a`](a98801a17f)
Thanks [@miguelg719](https://github.com/miguelg719)! - Fix schema
parsing bug for Pydantic `.model_json_schema()` on missing nested
references

- [#1858](https://github.com/browserbase/stagehand/pull/1858)
[`8bf5db8`](8bf5db8eb8)
Thanks [@monadoid](https://github.com/monadoid)! - Add explicit SSE
event names for local v3 streaming and update the generated SDK contract
to match.

- [#1937](https://github.com/browserbase/stagehand/pull/1937)
[`249f5ed`](249f5ed634)
Thanks [@monadoid](https://github.com/monadoid)! - Improve server-v3
error passthrough for local operation failures

- Updated dependencies
\[[`144e18e`](144e18e9e0),
[`d3c3736`](d3c3736c57),
[`5c889df`](5c889dfef9),
[`a1ab39e`](a1ab39e7aa),
[`f3fe7ce`](f3fe7ce597),
[`5fb9785`](5fb9785357),
[`f5d1f1f`](f5d1f1ff80),
[`8bf5db8`](8bf5db8eb8),
[`6dc2276`](6dc2276144)]:
    -   @browserbasehq/stagehand@3.2.1

## @browserbasehq/stagehand-server-v4@3.6.2

### Patch Changes

- Updated dependencies
\[[`144e18e`](144e18e9e0),
[`d3c3736`](d3c3736c57),
[`5c889df`](5c889dfef9),
[`a1ab39e`](a1ab39e7aa),
[`f3fe7ce`](f3fe7ce597),
[`5fb9785`](5fb9785357),
[`f5d1f1f`](f5d1f1ff80),
[`8bf5db8`](8bf5db8eb8),
[`6dc2276`](6dc2276144)]:
    -   @browserbasehq/stagehand@3.2.1

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
2026-04-07 18:54:01 -07:00
Derek
a4ca4308f6
Add browse cdp command for streaming CDP events (#1905) 2026-04-07 15:20:53 -07:00
Sean McGuire
7e2fc26945
[docs]: add docs for .keyPress() (#1974)
# why
- docs for `page.keyPress()` were missing
# what changed

<img width="730" height="727" alt="Screenshot 2026-04-07 at 1 41 38 PM"
src="https://github.com/user-attachments/assets/1bf50de3-93b6-4fca-b632-cdb80bcfc3da"
/>


<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Added docs for `page.keyPress()` in the v3 Page reference. Includes the
method signature, supported keys and modifier combos, the `delay`
option, and examples for single keys and combinations (Enter, Cmd+A,
ArrowDown, Ctrl+C, with delay).

<sup>Written for commit 0cbf3a9c6d34eef6da0cd3ad53b2e49dd88a39c8.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1974">Review in
cubic</a></sup>

<!-- End of auto-generated description by cubic. -->
2026-04-07 13:50:54 -07:00
Sean McGuire
7fe0fe48fc
[chore]: update readme (#1971)
<!-- This is an auto-generated description by cubic. -->
## Summary by cubic
Switched badge SVGs to green `#00C851` for Discord and License (light
and dark) and set their links to `display: inline-block` in
`packages/core/README.md` to keep badges aligned. Branding/readme-only;
no app code changes.

<sup>Written for commit 698eb0fcfd947d3efb1407935faa673dd474827a.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1971">Review in
cubic</a></sup>

<!-- End of auto-generated description by cubic. -->
2026-04-06 18:30:57 -07:00