1271 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>
@browserbasehq/stagehand@3.4.0
2026-05-11 14:17:14 -07:00
Sean McGuire
6c78ecd23c
[chore]: rm evals changeset (#2108)
# why
- changsets are not properly set up in evals workspace, & this package
is not yet published on npm
# what changed
- removed patch changeset for evals pkg


<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Removed the patch changeset for `@browserbasehq/stagehand-evals` to
prevent an accidental release. The evals workspace isn’t configured for
Changesets and the package isn’t published to npm.

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

<!-- End of auto-generated description by cubic. -->
stagehand-server-v3/v3.6.9
2026-05-11 14:13:01 -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. -->
stagehand-server-v3/v3.6.8
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. -->
stagehand-server-v3/v3.6.7
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>
stagehand-server-v3/v3.6.6
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. -->
stagehand-server-v3/v3.6.5
2026-05-06 19:11:05 +02:00
Miguel
886884bd70
Manual eval dispatch workflow (#2085)
# why

# what changed

# test plan


<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Adds a manual GitHub Actions workflow to run evaluation suites on demand
with selectable model, agent mode, trials, and concurrency. Builds once,
runs chosen evals in a matrix, and posts Braintrust results and
summaries.

- **New Features**
- Run agent, act/extract/observe, or external agent benchmarks
(webvoyager, onlineMind2Web, webtailbench).
- Inputs: `model`, `agent_mode` (auto/dom/hybrid/cua), `trials` (default
1), `concurrency` (default 50).
- One build job; artifacts reused across eval jobs. Dynamic matrix built
via `jq`.
- Executes evals with `pnpm` + `turbo` against
`@browserbasehq/stagehand-evals`, with
OpenAI/Anthropic/Google/Braintrust/Browserbase env wired and region
selection.
- Publishes job summary with Braintrust link and primary score, and
uploads CTRF report + V8 coverage (fails if no summary).

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

<!-- End of auto-generated description by cubic. -->
2026-05-06 10:07:50 -07: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`
stagehand-server-v3/v3.6.4
2026-05-04 10:32:27 -07:00
Miguel
ff1f1c3651
Remove old trace (#2075)
# why

# what changed

# test plan


<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Removed an accidental development transcript file from the repo to
reduce noise and avoid shipping non-code artifacts. No runtime or build
impact.

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

<!-- End of auto-generated description by cubic. -->
2026-05-02 21:43:38 -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>
@browserbasehq/browse-cli@0.6.0
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
Nick Sweeting
8c791bc086
Run claimed PRs CI as a maintainer so it they access secrets (#1984)
## Summary

- dispatch `ci.yml` after an external contributor PR is claimed so the
mirrored internal PR can run secret-backed CI without per-maintainer
tokens
- add a PR-context loader to `ci.yml` so dispatched runs can recover
labels, PR number, and internal-head gating from the GitHub API
- keep the existing mirror/refresh flow intact while returning the owned
PR number from the claim finalization step

## Why

GitHub attributes PR authorship to the credential that creates the PR.
Because we cannot store maintainer PATs in repo secrets, the claim
workflow cannot safely recreate mirrored PRs as the approving
maintainer. The viable low-churn path is to keep the mirrored PR
bot-created, then trigger trusted CI on the mirrored branch via
`workflow_dispatch`, which can be started from `GITHUB_TOKEN` and still
runs with repository secrets.

## Impact

- claimed PRs get a trusted `ci.yml` run on their head SHA after claim
succeeds
- the CI workflow now works for both `pull_request` and dispatched
claimed-PR runs
- e2e jobs still stay gated to internal-head PRs, but that decision is
now derived from loaded PR context rather than only the event payload

## Validation

- `pnpm exec prettier --check .github/workflows/ci.yml
.github/workflows/external-contributor-pr.yml`
- `git diff --check -- .github/workflows/ci.yml
.github/workflows/external-contributor-pr.yml`

<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Run trusted CI for claimed external PRs by dispatching `ci.yml` on the
mirrored branch. This keeps the mirror flow intact and enables
secret-backed CI without maintainer tokens.

- **New Features**
- `external-contributor-pr.yml` dispatches `ci.yml` after a successful
claim using the mirrored branch ref, passing the owned PR number;
exposes `claimed` and `owned-pr-number` outputs and sets `actions:
write`.
- `ci.yml` adds `workflow_dispatch` with a `pull_request_number` input
and a `load-pr-context` job to read labels, PR number, and
internal-head; this context drives eval selection, e2e gating, and
summary comments; adds `pull-requests: read`.

<sup>Written for commit 0b383701fb00ee06dd6d6a7c3f110baa35ae82a4.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1984">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-09 11:27:36 -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