477 Commits

Author SHA1 Message Date
github-actions[bot]
98cdd20cc5
Release @browserbasehq/browse-cli@0.6.0 (#1948)
Prepare the next browse-cli release by versioning the package on `main`.

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

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

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
2026-04-27 15:16:50 -07:00
Derek
e87f167d68
feat(cli): emit Page.lifecycleEvent in browse cdp (#2056)
## Summary

`browse cdp` enables the Page domain via `Page.enable`, but
`Page.enable` does not by itself emit `Page.lifecycleEvent` — that
requires a separate `Page.setLifecycleEventsEnabled` opt-in. As a
result, consumers of `browse cdp` today see only `Page.frameNavigated`
and miss the granular lifecycle milestones (`init`, `commit`,
`DOMContentLoaded`, `load`, `firstPaint`, `firstContentfulPaint`,
`firstMeaningfulPaint`, `networkAlmostIdle`, `networkIdle`).

This PR enables lifecycle events whenever the Page domain is enabled (so
it covers both the default-domain set and explicit `--domain Page`), and
adds a `--pretty` formatter case that prints the milestone name.

## Why

These events are exactly what observability/perf tools want from the
firehose:

- approximate page-ready timing (`DOMContentLoaded` / `load`)
- network-settled signal (`networkIdle`)
- paint timing (`firstPaint` / `firstContentfulPaint` /
`firstMeaningfulPaint`)

Without the opt-in, all of those have to be approximated from
`Page.frameNavigated` + `Network.loadingFinished`, which loses the
per-milestone resolution.

## Verification

Built locally with `pnpm exec tsx src/index.ts cdp 9333` against a
debuggable Chrome and triggered an `example.com` navigation. Before this
patch, no `Page.lifecycleEvent` lines. After:

```
[Page.lifecycleEvent] init
[Page.lifecycleEvent] commit
[Page.lifecycleEvent] DOMContentLoaded
[Page.lifecycleEvent] firstPaint
[Page.lifecycleEvent] firstContentfulPaint
[Page.lifecycleEvent] firstMeaningfulPaint
[Page.lifecycleEvent] load
[Page.lifecycleEvent] networkAlmostIdle
[Page.lifecycleEvent] networkIdle
```

Default mode (NDJSON) emits the same events with full params:

```json
{"sessionId":"…","method":"Page.lifecycleEvent","params":{"frameId":"…","loaderId":"…","name":"DOMContentLoaded","timestamp":468107.080156}}
```

## Test plan

- [ ] `pnpm --filter @browserbasehq/browse-cli typecheck` passes
- [ ] `pnpm --filter @browserbasehq/browse-cli eslint` passes
- [ ] `pnpm --filter @browserbasehq/browse-cli test` — no new failures
(pre-existing failures in `cli.test.ts` / `mode.test.ts` reproduce on
`main` and are unrelated to this change)
- [ ] Manual: `browse cdp <port>` against a debuggable Chrome shows
`Page.lifecycleEvent` lines after a navigation
- [ ] Manual: `browse cdp <port> --pretty` formats
`[Page.lifecycleEvent] <name>`
- [ ] Manual: `browse cdp <port> --domain Network --domain Console` (no
Page) emits no lifecycle events — the opt-in is gated correctly

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

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-27 11:24:40 -07:00
Shrey Pandya
ed4db535c3
[STG-1859] fix(cli): use exact DevToolsActivePort websocket path (#2049)
## Summary

- move local CDP discovery into a dedicated module so the
DevToolsActivePort behavior is directly testable
- reuse the exact `DevToolsActivePort` websocket path for `browse env
local --auto-connect`
- reuse the same exact-path lookup for bare numeric CDP targets in
`resolveWsTarget`
- avoid the extra speculative websocket verification pass on the
file-backed discovery path
- add regression coverage for exact-path resolution, stale file cleanup,
ambiguity, and fallback port probing

## Root Cause

The CLI was reading `DevToolsActivePort` but then discarding the exact
websocket path and probing generic endpoints first. On Chrome's
remote-debugging approval flow that could trigger extra preflight
requests before the real attach.

## Validation

- `pnpm --filter @browserbasehq/stagehand gen-version`
- `pnpm --filter @browserbasehq/stagehand build-dom-scripts`
- `pnpm --filter @browserbasehq/stagehand build`
- `pnpm --filter @browserbasehq/browse-cli build`
- `pnpm --filter @browserbasehq/browse-cli typecheck`
- `pnpm --filter @browserbasehq/browse-cli test`

Linear:
https://linear.app/browserbase/issue/STG-1859/use-exact-devtoolsactiveport-websocket-path-for-browse-cli-auto

<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Fixes local CDP auto-connect by using the exact websocket path from
DevToolsActivePort to avoid extra probes and speed up attach in Chrome’s
approval flow. Addresses Linear STG-1859 and improves
`@browserbasehq/browse-cli` for `browse env local --auto-connect` and
bare port targets.

- **Bug Fixes**
- Reuse the exact DevToolsActivePort websocket path for local
auto-connect.
- Prefer exact-path resolution for bare numeric ports in
`resolveWsTarget`, then fall back to `/json/version`, then
`/devtools/browser`.
- Skip speculative websocket verification when a file provides the exact
path.
- Clean up stale DevToolsActivePort files and return null on ambiguity.

- **Refactors**
- Extracted local CDP discovery to `local-cdp-discovery.ts` with tests
for exact-path resolution, stale cleanup, ambiguity, and fallback
probing.

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

<!-- End of auto-generated description by cubic. -->
2026-04-27 09:08:34 -07:00
github-actions[bot]
04765c11ef
Version Packages (#1979)
This PR was opened by the [Changesets
release](https://github.com/changesets/action) GitHub action. When
you're ready to do a release, you can merge this and the packages will
be published to npm automatically. If you're not ready to do a release
yet, that's fine, whenever you add more changesets to main, this PR will
be updated.


# Releases
## @browserbasehq/stagehand@3.3.0

### Minor Changes

- [#1980](https://github.com/browserbase/stagehand/pull/1980)
[`e471d2e`](e471d2e89d)
Thanks [@shrey150](https://github.com/shrey150)! - Support Browserbase
verified session settings and bump the Browserbase SDK.

### Patch Changes

- [#1954](https://github.com/browserbase/stagehand/pull/1954)
[`732b384`](732b3840f1)
Thanks [@github-actions](https://github.com/apps/github-actions)! -
Update Anthropic CUA to use adaptive thinking

- [#2001](https://github.com/browserbase/stagehand/pull/2001)
[`20b601d`](20b601dc87)
Thanks [@shrey150](https://github.com/shrey150)! - Include
`agent.execute()` usage in `stagehand.metrics` for API-backed sessions.

- [#1983](https://github.com/browserbase/stagehand/pull/1983)
[`8543c11`](8543c11f6b)
Thanks [@github-actions](https://github.com/apps/github-actions)! - Add
variable substitution to the keys tool in both live execution and cache
replay paths. When keys steps with `method="type"` contain
`%variableName%` tokens, they are now resolved against the provided
variables. This brings the keys tool to parity with the type tool's
variable handling.

- [#1973](https://github.com/browserbase/stagehand/pull/1973)
[`14b64ec`](14b64ec7d2)
Thanks [@monadoid](https://github.com/monadoid)! - Enable strict
structured outputs for supported model paths.

- [#2028](https://github.com/browserbase/stagehand/pull/2028)
[`a500de1`](a500de15cc)
Thanks [@tkattkat](https://github.com/tkattkat)! - Remove deprecated
provider option

- [#1975](https://github.com/browserbase/stagehand/pull/1975)
[`8f7192c`](8f7192cee9)
Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - make file
upload elements more explicit in page snapshot

## @browserbasehq/stagehand-docs@1.0.1

### Patch Changes

- [#2017](https://github.com/browserbase/stagehand/pull/2017)
[`6b9b46d`](6b9b46d81e)
Thanks [@monadoid](https://github.com/monadoid)! - Document the optional
MCP `start` `sessionId` parameter for attaching to an existing
Browserbase session.

## @browserbasehq/stagehand-evals@1.1.11

### Patch Changes

- Updated dependencies
\[[`732b384`](732b3840f1),
[`20b601d`](20b601dc87),
[`8543c11`](8543c11f6b),
[`14b64ec`](14b64ec7d2),
[`a500de1`](a500de15cc),
[`e471d2e`](e471d2e89d),
[`8f7192c`](8f7192cee9)]:
    -   @browserbasehq/stagehand@3.3.0

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

### Patch Changes

- Updated dependencies
\[[`732b384`](732b3840f1),
[`20b601d`](20b601dc87),
[`8543c11`](8543c11f6b),
[`14b64ec`](14b64ec7d2),
[`a500de1`](a500de15cc),
[`e471d2e`](e471d2e89d),
[`8f7192c`](8f7192cee9)]:
    -   @browserbasehq/stagehand@3.3.0

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

### Patch Changes

- Updated dependencies
\[[`732b384`](732b3840f1),
[`20b601d`](20b601dc87),
[`8543c11`](8543c11f6b),
[`14b64ec`](14b64ec7d2),
[`a500de1`](a500de15cc),
[`e471d2e`](e471d2e89d),
[`8f7192c`](8f7192cee9)]:
    -   @browserbasehq/stagehand@3.3.0

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
2026-04-27 08:47:22 -07:00
Sam F
6b9b46d81e
[STG-1837] Document MCP start sessionId support (#2017)
# why

The v3 MCP docs now need to describe the hosted server behavior where
`start` can attach to an existing Browserbase session via an optional
`sessionId`.

# what changed

- Updated the MCP setup and tools docs to document optional
`start.sessionId`.
- Clarified that omitting `sessionId` creates a new Browserbase session.
- Added a patch changeset for `@browserbasehq/stagehand-docs`.

# test plan

- `pnpm exec prettier --check
packages/docs/v3/integrations/mcp/setup.mdx
packages/docs/v3/integrations/mcp/tools.mdx`


<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Added docs for optional `sessionId` on MCP `start` to attach to an
existing Browserbase session; omitting it creates a new session.
Addresses STG-1837 and publishes a patch to
`@browserbasehq/stagehand-docs`.

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

<!-- End of auto-generated description by cubic. -->
2026-04-24 19:45:43 +02:00
Sean McGuire
8f7192cee9
[fix]: make file upload elements more explicit in page snapshot (#1975)
# why
- file upload elements sometimes have a 'button' AX role 
- this causes issues when users prompt `.observe()` to find "file upload
elements", since the model sees them as a 'button'
- addresses #972 
# what changed
- this PR preserves the semantics of file upload elements by using the
actual DOM tag name and 'type'
- eg, instead of `[0-12] button: Choose File`, we now use `[0-12] input,
file: Choose File`
# test plan
- added a unit test for the replacement logic
- added an `observe()` eval which checks that hidden file upload
elements are correctly found by the LLM


<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Make file upload inputs explicit in the page snapshot so `.observe()`
can reliably find them. Addresses Linear STG-934 by preventing file
inputs from being misclassified as buttons.

- **Bug Fixes**
- Enrich DOM tag names to include input type (e.g., `input, file`) and
use them in DOM maps.
- Force file inputs to appear as `input, file` in the a11y outline
instead of AX `button`.
- Add unit test and fix/register the `observe_file_uploads` eval in
`evals.config.json`.
  - Publish patch for `@browserbasehq/stagehand`.

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

<!-- End of auto-generated description by cubic. -->
2026-04-22 16:41:09 -07:00
tkattkat
a500de15cc
remove strictJson schema (#2028)
# why

Structured output mode is deprecated 

# what changed

removed usage of anthropic structured output mode 

# test plan

Ran tests locally + CI tests 


<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Removed the deprecated `anthropic.structuredOutputMode` option from
AISdk provider options to align with Anthropic’s deprecation and avoid
sending unsupported flags. Updated unit tests and added a changeset;
behavior for other providers is unchanged.

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

<!-- End of auto-generated description by cubic. -->
2026-04-22 14:31:57 -07:00
github-actions[bot]
732b3840f1
[Claimed #1912] Feat: Add Anthropic CUA adaptive thinking (#1954)
Mirrored from external contributor PR #1912 after approval by
@miguelg719.

Original author: @chromiebot
Original PR: https://github.com/browserbase/stagehand/pull/1912
Approved source head SHA: `0ea0332c525017c727743d11a68b8eb74f76b646`

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

## Original description
# why

# what changed

# test plan

<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Add adaptive thinking for Anthropic Claude 4.6 models in the `CUA`
client with effort controls and automatic `temperature=1`. Keeps legacy
`thinkingBudget` for older models and improves model detection and tool
versioning.

- **New Features**
- Detects 4.6 models (e.g., `claude-opus-4-6*`, `claude-sonnet-4-6*`,
incl. provider-prefixed) and sends `thinking: { type: "adaptive" }` with
`output_config.effort` (defaults to `"medium"`).
- Adds `ThinkingEffort` and `thinkingEffort` in `ClientOptions` (`"none"
| "low" | "medium" | "high" | "max"`); `"none"` disables adaptive
thinking.
- Forces `temperature: 1` with adaptive thinking and logs when
overriding a user value; logs when `thinkingBudget` is provided on 4.6
models.
- Uses `computer_20251124` for 4.6 and `claude-opus-4-5-20251101`; older
models continue with `thinking: { type: "enabled", budget_tokens }`.

- **Migration**
  - For 4.6 models, set `thinkingEffort`; `thinkingBudget` is ignored.
- Adaptive thinking forces `temperature: 1`; set `thinkingEffort:
"none"` to disable.

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

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

<!-- external-contributor-pr:owned source-pr=1912
source-sha=0ea0332c525017c727743d11a68b8eb74f76b646 claimer=miguelg719
-->

---------

Co-authored-by: Chromie Bot <chromie@browserbase.com>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Co-authored-by: miguel <miguelg71921@gmail.com>
2026-04-22 09:50:25 -07:00
Shrey Pandya
20b601dc87
[STG-1825] fix: include agent.execute usage in metrics (#2001) 2026-04-17 12:18:51 -07:00
github-actions[bot]
8543c11f6b
[Claimed #1978] fix: add variable substitution to keys step during cache replay (#1983)
Mirrored from external contributor PR #1978 after approval by @pirate.

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

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

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

Fixes #1776

## Problem

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

## Fix

This PR combines two fixes into one:

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

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

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

## Credit

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

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

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

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

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

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

---------

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

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

## Note

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


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

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

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

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

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

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

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

## Testing

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

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

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

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

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

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

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

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

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

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

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

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

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

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

## What this enables

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

## Architecture

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

## Linked PRs

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

## Testing

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

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

---------

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


# Releases
## @browserbasehq/stagehand@3.2.1

### Patch Changes

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

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

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

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

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

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

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

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

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

## @browserbasehq/stagehand-evals@1.1.10

### Patch Changes

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

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

### Patch Changes

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

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

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

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

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

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

### Patch Changes

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

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

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

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

## Original description

# why
Examples were quite stale

# what changed
Overhaul of examples/ and minor cleanups

# test plan


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

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

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

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



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

---------

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

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

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

## Original description
# why
Introducing [Model
Gateway](https://www.browserbase.com/blog/model-gateway) on Browserbase

# what changed
`modelApiKey` is now optional on API

# test plan


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

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

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

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



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

---------

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

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

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

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

---------

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

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

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

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

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

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

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

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

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

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

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

---------

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

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

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


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

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

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

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

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

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

## Why

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

## Impact

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

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

## Test Plan

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

Linear: STG-1752

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

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

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

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

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

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

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


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

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

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

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

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

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

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

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

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

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

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

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

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

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

---------

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

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

# what changed

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

# test plan

- wrote tests 
- tested locally with own middleware 

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

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

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

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

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

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

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


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

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

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

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

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

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

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

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

---------

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

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

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

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

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

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

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


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

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

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

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

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

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


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

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

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

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

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

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

## Test plan

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

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

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

---------

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

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

# what changed

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

# test plan

- tested locally using operator-example script 

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

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

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

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

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

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

### How it works

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

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

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

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

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

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

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

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

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

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

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-26 16:55:15 -07:00
Shrey Pandya
e81dde7157
STG-1672: Add --connect flag to browse CLI for existing Browserbase sessions (#1889)
## Summary

- Adds a global `--connect <session-id>` flag to the `browse` CLI that
connects to an existing Browserbase session instead of creating a new
one
- Uses Stagehand core's existing `browserbaseSessionID` support with
`keepAlive: true` so the session stays alive after the CLI disconnects
- Follows the same state-file pattern as `--context-id` (writes session
ID to `/tmp/browse-{session}.connect`, daemon reads it during
initialization)

## Test procedure

```
# 1. Sync cookies
node cookie-sync.mjs --domains github.com
# → Session ID: 3ee737d4-237f-4557-a1ca-09a3d5dcbaf2

# 2. Connect and browse (dev build)
browse --connect 3ee737d4-... open https://github.com/notifications  ✅
browse eval "..."  ✅
```

## Tests completed

- [x] `browse --connect <id> open ...` in local mode → errors with "only
supported in remote mode"
- [x] `browse --connect <id> open --context-id <ctx> ...` → errors with
mutual exclusion message
- [x] `--connect` writes session ID to connect file before daemon start
- [x] Commands without `--connect` clear stale connect file
- [x] `browse status` output includes `browserbaseSessionId` field
- [x] Manual: `browse --connect <valid-bb-session> open
https://example.com` connects and navigates
- [x] Manual: `browse stop` disconnects without killing the BB session

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

Fixes STG-1672


<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Adds a `--connect <session-id>` flag to the `browse` CLI to attach to an
existing Browserbase session instead of creating a new one, leaving the
session running after the CLI exits. Implements STG-1672.

- **New Features**
- New global `--connect <session-id>` for `browse` to attach to an
existing Browserbase session
  - Remote mode only; errors in local mode
  - Mutually exclusive with `--context-id`
- Persists the session ID to `/tmp/browse-{session}.connect`; clears
when unused and restarts the daemon if the ID changes
- Uses `browserbaseSessionID` with `keepAlive: true` so the session
persists after disconnect
  - `browse status` now includes a `browserbaseSessionId` field
  - Minor release for `@browserbasehq/browse-cli`

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

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

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-25 22:16:14 -07:00
Shrey Pandya
6e3c14bd8c
STG-1669: fix(cli): clear cached state when browser connection dies (#1887)
## Summary
- When the browse CLI daemon outlives its Chrome browser (e.g., between
Claude Code sessions), `ensureBrowserInitialized()` returns the cached
`stagehand`/`context` without checking if the browser is still alive
- This causes `"No Page found for awaitActivePage: no page available"`
errors requiring a manual `browse stop` + retry
- Fix: register an `onTransportClosed` handler on the CDP connection
that clears the cached state, so the next command triggers a full
re-initialization

## Root cause
The daemon is spawned as a detached process (`detached: true`,
`child.unref()`) and persists across CLI sessions. When Chrome dies,
`_onCdpClosed` fires and calls `stagehand.close()`, but the daemon's
closure variables `stagehand` and `context` are never cleared. The next
command hits the early return at `if (stagehand && context) { return ...
}` and tries to use dead objects.

## Test plan

**Regression test added to PR is illustrative** 

- [x] Start a `browse` session, close Chrome manually, run another
`browse open` — should auto-recover instead of erroring
- [x] Normal `browse` workflow (open, snapshot, click, stop) still works
- [x] Daemon restart across mode switches (local ↔ remote) still works
- [x] Regression test added: kills Chrome under daemon, verifies
auto-recovery (fails on main, passes with fix)

## Verified test results

**On `main` (without fix):** Test fails — after killing Chrome, the
retry returns exit code 1 with `"Error: No Page found for
awaitActivePage: no page available"`. The daemon is alive but returns
stale cached Stagehand/context objects.

**On this branch (with fix):** Test passes — after killing Chrome, the
`onTransportClosed` handler nulls the cached state, and the retry
triggers a full browser re-initialization. All 37 CLI tests pass (full
suite, 67s).

> **Note:** When building locally, use `npx tsup src/index.ts --format
cjs --out-dir dist --no-splitting` inside `packages/cli/` rather than
`pnpm run build:cli`, since turbo may serve a stale cached build that
doesn't include the fix.

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

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-25 21:27:31 -07:00
Shrey Pandya
6c89565cd1
feat(cli): add browse-cli metadata to Browserbase sessions (#1890)
## Summary
- Adds `userMetadata: { "browse-cli": "true" }` to every Browserbase
session created through the browse CLI
- Enables usage attribution to distinguish CLI-originated sessions from
SDK-originated ones

## Test plan
- [x] Run `browse open https://example.com` in Browserbase mode and
verify the session has `browse-cli: true` in its metadata
- [x] Verify local mode is unaffected

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

<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Adds `userMetadata: { "browse-cli": "true" }` to
`browserbaseSessionCreateParams` for sessions started by
`@browserbasehq/browse-cli` in Browserbase mode, enabling usage
attribution and distinguishing CLI vs SDK sessions. Satisfies STG-1678;
local mode is unaffected.

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

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

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-25 14:30:15 -07:00
Miguel
a98801a17f
Fix schema parsing bug for Pydantic .model_json_schema() (#1873)
# why
JSON schema parsing for schemas generated from Pydantic
`.model_json_schema()` were dropping the nested references

# what changed
Before (from test script) with schema: 
```python
class RequiredInputType(StrEnum):
    USERNAME = "username"
    EMAIL = "email"
    PHONE = "phone"
    OTP = "otp"
    PASSWORD = "password"
    CARD_LAST_8 = "card_last_8"
    SOMETHING_ELSE = "something_else"

class PageState(StrEnum):
    LOGIN_FORM = "login_form"
    ERROR = "error"
    AUTHENTICATED = "authenticated"
    UNKNOWN = "unknown"

class PageAnalysis(BaseModel):
    page_state: PageState
    required_input: RequiredInputType | None = None
    contact_id_of_required_input: str | None = None
    error_message: str | None = None
    reasoning: str = ""
```
<img width="654" height="373" alt="Screenshot 2026-03-23 at 1 09 01 PM"
src="https://github.com/user-attachments/assets/29a24eea-cfda-40a8-8e43-10f959c71ad2"
/>

After: 
<img width="650" height="310" alt="Screenshot 2026-03-23 at 1 06 17 PM"
src="https://github.com/user-attachments/assets/9f62d1ad-04bb-41e4-9dbc-85d7b68c84aa"
/>

1. Added resolveRefs() function that inlines $ref/$defs before Zod
conversion (Pydantic
  v2's model_json_schema() generates these)
2. Changed z.string().refine() → z.enum() so enum constraints are
expressed in the
  schema sent to the LLM, not just validated post-hoc


# test plan

<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Fixes missing nested `$ref` when converting Pydantic v2
`.model_json_schema()` to Zod in `@browserbasehq/stagehand-server-v3`,
and emits proper `z.enum()` types so LLM-facing schemas are accurate.
Adds a `test:unit` script, moves tests to `tests/`, and updates the
runner to scan directories or single files.

- **Bug Fixes**
- Resolves `$ref` from `$defs` before conversion via `resolveRefs()`
with a cycle guard, handling refs in objects, arrays,
`anyOf`/`oneOf`/`allOf`, and root-level refs (unknown refs fall back
safely).
- Replaces `z.string().refine()` with `z.enum()` so enum values are
surfaced in generated schemas and enforced.

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

<!-- End of auto-generated description by cubic. -->
2026-03-24 15:55:40 -07:00
Miguel
f3fe7ce597
Include LLM headers in ModelConfig (#1874)
# why
Custom headers for LLM requests are supported in Stagehand, canonical
SDKs were not accounting for this until now.

# what changed
Added headers to ModelConfig

# test plan



<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Adds an optional `headers` field to `ModelConfig` to send custom headers
with every LLM request. Also includes a patch changeset for
`@browserbasehq/stagehand`.

- **New Features**
- Add `headers?: Record<string, string>` to `ModelConfigObjectSchema` in
`packages/core/lib/v3/types/public/api.ts`.
- Update `packages/server-v3/openapi.v3.yaml` to document `headers` in
`ModelConfig`.
- Update `packages/server-v4/openapi.v4.yaml` to use selector-based
result/output schemas for page actions (click, hover, scroll,
drag-and-drop) and add `returnSelector` support.

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

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

---------

Co-authored-by: Sean McGuire <seanmcguire1@outlook.com>
2026-03-24 11:29:40 -07:00
Sam F
8bf5db8eb8
Add explicit SSE event names for local v3 streaming (#1858)
## Why
The stainless sdks are dropping the final finished SSE event instead of
yielding it. This is due to the fact that we were not using `event`
fields (basically setting event types) as per the SSE spec.

The fix is to emit explicit SSE `event:` names and match them in
Stainless. But on the hosted API we cannot switch that on for everyone
at once, because older clients still expect the old `data:`-only SSE
framing. Thus, we will need to have branching logic in our hosted
server:

1. Legacy (old stainless sdks, stagehand-js): continue to not return
`event` field.
2. New Stainless SDKs on `>= 3.13.0`: use typed SSE framing with
`event:` + `data:`.

Once this and it's core counterpart PR are merged, then we will release
another version of all stainless sdks - `3.13`, which will be the first
typed-SSE release.

## What Changed
- emit explicit SSE `event:` names from the local v3 streaming helper
while keeping the JSON `data:` payload unchanged
- switch Stainless streaming matching to explicit `event_type` handlers
- update the documented stream shape, regenerated v3 OpenAPI, and a
focused integration assertion

## Testing
- `pnpm --dir /tmp/stagehand-local-sse.lSk5Av --filter
@browserbasehq/stagehand-server-v3 run gen:openapi`
- `pnpm --dir /tmp/stagehand-local-sse.lSk5Av exec prettier --check
stainless.yml`
- `pnpm --dir /tmp/stagehand-local-sse.lSk5Av --filter
@browserbasehq/stagehand lint`
- `pnpm --dir /tmp/stagehand-local-sse.lSk5Av --filter
@browserbasehq/stagehand-server-v3 lint`

A test run with the three different client types against the updated
server:
<img width="765" height="230" alt="Screenshot 2026-03-20 at 11 01 50 AM"
src="https://github.com/user-attachments/assets/af97c8ec-d7f9-4ae6-95a0-16a3c2906934"
/>

<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Emit explicit SSE event names for v3 streaming (`starting`, `connected`,
`running`, `finished`, `error`) while keeping the JSON `data:` payload
unchanged. Updates the streaming helper, Stainless config, OpenAPI docs,
and tests to use and verify typed events.

- New Features
  - Server now sends `event: <status>` with `data: { data, type, id }`.
- Switched `stainless.yml` streaming matching to `event_type` (yields on
starting/connected/running/finished; handles `error`).
- Added integration test asserting event names match payload status;
updated OpenAPI description and core type docs.

- Dependencies
- Added changeset to publish patch updates for
`@browserbasehq/stagehand` and `@browserbasehq/stagehand-server-v3`.

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

<!-- End of auto-generated description by cubic. -->
2026-03-24 18:20:43 +01:00
Sean McGuire
144e18e9e0
[feat]: apply toolTimeout arg to more tools (#1843)
# why
- `toolTimeout` was only being applied to the `act`, `extract`,
`fillForm`, & `ariaTree` tools
- we want the `toolTimeout` to take effect across all of the tools (with
the exception of `wait` & `think`)
- additionally, when a timeout was being hit, the duration of the
timeout was not being included in the error logs
# what changed
- wrapped all agent tool calls (other than `wait` & `think`) in
`withTimeout()`
- update error logs to include the timeout duration in the log message
### updated error logs with timeout duration:
<img width="887" height="98" alt="Screenshot 2026-03-17 at 3 53 50 PM"
src="https://github.com/user-attachments/assets/957d2e68-0078-47c2-98d7-32f28f76f105"
/>

### example of tool call respecting timeout (`screenshot()` had no
`toolTimeout` before)

<img width="698" height="108" alt="Screenshot 2026-03-17 at 4 13 02 PM"
src="https://github.com/user-attachments/assets/344df89d-f545-4380-92bb-562633e34ce9"
/>

# test plan
- extended tests in `timeout.spec.ts` to validate that all of the tools
correctly respect `toolTimeout`

<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Applies a user-defined `toolTimeout` to all async agent tools (except
`wait` and `think`) via a centralized wrapper at tool init. Timeouts
return a consistent `TimeoutError` that includes the duration (ms) and
short hints. Addresses Linear STG-1510.

- New Features
- Centralized timeouts: wrap tool execute in `createAgentTools()` with
`withTimeout()`; covers `act`, `extract`, `fillForm`, `fillFormVision`,
`ariaTree`, `click`, `clickAndHold`, `dragAndDrop`, `type`, `keys`,
`scroll` (DOM/hybrid), `screenshot`, `goto`, `navback`, and `search`
(Brave/Browserbase).
- Consistent errors and logs: tools re-throw timeouts to the wrapper;
wrapper logs and returns `{ success: false, error }`; simplified
non-timeout messages in `search`, `click`, `clickAndHold`,
`dragAndDrop`, `type`, and `keys`.
- Tests: expanded `timeouts.spec.ts` to cover DOM and hybrid tools;
asserts the timeout duration (e.g., "1ms") is included.

- Migration
- No breaking changes. Set `toolTimeout` via `createAgentTools(v3, {
toolTimeout: <ms> })` or `v3.agent({ toolTimeout: <ms> })`.

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

<!-- End of auto-generated description by cubic. -->
2026-03-18 16:45:39 -07:00
github-actions[bot]
3c904cb789
Version Packages (#1754)
This PR was opened by the [Changesets
release](https://github.com/changesets/action) GitHub action. When
you're ready to do a release, you can merge this and the packages will
be published to npm automatically. If you're not ready to do a release
yet, that's fine, whenever you add more changesets to main, this PR will
be updated.


# Releases
## @browserbasehq/browse-cli@0.2.0

### Minor Changes

- [#1816](https://github.com/browserbase/stagehand/pull/1816)
[`687d54a`](687d54adda)
Thanks [@shrey150](https://github.com/shrey150)! - Add `--context-id`
and `--persist` flags to `browse open` for loading and persisting
Browserbase Contexts across sessions

- [#1793](https://github.com/browserbase/stagehand/pull/1793)
[`e38c13b`](e38c13b752)
Thanks [@shrey150](https://github.com/shrey150)! - Initial release of
browse CLI - browser automation for AI agents

### Patch Changes

- [#1806](https://github.com/browserbase/stagehand/pull/1806)
[`f8c7738`](f8c773898f)
Thanks [@shrey150](https://github.com/shrey150)! - Fix `browse env`
showing stale mode after `browse env remote`

- Updated dependencies
\[[`505e8c6`](505e8c6736),
[`2f43ffa`](2f43ffac11),
[`63ee247`](63ee247ac6),
[`7dc35f5`](7dc35f5e25),
[`335cf47`](335cf4730e),
[`6ba0a1d`](6ba0a1db7f),
[`4ff3bb8`](4ff3bb831a),
[`c27054b`](c27054bbd0),
[`2abf5b9`](2abf5b90f1),
[`7817fcc`](7817fcc315),
[`7390508`](73905088c5),
[`611f43a`](611f43ac8d),
[`521a10e`](521a10e369),
[`2402a3c`](2402a3c4d5)]:
    -   @browserbasehq/stagehand@3.2.0

## @browserbasehq/stagehand@3.2.0

### Minor Changes

- [#1779](https://github.com/browserbase/stagehand/pull/1779)
[`2f43ffa`](2f43ffac11)
Thanks [@shrey150](https://github.com/shrey150)! - feat: add
`cdpHeaders` option to `localBrowserLaunchOptions` for passing custom
HTTP headers when connecting to an existing browser via CDP URL

- [#1834](https://github.com/browserbase/stagehand/pull/1834)
[`63ee247`](63ee247ac6)
Thanks [@tkattkat](https://github.com/tkattkat)! - Update stagehand
agents search tool

- [#1774](https://github.com/browserbase/stagehand/pull/1774)
[`521a10e`](521a10e369)
Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - add new
page.setExtraHTTPHeaders() method

### Patch Changes

- [#1759](https://github.com/browserbase/stagehand/pull/1759)
[`505e8c6`](505e8c6736)
Thanks [@shrey150](https://github.com/shrey150)! - Add bedrock to the
provider enum in model configuration schemas and regenerate OpenAPI
spec.

- [#1814](https://github.com/browserbase/stagehand/pull/1814)
[`7dc35f5`](7dc35f5e25)
Thanks [@tkattkat](https://github.com/tkattkat)! - Change usage of
openai provider in agent to default to store:false

- [#1846](https://github.com/browserbase/stagehand/pull/1846)
[`335cf47`](335cf4730e)
Thanks [@aq17](https://github.com/aq17)! - Fix streaming finished event
being silently dropped. The final SSE event containing the result
payload (success status, message, actions, usage, and messages) was
previously discarded instead of being yielded to the caller.

- [#1764](https://github.com/browserbase/stagehand/pull/1764)
[`6ba0a1d`](6ba0a1db7f)
Thanks [@shrey150](https://github.com/shrey150)! - Expose `headers` in
`GoogleVertexProviderSettings` so model configs can pass custom provider
headers (for example `X-Goog-Priority`) without TypeScript errors.

- [#1847](https://github.com/browserbase/stagehand/pull/1847)
[`4ff3bb8`](4ff3bb831a)
Thanks [@miguelg719](https://github.com/miguelg719)! - Enable FlowLogger
on BROWSERBASE_FLOW_LOGS=1

- [#1752](https://github.com/browserbase/stagehand/pull/1752)
[`c27054b`](c27054bbd0)
Thanks [@derekmeegan](https://github.com/derekmeegan)! - fix: pause
Browserbase agents while captcha solving is active and improve CUA
recovery after the solve completes

- [#1800](https://github.com/browserbase/stagehand/pull/1800)
[`2abf5b9`](2abf5b90f1)
Thanks [@shrey150](https://github.com/shrey150)! - Make projectId
optional for Browserbase sessions — only BROWSERBASE_API_KEY is required

- [#1766](https://github.com/browserbase/stagehand/pull/1766)
[`7817fcc`](7817fcc315)
Thanks [@tkattkat](https://github.com/tkattkat)! - Add configurable
timeout to tools in agent

- [#1749](https://github.com/browserbase/stagehand/pull/1749)
[`7390508`](73905088c5)
Thanks [@pirate](https://github.com/pirate)! - When connecting to a
browser session that has zero open tabs, Stagehand now automatically
creates an initial `about:blank` tab so the connection can continue.

- [#1761](https://github.com/browserbase/stagehand/pull/1761)
[`611f43a`](611f43ac8d)
Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - fix issue
where handlePossibleNavigation was producing unnecessary error logs on
clicks that trigger page close

- [#1817](https://github.com/browserbase/stagehand/pull/1817)
[`2402a3c`](2402a3c4d5)
Thanks [@tkattkat](https://github.com/tkattkat)! - Add support for
passing custom headers in clientOptions

## @browserbasehq/stagehand-evals@1.1.9

### Patch Changes

- Updated dependencies
\[[`505e8c6`](505e8c6736),
[`2f43ffa`](2f43ffac11),
[`63ee247`](63ee247ac6),
[`7dc35f5`](7dc35f5e25),
[`335cf47`](335cf4730e),
[`6ba0a1d`](6ba0a1db7f),
[`4ff3bb8`](4ff3bb831a),
[`c27054b`](c27054bbd0),
[`2abf5b9`](2abf5b90f1),
[`7817fcc`](7817fcc315),
[`7390508`](73905088c5),
[`611f43a`](611f43ac8d),
[`521a10e`](521a10e369),
[`2402a3c`](2402a3c4d5)]:
    -   @browserbasehq/stagehand@3.2.0

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

### Patch Changes

- [#1759](https://github.com/browserbase/stagehand/pull/1759)
[`505e8c6`](505e8c6736)
Thanks [@shrey150](https://github.com/shrey150)! - Add bedrock to the
provider enum in model configuration schemas and regenerate OpenAPI
spec.

- Updated dependencies
\[[`505e8c6`](505e8c6736),
[`2f43ffa`](2f43ffac11),
[`63ee247`](63ee247ac6),
[`7dc35f5`](7dc35f5e25),
[`335cf47`](335cf4730e),
[`6ba0a1d`](6ba0a1db7f),
[`4ff3bb8`](4ff3bb831a),
[`c27054b`](c27054bbd0),
[`2abf5b9`](2abf5b90f1),
[`7817fcc`](7817fcc315),
[`7390508`](73905088c5),
[`611f43a`](611f43ac8d),
[`521a10e`](521a10e369),
[`2402a3c`](2402a3c4d5)]:
    -   @browserbasehq/stagehand@3.2.0

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

### Patch Changes

- Updated dependencies
\[[`505e8c6`](505e8c6736),
[`2f43ffa`](2f43ffac11),
[`63ee247`](63ee247ac6),
[`7dc35f5`](7dc35f5e25),
[`335cf47`](335cf4730e),
[`6ba0a1d`](6ba0a1db7f),
[`4ff3bb8`](4ff3bb831a),
[`c27054b`](c27054bbd0),
[`2abf5b9`](2abf5b90f1),
[`7817fcc`](7817fcc315),
[`7390508`](73905088c5),
[`611f43a`](611f43ac8d),
[`521a10e`](521a10e369),
[`2402a3c`](2402a3c4d5)]:
    -   @browserbasehq/stagehand@3.2.0

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
2026-03-18 14:38:34 -07:00
Derek
c27054bbd0
[feat]: auto-pause agent during Browserbase captcha solving (#1752)
# why

Browserbase can solve captchas asynchronously, but agents were still
trying to interact with the page while the solver was active. That led
to CUA and DOM/hybrid flows clicking solved captcha widgets again,
pausing on confirmation questions, or resuming with stale assumptions
instead of continuing the original task cleanly.

This PR pauses agent execution while Browserbase's captcha solver is
active and hardens the post-solve resume path so the agent keeps working
on the original task after Browserbase finishes.

# what changed

- added a shared `CaptchaSolver` utility that listens for Browserbase
`browserbase-solving-started/finished/errored` console events, supports
concurrent waiters, and disposes listeners cleanly
- paused DOM/hybrid `prepareStep` execution and CUA `prepareStep` /
action execution while Browserbase is solving a captcha
- enabled Browserbase captcha solving by default unless
`browserSettings.solveCaptchas: false`
- updated agent prompts and follow-up messages to tell the model that
captchas are handled automatically and should not be clicked again after
they are solved
- added OpenAI CUA recovery behavior so it can:
  - carry one-shot context notes into the next model turn
  - auto-continue when the model asks for confirmation instead of acting
- guard post-solve clicks that target the solved captcha widget and
restate the original instruction so the model re-anchors on the task
- added focused unit coverage for solver state, Browserbase session
accessors, CUA/regular agent hooks, and OpenAI CUA confirmation handling

# test plan

- `pnpm --filter @browserbasehq/stagehand lint`
- `pnpm --filter @browserbasehq/stagehand build:esm`
- `cd packages/core && pnpm exec vitest run --config
vitest.esm.config.mjs dist/esm/tests/unit/openai-cua-client.test.js
dist/esm/tests/unit/captcha-solver.test.js
dist/esm/tests/unit/agent-captcha-hooks.test.js
dist/esm/tests/unit/browserbase-session-accessors.test.js`

Browserbase smoke:

- OpenAI CUA + reCAPTCHA demo: strict pass on `Verification Success`
- Anthropic CUA + reCAPTCHA demo: strict pass on `Verification Success`
- Hybrid Gemini + reCAPTCHA demo: strict pass on `Verification Success`
- OpenAI CUA + `solveCaptchas: false`: solver stays disabled, no
wait/resume path is triggered, and the agent stops at the captcha
instead of bypassing it

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: Shrey Pandya <shrey@browserbase.com>
2026-03-18 17:03:59 -04:00
Miguel
4ff3bb831a
Enable FlowLogger on BROWSERBASE_FLOW_LOGS=1 (#1847) 2026-03-18 13:58:33 -07:00
Alex Qiu
335cf4730e
[STG-1607] Yield finished SSE event instead of silently dropping it (#1846)
# why

Monarch Money reported a bug in the Python SDK (stagehand-python
v3.6.0).

In src/stagehand/_streaming.py, both the sync Stream.__stream__() (line
62-63) and async AsyncStream.__stream__() (line 147-148) have:

```
python
if sse.data.startswith('{"data":{"status":"finished"'):
    break  # ← drops the event without yielding it
```

When the server sends the finished SSE event (which contains success,
message, actions, usage, and messages), the SDK immediately breaks out
of the loop without yielding the event to the caller. This means the
final result payload is silently dropped.

# what changed

The streaming on_event config had `handle: done` for the
`{"data":{"status":"finished"...}}` event. Stainless generates this as a
bare break, which exits the SSE loop without yielding the event –
silently dropping the final result payload (success status, message,
actions, usage, and messages) from every streaming response.

Fix – Changed to `handle: yield` so the finished event is delivered to
callers before the stream terminates. This is safe because the server
explicitly calls `reply.raw.end()` immediately after sending the
finished event (packages/server-v3/src/lib/stream.ts), so the SSE
connection closes right after the yield and the loop exits naturally on
EOF – no hang risk.

# test plan

Regenerate SDKs and confirm fix
2026-03-18 14:26:03 -04:00
tkattkat
63ee247ac6
update search tool (#1834)
# Why

Add Browserbase Search API as the primary search tool for agents (`POST
/v1/search`), leveraging the Browserbase API key users already have
configured. Brave Search remains fully supported as a backwards
compatible fallback for existing users with `BRAVE_API_KEY` set.

# What Changed

- **Browserbase Search tool**: New search tool powered by the
Browserbase Search API, enabled via `useSearch: true` in
`agent.execute()`.
- **Brave Search (backwards-compatible)**: Existing users with
`BRAVE_API_KEY` in their environment continue to get the search tool
automatically with no code changes required.
- **Priority**: `useSearch: true` with a Browserbase API key takes
precedence. If not set, falls back to Brave if `BRAVE_API_KEY` is
present.
- **Validation**: If `useSearch: true` is set without a valid
Browserbase API key, a clear error is thrown at preparation time (before
the agent loop starts).
- **Separate files**: `browserbaseSearch.ts` and `braveSearch.ts` keep
the implementations cleanly isolated.


```typescript
const agent = stagehand.agent({ mode: "hybrid" });

const result = await agent.execute({
  instruction: "use the search tool to find me the capital of france",
  useSearch: true,
});
```

# Test Plan

- [x] Run agent with `useSearch: true` and a valid `BROWSERBASE_API_KEY`
— Browserbase search tool should return results
- [x] Run agent with `useSearch: true` and no Browserbase API key —
should throw `MissingEnvironmentVariableError`
2026-03-16 16:06:30 -07:00
tkattkat
2402a3c4d5
Add support for passing custom headers in clientOptions (#1817)
# why

Allow users to pass custom headers in their LLM calls

# what changed

Add headers to the model.ts types 

# test plan


<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Adds `headers` support to `ClientOptions` so clients can send custom
HTTP headers with every provider request. Useful for auth tokens or
routing hints without changing global config.

- **New Features**
- Added `headers?: Record<string, string>` to `ClientOptions` in
`packages/core/lib/v3/types/public/model.ts`; headers are sent with each
request.
  - No breaking changes; default behavior is unchanged.

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

<!-- End of auto-generated description by cubic. -->
2026-03-12 15:21:00 -07:00
Shrey Pandya
687d54adda
feat(cli): add --context-id and --persist to browse open (#1816)
## Summary
- Adds `--context-id <id>` and `--persist` flags to `browse open` so
agents can load/persist browser state (cookies, localStorage, etc.)
across Browserbase sessions using Contexts
- Validates edge cases: `--persist` requires `--context-id`,
`--context-id` requires remote mode, context change triggers daemon
restart

## Usage
```bash
# Load a context (read-only — state not saved back)
browse open https://app.com --context-id ctx_abc123

# Load and persist changes back on session end
browse open https://app.com --context-id ctx_abc123 --persist
```

## How it works
1. `browse open --context-id` writes context config to
`/tmp/browse-{session}.context`
2. The daemon reads this file during browser initialization and passes
it through as `browserbaseSessionCreateParams.browserSettings.context`
3. If a second `browse open` is called with a different context ID, the
daemon is restarted (context is baked into the BB session at creation
time)

Context config uses a temp file (same pattern as `.mode`) because it's
needed at Browserbase session creation time, before the daemon's command
socket is up.

## Test plan
- [x] `browse open https://example.com --context-id <known-id>
--persist` on remote mode — verify session created with context in BB
dashboard
- [x] `browse stop` then reopen with same context — verify state
persists
- [x] Verify context mismatch triggers daemon restart (open with context
A, then open with context B)
- [x] Same context, second open — verify no unnecessary restart
- [x] `browse open https://example.com --context-id <id>` on local mode
— verify clear error
- [x] `browse open https://example.com --persist` without `--context-id`
— verify clear error
- [x] Plain `browse open` (no context flags) — verify no regression
- [x] `cleanupStaleFiles` removes `.context` file on shutdown
- [x] Stale `.context` file from crashed daemon is cleared on next
`browse open` without `--context-id`

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

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-12 13:25:27 -07:00
tkattkat
7dc35f5e25
default to store false for openai use with agent (#1814)
# Why

OpenAI organizations with Zero Data Retention (ZDR) rejects stored
responses from the Responses API (`store: true` is the default when the
AI SDK auto selects it). This causes agent runs to fail

# What Changed

- Set `openai: { store: false }` in `providerOptions` across
`generateText` / `streamText` calls: `v3AgentHandler.ts` (execute +
stream), `handleDoneToolCall.ts`,
- Simplified the existing Gemini `providerOptions` — removed the
conditional `modelId.includes("gemini-3")` check and always pass
`google: { mediaResolution: "MEDIA_RESOLUTION_HIGH" }` since non-Google
providers ignore it.

# Test Plan

- [ ] Run agent in mode with an OpenAI model to confirm no breaking
changes


<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Defaulted agent calls to OpenAI to not store responses, preventing
failures for Zero Data Retention orgs. Also simplified Gemini options by
always sending high media resolution.

- **Bug Fixes**
- Set `providerOptions.openai.store` to `false` for agent `generateText`
and `streamText` calls in `v3AgentHandler` (execute + stream) and
`handleDoneToolCall`, avoiding Responses API rejections in ZDR orgs.

- **Refactors**
- Always pass `google: { mediaResolution: "MEDIA_RESOLUTION_HIGH" }` in
`providerOptions`; non-Google providers ignore it. Added a changeset for
a patch release of `@browserbasehq/stagehand`.

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

<!-- End of auto-generated description by cubic. -->
2026-03-11 17:18:28 -07:00
Shrey Pandya
f8c773898f
fix: browse env inconsistently updates internal state (#1806)
## Summary
- `browse env` showed stale "local" mode after `browse env remote`
- Root cause: `.mode` file was only written during lazy browser init
(`ensureBrowserInitialized`), not at daemon startup. Between daemon
start and first command, `readCurrentMode()` returned `null` and fell
back to hardcoded `"local"`
- Write `.mode` eagerly in `runDaemon()` at startup so it's immediately
available
- Fall back to `desiredMode` instead of `"local"` in the `env` display
handler as a safety net

## Test plan
- [x] Reproduced bug: `browse env remote` → `browse env` showed
`"mode":"local"`
- [x] Verified fix: `browse env remote` → `browse env` now shows
`"mode":"remote"`
- [x] `mode.test.ts` passes (3/3)


<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Fixes `browse env` showing stale "local" after `browse env remote`
(STG-1547). The daemon now writes `.mode` at startup, the display falls
back to `desiredMode` until mode is written, and a patch changeset is
added for `@browserbasehq/browse-cli`.

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

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

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-10 12:24:38 -07:00