# 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. -->
# 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. -->
# 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`
# 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. -->
## 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. -->
# 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. -->
## 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>
# 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. -->
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%
```
# 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>
# 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>
# 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. -->
# 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. -->
# 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>
# 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>
# 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`
# 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. -->
## 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>
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>
# 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. -->
## 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>
## 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. -->
# 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. -->
# 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. -->
# 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. -->
# 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. -->
# 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>
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>
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>
# 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>
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>
# 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. -->
# 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. -->
# 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. -->
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>
## 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. -->
## 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. -->
# 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. -->
## 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. -->
## 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>
# why
- docs for `page.keyPress()` were missing
# what changed
<img width="730" height="727" alt="Screenshot 2026-04-07 at 1 41 38 PM"
src="https://github.com/user-attachments/assets/1bf50de3-93b6-4fca-b632-cdb80bcfc3da"
/>
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Added docs for `page.keyPress()` in the v3 Page reference. Includes the
method signature, supported keys and modifier combos, the `delay`
option, and examples for single keys and combinations (Enter, Cmd+A,
ArrowDown, Ctrl+C, with delay).
<sup>Written for commit 0cbf3a9c6d34eef6da0cd3ad53b2e49dd88a39c8.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1974">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
<!-- This is an auto-generated description by cubic. -->
## Summary by cubic
Switched badge SVGs to green `#00C851` for Discord and License (light
and dark) and set their links to `display: inline-block` in
`packages/core/README.md` to keep badges aligned. Branding/readme-only;
no app code changes.
<sup>Written for commit 698eb0fcfd947d3efb1407935faa673dd474827a.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1971">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->