# 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. -->
# why
- pnpm installs optional deps by default, which meant installing
`stagehand` would also pull in `playwright-core`, `patchright-core`, &
`puppeteer-core`
- these packages should be supplied by the consumer **_only if_** they
want to use `stagehand` with an existing browser automation framework.
they are otherwise not required
- moving them into peer dependencies prevents unnecessary installs, &
reflects a more accurate dependency graph
# what changed
- moved `playwright-core`, `patchright-core`, & `puppeteer-core` in
`packages/core` from optional deps to optional peer deps
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Moved `playwright-core`, `patchright-core`, and `puppeteer-core` to
optional peer dependencies in `@browserbasehq/stagehand` to stop
automatic installs and let consumers opt in only if needed. Also aligned
`playwright` version ranges across packages.
- **Dependencies**
- In `packages/core`: moved `playwright-core`, `patchright-core`,
`puppeteer-core` from optional deps to optional peer deps (all marked
optional).
- Updated internal dev deps to keep tests working: `playwright`,
`playwright-core`, `puppeteer-core`, `patchright-core`.
- Aligned `playwright` ranges: `packages/evals` uses `>=1.55.1 <1.57.0`;
`packages/server-v3` and `packages/server-v4` use `^1.55.1`.
- **Migration**
- If you use Stagehand with Playwright, add `playwright-core@^1.55.1`.
- If you use Puppeteer, add `puppeteer-core@^24.43.0`.
- If you use Patchright, add `patchright-core@^1.55.2`.
<sup>Written for commit dc726fc12933305106cb7936eb6a18310cfb7c53.
Summary will update on new commits.</sup>
<!-- End of auto-generated description by cubic. -->
# why
- to bump a small set of direct and transitive dependencies to pick up
patched upstream releases
# what changed
- bumped `playwright` to 1.55.1 across workspace all workspace packages
- bumped `@playwright/test` in `packages/core` to 1.55.1
- bumped `playwright-core` in `packages/core` to 1.55.1
- bumped `puppeteer-core` in `packages/core` to 24.43.0
- bumped `jsdom` in `packages/core` to 29.1.1.
- bumped `@browserbasehq/sdk` where needed to pick up a patched
transitive dependency tree
# test plan
- existing test suite + pnpm audit
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Bumps key direct and transitive dependencies across the monorepo to pick
up patched upstream releases and align browser tooling. Ships patch
releases for Stagehand packages.
- **Dependencies**
- `packages/core`: `playwright` → `^1.59.1`, `playwright-core` →
`^1.59.1`, `@playwright/test` → `^1.59.1`, `puppeteer-core` →
`^24.43.0`, `jsdom` → `^29.1.1`, `openai` → `^4.104.0`,
`@langchain/openai` → `^0.4.9`.
- `packages/server-v3` and `packages/server-v4`: `playwright` →
`1.55.1`.
- `packages/evals`: `openai` → `^4.104.0`, `playwright` → `^1.55.1`,
`braintrust` → `^0.4.10`, added `@types/node` and `types: ["node"]` in
`tsconfig`.
- Updated `pnpm-lock.yaml`.
- Patch releases: `@browserbasehq/stagehand`,
`@browserbasehq/stagehand-evals`, `@browserbasehq/stagehand-server-v3`,
`@browserbasehq/stagehand-server-v4`.
- **Migration**
- Reinstall deps: `pnpm install`.
- Reinstall Playwright browsers if needed: `npx playwright install`.
<sup>Written for commit db96e496ead3c081d74484784763aa86b6d096a9.
Summary will update on new commits.</sup>
<!-- End of auto-generated description by cubic. -->
## Summary
- default the v3 server listener to localhost unless HOST is explicitly
set
- warn when HOST=0.0.0.0 opts into all-interface binding
- make the v4 SEA build choose a Node binary that contains the SEA fuse
## Validation
- pnpm --filter @browserbasehq/stagehand-server-v3 run build:esm-tests
- pnpm --filter @browserbasehq/stagehand-server-v3 run typecheck
- pnpm --filter @browserbasehq/stagehand-server-v4 run typecheck
- pnpm --filter @browserbasehq/stagehand-server-v3 run test:unit --
packages/server-v3/dist/tests/unit/listenHost.test.js
- pnpm --filter @browserbasehq/stagehand-server-v4 run build:sea:esm --
--binary-name=stagehand-server-v4-localhost-binding-test
Leaving the full suite to CI.
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Default `@browserbasehq/stagehand-server-v3` to listen on localhost
unless `HOST` is set, and warn on `HOST=0.0.0.0` to prevent accidental
exposure. Also make the `@browserbasehq/stagehand-server-v4` SEA build
use a Node binary that includes the SEA fuse for reliable builds.
- New Features
- Default listen host to `localhost` when `HOST` is unset or blank;
respect explicit values.
- Warn when `HOST=0.0.0.0` to make all-interface binding explicit.
- Migration
- If you need external access, set `HOST=0.0.0.0` (or a specific
interface).
<sup>Written for commit 3cecdce8251f43aa3853ca56f8924eb0dda9dff7.
Summary will update on new commits.</sup>
<!-- End of auto-generated description by cubic. -->
# why
- to let users exclude parts of the page from the snapshot that
`observe()` sends to the model, the same way they can with `extract()`
# what changed
- this PR is just wiring the added param through observe & updating
types. it uses the same underlying functionality that was added in #2084
when adding `ignoreSelectors` to `extract()`
- `packages/core/lib/v3/types/public/methods.ts`,
`packages/core/lib/v3/types/private/handlers.ts`, &
`packages/core/lib/v3/types/public/api.ts`:
- added the `ignoreSelectors` option to the public api, internal handler
params, & request schema
- `packages/core/lib/v3/v3.ts` &
`packages/core/lib/v3/handlers/observeHandler.ts`:
- passed `ignoreSelectors` through the observe path into
`captureHybridSnapshot()`
# test plan
- updated `packages/core/tests/unit/public-api/public-types.test.ts` to
cover the new `ignoreSelectors` param
- updated `packages/core/tests/unit/api-variables-schema.test.ts` &
`packages/core/tests/unit/api-client-observe-variables.test.ts` to cover
request validation and serialization for `observe({ ignoreSelectors })`
- updated `packages/core/tests/unit/timeout-handlers.test.ts` to cover
`ObserveHandler` passing `ignoreSelectors` into
`captureHybridSnapshot()`
### notes
- the test file placement is a little weird right now:
- `timeout-handlers.test.ts` already contains broader parameter
threading tests, so this was the smallest change for now
- this can be cleaned up in a later refactor
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Add `ignoreSelectors` to `observe()` so you can exclude elements from
the snapshot sent to the model. Brings `observe()` to parity with
`extract()`.
- **New Features**
- Support `observe({ ignoreSelectors: ["nav", ".cookie-banner"] })` to
skip elements and subtrees during snapshot capture.
- Plumbed through public types, internal handler params, and
`captureHybridSnapshot()` call path.
- Request schema and `packages/server-v3/openapi.v3.yaml` updated;
client serialization and validation covered by tests.
- Published as a minor for `@browserbasehq/stagehand`.
<sup>Written for commit c7b538c04d439b13d28db843a12344529171219b.
Summary will update on new commits.</sup>
<!-- End of auto-generated description by cubic. -->
## Summary
- remove ModelApiKey from the server-v3 OpenAPI global security
requirement
- update the checked-in v3 OpenAPI spec so Stainless no longer treats
model API key as required client auth
## Verification
- pnpm --filter @browserbasehq/stagehand-server-v3 run lint
- pnpm --filter @browserbasehq/stagehand-server-v3 run build
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Make the model API key optional by removing `ModelApiKey` from server v3
OpenAPI global security (STG-1806). Update the spec/generator in
`@browserbasehq/stagehand-server-v3` and add a patch changeset so
Stainless clients no longer require a model key.
- **Migration**
- Regenerate clients from the v3 OpenAPI (e.g., Stainless) to drop
`ModelApiKey` as required auth.
<sup>Written for commit 3c74893febe6a3501f26eaa700ba2290c02cad56.
Summary will update on new commits.</sup>
<!-- End of auto-generated description by cubic. -->
---------
Co-authored-by: samfinton <samfinton@samLaptopm5.galaxus.box>
Linear:
https://linear.app/browserbase/issue/STG-1935/strengthen-observe-element-id-prompting
## Summary
- keep the strict `number-number` observe element ID schema intact
- strengthen the observe system prompt to tell the model to copy the
full bracketed tree ID, including frame ordinal and hyphen
- strengthen the schema description with the concrete `[0-18372] ->
"0-18372", not "18372"` example
- add prompt regression coverage, main-frame `0-...` observe integration
coverage, and a patch changeset
- add `observe/observe_main_frame_element_ids` as a regression eval for
multiple main-frame targets
## Eval Coverage
Current bench eval count after this PR:
```text
146 total bench evals
12 observe bench evals
```
This PR adds one observe regression eval:
`observe/observe_main_frame_element_ids`.
## Validation
- `pnpm --filter @browserbasehq/stagehand run build`
- `pnpm --filter @browserbasehq/stagehand run test:core --
packages/core/dist/esm/tests/unit/prompt-observe-variables.test.js`
- `pnpm --filter @browserbasehq/stagehand run test:e2e --
packages/core/dist/esm/tests/integration/observe-element-id-format.spec.js`
- `pnpm --filter @browserbasehq/stagehand run lint`
- `pnpm --filter @browserbasehq/stagehand-evals run typecheck`
- `pnpm --filter @browserbasehq/stagehand-evals run test:unit --
tests/taskConfig.test.ts`
- `pnpm --filter @browserbasehq/stagehand-evals run lint`
- `env STAGEHAND_E2E_TARGET=BROWSERBASE pnpm exec tsx
/Users/shrey/Developer/scratchpad/stagehand-observe-bare-id-e2e/index.ts`
- `pnpm --filter @browserbasehq/stagehand-evals exec tsx cli.ts run
observe_main_frame_element_ids -e browserbase -t 1 -c 1 -m
anthropic/claude-sonnet-4-6`
Real Browserbase E2E used `anthropic/claude-sonnet-4-6` and verified raw
model IDs plus click success:
```text
Attempt 1 raw model elementId: 0-5011
Attempt 1 act success: true
Attempt 1 DOM clicked marker: yes
Attempt 2 raw model elementId: 0-5011
Attempt 2 act success: true
Attempt 2 DOM clicked marker: yes
Attempt 3 raw model elementId: 0-5011
Attempt 3 act success: true
Attempt 3 DOM clicked marker: yes
```
The new Browserbase bench eval also passed with
`anthropic/claude-sonnet-4-6`:
```text
observe/observe_main_frame_element_ids anthropic/claude-sonnet-4-6 passed
Results: 1 passed, 0 failed (1 total)
Pass rate: 100%
```
# why
`experimental: true` is no longer required for agent variable support
# what changed
- Removed the experimental gate on agent variables: dropped the
variables check in `validateExperimentalFeatures.ts` and the
@experimental JSDoc on `AgentExecuteOptionsBase.variables`.
- Added a variables field to the AgentExecuteOptions API schema
(`packages/core/lib/v3/types/public/api.ts`) and reflected it in the
generated `openapi.v3.yaml` (both request and output components).
- Updated docs to drop `experimental: true` from the Variables Note and
Basic Usage example (kept the "Non-CUA agents only" caveat).
- Added unit tests covering the new surface
- Added integration coverage on the login eval site: new variables
describe blocks in `act.test.ts` and `agentExecute.test.ts` (simple and
rich { value, description } forms, verified via CDP), and updated
`observe.test.ts`'s existing variables tests to use the same scenario.
# test plan
- [x] pnpm --filter @browserbasehq/stagehand-server-v3 typecheck —
passes.
- [x] pnpm exec prettier --check on the three test files — passes.
- [x] pnpm exec eslint on the three test files — passes.
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Enable variables in v3 `agentExecute` without experimental mode, with
end-to-end substitution across `act`, `observe`, and agent tools.
Tightened `fillFormVision` so secrets are only substituted at type-time
and never leak via logs, replays, or tool outputs.
- **New Features**
- Added `variables` to `AgentExecuteOptionsSchema` and server OpenAPI
(`Variables`).
- Removed experimental gating for variables; CUA-mode rejection remains.
- Updated JSDoc and docs to drop the experimental requirement.
- Added tests: unit (validation, client serialization, schema) and
integration for substitution in `act`, `observe`, and `agentExecute`
(simple and rich forms).
- **Bug Fixes**
- Updated `fillFormVision` to substitute variables only when typing and
keep placeholders in action logs, replays, and returned arguments.
<sup>Written for commit a6e9d621d396cab397bd5348c814629373693cf0.
Summary will update on new commits.</sup>
<!-- End of auto-generated description by cubic. -->
---------
Co-authored-by: Chromie <miguel@browserbase.com>
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: tkattkat <tkat@tkat.net>
# why
Browserbase API keys are project-scoped, so Stagehand should keep
accepting project IDs without requiring them.
# what changed
- Mark `browserbaseSessionCreateParams.projectId` deprecated in
Zod/OpenAPI.
- Make `BROWSERBASE_PROJECT_ID` nullable/deprecated in Stainless config.
- Use Browserbase-returned `projectId` in the local server instead of
`x-bb-project-id`.
```ts
projectId: z.string().optional().meta({ deprecated: true })
```
# test plan
- `pnpm --filter @browserbasehq/stagehand run lint`
- `pnpm --filter @browserbasehq/stagehand-server-v3 run lint`
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Deprecate Browserbase project ID per STG-1808; Stagehand now relies on
project-scoped API keys and the project ID returned by Browserbase. The
`x-bb-project-id` header, session `projectId` param, and
`BROWSERBASE_PROJECT_ID` config are deprecated but remain optional for
now.
- **Refactors**
- Marked `projectId` in session create params as deprecated in
Zod/OpenAPI; updated security scheme descriptions to reflect deprecation
of `x-bb-project-id`.
- Made `BROWSERBASE_PROJECT_ID` nullable and marked deprecated in
`stainless.yml`.
- Server now resolves `projectId` from the retrieved/created Browserbase
session; stops reading `x-bb-project-id` and adjusts validation
messages.
- **Migration**
- Stop sending `x-bb-project-id` and remove `BROWSERBASE_PROJECT_ID`;
they’re no longer needed.
- Avoid passing `projectId` in session creation; it’s accepted but
deprecated.
<sup>Written for commit 5ee90b860105739405927eec695060a1d1a066fc.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/2039">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
# why
- to allow users to specify selectors whose content should be omitted
from the LLM request inside of `extract()`
# what changed
- added `ignoreSelectors` to `extract()` so callers can exclude parts of
the page from the extraction snapshot
- `packages/core/lib/v3/understudy/a11y/snapshot/capture.ts`:
- added `resolveIgnoreSelectorRoots()` to resolve ignore selectors into
`frameId + backendNodeId`
- added `buildFrameExclusionIntervals()` to turn those roots into
per-frame subtree ranges
- updated `collectPerFrameMaps()` / `tryScopedSnapshot()` to skip
ignored nodes when building snapshot data
- `packages/core/lib/v3/understudy/a11y/snapshot/domTree.ts`:
- updated `buildSessionDomIndex()` to record dfs entry/exit positions
for each backend node so ignored subtrees can be filtered by interval
membership instead of having to re-traverse the tree
- `packages/core/lib/v3/understudy/a11y/snapshot/a11yTree.ts`:
- updated `a11yForFrame()` to accept an ignore predicate and remove
ignored nodes from the outline (the stringified tree) and `urlMap`
- `packages/core/lib/v3/handlers/extractHandler.ts` and
`packages/core/lib/v3/v3.ts`:
- passed `ignoreSelectors` down through the extract path into
`captureHybridSnapshot()`
- kept `xpathMap` values based on the original dom structure and only
skipped ignored entries, so surviving selectors do not get renumbered
# test plan
- updated `packages/core/tests/unit/public-api/public-types.test.ts` to
cover the new `ignoreSelectors` option on `extract()`
- updated `packages/core/tests/unit/snapshot-a11y-resolvers.test.ts` to
cover ignored backend nodes being removed from the a11y outline and
`urlMap`, and to cover scoped snapshots dropping ignored xpath entries
- updated
`packages/core/tests/unit/snapshot-capture-orchestration.test.ts` to
cover the new capture flow, including filtered per-frame maps and merged
snapshot output when `ignoreSelectors` is used
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Adds `ignoreSelectors` to `extract()` so callers can exclude elements
and their subtrees from snapshots and the LLM input. Supports CSS and
XPath (with iframe hops) across shadow DOM and iframes, without
renumbering existing XPaths; also adds a fast path for scoped snapshots
and excludes child frame subtrees when an iframe host is ignored.
- **New Features**
- `extract({ ignoreSelectors: string[] })`: drops matching nodes and
descendants from DOM maps, a11y outline, and `urlMap`; `xpathMap` keeps
original values but omits ignored entries.
- Applies to full-page and scoped snapshots; filters resolved per frame,
excludes child frames when their iframe host is ignored, and enforces
DFS enter/exit intervals for speed.
- A11y tree accepts an ignore predicate and filters before building the
outline and links.
- Scoped snapshots return early when only `selector` is provided (no
`ignoreSelectors`) for faster capture.
- Plumbed through `extractHandler`, `v3`, and `captureHybridSnapshot()`;
public types and OpenAPI updated in `@browserbasehq/stagehand`; unit
tests added.
<sup>Written for commit 0ad2f67d8fe81d15945599c60351ac45f66f1277.
Summary will update on new commits.</sup>
<!-- End of auto-generated description by cubic. -->
# why
Reasoning models (e.g. `openai/gpt-5-mini`) emit `AI SDK Warning: The
"temperature" setting is not supported by this model` whenever the v3
agent
runs against them, because `V3AgentHandler` hardcoded `temperature: 1`
on every `generateText`/`streamText` call. There was no constructor or
agent-config option to override it, so users running reasoning models
with `experimental: true` had no way to silence the warning.
# what changed
- Removed the hardcoded `temperature: 1` from both the non-streaming and
streaming agent paths in
`packages/core/lib/v3/handlers/v3AgentHandler.ts`.
- Agent calls now omit `temperature` entirely, so the AI SDK no longer
flags it as user-set on models that don't accept it. Models that do
accept
temperature still default to the AI SDK provider's own default.
- Added unit coverage in
`packages/core/tests/unit/agent-temperature.test.ts` asserting neither
code path passes a `temperature` to the LLM
client.
- Added a patch changeset
(`.changeset/remove-agent-temperature-default.md`).
# test plan
- [ ] `pnpm --filter @browserbasehq/stagehand test agent-temperature` —
new unit tests pass
- [ ] Existing v3 agent unit suite stays green
- [ ] Manual: `agent.execute(...)` against `openai/gpt-5-mini` with
`experimental: true` — confirm no `"temperature" setting is not
supported`
warning in stderr
- [ ] Manual: same call against a non-reasoning model (e.g.
`openai/gpt-4.1-mini`) — confirm agent still completes a multi-step task
end-to-end
- [ ] Manual: hybrid-mode agent run on a reasoning model — verify
streaming path is also clean
---------
Co-authored-by: Filip Michalsky <filip-michalsky@users.noreply.github.com>
# why
Stagehand could lose a known parent-child frame relationship after
adopting an OOPIF child session. In practice, that meant the registry
could forget that a child frame still belonged under the top-level page,
leaving later iframe resolution with an incomplete frame tree.
# what changed
Added a deterministic FrameRegistry unit test for the OOPIF adoption
ordering. Updated `seedFromFrameTree()` to preserve an already-known
parent when a child frame tree snapshot does not include parent
metadata.
# test plan
Before the fix, the new test failed with `expected null to be
'root-frame'`. After the fix, this passes:
`pnpm --dir packages/core run build:esm && pnpm --dir packages/core run
test:core --
packages/core/dist/esm/tests/unit/frame-registry-oopif-adoption.test.js`
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Fixes a bug where the frame registry could lose a known parent-child
link after adopting an OOPIF child session. Preserves the parent edge
when seeding from a child frame tree that lacks parent metadata to keep
the iframe tree complete.
- Bug Fixes
- Updated `FrameRegistry.seedFromFrameTree()` to retain an existing
parent when `parentId` is missing and to sync child sets accordingly.
- Added a unit test for OOPIF adoption ordering and seeding to prevent
regressions, and a changeset for `@browserbasehq/stagehand` patch
release.
<sup>Written for commit 1e50e9c3ed4d56c158c1b694bbd04d2aac55821c.
Summary will update on new commits.</sup>
<!-- End of auto-generated description by cubic. -->
---------
Co-authored-by: samfinton <samfinton@samLaptopm5.galaxus.box>
# why
Stagehand should standardize public docs and runtime overrides on
`STAGEHAND_API_URL` without breaking users who still export
`STAGEHAND_BASE_URL`.
# what changed
- Prefer `STAGEHAND_API_URL`, with `STAGEHAND_BASE_URL` as a deprecated
legacy fallback.
- Emit a one-time deprecation warning when the legacy fallback is used.
- Update server-v3 test env plumbing, CI, and docs to use
`STAGEHAND_API_URL`.
- Add patch changesets for core and server-v3.
```ts
const configuredBaseUrl =
process.env.STAGEHAND_API_URL ?? process.env.STAGEHAND_BASE_URL;
```
# test plan
- `pnpm --filter @browserbasehq/stagehand run build:esm`
- `pnpm --filter @browserbasehq/stagehand run test:core --
packages/core/dist/esm/tests/unit/api-optional-model-api-key.test.js`
- `pnpm --filter @browserbasehq/stagehand run typecheck`
- `pnpm --filter @browserbasehq/stagehand-server-v3 run typecheck`
- `pnpm --filter @browserbasehq/stagehand run lint`
- `pnpm --filter @browserbasehq/stagehand-server-v3 run lint`
- `pnpm exec prettier --check .changeset/rude-tips-check.md
.github/workflows/ci.yml packages/docs/v3/sdk/java.mdx
packages/docs/v3/sdk/python.mdx turbo.json`
- `pnpm changeset status --since origin/main --verbose`
# why
Dom mode has been deprecated for a while, and is now being replaced with
hybrid as a default
# what changed
- When a hybrid capable model is provided, it is used with hybrid mode
by default
- When a non hybrid capable model is provided, it is used with dom mode
- if dom or hybrid is explicitly provided, it will use the provided mode
# test plan
tested locally + wrote tests
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Set the default v3 agent mode to hybrid, with automatic routing to dom
for models that aren’t hybrid-capable. Explicit mode settings are always
respected; CUA behavior is unchanged.
- **New Features**
- Auto-selects "hybrid" for models matching
`HYBRID_CAPABLE_MODEL_PATTERNS` (`gemini-3`, `claude`, `gpt-5.4`,
`gpt-5.5`); otherwise uses "dom".
- Routes using the provided agent model (string or config), or falls
back to the Stagehand-level model when undefined.
- Honors explicit `mode` (`dom`, `hybrid`, `cua`); if `mode` is unset,
deprecated `cua: true` enables CUA.
- Logs the resolved mode and warns when "hybrid" is used with
non-hybrid-capable models.
- Adds unit tests for routing and handler fallbacks.
<sup>Written for commit 01e7d69945369cca735dff9ba088538420e344c9.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/2047">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
## What Changed
Adds three new models to the list of supported CUA (Computer Use Agent)
models:
- `openai/gpt-5.4-mini`
- `openai/gpt-5.5`
- `anthropic/claude-haiku-4-5`
---
## Files Changed
### `packages/core/lib/v3/types/public/agent.ts`
- Added the three models to the `AVAILABLE_CUA_MODELS` const array
- This drives:
- The `AvailableCuaModel` type
- The runtime CUA model check in `resolveModel()`
### `packages/core/lib/v3/agent/AgentProvider.ts`
- Added model → provider mappings in `modelToAgentProviderMap`:
- `gpt-5.4-mini` → `openai`
- `gpt-5.5` → `openai`
- `claude-haiku-4-5` → `anthropic`
- Ensures `AgentProvider.getAgentProvider()` resolves them correctly
### `packages/core/tests/unit/public-api/llm-and-agents.test.ts`
- Updated the `expectedModels` list in the type-level test to stay in
sync with the source of truth
---
## How It Was Tested
- ✅ Build passes (`pnpm turbo run build`)
- ✅ All **204 public-api unit tests** pass
- ✅ All **608 unit tests** pass
- ⚠️ 4 pre-existing failures in `flowlogger-eventstore.test.js`
(confirmed on base branch)
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Adds support for three new Computer Use Agent models and maps them to
the right providers. Apps can now use `openai/gpt-5.4-mini`,
`openai/gpt-5.5`, and `anthropic/claude-haiku-4-5` via the public API.
- **New Features**
- Registered the models in `AVAILABLE_CUA_MODELS` and mapped providers:
`gpt-5.4-mini` → `openai`, `gpt-5.5` → `openai`, `claude-haiku-4-5` →
`anthropic`.
- Updated public API tests to include the new models.
- Added a changeset to release these additions as a patch in
`@browserbasehq/stagehand`.
<sup>Written for commit ec5b691fdf9e469e11b4d025a11a7ac32dbba0c5.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/2065?utm_source=github">Review
in cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
---------
Co-authored-by: Chromie <miguel@browserbase.com>
Co-authored-by: Claude <noreply@anthropic.com>
Prepare the next browse-cli release by versioning the package on `main`.
What this PR does:
- bumps `packages/cli/package.json` to `0.6.0`
- updates the browse-cli changelog
- consumes the pending browse-cli changesets
After this PR merges, the `Release` workflow on `main` will publish
`@browserbasehq/browse-cli@0.6.0` from that exact commit using `pnpm
pack` + `npm publish --provenance`.
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
## Summary
`browse cdp` enables the Page domain via `Page.enable`, but
`Page.enable` does not by itself emit `Page.lifecycleEvent` — that
requires a separate `Page.setLifecycleEventsEnabled` opt-in. As a
result, consumers of `browse cdp` today see only `Page.frameNavigated`
and miss the granular lifecycle milestones (`init`, `commit`,
`DOMContentLoaded`, `load`, `firstPaint`, `firstContentfulPaint`,
`firstMeaningfulPaint`, `networkAlmostIdle`, `networkIdle`).
This PR enables lifecycle events whenever the Page domain is enabled (so
it covers both the default-domain set and explicit `--domain Page`), and
adds a `--pretty` formatter case that prints the milestone name.
## Why
These events are exactly what observability/perf tools want from the
firehose:
- approximate page-ready timing (`DOMContentLoaded` / `load`)
- network-settled signal (`networkIdle`)
- paint timing (`firstPaint` / `firstContentfulPaint` /
`firstMeaningfulPaint`)
Without the opt-in, all of those have to be approximated from
`Page.frameNavigated` + `Network.loadingFinished`, which loses the
per-milestone resolution.
## Verification
Built locally with `pnpm exec tsx src/index.ts cdp 9333` against a
debuggable Chrome and triggered an `example.com` navigation. Before this
patch, no `Page.lifecycleEvent` lines. After:
```
[Page.lifecycleEvent] init
[Page.lifecycleEvent] commit
[Page.lifecycleEvent] DOMContentLoaded
[Page.lifecycleEvent] firstPaint
[Page.lifecycleEvent] firstContentfulPaint
[Page.lifecycleEvent] firstMeaningfulPaint
[Page.lifecycleEvent] load
[Page.lifecycleEvent] networkAlmostIdle
[Page.lifecycleEvent] networkIdle
```
Default mode (NDJSON) emits the same events with full params:
```json
{"sessionId":"…","method":"Page.lifecycleEvent","params":{"frameId":"…","loaderId":"…","name":"DOMContentLoaded","timestamp":468107.080156}}
```
## Test plan
- [ ] `pnpm --filter @browserbasehq/browse-cli typecheck` passes
- [ ] `pnpm --filter @browserbasehq/browse-cli eslint` passes
- [ ] `pnpm --filter @browserbasehq/browse-cli test` — no new failures
(pre-existing failures in `cli.test.ts` / `mode.test.ts` reproduce on
`main` and are unrelated to this change)
- [ ] Manual: `browse cdp <port>` against a debuggable Chrome shows
`Page.lifecycleEvent` lines after a navigation
- [ ] Manual: `browse cdp <port> --pretty` formats
`[Page.lifecycleEvent] <name>`
- [ ] Manual: `browse cdp <port> --domain Network --domain Console` (no
Page) emits no lifecycle events — the opt-in is gated correctly
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
## Summary
- move local CDP discovery into a dedicated module so the
DevToolsActivePort behavior is directly testable
- reuse the exact `DevToolsActivePort` websocket path for `browse env
local --auto-connect`
- reuse the same exact-path lookup for bare numeric CDP targets in
`resolveWsTarget`
- avoid the extra speculative websocket verification pass on the
file-backed discovery path
- add regression coverage for exact-path resolution, stale file cleanup,
ambiguity, and fallback port probing
## Root Cause
The CLI was reading `DevToolsActivePort` but then discarding the exact
websocket path and probing generic endpoints first. On Chrome's
remote-debugging approval flow that could trigger extra preflight
requests before the real attach.
## Validation
- `pnpm --filter @browserbasehq/stagehand gen-version`
- `pnpm --filter @browserbasehq/stagehand build-dom-scripts`
- `pnpm --filter @browserbasehq/stagehand build`
- `pnpm --filter @browserbasehq/browse-cli build`
- `pnpm --filter @browserbasehq/browse-cli typecheck`
- `pnpm --filter @browserbasehq/browse-cli test`
Linear:
https://linear.app/browserbase/issue/STG-1859/use-exact-devtoolsactiveport-websocket-path-for-browse-cli-auto
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Fixes local CDP auto-connect by using the exact websocket path from
DevToolsActivePort to avoid extra probes and speed up attach in Chrome’s
approval flow. Addresses Linear STG-1859 and improves
`@browserbasehq/browse-cli` for `browse env local --auto-connect` and
bare port targets.
- **Bug Fixes**
- Reuse the exact DevToolsActivePort websocket path for local
auto-connect.
- Prefer exact-path resolution for bare numeric ports in
`resolveWsTarget`, then fall back to `/json/version`, then
`/devtools/browser`.
- Skip speculative websocket verification when a file provides the exact
path.
- Clean up stale DevToolsActivePort files and return null on ambiguity.
- **Refactors**
- Extracted local CDP discovery to `local-cdp-discovery.ts` with tests
for exact-path resolution, stale cleanup, ambiguity, and fallback
probing.
<sup>Written for commit 440eee4c562a71775cf3e413d5e929a0881837de.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/2049">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
# why
The v3 MCP docs now need to describe the hosted server behavior where
`start` can attach to an existing Browserbase session via an optional
`sessionId`.
# what changed
- Updated the MCP setup and tools docs to document optional
`start.sessionId`.
- Clarified that omitting `sessionId` creates a new Browserbase session.
- Added a patch changeset for `@browserbasehq/stagehand-docs`.
# test plan
- `pnpm exec prettier --check
packages/docs/v3/integrations/mcp/setup.mdx
packages/docs/v3/integrations/mcp/tools.mdx`
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Added docs for optional `sessionId` on MCP `start` to attach to an
existing Browserbase session; omitting it creates a new session.
Addresses STG-1837 and publishes a patch to
`@browserbasehq/stagehand-docs`.
<sup>Written for commit edc7cbdef0ce712d369699589e1b24b426bffdd6.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/2017">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
# why
- file upload elements sometimes have a 'button' AX role
- this causes issues when users prompt `.observe()` to find "file upload
elements", since the model sees them as a 'button'
- addresses #972
# what changed
- this PR preserves the semantics of file upload elements by using the
actual DOM tag name and 'type'
- eg, instead of `[0-12] button: Choose File`, we now use `[0-12] input,
file: Choose File`
# test plan
- added a unit test for the replacement logic
- added an `observe()` eval which checks that hidden file upload
elements are correctly found by the LLM
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Make file upload inputs explicit in the page snapshot so `.observe()`
can reliably find them. Addresses Linear STG-934 by preventing file
inputs from being misclassified as buttons.
- **Bug Fixes**
- Enrich DOM tag names to include input type (e.g., `input, file`) and
use them in DOM maps.
- Force file inputs to appear as `input, file` in the a11y outline
instead of AX `button`.
- Add unit test and fix/register the `observe_file_uploads` eval in
`evals.config.json`.
- Publish patch for `@browserbasehq/stagehand`.
<sup>Written for commit 2fad86f408ebb3d990935575a839bcb3e67d0eca.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1975">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
# why
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. -->
Mirrored from external contributor PR #1912 after approval by
@miguelg719.
Original author: @chromiebot
Original PR: https://github.com/browserbase/stagehand/pull/1912
Approved source head SHA: `0ea0332c525017c727743d11a68b8eb74f76b646`
@chromiebot, please continue any follow-up discussion on this mirrored
PR. When the external PR gets new commits, this same internal PR will be
marked stale until the latest external commit is approved and refreshed
here.
## Original description
# why
# what changed
# test plan
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Add adaptive thinking for Anthropic Claude 4.6 models in the `CUA`
client with effort controls and automatic `temperature=1`. Keeps legacy
`thinkingBudget` for older models and improves model detection and tool
versioning.
- **New Features**
- Detects 4.6 models (e.g., `claude-opus-4-6*`, `claude-sonnet-4-6*`,
incl. provider-prefixed) and sends `thinking: { type: "adaptive" }` with
`output_config.effort` (defaults to `"medium"`).
- Adds `ThinkingEffort` and `thinkingEffort` in `ClientOptions` (`"none"
| "low" | "medium" | "high" | "max"`); `"none"` disables adaptive
thinking.
- Forces `temperature: 1` with adaptive thinking and logs when
overriding a user value; logs when `thinkingBudget` is provided on 4.6
models.
- Uses `computer_20251124` for 4.6 and `claude-opus-4-5-20251101`; older
models continue with `thinking: { type: "enabled", budget_tokens }`.
- **Migration**
- For 4.6 models, set `thinkingEffort`; `thinkingBudget` is ignored.
- Adaptive thinking forces `temperature: 1`; set `thinkingEffort:
"none"` to disable.
<sup>Written for commit ebe95e77418c755ecc4b3d03235cb3d3cb2e03cc.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1954">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
<!-- external-contributor-pr:owned source-pr=1912
source-sha=0ea0332c525017c727743d11a68b8eb74f76b646 claimer=miguelg719
-->
---------
Co-authored-by: Chromie Bot <chromie@browserbase.com>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Co-authored-by: miguel <miguelg71921@gmail.com>
Mirrored from external contributor PR #1978 after approval by @pirate.
Original author: @a7med3liamin
Original PR: https://github.com/browserbase/stagehand/pull/1978
Approved source head SHA: `2149aa265a04dc37154d5a84411f3ab4d1045897`
@a7med3liamin, please continue any follow-up discussion on this mirrored
PR. When the external PR gets new commits, this same internal PR will be
marked stale until the latest external commit is approved and refreshed
here.
## Original description
- [x] Check the [documentation](https://docs.stagehand.dev/) for
relevant information
- [x] Search existing
[issues](https://github.com/browserbase/stagehand/issues) to avoid
duplicates
Fixes#1776
## Problem
The `keys` tool has no variable substitution in either the live
execution or cache replay paths. When the agent uses `%variableName%`
tokens with the keys tool, the literal token string gets typed instead
of the resolved value.
## Fix
This PR combines two fixes into one:
### 1. Live execution (original fix by @trillville from #1777)
- Accept `variables` parameter in `keysTool` (matching `typeTool`)
- Call `substituteVariables()` before `page.type()` in the `method ===
"type"` branch
- Pass `variables` to `keysTool` in `createAgentTools`
- Update schema description to advertise available variables to the LLM
- Return original token in result to avoid exposing sensitive values to
LLM
### 2. Cache replay (new fix)
- Import `substituteVariables` in `AgentCache.ts`
- Pass `variables` through to `replayAgentKeysStep`
- Call `substituteVariables(text, variables)` before `page.type()` in
the replay path
Without fix#2, cached `keys` steps with `method="type"` replay by
typing literal `%variableName%` tokens even when variables are provided,
since `replayAgentKeysStep` had no access to the variables map.
## Credit
The live execution fix (part 1) is from @trillville's work in
#1777/#1813. We merged it here with the cache replay fix per @pirate's
request to consolidate into a single PR.
<!-- external-contributor-pr:owned source-pr=1978
source-sha=2149aa265a04dc37154d5a84411f3ab4d1045897 claimer=pirate -->
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Add variable substitution to the `keys` tool for both live execution and
cache replay so `%variableName%` tokens are resolved before typing. This
fixes cases where literal tokens were typed and brings parity with the
`type` tool.
- **Bug Fixes**
- Pass `variables` into `keys` and call `substituteVariables()` before
`page.type()`; update the input schema to list available variables.
- In cache replay, forward `variables` to `replayAgentKeysStep` and
substitute before typing to avoid replaying literal tokens.
- Record and return the original tokenized value (not the resolved
value) to avoid leaking sensitive data.
<sup>Written for commit abb3905cd9563609b01e78bf190a21a5998b9bb4.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1983">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
---------
Co-authored-by: Ahmed Ali <a7med3liamin@gmail.com>
Co-authored-by: trillville <trillville@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: Nick Sweeting <git@sweeting.me>
## Summary
- Reverts PR #1822 which added `providerOptions` for extensible model
auth (Bedrock/Vertex)
- Removes `providerOptions` bag from model config schema, Bedrock
examples, provider config, and server-side `modelClientOptions`
storage/passthrough
## Note
- One test from PR #1980 (`accepts verified Browserbase session
settings` in `model-config-schema.test.ts`) was removed as part of this
revert since the test file was originally created by #1822. That test
may need to be re-added in a separate file.
Made with [Cursor](https://cursor.com)
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Reverts the `providerOptions`-based model auth from #1822 (STG-1573) and
restores the previous auth flow: no provider options passthrough; model
auth is via the `x-model-api-key` header.
- **Refactors**
- Removed `providerOptions` and server-side `modelClientOptions`
passthrough from core and server.
- Deleted Bedrock examples and provider config; pruned related schemas
and tests.
- Simplified OpenAPI: removed ProviderOptions/ModelClientOptions
components and helpers extracting model config from request bodies.
- **Migration**
- Remove `providerOptions` from all model configs and requests.
- Do not send `modelClientOptions` in session start; the server ignores
it.
- Send model API keys via the `x-model-api-key` header; remove any
`skipApiKeyFallback` usage.
- If you adopted `vertex/*` names from #1822, switch to `google/*`.
<sup>Written for commit 1a3bbcb39c9831d4b0fa0e754fe57a255c392ab8.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1987">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
## Summary
- bump `@browserbasehq/sdk` to `^2.10.0` in `packages/core`,
`packages/server-v3`, and `packages/server-v4`
- add Browserbase `verified`, `os`, and custom captcha session settings
to the Stagehand Browserbase session-create schema and generated OpenAPI
specs
- keep legacy `advancedStealth` behavior working by treating it as a
compatibility alias for the new verified-mode checks in Stagehand
internals
## Testing
- `pnpm --filter @browserbasehq/stagehand build:esm`
- `pnpm --filter @browserbasehq/stagehand test:core --
packages/core/dist/esm/tests/unit/browserbase-session-accessors.test.js
packages/core/dist/esm/tests/unit/model-config-schema.test.js`
- `pnpm --filter @browserbasehq/stagehand typecheck`
- `pnpm --filter @browserbasehq/stagehand-server-v3 typecheck`
- `pnpm --filter @browserbasehq/stagehand-server-v4 typecheck`
- Browserbase-backed smoke test creating a real Stagehand session with
`browserSettings.verified: true`
Linear:
https://linear.app/browserbase/issue/STG-1798/support-browserbase-verified-session-settings
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Adds support for Browserbase Verified sessions with new session settings
across Stagehand APIs and a fixed Google CUA viewport when Verified,
addressing Linear STG-1798. Deprecates the `isAdvancedStealth` alias in
favor of `v3.isVerified`, and fixes abort-signal handling to fail fast
on already-aborted signals.
- New Features
- Add `verified`, `os`, `captchaImageSelector`, and
`captchaInputSelector` to Browserbase browser settings and generated
OpenAPI (v3 and v4).
- Introduce `v3.isVerified`; keep `isAdvancedStealth` as a deprecated,
backward-compatible alias.
- Use a 1288x711 viewport for Google CUA when Verified; otherwise use
the configured viewport.
- Dependencies
- Bump `@browserbasehq/sdk` to `^2.10.0` in `packages/core`,
`packages/server-v3`, and `packages/server-v4`.
<sup>Written for commit c2bde3337fbbb9b8143dc6ce2d0a6203282d8055.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1980">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
## Why
Local Chromium startup in CI intermittently fails with `ECONNREFUSED`
before tests ever reach their real assertions. The failures reproduce on
a clean branch off `main`, so this PR is focused only on hardening local
browser/session startup.
## What changed
- retries the full local `V3.init()` launch-and-connect path for
transient startup failures instead of failing immediately on the first
refused connection
- adds failure-only launch diagnostics so if the flake returns we
capture Chrome stdout/stderr plus devtools endpoint state
- limits the retry logic to local browser startup so Browserbase-backed
sessions are unaffected
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Hardens CI by retrying and verifying local Chromium startup to reduce
ECONNREFUSED flakes. Enables strict structured outputs across supported
AI SDK providers.
- **Bug Fixes**
- Retries local browser init once in CI on ECONNREFUSED/ECONNRESET and
CDP-connect errors; waits and cleans up between attempts.
- Installs stable Chrome via `browser-actions/setup-chrome` and runs a
preflight launch check before server-v3 integration and local E2E tests,
passing `CHROME_PATH` to the verifier.
- **New Features**
- Enables strict structured outputs: sets `strict: true` in
`OpenAIClient` `json_schema` and adds provider options for `openai`,
`azure`, `google`, `vertex`, `anthropic`, `groq`, `cerebras`, and
`mistral`.
- Adds unit tests for AI SDK provider options; publishes a patch to
`@browserbasehq/stagehand`.
<sup>Written for commit 134e98d3895b76f72fe0cd82132835f7bdf7b0da.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1973">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
## Summary
- Add `providerOptions` bag to model config schema for provider-specific
auth (Bedrock, Vertex, future providers) without polluting the shared
schema with vendor-specific fields
- Make `modelApiKey` optional so providers with non-API-key auth (e.g.
AWS SigV4) can work without it
- Server stores `modelClientOptions` from session start and reuses them
on subsequent act/observe/extract/execute calls — SDKs don't need to
reimplement this logic
- Send `modelClientOptions` (including `providerOptions`) in the session
start request body; server merges stored + per-request config
## What this enables
- **Bedrock**: pass `region`, `accessKeyId`, `secretAccessKey`,
`sessionToken` via `providerOptions`
- **Vertex**: pass `project`, `location`, `googleAuthOptions` via
`providerOptions`
- **Future providers**: any provider with non-standard auth just adds
fields to `providerOptions` — zero schema or server changes needed
## Architecture
```
SDK Server AI SDK
───────────────────────── ───────────────────────── ──────────────
modelClientOptions: { Stores in session, createAmazonBedrock({
apiKey?, merges on each request, apiKey,
providerOptions: { ──► passes to V3 constructor ──► region,
region, accessKeyId,
accessKeyId, Server is vendor-agnostic: secretAccessKey,
... just passes providerOptions ...
} through unchanged })
}
```
## Linked PRs
- core: https://github.com/browserbase/core/pull/8004
## Testing
<img width="694" height="945" alt="image"
src="https://github.com/user-attachments/assets/39dc4bd2-4008-4776-bcdb-cf3b5eefc726"
/>
<img width="748" height="641" alt="image"
src="https://github.com/user-attachments/assets/ab1c6bcf-322b-4e78-9a96-9dbc5045ba02"
/>
---------
Co-authored-by: Shrey Pandya <shrey@browserbase.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: ci-test <ci-test@example.com>
Co-authored-by: monadoid <sam.finton@gmail.com>
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>
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>
## 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>
## 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>
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>
## 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. -->
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>
## 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. -->
## 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>
# 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. -->
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>
## 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>
# 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. -->
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>
# 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. -->
## 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>
# 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. -->
## 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>