493 Commits

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


# Releases
## @browserbasehq/stagehand@3.4.0

### Minor Changes

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

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

### Patch Changes

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

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

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

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

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

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

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

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

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

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

## @browserbasehq/stagehand-evals@2.0.1

### Patch Changes

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

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

### Patch Changes

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

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

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

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

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

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

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

### Patch Changes

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

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

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
2026-05-11 14:17:14 -07:00
Sean McGuire
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. -->
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
a783b99fb9
[chore]: bump various transitive deps across monorepo (#2098)
# why
- to bump a small set of direct and transitive dependencies to pick up
patched upstream releases
# what changed
- bumped `playwright` to 1.55.1 across workspace all workspace packages
- bumped `@playwright/test` in `packages/core` to 1.55.1
- bumped `playwright-core` in `packages/core` to 1.55.1
- bumped `puppeteer-core` in `packages/core` to 24.43.0
- bumped `jsdom` in `packages/core` to 29.1.1.
- bumped `@browserbasehq/sdk` where needed to pick up a patched
transitive dependency tree
# test plan
- existing test suite + pnpm audit

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

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

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

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

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

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

Leaving the full suite to CI.

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

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

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

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

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

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

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

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


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

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

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

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

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

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

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

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

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

---------

Co-authored-by: samfinton <samfinton@samLaptopm5.galaxus.box>
2026-05-07 20:22:09 +02:00
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
Miguel
21c78b3a50
remove experimental requirement on agent variables (#2079) (#2080)
# why
`experimental: true` is no longer required for agent variable support

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

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

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

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

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

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

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

---------

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

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

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

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

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

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

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

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

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

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

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

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

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

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

---------

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

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

# what changed

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

# test plan

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

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

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

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

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

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

---------

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

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

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

# test plan
- `pnpm --filter @browserbasehq/stagehand run build:esm`
- `pnpm --filter @browserbasehq/stagehand run test:core --
packages/core/dist/esm/tests/unit/api-optional-model-api-key.test.js`
- `pnpm --filter @browserbasehq/stagehand run typecheck`
- `pnpm --filter @browserbasehq/stagehand-server-v3 run typecheck`
- `pnpm --filter @browserbasehq/stagehand run lint`
- `pnpm --filter @browserbasehq/stagehand-server-v3 run lint`
- `pnpm exec prettier --check .changeset/rude-tips-check.md
.github/workflows/ci.yml packages/docs/v3/sdk/java.mdx
packages/docs/v3/sdk/python.mdx turbo.json`
- `pnpm changeset status --since origin/main --verbose`
2026-05-04 10:32:27 -07:00
tkattkat
a87c1fc435
default agent to hybrid mode (#2047)
# why

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

# what changed

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

# test plan
tested locally + wrote tests 

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

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

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

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

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

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

---

## Files Changed

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

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

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

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

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

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

---

## How It Was Tested

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

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

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

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

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

---------

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

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

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

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
2026-04-27 15:16:50 -07:00
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
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
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
Shrey Pandya
20b601dc87
[STG-1825] fix: include agent.execute usage in metrics (#2001) 2026-04-17 12:18:51 -07:00
github-actions[bot]
8543c11f6b
[Claimed #1978] fix: add variable substitution to keys step during cache replay (#1983)
Mirrored from external contributor PR #1978 after approval by @pirate.

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

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

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

Fixes #1776

## Problem

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

## Fix

This PR combines two fixes into one:

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

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

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

## Credit

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

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

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

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

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

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

---------

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

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

## Note

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


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

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

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

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

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

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

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

## Testing

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

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

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

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

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

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

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

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

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

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

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

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

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

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

## What this enables

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

## Architecture

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

## Linked PRs

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

## Testing

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

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

---------

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


# Releases
## @browserbasehq/stagehand@3.2.1

### Patch Changes

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

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

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

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

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

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

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

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

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

## @browserbasehq/stagehand-evals@1.1.10

### Patch Changes

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

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

### Patch Changes

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

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

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

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

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

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

### Patch Changes

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

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
2026-04-07 18:54:01 -07:00
Derek
a4ca4308f6
Add browse cdp command for streaming CDP events (#1905) 2026-04-07 15:20:53 -07:00
github-actions[bot]
5fb9785357
[Claimed #1960] chore: update examples (#1964)
Mirrored from external contributor PR #1960 after approval by
@miguelg719.

Original author: @chromiebot
Original PR: https://github.com/browserbase/stagehand/pull/1960
Approved source head SHA: `b013423199f609fc744a7f23127511929a1ec0fc`

@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
Examples were quite stale

# what changed
Overhaul of examples/ and minor cleanups

# test plan


<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Standardizes non-CUA examples to use model strings with built-in API key
resolution. Updates the MCP demo to the current agent API, replaces
deprecated OpenAI model names, and removes dead eval/client code to
reduce boilerplate.

- **Refactors**
- Switched examples to model strings (e.g., `openai/gpt-5`) without
inline API keys when `env: "BROWSERBASE"`; kept a LOCAL override in
`parameterize-api-key.ts` using `gpt-4.1-mini`.
- Updated `mcp.ts` to current agent API: `connectToMCPServer`, `mode:
"hybrid"`, model `anthropic/claude-sonnet-4-6`, and a `systemPrompt`.
- Replaced deprecated OpenAI models in custom-client examples: `gpt-4o`
→ `gpt-4.1`, `gpt-4o-mini` → `gpt-4.1-mini`; replaced `V3` with
`Stagehand` in `v3-example.ts` and `v3-agent.ts`, and fixed imports to
`../lib/v3/*`.
- Removed dead code (examples `external_clients/*`, evals `llm_clients`
and category, `examples/CHANGELOG.md`, `examples/tsconfig.json`) and
added a patch changeset.

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

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



<!-- external-contributor-pr:owned source-pr=1960
source-sha=b013423199f609fc744a7f23127511929a1ec0fc claimer=miguelg719
-->

---------

Co-authored-by: Chromie Bot <chromie@browserbase.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: miguel <miguelg71921@gmail.com>
Co-authored-by: Chromie <miguel@browserbase.com>
2026-04-06 15:09:34 -07:00
github-actions[bot]
5c889dfef9
[Claimed #1923] feat: Make model api key optional on API (#1953)
Mirrored from external contributor PR #1923 after approval by
@miguelg719.

Original author: @chromiebot
Original PR: https://github.com/browserbase/stagehand/pull/1923
Approved source head SHA: `49c1be2be843d441e3234f6ab591e2ce5bd84087`

@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
Introducing [Model
Gateway](https://www.browserbase.com/blog/model-gateway) on Browserbase

# what changed
`modelApiKey` is now optional on API

# test plan


<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Make the model API key optional in `StagehandAPIClient.init()` so
sessions can start without a key, supporting Model Gateway. When
provided, behavior is unchanged and the `x-model-api-key` header is
sent.

- **Bug Fixes**
  - Remove throw in `init()`; make `modelApiKey` optional across types.
- Conditionally send `x-model-api-key`; omit model `apiKey` in
`prepareModelConfig` when undefined.
- Add unit tests for header behavior and a server integration test for
starting without the header; add a patch changeset for
`@browserbasehq/stagehand`.

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

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



<!-- external-contributor-pr:owned source-pr=1923
source-sha=49c1be2be843d441e3234f6ab591e2ce5bd84087 claimer=miguelg719
-->

---------

Co-authored-by: Chromie Bot <chromie@browserbase.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: miguel <miguelg71921@gmail.com>
2026-04-06 14:28:27 -07:00
Derek
34598b936f
Add browse upload command for file uploads (#1906)
## Summary
- Adds `browse upload <selector> <files...>` command to upload files to
`<input type="file">` elements
- Uses Understudy's `setInputFiles` under the hood, which handles both
local (CDP `DOM.setFileInputFiles`) and remote/Browserbase (base64
payload injection) paths automatically
- Supports ref-based selectors from `browse snapshot` (e.g., `browse
upload @0-5 ./doc.pdf`)
- Supports multiple files: `browse upload @0-5 ./a.png ./b.png`

## Usage
```bash
browse upload <selector> <file>            # single file
browse upload @0-5 ./document.pdf          # using ref from snapshot
browse upload @0-5 ./a.png ./b.png         # multiple files
```

## Test plan
- [X] Test single file upload on a local page with `<input type="file">`
- [X] Test multiple file upload
- [X] Test with ref-based selector from snapshot
- [X] Test on remote Browserbase session (base64 injection path)

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

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-02 15:23:02 -07:00
Shrey Pandya
666baf1df9
[STG-1741] feat(cli): add global flags for Browserbase session parameters (#1935)
## Summary
- Add global CLI flags for commonly used Browserbase session parameters
to the `browse` CLI
- Users no longer need external tools or workarounds to configure
`advancedStealth`, `proxies`, `solveCaptchas`, etc.
- Flags are remote-mode only and trigger daemon restart when changed

### New flags
| Flag | Description |
|------|-------------|
| `--proxies` | Enable Browserbase proxy |
| `--advanced-stealth` | Enable advanced stealth mode |
| `--solve-captchas` / `--no-solve-captchas` | Toggle CAPTCHA solving |
| `--region <region>` | Session region |
| `--keep-alive` | Keep session alive after disconnection |
| `--session-timeout <seconds>` | Session timeout |
| `--block-ads` | Enable ad blocking |

### Examples
```bash
browse --proxies --advanced-stealth open https://example.com
browse --region us-east-1 --solve-captchas open https://example.com
```

Session flags are validated to only work in remote mode and will error
with a helpful message if used in local mode.

Linear:
https://linear.app/browserbase/issue/STG-1741/featcli-add-global-flags-for-browserbase-session-parameters

## Test plan
- [ ] `browse --help` shows new flags with "(remote only)" descriptions
- [ ] `browse --proxies open https://example.com` (in remote mode)
creates session with proxy enabled
- [ ] `browse --advanced-stealth --solve-captchas open
https://example.com` configures both settings
- [ ] `browse --proxies open https://example.com` (in local mode) errors
with helpful message
- [ ] Changing flags restarts the daemon automatically
- [ ] `browse status` shows active session params
- [ ] Build succeeds

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

<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Add global flags to `browse` to configure Browserbase session settings
in remote mode (proxies, stealth, CAPTCHA solving, region, keep-alive,
timeouts) without JSON. Settings persist per session, trigger a daemon
restart when changed, and appear as `sessionParams` in `browse status`
JSON; also fixes lint errors. Addresses Linear STG-1741.

- **New Features**
- Flags: `--proxies`, `--advanced-stealth`,
`--solve-captchas`/`--no-solve-captchas`, `--block-ads`, `--region
<region>`, `--keep-alive`, `--session-timeout <seconds>`; remote-only
with a clear error in local mode

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

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

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-02 05:09:43 +00:00
github-actions[bot]
2888856d08
Release @browserbasehq/browse-cli@0.5.0 (#1946)
Prepare the next browse-cli release by versioning the package on `main`.

What this PR does:
- bumps `packages/cli/package.json` to `0.5.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.5.0` from that exact commit using `pnpm
pack` + `npm publish --provenance`.


<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Publish `@browserbasehq/browse-cli@0.5.0`, defaulting `browse env local`
to an isolated browser and adding `--auto-connect` to opt into attaching
to an existing debuggable Chrome; explicit CDP attach via `browse env
local <port|url>` remains unchanged.

- **Migration**
- If you previously relied on auto-attach, run: `browse env local
--auto-connect`.

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

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

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
2026-04-01 21:50:21 +00:00
Shrey Pandya
2df4b01cbb
[STG-1752] fix(cli): default browse env local to isolated (#1945)
## Summary

- make `browse env local` default back to an isolated local browser
- add `browse env local --auto-connect` as the explicit opt-in path for
auto-discovering a debuggable local Chrome
- keep explicit CDP attach via `browse env local <port|url>` and add
tests to lock in the strategy behavior

## Why

`browse env local` was auto-attaching to an existing local Chrome by
default. That can trigger Chrome's remote debugging approval dialog
unexpectedly and makes isolated local usage less predictable.

## Impact

Users now get a clean local browser by default, while still having two
explicit ways to reuse an existing browser when they want to:

- `browse env local --auto-connect`
- `browse env local <port|url>`

## Test Plan

- `pnpm --filter @browserbasehq/browse-cli build`
- `pnpm --filter @browserbasehq/browse-cli test`
- `pnpm exec prettier --check packages/cli && cd packages/cli && pnpm
run eslint && pnpm run typecheck`
- e2e smoke test against a disposable Chrome CDP endpoint on
`127.0.0.1:9229` using a temporary `HOME` / user-data-dir so the checks
do not touch a real browsing profile
- verified `browse env local` returns `localStrategy: "isolated"`
- verified `browse status` in isolated mode reports `localSource:
"isolated"`
- verified `browse env local` and `browse status` both print the hint to
use `browse env local --auto-connect` to reuse local credentials/cookies
- verified `browse env local --auto-connect` returns `localStrategy:
"auto"`
- verified `browse env local --auto-connect` prints the hint that plain
`browse env local` switches back to an isolated Chromium browser
- verified `open https://example.com` succeeds after `--auto-connect`
- verified `browse status` after `--auto-connect` reports `localSource:
"attached-existing"` with the resolved CDP URL and the isolated-browser
hint
- verified `browse env local 9229` returns `localStrategy: "cdp"`
- verified `browse status` after `browse env local 9229` reports
`localSource: "attached-explicit"`

Linear: STG-1752

<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Defaulted `browse env local` to a clean, isolated browser. Added
`--auto-connect` to opt into reusing a debuggable Chrome, kept explicit
CDP attach via `browse env local <port|url>`, and added mode hints to
guide users. Addresses Linear STG-1752 to make local usage predictable
and avoid surprise debugging prompts.

- **New Features**
- Isolated local browser is now the default; auto-discovery only with
`--auto-connect`.
- Mode hints in `browse env`/`browse status` suggest when to use
`--auto-connect` or switch back to isolated.
  - `browse env local <port|url>` remains for explicit CDP targets.
- Centralized strategy resolution in `src/local-strategy.ts` with unit
tests.
- Clearer `browse env` usage and validation; rejects mixing
`--auto-connect`, `--isolated`, or a target. `--isolated` is deprecated
(accepted; hidden from help).

- **Migration**
  - To reuse an existing Chrome: `browse env local --auto-connect`.
  - To attach to a specific target: `browse env local <port|url>`.
  - No changes if you want a clean isolated browser by default.

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

<!-- End of auto-generated description by cubic. -->
2026-04-01 21:47:27 +00:00
github-actions[bot]
977f3524d1
Release @browserbasehq/browse-cli@0.4.2 (#1942)
Prepare the next browse-cli release by versioning the package on `main`.

What this PR does:
- bumps `packages/cli/package.json` to `0.4.2`
- 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.4.2` from that exact commit using `pnpm
pack` + `npm publish --provenance`.


<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Publish `@browserbasehq/browse-cli` 0.4.2 by bumping the version and
updating the changelog. This release adds a command to convert page HTML
to Markdown.

- **New Features**
- Add `browse get markdown [selector]` to convert page HTML to Markdown.
Defaults to body; supports an optional selector; preserves links,
tables, and code blocks via `node-html-markdown`.

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

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

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
2026-03-31 16:29:37 -07:00
Sam F
249f5ed634
fix: pass through server-v3 operation errors (#1937)
## Summary
- return underlying operation error messages from server-v3 streaming
handlers
- return underlying non-AppError messages from the top-level server-v3
error wrapper
- preserve existing status code behavior while making local
act/extract/observe 500s diagnosable

## Testing
- pnpm --filter @browserbasehq/stagehand-server-v3 typecheck

<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Pass through underlying operation errors in
`@browserbasehq/stagehand-server-v3` so clients see real failure
messages during streaming and top-level responses, and force flow logs
on for easier debugging. Status codes stay the same, making local
act/extract/observe 500s diagnosable.

- **Bug Fixes**
- Streaming + error wrapper: return the thrown error’s message for
non-`AppError` cases; fall back to a default when not an `Error`,
preserving status codes.
- Observe route: remove unused `Variables` import/cast to satisfy lint;
no behavior change.

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

<!-- End of auto-generated description by cubic. -->
2026-03-31 22:44:33 +02:00
Derek
3917df4851
Add browse get markdown command (#1907)
## Summary
- Adds `browse get markdown [selector]` to convert page HTML to clean
markdown
- Defaults to body content when no selector given, accepts optional
CSS/XPath/ref selector
- Uses `node-html-markdown` for quality conversion (links, tables, code
blocks preserved)
- Useful for agents that need readable page content without HTML noise

## Usage
```bash
browse get markdown                # full page body as markdown
browse get markdown .article       # specific element
browse get markdown @0-5           # ref from snapshot
```

## Test results
| Test | Local | Remote (Browserbase) |
|------|-------|---------------------|
| `get markdown` (body default) | HN full page markdown | HN full page
markdown |
| `get markdown .titleline` (selector) | Clean link with title | Clean
link with title |

## Test plan
- [x] Test locally with no selector (full body)
- [x] Test locally with CSS selector
- [x] Test on remote Browserbase session (no selector)
- [x] Test on remote Browserbase session (with selector)

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

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-31 13:06:28 -07:00
tkattkat
d3c3736c57
Add support for LLM middleware (#1872)
# why

- In some scenarios, users need more granular control / access to the
LLM at the provider leve

# what changed

- Added support for passing custom "middleware" in the model options 

# test plan

- wrote tests 
- tested locally with own middleware 

<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Adds first-class LLM middleware to intercept and wrap model calls for
logging, usage tracking, or request transforms without changing call
sites. Per-call middleware is used only for that call and is not cached.

- **New Features**
- Accepts `middleware: LanguageModelV2Middleware` in `V3` model config;
`LLMProvider` and `getAISDKLanguageModel` wrap models via
`wrapLanguageModel` from `ai`.
- Supports per-call overrides via `model` options; override middleware
is passed through `LLMProvider.getClient`, applies only to that call,
and is never cached.
- Works across providers and preserves `modelId`, `doGenerate`, and
`doStream`. Tests cover usage capture, streaming, errors, chaining, and
edge cases.

- **Migration**
- To use: pass `middleware` in `model` config or a per-call override,
e.g. `{ modelName: 'openai/gpt-4o', apiKey: '...', middleware }`.
- Middleware is only applied in direct/local execution and is not
serialized over HTTP.

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

<!-- End of auto-generated description by cubic. -->
2026-03-31 11:10:16 -07:00
github-actions[bot]
ad055f9153
Release @browserbasehq/browse-cli@0.4.1 (#1932)
Prepare the next browse-cli release by versioning the package on `main`.

What this PR does:
- bumps `packages/cli/package.json` to `0.4.1`
- 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.4.1` from that exact commit using `pnpm
pack` + `npm publish --provenance`.


<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Release `@browserbasehq/browse-cli@0.4.1`, a patch that fixes an invalid
session metadata key. This bumps the package version and updates the
changelog for publishing from `main`.

- **Bug Fixes**
- Use underscore in `browse_cli` session metadata keys instead of a
hyphen.

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

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

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
2026-03-31 08:50:43 -07:00
Derek
56d7b9f5cc
[STG-1733] fix: use valid metadata key for browse-cli sessions (#1911)
## Summary
- The `browse-cli` metadata key (with hyphen) is rejected by the
Browserbase API as an invalid metadata key, causing `env remote` to fail
with a `400 Key is not a valid metadata key: browse-cli` error.
- Changed the key to `browse_cli` (underscore) which is a valid metadata
key format.

Linear:
https://linear.app/browserbase/issue/STG-1733/fix-use-valid-metadata-key-for-browse-cli-sessions

## Test plan
- [x] Verified old key (`browse-cli`) returns 400 from Browserbase API
- [x] Verified new key (`browse_cli`) returns 201 and session creates
successfully

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

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: Shrey Pandya <shrey@browserbase.com>
2026-03-31 08:29:22 -07:00
Sean McGuire
a1ab39e7aa
[fix]: attach to manually-created new tabs (#1924)
# why
- when a user created a new tab by clicking the "+" icon in a headful
chromium browser, stagehand would not attach to it, because it filtered
out the `"chrome://newtab"` url pattern
# what changed
- extended the conditional in `isNonWebTarget()` to allow for
`"chrome://newtab"` URLs to pass through, so that stagehand can attach
to them
<img width="491" height="95" alt="Screenshot 2026-03-30 at 4 00 48 PM"
src="https://github.com/user-attachments/assets/64638fc4-7334-4438-8df5-5a91344b6afb"
/>
# test plan
- added a test which creates a newtab target, & confirms that a new page
object gets created

<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Fixes `@browserbasehq/stagehand` not attaching to tabs opened via the
"+" button in Chromium by tracking `chrome://newtab/` page targets so a
page is created and becomes usable after navigation.

- **Bug Fixes**
- Updated `isNonWebTarget()` to always track top-level `page` targets,
even with non-web schemes like `chrome://newtab/`.
- Added Playwright tests to verify `chrome://newtab/` tabs appear in
`pages()` and work after navigating to a web URL.

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

<!-- End of auto-generated description by cubic. -->
2026-03-30 17:20:02 -07:00
github-actions[bot]
be6798aefd
Release @browserbasehq/browse-cli@0.4.0 (#1925)
Prepare the next browse-cli release by versioning the package on `main`.

What this PR does:
- bumps `packages/cli/package.json` to `0.4.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.4.0` from that exact commit using `pnpm
pack` + `npm publish --provenance`.


<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Release `@browserbasehq/browse-cli` 0.4.0 with new session attach and
smarter local Chrome discovery, plus stability fixes. Bumps the package
version and updates the changelog; the Release workflow will publish
from this commit.

- **New Features**
  - Add `--connect` to attach to an existing Browserbase session by ID.
- `browse env local` auto-discovers debuggable Chrome and attaches when
found (falls back to isolated). Adds `--isolated`, positional CDP
target, and `--ws` accepts bare port numbers.

- **Bug Fixes**
  - Add CLI metadata to Browserbase sessions created via the CLI.
- Clear cached browser state when CDP connection drops to prevent
“awaitActivePage: no page available” errors.

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

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

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
2026-03-30 16:17:16 -07:00
Sean McGuire
f5d1f1ff80
[fix]: handle mapping timeout -> timeoutMs (#1901)
# why
- the `timeoutMs` param in `goto` was not being respected when using the
stagehand api
- the `/navigate` route on the server expects `timeout`, while the
actual `goto()` implementation in node expects `timeoutMs`
# what changed
- added logic to correctly send the `timeoutMs` param to the server as
`timeout`
- added server side logic to map the `timeout` back to `timoeutMs`
(which is what `goto()` expects)
### screenshot: (navigate correctly adheres to defined timeout)
<img width="691" height="462" alt="Screenshot 2026-03-27 at 4 13 04 PM"
src="https://github.com/user-attachments/assets/946de567-70d5-4fa9-be8e-646bb996e894"
/>


<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Fixes timeout handling for navigation by mapping `timeoutMs` on the
client to `timeout` over the API, then back to `timeoutMs` for
`page.goto()`. Navigations now respect the configured timeout when using
the Stagehand API.

- **Bug Fixes**
  - Client sends `timeout` to `/navigate` from `options.timeoutMs`.
  - Server maps `timeout` to `timeoutMs` before calling `page.goto()`.

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

<!-- End of auto-generated description by cubic. -->
2026-03-27 16:24:51 -07:00
Shrey Pandya
bd2a9cfcad
STG-1668: browse env local auto-discovers existing Chrome via CDP (#1886)
## Summary

- `browse env local` now auto-discovers an already-running Chrome with
remote debugging enabled (via `DevToolsActivePort` files and common port
probing), attaching to it instead of always launching an isolated
browser
- Falls back to isolated launch when no debuggable Chrome is found —
keeps the command reliable
- Added `--isolated` flag to force clean isolated browser (old behavior)
- Added positional CDP target argument: `browse env local 9222` or
`browse env local ws://...`
- `browse status` now reports `localStrategy`, `localSource`,
`resolvedCdpUrl`, and `fallbackReason`

**Sister PR:** browserbase/skills#54

## Test plan

<img width="698" height="373" alt="image"
src="https://github.com/user-attachments/assets/1612cf7e-61f4-46b8-9cc6-e739c7363a5a"
/>

- [x] All 44 existing tests pass
- [x] `browse env local` with Chrome running +
`--remote-debugging-port=9222` → attaches to existing Chrome
- [x] `browse env local` without debuggable Chrome → falls back to
isolated launch
- [x] `browse env local --isolated` → always launches clean browser
- [x] `browse env local 9222` → persists CDP strategy targeting
127.0.0.1:9222
- [x] `browse status` shows local strategy details
- [x] `browse env remote` → unchanged

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

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-27 16:13:51 -07:00
tkattkat
6dc2276144
Fix OpenAI cua agent (#1899)
# why

- OpenAI now requires a screenshot on initial message for computer use
agents

# what changed

- added screenshot to initial message 
- imported types from openai sdk for stronger typing 

# test plan

- tested locally using operator-example script 

<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Send an initial screenshot with the first message in `OpenAICUAClient`
to meet OpenAI’s computer-use requirement and prevent startup errors.
Also adopt `openai` SDK response types for stricter typing.

- **Bug Fixes**
- Capture and attach a high-detail screenshot on the first request when
available; gracefully skip on failure.
- Build the first message using `EasyInputMessage`, `ResponseInputText`,
and `ResponseInputImage`; include an optional system message from
`userProvidedInstructions`; make `createInitialInputItems` async and
update method signatures to accept a unified `OpenAIRequestInputItem`
type.

- **Dependencies**
  - Add changeset for a patch release of `@browserbasehq/stagehand`.

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

<!-- End of auto-generated description by cubic. -->
2026-03-27 11:40:39 -07:00
Shrey Pandya
3bd09d3abc
chore: Decouple browse-cli release cycle from stagehand core (#1885)
## Summary

- Adds `@browserbasehq/browse-cli` to the changeset `ignore` list so the
main "Version Packages" PR no longer includes CLI version bumps
- Creates a new `release-cli.yml` workflow (triggered via
`workflow_dispatch`) that independently versions and publishes
browse-cli to npm

### How it works

**Main release flow (`release.yml`)** — unchanged, but now skips
browse-cli. Core stagehand changesets are versioned and published as
before.

**CLI release flow (`release-cli.yml`)** — triggered manually via GitHub
Actions "Run workflow":
1. Detects pending browse-cli changesets (fails early if a changeset
mixes browse-cli with other packages)
2. Temporarily swaps the changeset ignore config to version only
browse-cli
3. Runs `changeset version` to consume CLI changesets and bump
`packages/cli/package.json`
4. Builds all packages, publishes browse-cli to npm via Trusted
Publishing
5. Commits the version bump and pushes a git tag

### Constraints
- Changesets that reference **both** browse-cli and another package
(e.g., stagehand core) must be split into separate changeset files — the
workflow enforces this with a pre-check
- browse-cli is excluded from canary (`alpha`) releases — add a canary
step to `release-cli.yml` if needed later

## Test plan
- [ ] Verify existing `release.yml` still creates "Version Packages" PR
for core changesets (browse-cli changesets should be excluded)
- [ ] Trigger `release-cli.yml` via workflow_dispatch with a pending
browse-cli changeset and verify it publishes correctly
- [ ] Verify mixed changeset detection fails the workflow with a clear
error

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

<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Decouples the `@browserbasehq/browse-cli` release cycle from stagehand
core so we can ship CLI updates independently. Implements STG-1663.

- **New Features**
- Adds `@browserbasehq/browse-cli` to `.changeset` ignore so
`release.yml` skips CLI.
- Adds `release-cli.yml` (manual via `workflow_dispatch`, restricted to
`main`) to version and publish CLI with Trusted Publishing.
  - Pre-checks for CLI-only changesets; fails on mixed changesets.
- Temporarily swaps `.changeset` ignore to version only CLI and strips
the `@browserbasehq/stagehand` workspace dep before `changeset version`
to satisfy Changesets; restores both after.
- Builds and publishes `packages/cli` to npm, commits the bump, and
tags.

- **Migration**
  - Split changesets that touch CLI and core.
  - Use the “Release CLI” workflow to publish CLI releases.
  - Canary releases for CLI are not included.

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

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

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-26 16:55:15 -07:00