Prepare the next browse-cli release by versioning the package on `main`.
What this PR does:
- bumps `packages/cli/package.json` to `0.6.0`
- updates the browse-cli changelog
- consumes the pending browse-cli changesets
After this PR merges, the `Release` workflow on `main` will publish
`@browserbasehq/browse-cli@0.6.0` from that exact commit using `pnpm
pack` + `npm publish --provenance`.
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
# why
The docs-only changeset from PR #2017 created release metadata for a
docs workspace package that should not be published to npm.
# what changed
Reverted the generated docs package changelog and version bump while
keeping the actual MCP documentation updates intact.
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Removed accidental release metadata for the docs workspace so it isn’t
treated as a publishable package. Keeps the MCP docs from #2017 intact.
Aligns with Linear STG-1869.
- **Bug Fixes**
- Deleted `packages/docs/CHANGELOG.md`.
- Reset `@browserbasehq/stagehand-docs` version to 1.0.0.
<sup>Written for commit ff9c8eb5122903c20745ebf5237137ea8797499c.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/2057?utm_source=github">Review
in cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
## Summary
`browse cdp` enables the Page domain via `Page.enable`, but
`Page.enable` does not by itself emit `Page.lifecycleEvent` — that
requires a separate `Page.setLifecycleEventsEnabled` opt-in. As a
result, consumers of `browse cdp` today see only `Page.frameNavigated`
and miss the granular lifecycle milestones (`init`, `commit`,
`DOMContentLoaded`, `load`, `firstPaint`, `firstContentfulPaint`,
`firstMeaningfulPaint`, `networkAlmostIdle`, `networkIdle`).
This PR enables lifecycle events whenever the Page domain is enabled (so
it covers both the default-domain set and explicit `--domain Page`), and
adds a `--pretty` formatter case that prints the milestone name.
## Why
These events are exactly what observability/perf tools want from the
firehose:
- approximate page-ready timing (`DOMContentLoaded` / `load`)
- network-settled signal (`networkIdle`)
- paint timing (`firstPaint` / `firstContentfulPaint` /
`firstMeaningfulPaint`)
Without the opt-in, all of those have to be approximated from
`Page.frameNavigated` + `Network.loadingFinished`, which loses the
per-milestone resolution.
## Verification
Built locally with `pnpm exec tsx src/index.ts cdp 9333` against a
debuggable Chrome and triggered an `example.com` navigation. Before this
patch, no `Page.lifecycleEvent` lines. After:
```
[Page.lifecycleEvent] init
[Page.lifecycleEvent] commit
[Page.lifecycleEvent] DOMContentLoaded
[Page.lifecycleEvent] firstPaint
[Page.lifecycleEvent] firstContentfulPaint
[Page.lifecycleEvent] firstMeaningfulPaint
[Page.lifecycleEvent] load
[Page.lifecycleEvent] networkAlmostIdle
[Page.lifecycleEvent] networkIdle
```
Default mode (NDJSON) emits the same events with full params:
```json
{"sessionId":"…","method":"Page.lifecycleEvent","params":{"frameId":"…","loaderId":"…","name":"DOMContentLoaded","timestamp":468107.080156}}
```
## Test plan
- [ ] `pnpm --filter @browserbasehq/browse-cli typecheck` passes
- [ ] `pnpm --filter @browserbasehq/browse-cli eslint` passes
- [ ] `pnpm --filter @browserbasehq/browse-cli test` — no new failures
(pre-existing failures in `cli.test.ts` / `mode.test.ts` reproduce on
`main` and are unrelated to this change)
- [ ] Manual: `browse cdp <port>` against a debuggable Chrome shows
`Page.lifecycleEvent` lines after a navigation
- [ ] Manual: `browse cdp <port> --pretty` formats
`[Page.lifecycleEvent] <name>`
- [ ] Manual: `browse cdp <port> --domain Network --domain Console` (no
Page) emits no lifecycle events — the opt-in is gated correctly
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
## Summary
- move local CDP discovery into a dedicated module so the
DevToolsActivePort behavior is directly testable
- reuse the exact `DevToolsActivePort` websocket path for `browse env
local --auto-connect`
- reuse the same exact-path lookup for bare numeric CDP targets in
`resolveWsTarget`
- avoid the extra speculative websocket verification pass on the
file-backed discovery path
- add regression coverage for exact-path resolution, stale file cleanup,
ambiguity, and fallback port probing
## Root Cause
The CLI was reading `DevToolsActivePort` but then discarding the exact
websocket path and probing generic endpoints first. On Chrome's
remote-debugging approval flow that could trigger extra preflight
requests before the real attach.
## Validation
- `pnpm --filter @browserbasehq/stagehand gen-version`
- `pnpm --filter @browserbasehq/stagehand build-dom-scripts`
- `pnpm --filter @browserbasehq/stagehand build`
- `pnpm --filter @browserbasehq/browse-cli build`
- `pnpm --filter @browserbasehq/browse-cli typecheck`
- `pnpm --filter @browserbasehq/browse-cli test`
Linear:
https://linear.app/browserbase/issue/STG-1859/use-exact-devtoolsactiveport-websocket-path-for-browse-cli-auto
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Fixes local CDP auto-connect by using the exact websocket path from
DevToolsActivePort to avoid extra probes and speed up attach in Chrome’s
approval flow. Addresses Linear STG-1859 and improves
`@browserbasehq/browse-cli` for `browse env local --auto-connect` and
bare port targets.
- **Bug Fixes**
- Reuse the exact DevToolsActivePort websocket path for local
auto-connect.
- Prefer exact-path resolution for bare numeric ports in
`resolveWsTarget`, then fall back to `/json/version`, then
`/devtools/browser`.
- Skip speculative websocket verification when a file provides the exact
path.
- Clean up stale DevToolsActivePort files and return null on ambiguity.
- **Refactors**
- Extracted local CDP discovery to `local-cdp-discovery.ts` with tests
for exact-path resolution, stale cleanup, ambiguity, and fallback
probing.
<sup>Written for commit 440eee4c562a71775cf3e413d5e929a0881837de.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/2049">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
# why
The v3 MCP docs now need to describe the hosted server behavior where
`start` can attach to an existing Browserbase session via an optional
`sessionId`.
# what changed
- Updated the MCP setup and tools docs to document optional
`start.sessionId`.
- Clarified that omitting `sessionId` creates a new Browserbase session.
- Added a patch changeset for `@browserbasehq/stagehand-docs`.
# test plan
- `pnpm exec prettier --check
packages/docs/v3/integrations/mcp/setup.mdx
packages/docs/v3/integrations/mcp/tools.mdx`
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Added docs for optional `sessionId` on MCP `start` to attach to an
existing Browserbase session; omitting it creates a new session.
Addresses STG-1837 and publishes a patch to
`@browserbasehq/stagehand-docs`.
<sup>Written for commit edc7cbdef0ce712d369699589e1b24b426bffdd6.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/2017">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
# why
- file upload elements sometimes have a 'button' AX role
- this causes issues when users prompt `.observe()` to find "file upload
elements", since the model sees them as a 'button'
- addresses #972
# what changed
- this PR preserves the semantics of file upload elements by using the
actual DOM tag name and 'type'
- eg, instead of `[0-12] button: Choose File`, we now use `[0-12] input,
file: Choose File`
# test plan
- added a unit test for the replacement logic
- added an `observe()` eval which checks that hidden file upload
elements are correctly found by the LLM
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Make file upload inputs explicit in the page snapshot so `.observe()`
can reliably find them. Addresses Linear STG-934 by preventing file
inputs from being misclassified as buttons.
- **Bug Fixes**
- Enrich DOM tag names to include input type (e.g., `input, file`) and
use them in DOM maps.
- Force file inputs to appear as `input, file` in the a11y outline
instead of AX `button`.
- Add unit test and fix/register the `observe_file_uploads` eval in
`evals.config.json`.
- Publish patch for `@browserbasehq/stagehand`.
<sup>Written for commit 2fad86f408ebb3d990935575a839bcb3e67d0eca.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1975">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
# why
`z.boolean().default(false)` on line 448 is incompatible with OpenAI's
strict structured-output mode.
OpenAI's error:
> 'required' is required to be supplied and to be an array including
every key in properties. Missing 'twoStep'.
# what changed
# test plan
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Made `twoStep` a required boolean in the `act` schema (no default). This
removes the silent `false` default and forces callers to be explicit
about two-step actions.
- **Migration**
- Always pass `twoStep: true | false` when calling `act`.
- `tsconfig.json` change is formatting-only; no runtime impact.
<sup>Written for commit ca56e780634eacba7aab77ef1222bb4bcbf0a766.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/2029">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
# why
Structured output mode is deprecated
# what changed
removed usage of anthropic structured output mode
# test plan
Ran tests locally + CI tests
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Removed the deprecated `anthropic.structuredOutputMode` option from
AISdk provider options to align with Anthropic’s deprecation and avoid
sending unsupported flags. Updated unit tests and added a changeset;
behavior for other providers is unchanged.
<sup>Written for commit 64daca7b23c0d19e6281fffc7a1d30350477eabd.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/2028">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
# why
After adding regex schema validation for element ids in `act`, the
models were left with no choice to say 'no candidate found/no action to
be taken' since an empty string on element id would fail validation.
This PR corrects the regressed behavior
# what changed
`act()` no longer throws when the model can't find a target. Callers get
the structured `success: false` result, matching the behavior
`observe()` already has ([]) when nothing matches.
- `packages/core/lib/inference.ts` — wrap the act fields (elementId,
description, method, arguments, twoStep) under action: {...}.nullable().
When the model returns action: null, inference returns element:
undefined and the existing handler branch returns { success: false,
actions: [], message: "Failed to perform act: No action found" }.
- Lift `twoStep` out of the nullable action object and back to the top
level of the act schema — small models (gpt-4.1-nano) flatten booleans
out of anyOf variants during structured output, causing spurious
AI_NoObjectGeneratedError on otherwise-valid responses.
- `packages/core/lib/prompt.ts` — update buildActSystemPrompt,
buildActPrompt, and buildStepTwoPrompt to instruct the model to set
action: null when no element matches, with an explicit ban on empty
strings / placeholder values.
- `packages/core/lib/v3/handlers/actHandler.ts` — no logic change; the
existing no-action branch is now reachable.
Act will return the following on these cases:
<img width="586" height="343" alt="Screenshot 2026-04-22 at 1 19 33 PM"
src="https://github.com/user-attachments/assets/34efa7dd-7e80-4c6e-916f-de29d4e28083"
/>
# test plan
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Stops `act` from throwing when no element matches by making the response
`action` nullable and updating prompts/parsing to treat “no action” as
valid. Fixes the regression where empty element IDs failed validation.
Aligns with Linear STG-1849.
- **Bug Fixes**
- Changed `act` schema to `{ action: { elementId, description, method,
arguments } | null, twoStep: boolean }` with the element ID regex;
`twoStep` is top‑level and defaults to `false`.
- Updated prompts to set `action: null` when no element matches and to
not fabricate elements or use empty/placeholder values.
- Adjusted parsing to handle `action === null` and return `element:
undefined`, letting the existing no‑action path return `success: false`.
- Updated integration tests and test utils to use the new `action` shape
and top‑level `twoStep`.
<sup>Written for commit 1cb51fa47ffefe7b7b931eb011ca6c468aa0bf97.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/2027">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
---------
Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>
Mirrored from external contributor PR #1912 after approval by
@miguelg719.
Original author: @chromiebot
Original PR: https://github.com/browserbase/stagehand/pull/1912
Approved source head SHA: `0ea0332c525017c727743d11a68b8eb74f76b646`
@chromiebot, please continue any follow-up discussion on this mirrored
PR. When the external PR gets new commits, this same internal PR will be
marked stale until the latest external commit is approved and refreshed
here.
## Original description
# why
# what changed
# test plan
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Add adaptive thinking for Anthropic Claude 4.6 models in the `CUA`
client with effort controls and automatic `temperature=1`. Keeps legacy
`thinkingBudget` for older models and improves model detection and tool
versioning.
- **New Features**
- Detects 4.6 models (e.g., `claude-opus-4-6*`, `claude-sonnet-4-6*`,
incl. provider-prefixed) and sends `thinking: { type: "adaptive" }` with
`output_config.effort` (defaults to `"medium"`).
- Adds `ThinkingEffort` and `thinkingEffort` in `ClientOptions` (`"none"
| "low" | "medium" | "high" | "max"`); `"none"` disables adaptive
thinking.
- Forces `temperature: 1` with adaptive thinking and logs when
overriding a user value; logs when `thinkingBudget` is provided on 4.6
models.
- Uses `computer_20251124` for 4.6 and `claude-opus-4-5-20251101`; older
models continue with `thinking: { type: "enabled", budget_tokens }`.
- **Migration**
- For 4.6 models, set `thinkingEffort`; `thinkingBudget` is ignored.
- Adaptive thinking forces `temperature: 1`; set `thinkingEffort:
"none"` to disable.
<sup>Written for commit ebe95e77418c755ecc4b3d03235cb3d3cb2e03cc.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1954">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
<!-- external-contributor-pr:owned source-pr=1912
source-sha=0ea0332c525017c727743d11a68b8eb74f76b646 claimer=miguelg719
-->
---------
Co-authored-by: Chromie Bot <chromie@browserbase.com>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Co-authored-by: miguel <miguelg71921@gmail.com>
Mirrored from external contributor PR #2010 after approval by @pirate.
Original author: @octo-patch
Original PR: https://github.com/browserbase/stagehand/pull/2010
Approved source head SHA: `fd9ed12d2499c022b45ba30703c75082dc743a78`
@octo-patch, please continue any follow-up discussion on this mirrored
PR. When the external PR gets new commits, this same internal PR will be
marked stale until the latest external commit is approved and refreshed
here.
## Original description
Fixes#1287
## Problem
On slow machines, Chrome may still be setting up the first tab by the
time
the CDP WebSocket handshake completes. `V3Context.create()` previously
waited a fixed 5 seconds (`DEFAULT_FIRST_TOP_LEVEL_PAGE_TIMEOUT_MS`) for
the first top-level page to register, regardless of any user-supplied
timeout, causing a `TimeoutError: waitForFirstTopLevelPage (no top-level
Page) timed out after 5000ms` on slow hardware.
## Solution
Take the *maximum* of `localBrowserLaunchOptions.connectTimeoutMs` and
the
existing env-var / CI-derived default. This means users who already bump
`connectTimeoutMs` to accommodate a slow environment automatically get
the
same patience when waiting for the initial page—no new API surface
needed.
```ts
// Before
await ctx.ensureFirstTopLevelPage(getFirstTopLevelPageTimeoutMs());
// After
const firstPageTimeoutMs = Math.max(
opts?.localBrowserLaunchOptions?.connectTimeoutMs ?? 0,
getFirstTopLevelPageTimeoutMs(),
);
await ctx.ensureFirstTopLevelPage(firstPageTimeoutMs);
```
Existing escape hatches (`STAGEHAND_FIRST_TOP_LEVEL_PAGE_TIMEOUT_MS` env
var, `CI` auto-bump to 30 s) are unchanged—this change only applies a
floor when the user has explicitly set a higher `connectTimeoutMs`.
## Testing
- Existing unit and integration tests continue to pass (no change to
default behaviour).
- Users on slow machines / WSL2 can now set `connectTimeoutMs: 30000` in
`localBrowserLaunchOptions` and the first-page wait will scale with it.
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Respect `connectTimeoutMs` when waiting for the first top‑level page to
avoid startup timeouts on slow machines. Fixes#1287.
- **Bug Fixes**
- `V3Context.create()` now waits up to
`max(localBrowserLaunchOptions.connectTimeoutMs,
getFirstTopLevelPageTimeoutMs())` for the first page.
- Keeps `STAGEHAND_FIRST_TOP_LEVEL_PAGE_TIMEOUT_MS` and CI defaults
unchanged; no API changes.
<sup>Written for commit 0998c755700d9ea9f4671c8543fa375a8d789feb.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/2025">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
<!-- external-contributor-pr:owned source-pr=2010
source-sha=fd9ed12d2499c022b45ba30703c75082dc743a78 claimer=pirate -->
---------
Co-authored-by: octo-patch <octo-patch@users.noreply.github.com>
Co-authored-by: Nick Sweeting <git@sweeting.me>
# why
# what changed
# test plan
---------
Co-authored-by: Filip Michalsky <filip-michalsky@users.noreply.github.com>
Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>
Mirrored from external contributor PR #2019 after approval by @pirate.
Original author: @BABTUNA
Original PR: https://github.com/browserbase/stagehand/pull/2019
Approved source head SHA: `54b258b01fa9e29ea5e044f50c7dbe159364690b`
@BABTUNA, please continue any follow-up discussion on this mirrored PR.
When the external PR gets new commits, this same internal PR will be
marked stale until the latest external commit is approved and refreshed
here.
## Original description
Title
fix(core): add FlowLogger parity for Microsoft CUA
Description
# why
`MicrosoftCUAClient` was the only CUA provider not emitting FlowLogger
LLM
request/response events.
OpenAI, Google, and Anthropic clients already emit these events, so
Microsoft CUA lacked observability parity.
# what changed
- Added FlowLogger imports and request/response logging to
`MicrosoftCUAClient`:
- `FlowLogger.logLlmRequest(...)` before the model call
- `FlowLogger.logLlmResponse(...)` after a successful response
- Added request ID correlation via `uuidv7` so request/response pair
correctly in logs.
- Kept existing execution behavior unchanged (logging-only change).
- Added unit tests for Microsoft CUA logging behavior:
- emits request + response on success
- emits only request when the model call fails
# test plan
- `prettier --check` on touched files
- `eslint` on touched files
- `tsc -p packages/core/tsconfig.json --noEmit`
- Added unit test file:
- `packages/core/tests/unit/microsoft-cua-client.test.ts`
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Add LLM request/response logging to `MicrosoftCUAClient` to match other
providers and improve observability. This brings Microsoft CUA to parity
with OpenAI, Google, and Anthropic clients.
- **Bug Fixes**
- Emit `FlowLogger.logLlmRequest` before the model call and
`FlowLogger.logLlmResponse` after success.
- Correlate events with a `requestId` using `uuid` v7.
- No behavior changes to execution; logging-only.
- Added unit tests for success (request + response) and failure (request
only).
<sup>Written for commit 221e83a7b56b115504c09d3154dcc9690fe0cee8.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/2023">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
<!-- external-contributor-pr:owned source-pr=2019
source-sha=54b258b01fa9e29ea5e044f50c7dbe159364690b claimer=pirate -->
---------
Co-authored-by: Benjamin Barrera-Altuna <benbarrera13@gmail.com>
Co-authored-by: Nick Sweeting <git@sweeting.me>
# why
# what changed
# test plan
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Updated the default Gemini eval model to `google/gemini-2.5-flash` and
updated CI `EVAL_MODELS` to use it, so evals run against the latest
flash model both by default and in CI.
<sup>Written for commit 87f421eea7d9e5160e9b3c97ce2b95ecf945eb34.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/2024">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
# why
Currently, if a cdp url is set, but browser.type is not set to local a
session is created on api
# what changed
We now warn people that they need to set the browser.type to local to
properly use their own custom cdp url
# test plan
tested locally with http requests + from go client + added tests
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Return 400 on POST /v1/sessions/start when `browser.cdpUrl` is provided
but `browser.type` is not "local", preventing unintended session
creation and guiding correct local CDP usage.
- **Bug Fixes**
- Reject requests with `cdpUrl` when `browser.type` is missing or not
"local"; respond 400 with a clear message to set `browser.type` to
"local".
- Keep local validation: when `browser.type` is "local", require
`cdpUrl` or `launchOptions`.
- Add integration tests for missing type and `type="browserbase"` with
`cdpUrl`.
<sup>Written for commit 58a6c551387d168ceb0f5273e4bb95965771eead.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1744">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
# why
# what changed
# test plan
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Unifies the build for browser-injected DOM scripts by replacing four
generators with a single builder. Simplifies the pipeline and removes
redundant file copying, with no runtime changes expected.
- **Refactors**
- Added `scripts/build-dom-scripts.ts` to build all DOM-injected assets:
IIFE strings for `piercer.entry.ts` and
`rerenderMissingShadows.entry.ts`; bootstrap + per-function sources for
`locator` (`__stagehandLocatorScripts`) and `a11y`
(`__stagehandA11yScripts`); sources-only for `screenshot` scripts.
- Removed `genDomScripts.ts`, `genLocatorScripts.ts`,
`genScreenshotScripts.ts`, `genA11yScripts.ts`.
- Updated `packages/core/package.json` to a single `build-dom-scripts`
command and simplified `turbo.json` to one task with
`lib/v3/dom/build/**` outputs.
- Removed JS copy steps from `scripts/build-cjs.ts` and
`scripts/build-esm.ts`; generated TS emits compile with the rest of the
package.
- Updated `tsconfig.json` to include generated files (removed old
`gen*.ts` exclude).
- **Migration**
- Use `pnpm run build-dom-scripts`; the old `build-dom-scripts:*`
scripts are removed.
<sup>Written for commit ac3839794447064bb865a0b6070decb2f2518169.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1988">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
Mirrored from external contributor PR #1978 after approval by @pirate.
Original author: @a7med3liamin
Original PR: https://github.com/browserbase/stagehand/pull/1978
Approved source head SHA: `2149aa265a04dc37154d5a84411f3ab4d1045897`
@a7med3liamin, please continue any follow-up discussion on this mirrored
PR. When the external PR gets new commits, this same internal PR will be
marked stale until the latest external commit is approved and refreshed
here.
## Original description
- [x] Check the [documentation](https://docs.stagehand.dev/) for
relevant information
- [x] Search existing
[issues](https://github.com/browserbase/stagehand/issues) to avoid
duplicates
Fixes#1776
## Problem
The `keys` tool has no variable substitution in either the live
execution or cache replay paths. When the agent uses `%variableName%`
tokens with the keys tool, the literal token string gets typed instead
of the resolved value.
## Fix
This PR combines two fixes into one:
### 1. Live execution (original fix by @trillville from #1777)
- Accept `variables` parameter in `keysTool` (matching `typeTool`)
- Call `substituteVariables()` before `page.type()` in the `method ===
"type"` branch
- Pass `variables` to `keysTool` in `createAgentTools`
- Update schema description to advertise available variables to the LLM
- Return original token in result to avoid exposing sensitive values to
LLM
### 2. Cache replay (new fix)
- Import `substituteVariables` in `AgentCache.ts`
- Pass `variables` through to `replayAgentKeysStep`
- Call `substituteVariables(text, variables)` before `page.type()` in
the replay path
Without fix#2, cached `keys` steps with `method="type"` replay by
typing literal `%variableName%` tokens even when variables are provided,
since `replayAgentKeysStep` had no access to the variables map.
## Credit
The live execution fix (part 1) is from @trillville's work in
#1777/#1813. We merged it here with the cache replay fix per @pirate's
request to consolidate into a single PR.
<!-- external-contributor-pr:owned source-pr=1978
source-sha=2149aa265a04dc37154d5a84411f3ab4d1045897 claimer=pirate -->
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Add variable substitution to the `keys` tool for both live execution and
cache replay so `%variableName%` tokens are resolved before typing. This
fixes cases where literal tokens were typed and brings parity with the
`type` tool.
- **Bug Fixes**
- Pass `variables` into `keys` and call `substituteVariables()` before
`page.type()`; update the input schema to list available variables.
- In cache replay, forward `variables` to `replayAgentKeysStep` and
substitute before typing to avoid replaying literal tokens.
- Record and return the original tokenized value (not the resolved
value) to avoid leaking sensitive data.
<sup>Written for commit abb3905cd9563609b01e78bf190a21a5998b9bb4.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1983">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
---------
Co-authored-by: Ahmed Ali <a7med3liamin@gmail.com>
Co-authored-by: trillville <trillville@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: Nick Sweeting <git@sweeting.me>
## Summary
- Reverts PR #1822 which added `providerOptions` for extensible model
auth (Bedrock/Vertex)
- Removes `providerOptions` bag from model config schema, Bedrock
examples, provider config, and server-side `modelClientOptions`
storage/passthrough
## Note
- One test from PR #1980 (`accepts verified Browserbase session
settings` in `model-config-schema.test.ts`) was removed as part of this
revert since the test file was originally created by #1822. That test
may need to be re-added in a separate file.
Made with [Cursor](https://cursor.com)
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Reverts the `providerOptions`-based model auth from #1822 (STG-1573) and
restores the previous auth flow: no provider options passthrough; model
auth is via the `x-model-api-key` header.
- **Refactors**
- Removed `providerOptions` and server-side `modelClientOptions`
passthrough from core and server.
- Deleted Bedrock examples and provider config; pruned related schemas
and tests.
- Simplified OpenAPI: removed ProviderOptions/ModelClientOptions
components and helpers extracting model config from request bodies.
- **Migration**
- Remove `providerOptions` from all model configs and requests.
- Do not send `modelClientOptions` in session start; the server ignores
it.
- Send model API keys via the `x-model-api-key` header; remove any
`skipApiKeyFallback` usage.
- If you adopted `vertex/*` names from #1822, switch to `google/*`.
<sup>Written for commit 1a3bbcb39c9831d4b0fa0e754fe57a255c392ab8.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1987">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
## Summary
- bump `@browserbasehq/sdk` to `^2.10.0` in `packages/core`,
`packages/server-v3`, and `packages/server-v4`
- add Browserbase `verified`, `os`, and custom captcha session settings
to the Stagehand Browserbase session-create schema and generated OpenAPI
specs
- keep legacy `advancedStealth` behavior working by treating it as a
compatibility alias for the new verified-mode checks in Stagehand
internals
## Testing
- `pnpm --filter @browserbasehq/stagehand build:esm`
- `pnpm --filter @browserbasehq/stagehand test:core --
packages/core/dist/esm/tests/unit/browserbase-session-accessors.test.js
packages/core/dist/esm/tests/unit/model-config-schema.test.js`
- `pnpm --filter @browserbasehq/stagehand typecheck`
- `pnpm --filter @browserbasehq/stagehand-server-v3 typecheck`
- `pnpm --filter @browserbasehq/stagehand-server-v4 typecheck`
- Browserbase-backed smoke test creating a real Stagehand session with
`browserSettings.verified: true`
Linear:
https://linear.app/browserbase/issue/STG-1798/support-browserbase-verified-session-settings
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Adds support for Browserbase Verified sessions with new session settings
across Stagehand APIs and a fixed Google CUA viewport when Verified,
addressing Linear STG-1798. Deprecates the `isAdvancedStealth` alias in
favor of `v3.isVerified`, and fixes abort-signal handling to fail fast
on already-aborted signals.
- New Features
- Add `verified`, `os`, `captchaImageSelector`, and
`captchaInputSelector` to Browserbase browser settings and generated
OpenAPI (v3 and v4).
- Introduce `v3.isVerified`; keep `isAdvancedStealth` as a deprecated,
backward-compatible alias.
- Use a 1288x711 viewport for Google CUA when Verified; otherwise use
the configured viewport.
- Dependencies
- Bump `@browserbasehq/sdk` to `^2.10.0` in `packages/core`,
`packages/server-v3`, and `packages/server-v4`.
<sup>Written for commit c2bde3337fbbb9b8143dc6ce2d0a6203282d8055.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1980">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
# why
# what changed
# test plan
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Bumped `drizzle-orm` to `1.0.0-beta.20` to patch a security
vulnerability in `server-v4`. Addresses Linear STG-1801.
<sup>Written for commit 76ec8a0ea3ec184425b3d34823cae69e35df3864.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1981">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
## Why
Local Chromium startup in CI intermittently fails with `ECONNREFUSED`
before tests ever reach their real assertions. The failures reproduce on
a clean branch off `main`, so this PR is focused only on hardening local
browser/session startup.
## What changed
- retries the full local `V3.init()` launch-and-connect path for
transient startup failures instead of failing immediately on the first
refused connection
- adds failure-only launch diagnostics so if the flake returns we
capture Chrome stdout/stderr plus devtools endpoint state
- limits the retry logic to local browser startup so Browserbase-backed
sessions are unaffected
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Hardens CI by retrying and verifying local Chromium startup to reduce
ECONNREFUSED flakes. Enables strict structured outputs across supported
AI SDK providers.
- **Bug Fixes**
- Retries local browser init once in CI on ECONNREFUSED/ECONNRESET and
CDP-connect errors; waits and cleans up between attempts.
- Installs stable Chrome via `browser-actions/setup-chrome` and runs a
preflight launch check before server-v3 integration and local E2E tests,
passing `CHROME_PATH` to the verifier.
- **New Features**
- Enables strict structured outputs: sets `strict: true` in
`OpenAIClient` `json_schema` and adds provider options for `openai`,
`azure`, `google`, `vertex`, `anthropic`, `groq`, `cerebras`, and
`mistral`.
- Adds unit tests for AI SDK provider options; publishes a patch to
`@browserbasehq/stagehand`.
<sup>Written for commit 134e98d3895b76f72fe0cd82132835f7bdf7b0da.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1973">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
## Summary
- Add `providerOptions` bag to model config schema for provider-specific
auth (Bedrock, Vertex, future providers) without polluting the shared
schema with vendor-specific fields
- Make `modelApiKey` optional so providers with non-API-key auth (e.g.
AWS SigV4) can work without it
- Server stores `modelClientOptions` from session start and reuses them
on subsequent act/observe/extract/execute calls — SDKs don't need to
reimplement this logic
- Send `modelClientOptions` (including `providerOptions`) in the session
start request body; server merges stored + per-request config
## What this enables
- **Bedrock**: pass `region`, `accessKeyId`, `secretAccessKey`,
`sessionToken` via `providerOptions`
- **Vertex**: pass `project`, `location`, `googleAuthOptions` via
`providerOptions`
- **Future providers**: any provider with non-standard auth just adds
fields to `providerOptions` — zero schema or server changes needed
## Architecture
```
SDK Server AI SDK
───────────────────────── ───────────────────────── ──────────────
modelClientOptions: { Stores in session, createAmazonBedrock({
apiKey?, merges on each request, apiKey,
providerOptions: { ──► passes to V3 constructor ──► region,
region, accessKeyId,
accessKeyId, Server is vendor-agnostic: secretAccessKey,
... just passes providerOptions ...
} through unchanged })
}
```
## Linked PRs
- core: https://github.com/browserbase/core/pull/8004
## Testing
<img width="694" height="945" alt="image"
src="https://github.com/user-attachments/assets/39dc4bd2-4008-4776-bcdb-cf3b5eefc726"
/>
<img width="748" height="641" alt="image"
src="https://github.com/user-attachments/assets/ab1c6bcf-322b-4e78-9a96-9dbc5045ba02"
/>
---------
Co-authored-by: Shrey Pandya <shrey@browserbase.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: ci-test <ci-test@example.com>
Co-authored-by: monadoid <sam.finton@gmail.com>
# why
- docs for `page.keyPress()` were missing
# what changed
<img width="730" height="727" alt="Screenshot 2026-04-07 at 1 41 38 PM"
src="https://github.com/user-attachments/assets/1bf50de3-93b6-4fca-b632-cdb80bcfc3da"
/>
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Added docs for `page.keyPress()` in the v3 Page reference. Includes the
method signature, supported keys and modifier combos, the `delay`
option, and examples for single keys and combinations (Enter, Cmd+A,
ArrowDown, Ctrl+C, with delay).
<sup>Written for commit 0cbf3a9c6d34eef6da0cd3ad53b2e49dd88a39c8.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1974">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
<!-- This is an auto-generated description by cubic. -->
## Summary by cubic
Switched badge SVGs to green `#00C851` for Discord and License (light
and dark) and set their links to `display: inline-block` in
`packages/core/README.md` to keep badges aligned. Branding/readme-only;
no app code changes.
<sup>Written for commit 698eb0fcfd947d3efb1407935faa673dd474827a.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1971">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
## Summary
- Replace the Stagehand light mode logo with the colored version (green
icon instead of all-black)
- Replace the Director icon with the new colored logomark (blue
geometric design)
- Updates both `packages/docs/logo/` and `media/` copies to stay in sync
## Test plan
- [ ] Verify the docs site shows the green Stagehand logo in light mode
- [ ] Verify the Director icon renders correctly where referenced
🤖 Generated with [Claude Code](https://claude.com/claude-code)
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Replaced the Stagehand light-mode logo with its green-colored version
and updated the Director icon to the new blue logomark. Synced assets in
`media/` and `packages/docs/logo/` to keep the docs and site consistent.
<sup>Written for commit 4c151ecad3e24fabf19471eb68589e2096174842.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1970">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
## Summary
- Replace old yellow hand icon logos with new "S" logomark across all
locations (README, docs site logos, SVGs)
- Update favicon from old yellow hand to new green "S" logomark
- 10 files updated; no markdown changes needed since filenames were
preserved
## Test plan
- [ ] Verify README logo renders correctly on GitHub (light and dark
mode)
- [ ] Verify docs site logo renders at stagehand.dev
- [ ] Verify favicon appears correctly in browser tab
🤖 Generated with [Claude Code](https://claude.com/claude-code)
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Updated Stagehand branding across docs and assets: replaced the yellow
hand with the green “S” logomark, refreshed dark/light wordmark SVGs,
updated favicons, and set the docs accent color to `#00C851`. Filenames
are unchanged; `packages/docs/logo/light.svg` now uses the new wordmark,
and the docs name is set to “Stagehand”.
- **Migration**
- Verify README logos (light/dark) render on GitHub.
- Verify docs header logos (light/dark) and `/favicon.svg` on
stagehand.dev.
- Confirm docs UI accents use `#00C851`.
- Hard refresh or clear cache to see the new favicon and styles.
<sup>Written for commit 8ebc28c8c68b44aa0b8e11579856533e5894447a.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1967">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.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>
Mirrored from external contributor PR #1959 after approval by
@miguelg719.
Original author: @chromiebot
Original PR: https://github.com/browserbase/stagehand/pull/1959
Approved source head SHA: `f55ff5558f2454e9f266b7f29ef0b511bd891b9e`
@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
When using Browserbase, apiKey is now optional for
openai/google/anthropic providers. Replace model object `{ modelName,
apiKey }` with simple string format `"provider/model"` to reduce
friction in docs examples.
Updated files:
- best-practices/caching.mdx (1 instance)
- best-practices/deployments.mdx (1 instance)
- best-practices/deterministic-agent.mdx (4 instances)
# why
# what changed
# test plan
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Switch Browserbase docs snippets to use a single `provider/model` string
for model config, replacing the `{ modelName, apiKey }` object and
omitting `apiKey` where it’s optional for OpenAI, Google, and Anthropic.
Updated examples across Basics (`act`, `agent`) and Best Practices
(`caching`, `deployments`, `deterministic-agent`), including refreshed
Google model IDs like `google/gemini-3-flash-preview` and
`google/gemini-2.5-flash`.
<sup>Written for commit 7dc7863f2f5e89bb87b7b93ea9a5b819d4ada62b.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1961">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
<!-- external-contributor-pr:owned source-pr=1959
source-sha=f55ff5558f2454e9f266b7f29ef0b511bd891b9e claimer=miguelg719
-->
---------
Co-authored-by: Chromie Bot <chromie@browserbase.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: Chromie <miguel@browserbase.com>
Co-authored-by: Miguel <36487034+miguelg719@users.noreply.github.com>
# why
# what changed
# test plan
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Adds a new Model Gateway section to the v3 Models docs so users can run
`@browserbasehq/stagehand` with only a Browserbase API key. Includes
setup, provider switching, a note about Browserbase-hosted browsers,
benefits, and API key updates.
- **New Features**
- Added “Model Gateway” docs with setup using `env: "BROWSERBASE"` and
model examples (`openai/gpt-5`, `anthropic/claude-sonnet-4-6`,
`google/gemini-3-flash-preview`); requires Browserbase-hosted browsers
(not `env: "LOCAL"`).
- Included tabs to switch providers without extra keys.
- Listed key benefits (one key/bill, market pricing, reliability, no
tier gates, action caching) and added a supported providers table.
- Updated API keys table to include `BROWSERBASE_API_KEY`, added a
top-page callout linking to the blog, and fixed a model link in the doc.
<sup>Written for commit e54e7a9e625be46d84bad2d05d8fbcab6db4ca84.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1957">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
## Summary
- Remove all `BROWSERBASE_PROJECT_ID` / `projectId` references from v3
docs, SDK docs, integration guides, migration guides, and CLI README (30
files)
- Only `BROWSERBASE_API_KEY` is required — `projectId` is optional in
all code control paths (conditionally included via spread patterns,
never validated as required)
- Preserves unrelated GCP project ID references in `models.mdx`
## Test plan
- [ ] Verify docs site builds without errors
- [ ] Spot-check code examples still make sense without projectId
- [ ] Confirm no broken references or formatting issues
🤖 Generated with [Claude Code](https://claude.com/claude-code)
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Removed all `BROWSERBASE_PROJECT_ID`/`projectId` references across v3
docs so setup only requires `BROWSERBASE_API_KEY`. Also updated
Anthropic model references to `anthropic/claude-sonnet-4-6` across
examples and guides.
- **Migration**
- Remove `BROWSERBASE_PROJECT_ID` from env files, deployment configs,
session params, and env var lists; keep `BROWSERBASE_API_KEY` only.
- Existing code passing `projectId` still works; it’s optional and not
required.
- Unrelated GCP project ID mentions remain unchanged.
- **Refactors**
- Replaced all `anthropic/claude-sonnet-4-20250514` references with
`anthropic/claude-sonnet-4-6` across v3 docs (agent examples, warnings,
best practices).
- Simplified MCP config by removing the `CardGroup` wrapper around a
single card.
<sup>Written for commit 7a1688d2cf03f68e4a14e43259c4edcd205a164a.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1958">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
## Summary
- Renamed `@browserbasehq/mcp-server-browserbase` to
`@browserbasehq/mcp` in v2 and v3 MCP docs (setup and configuration
pages)
## Linear
[STG-1769](https://linear.app/browserbase/issue/STG-1769/rename-mcp-package-in-docs)
## Test plan
- [ ] Verify v2 docs render correctly with new package name
- [ ] Verify v3 docs render correctly with new package name
🤖 Generated with [Claude Code](https://claude.com/claude-code)
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Renamed the MCP package in v2 and v3 docs from
`@browserbasehq/mcp-server-browserbase` to `@browserbasehq/mcp`,
updating setup and configuration examples and CLI notes. Also removed an
unnecessary changeset since this is docs-only, aligning with STG-1769.
<sup>Written for commit 501df497ea10e3bdfe17227535d0e61717155355.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1952">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
# why
Stainless generated clients had custom code changes that shouldn't have
been custom code, they should've bene updated in the api spec. This
fixes the root cause by replacing those, and then I'll have a follow-up
PR for the python sdk to remove those custom code changes.
# what changed
# test plan
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Updated v3 API examples to use OpenAI `openai/gpt-5.4-mini`, replacing
previous defaults across the OpenAPI spec, core types, and
`stainless.yml`. This aligns examples with our base URL and API key docs
and avoids custom patches in Stainless-generated clients; no behavior
changes.
<sup>Written for commit b6d9710116af97dda9829db61df8dc3fac35da40.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1951">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
## 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>
Mirrored from external contributor PR #1844 after approval by
@miguelg719.
Original author: @praveentcom
Original PR: https://github.com/browserbase/stagehand/pull/1844
Approved source head SHA: `a637dc329bfc5426bb71c8551c812191ed631527`
@praveentcom, 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
All GPT-5.x series models don't support `minimal` as the
`reasoningEffort`. Currently, it is enabled only for GPT-5.1 and GPT-5.2
models to set the reasoningEffort as `low`. This would start throwing
errors like these.
`Unsupported value: 'minimal' is not supported with the 'gpt-5.4' model.
Supported values are: 'none', 'low', 'medium', 'high', and 'xhigh'.`
This PR fixes the behavior to set the reasoning effort as low for all
GPT-5.x series models so that we don't need to manually patch it every
time when a new SOTA model is released.
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Default `reasoningEffort` to "none" for all `gpt-5.*` models (excluding
`codex`) to avoid unsupported "minimal" errors, with an override via
`ClientOptions.reasoningEffort`, and default GPT-5 `textVerbosity` set
to "low".
Also plumbs `clientOptions` into both `AISdkClient` and
`AISdkClientWrapped` and applies the same reasoning/text-verbosity
behavior (`codex` stays "medium").
<sup>Written for commit a9797cca806822a8c388fac44753602d3a0fb60b.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1852">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
<!-- external-contributor-pr:owned source-pr=1844
source-sha=a637dc329bfc5426bb71c8551c812191ed631527 claimer=miguelg719
-->
---------
Co-authored-by: Praveen Thirumurugan <mail@praveent.com>
Co-authored-by: miguel <miguelg71921@gmail.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>