# 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>
# why
The intent is we just want the v4 stubs - and the openapi spec (and a
few useless tests for now). This isn't all of of the v4 stubs yet
(missing `/logs` etc), but we'll add in the rest of the stubs in
parallel.
# what changed
- Removes all "copied over" v3 *functionality* and /sessions routes etc.
- Adds v4 stubs like `/browsersession` which return simple JSON objects
# test plan
Lint + (pretty useless) tests pass, checked /documentation accessible
locally and included screenshot.
<img width="1663" height="971" alt="Screenshot 2026-03-18 at 10 36
59 AM"
src="https://github.com/user-attachments/assets/ede65965-f0b6-452e-a841-59ad25c2d456"
/>
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Adds `@browserbasehq/stagehand-server-v4`, a schema‑first, stubbed v4
API for BrowserSession and Page, with a regenerated OpenAPI v4 spec.
Replaces the legacy v4 sessions runtime with simple stubs and a minimal
server boot, leaving `packages/server` unchanged.
- **New Features**
- Full v4 routes: `/v4/browsersession` (create/get/end + actions) and
`/v4/page` (navigation, frames, input, CDP, screenshots, etc.), plus
`/healthz` and `/readyz`.
- Zod v4 schemas for BrowserSession/Page expose OpenAPI components;
generator builds from route registries (`browserSessionRoutes`,
`pageRoutes`); `openapi.v4.yaml` updated.
- Integration tests for v4 BrowserSession and Page; test utils updated
for v4 shapes and a default `x-model-api-key`.
- **Refactors**
- Removed legacy v4 runtime and infra (old `sessions/*` routes, session
store, SSE, auth/env/logging/response, CORS/metrics, SEA fuse) and
legacy tests; server registers only v4 routes/components.
- Simplified health/readiness handlers and error handling with a
lightweight `AppError` in `src/types/error.ts`.
- Fixed query parameter handling in stub GET handlers and OpenAPI so GET
endpoints use the correct querystring shapes.
<sup>Written for commit 8dede23385c238df900d30835d55ba59d9df3245.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1840">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
# why
Nick's PR had both some server-v3 changes and server-v4 changes. I split
it into two prs - just the v3 changes here, and just the v4 changes
[here](https://github.com/browserbase/stagehand/pull/1840) (WIP).
Then, once I rebased this PR, it's really just one small change to the
node SEA binary stuff.
# test plan
Verified the split with exact file manifests before creating the branch
and ran `pnpm install --lockfile-only --ignore-scripts`.
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Renamed the Stagehand server to `packages/server-v3` and
`@browserbasehq/stagehand-server-v3`. Updated CI, release, tests, and
SEA build logic; no API or runtime changes.
- **Refactors**
- Moved `packages/server` to `packages/server-v3` and renamed the
package to `@browserbasehq/stagehand-server-v3`.
- Updated GitHub workflows (CI, SEA build, release) and artifacts to
`stagehand-server-v3-*`.
- Switched OpenAPI/Stainless references to
`packages/server-v3/openapi.v3.yaml`.
- Updated test discovery/commands and Turbo tasks to target
`@browserbasehq/stagehand-server-v3`; adjusted ESLint, workspace, and
scripts accordingly.
- Hardened SEA build: verify Node binary includes the required fuse,
fall back to the official Node distro when needed, enforce fuse
presence, use `stagehand-server-v3-sea` temp paths, centralize the fuse
value, and add a clear cache recovery hint when the cached Node binary
lacks the fuse.
- **Migration**
- Use `@browserbasehq/stagehand-server-v3` in `pnpm`/Turbo filters and
scripts.
- Run local tasks from `packages/server-v3`.
- For SEA builds/tests, use binaries named
`stagehand-server-v3-<platform>-<arch>` and set `SEA_BINARY_NAME` if
needed.
<sup>Written for commit 645a2e6a83b40f271314cac31da41632f7eb7abf.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1839">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
# why
This is the real, recovered FlowLogger PR + improvements based on
yesterday's review session.
I accidentally force-pushed an earlier, incomplete branch state onto the
original flow logger PR and dropped several days of work. This PR
replaces that broken state with the actual recovered branch and the
follow-up fixes needed to make the design correct again.
<img width="1569" height="1015" alt="image"
src="https://github.com/user-attachments/assets/f99171fe-27df-488c-a87a-75605c2a3c1b"
/>
## what this PR does
This restores the intended v3 FlowLogger/EventStore design:
- every `V3` instance owns exactly one FlowLogger session
- every `V3` instance owns exactly one `EventStore`
- FlowLogger produces structured `FlowEvent`s on the instance bus
- EventStore consumes those events and fans them out to sinks
- the default query history is shallow and bounded so logging does not
grow memory without limit
The goal is a stable, queryable execution tree for
Stagehand/agent/CDP/LLM work that preserves parent/child relationships,
survives ALS re-entry, and does not let sink failures break main
execution.
## architecture
### FlowLogger
`packages/core/lib/v3/flowlogger/FlowLogger.ts`
FlowLogger owns:
- the `FlowEvent` model
- the `FlowLoggerContext` stored in AsyncLocalStorage
- method/closure wrappers: `wrapWithLogging(...)`, `runWithLogging(...)`
- re-entry helpers: `withContext(...)`, `resolveContext(...)`
- CDP event helpers
- LLM request/response helpers and middleware
FlowLogger is the event producer. It is responsible for building the
execution tree and maintaining the active parent stack. It is not
responsible for persistence or output destinations.
### EventStore
`packages/core/lib/v3/flowlogger/EventStore.ts`
EventStore owns:
- per-session sink registration
- query routing
- file-backed session directory setup
- bounded in-memory ancestry retention
- store lifecycle and teardown
Sink implementations live in
`packages/core/lib/v3/flowlogger/EventSink.ts`, and
prettifying/sanitization lives in
`packages/core/lib/v3/flowlogger/prettify.ts`.
EventStore is the consumer/router layer. It is intentionally
per-instance and single-session.
### V3 wiring
`packages/core/lib/v3/v3.ts`
In the `V3` constructor:
- `this.eventStore = new EventStore(this.sessionId, opts)`
- `this.flowLoggerContext = FlowLogger.init(this.sessionId, this.bus)`
- `this.bus.on("*", this.eventStore.emit)`
So FlowLogger always has a per-instance context, and the bus is the
handoff point between FlowLogger and EventStore.
## lifecycle
### FlowLogger lifecycle
1. `V3` creates the per-instance `FlowLoggerContext`
2. instrumented methods enter through `wrapWithLogging(...)` or
`runWithLogging(...)`
3. a started event is emitted
4. that event is pushed onto `parentEvents`
5. nested work inherits that parent stack through ALS
6. completed/error events are emitted on unwind
7. `V3.close()` clears the in-memory flow context
### EventStore lifecycle
1. `V3` creates one `EventStore(sessionId, opts)`
2. the default shallow in-memory query sink is attached immediately
3. optional sinks are attached based on runtime config
4. `V3` forwards wildcard bus events into the store
5. `destroy()` tears down the configured sinks
## config / runtime options
### always-on pieces
Every `V3` instance always gets:
- FlowLogger context
- shared event bus
- one EventStore
- one default shallow in-memory query sink
So instrumentation exists even if no human-visible sink is active.
### stderr sink
Enabled automatically when:
- `verbose: 2`
- `BROWSERBASE_FLOW_LOGS=1`
Behavior:
- writes prettified logs to stderr
- suppresses CDP events to keep interactive output high-signal
- does not retain history
- is best-effort only
### file sinks
Enabled automatically when:
- `BROWSERBASE_CONFIG_DIR` is set
Behavior:
- `JsonlFileEventSink` writes full events to `session_events.jsonl`
- `PrettyLogFileEventSink` writes prettified lines to
`session_events.log`
- `session.json` is written with sanitized options
- `sessions/latest` is maintained best-effort
- file sinks are write-only; `query()` returns `[]`
### queryable in-memory history
Default behavior:
- EventStore attaches a `ShallowInMemoryEventSink`
- retention limit is `500` events per session
- retained events keep ancestry metadata only
- retained `data` is intentionally stripped in the default sink
That shallow history is what pretty formatting uses to recover recent
ancestry without retaining screenshots/base64 payloads forever.
## memory impact
The main memory constraint is the default query sink.
What it retains:
- up to 500 recent shallow events per `V3` instance
- ids, timestamps, event types, parent ids, session id
What it does not retain by default:
- full screenshots
- large base64 blobs
- full historical payloads
Implications:
- memory scales roughly with `number_of_sessions * 500 shallow events`
- stderr sink does not retain history
- file sinks do not materially retain history in process memory beyond
normal stream buffering
- attaching `InMemoryEventSink` explicitly is an opt-in to full-payload
retention
## usage patterns
### use `wrapWithLogging(...)`
For class methods that should emit their own started/completed/error
envelope:
- `V3.act`
- `V3.extract`
- `V3.observe`
- page/understudy methods
- agent execute entrypoints
### use `runWithLogging(...)`
For closures or non-decorator code paths that still need a lifecycle
envelope.
### use `withContext(...)` / `resolveContext(...)`
For callback-driven or later async work:
- websocket callbacks
- CDP response/message dispatch
- detached async continuations
`currentContext` is strict and may throw when ALS is missing.
`resolveContext(...)` is the non-throwing lookup for “active ALS if
present, otherwise instance-owned fallback”.
### LLM logging is best-effort
If no flow context is active, LLM logging should no-op. Missing context
must not break model execution.
## reviewer expectations / edge cases
Please review this PR with these expectations in mind:
- ALS can legitimately be missing in later callbacks or detached async
work; that should not break execution unless a caller explicitly uses
strict `currentContext`
- there should be no global or multi-session fallback store; logging
belongs to a real `V3` instance/session
- parent-chain correctness matters more than sink behavior; events must
land under the right parent chain
- sink failures should not break the main library; sinks are
intentionally best-effort
- completion/error pretty lines should resolve back to the original
started-event ancestry, not synthetic completion ids
- `sessionId` often matches `browserbaseSessionId` today, but code
should not rely on that as a permanent invariant
- this PR is about FlowLogger/EventStore architecture and correctness,
not a model-default migration
---------
Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>
# why
- there is a vulnerability in `"langchain/core"` for versions lower than
`0.3.80` (more info
[here](https://www.cve.org/CVERecord?id=CVE-2025-68665))
- we have this package as an optional dep
# what changed
- bumps the optional `"langchain/core"` dep to `^0.3.80`
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Bumps optional `@langchain/core` to ^0.3.80 to resolve a vulnerability
in earlier versions. Lockfile refreshed; no runtime changes.
<sup>Written for commit 5e5d812cea51bd495beeed091f7d03d28f204940.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1841">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
Reverts browserbase/stagehand#1824
See https://github.com/browserbase/stagehand/pull/1836 for context
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Reverts the new flow-logging schema and event store, restoring the
previous session file–based logger. Updates agents, handlers, and evals
to use `SessionFileLogger` and removes the `sessionId` option from
`V3Options`. This undoes the STG-1566 observability changes to stabilize
logging.
- **Refactors**
- Remove `packages/core/lib/v3/eventStore.ts` and related wiring.
- Restore `SessionFileLogger` in `flowLogger.ts` with helpers like
`formatCuaPromptPreview`, `formatLlmPromptPreview`, `logAction`, and
`logStagehandStep`.
- Replace `FlowLogger` usage with `SessionFileLogger` across
agents/handlers; update LLM clients (`OpenAICUAClient`,
`AnthropicCUAClient`, `GoogleCUAClient`, `AISdkClient`) to log
requests/responses with operation names.
- Simplify Understudy/CDP instrumentation; remove FlowLogger context in
`cdp.ts`; use `logAction` in `page.ts`.
- Remove `toTitleCase` and log explicit action names (e.g.,
`Understudy.<method>`, `Page.close`).
- Evals: switch to event-driven screenshot collection via the V3 event
bus; drop interval polling.
- Remove `sessionId` handling and related code in `v3.ts`.
- **Migration**
- Remove `sessionId` from `V3Options` if you were passing it.
- Any direct uses of the reverted `eventStore` or the new observability
schema are no longer available.
<sup>Written for commit f4b687fc42200f562585906520f1b9675f23fa17.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1837">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
# 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`
Refactored flow logging to an event-based system with `FlowLogger` and a
pluggable `eventStore`, improving LLM/CDP traces, action and screenshot
events, and concise prompt/response summaries. `V3` now carries a
`sessionId` and `flowLoggerContext`. Split the server into `server-v3`
and `server-v4` with separate OpenAPI, routes, and SEA builds, and
updated CI.
- **New Features**
- Added `eventStore` with `FileEventStore`, queries, aggregate metrics,
and bus attachment; exported `getEventStore`, `setEventStore`,
`destroyEventStore`, and `getFlowLogConfigDir`.
- Replaced `SessionFileLogger` with `FlowLogger` across agents and
handlers; added `wrapWithLogging` for `Page` actions; standardized event
names via `toTitleCase`.
- Switched to concise LLM summary helpers (`extractLlmPromptSummary`,
`extractLlmCuaPromptSummary`, `extractLlmCuaResponseSummary`) and
`FlowLogger.createLlmLoggingMiddleware`.
- `V3Options.sessionId` now used to associate flows; CDP calls are
linked to flow events for better correlation.
- Exported `FlowLogger`, `FlowEvent`, and `toTitleCase` from
`@core/v3/index`.
- **Migration**
- Replace `SessionFileLogger` and `@logAction` with `FlowLogger` methods
(`log*`, `wrapWithLogging`).
- Use `setEventStore/getEventStore` to plug custom storage
(`FileEventStore` by default); optionally pass `sessionId` in
`V3Options`.
- Update paths/scripts from `packages/server` to `packages/server-v3`;
use new binaries `stagehand-server-v3-*`/`stagehand-server-v4-*`.
<sup>Written for commit c35fdbd446a034056d52e3de54b2620b74f75156.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1824">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
---------
Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>
# why
Sync the Stagehand MCP docs with the Browserbase MCP docs for STG-1576.
# what changed
Copied the refreshed Browserbase MCP introduction and setup pages into
`packages/docs/v3/integrations/mcp`.
# test plan
`pnpm exec prettier --check packages/docs/docs.json
packages/docs/v3/integrations/mcp/introduction.mdx
packages/docs/v3/integrations/mcp/setup.mdx`; `pnpm --dir packages/docs
exec mint broken-links` (unrelated existing failures only); `pnpm lint`
fails in `packages/core` on an existing ESLint rule config issue.
---------
Co-authored-by: ci-test <ci-test@example.com>
# 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. -->
# why
when running pnpm format, it formats files that are not relevant to
current changes which is annoying
# what changed
formatted the unformatted files in cli package
# test plan
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Standardized Prettier/ESLint formatting in `packages/cli` so `pnpm
format` runs are stable and don’t touch unrelated files. No functional
changes.
- **Refactors**
- Applied Prettier across `packages/cli/src` and tests (line breaks,
parens, quotes).
- Tidied lint/Prettier config formatting (`eslint.config.mjs`,
`.prettierrc` newline).
- Adjusted test imports and one assertion to match formatter.
<sup>Written for commit 31570dbe68a938aa5e12ccb4c36d130a5e9833c9.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1819">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
## 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>
# 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. -->
## Summary
- Stacked on #1800
- Only `BROWSERBASE_API_KEY` is required for remote mode in the CLI
- `BROWSERBASE_PROJECT_ID` is still passed through if set, but no longer
checked
## Changes
- `packages/cli/src/index.ts` — `hasBrowserbaseCredentials()` only
checks for API key
- `packages/cli/tests/mode.test.ts` — Updated test to match new error
message
- `packages/cli/README.md` — Updated docs to reflect optional project ID
## Test plan
- [x] Existing mode test updated
- [x] Manual: `browse env remote` with only `BROWSERBASE_API_KEY` set
🤖 Generated with [Claude Code](https://claude.com/claude-code)
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Make `BROWSERBASE_PROJECT_ID` optional in the CLI for remote mode, so
only `BROWSERBASE_API_KEY` is required. The project ID is still
forwarded when provided.
- **Bug Fixes**
- Updated remote mode check and error message to only require
`BROWSERBASE_API_KEY`.
- Autodetection now defaults to `remote` when the API key is set;
otherwise `local`.
- Updated tests and `@browserbasehq/browse-cli` README to match.
<sup>Written for commit 99eb1869225948dc8f9a868c27a7bf0c3a47367d.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1803">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
## Summary
- `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>
# Follow-up Tasks
- [ ] Update stainless SDK custom code for all languages to pull new
`stagehand-server-v3-darwin-x64` binary names (`-v3-` added)
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Split the Stagehand API into `packages/server-v3` and
`packages/server-v4`, each with its own builds, tests, SEA binaries, and
release workflows. Delivers STG-1536 and lets us keep v3 stable while
iterating on v4; CI/test discovery and OpenAPI artifacts are versioned.
- **Refactors**
- Renamed the original server to `packages/server-v3`
(`@browserbasehq/stagehand-server-v3`); updated docs and runtime path
helpers (now synced across core/docs/evals and both servers), ESLint
globs/ignores, scripts/Turbo filters, tests, and Stainless to read
`packages/server-v3/openapi.v3.yaml`; v3 SEA binaries use
`stagehand-server-v3-*`.
- Added `packages/server-v4` (`@browserbasehq/stagehand-server-v4`) with
`/v4/**` routes, SSE streaming via `x-stream-response`, LRU/TTL
in-memory session store, health/readiness, logging/metrics,
`openapi.v4.yaml` + generator, SEA tooling, and v4 integration tests.
- CI: path filters, test discovery, and artifacts cover both versions;
added `stagehand-server-v4-release.yml` and
`stagehand-server-v4-sea-build.yml`; renamed v3 workflows; artifacts
include `packages/server-v3/**` and `packages/server-v4/**` dists and
OAS.
- **Migration**
- Replace `packages/server/**` refs with `packages/server-v3/**` or
`packages/server-v4/**`.
- Use new package filters and binary names:
`@browserbasehq/stagehand-server-v3` /
`@browserbasehq/stagehand-server-v4`; `stagehand-server-v3-*` /
`stagehand-server-v4-*`.
- Update OpenAPI consumers to `packages/server-v3/openapi.v3.yaml` or
`packages/server-v4/openapi.v4.yaml`.
<sup>Written for commit 2b9114ca8097d28ac1567fc67062b24f789a5c2e.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1796">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
# why
cdpHeaders is already plumbed through packages/server correctly, it was
just missing from the spec.
- packages/core/lib/v3/types/public/api.ts:15 defines cdpHeaders on
LocalBrowserLaunchOptionsSchema.
- packages/server/src/routes/v1/sessions/start.ts:192 forwards
browser.launchOptions with a spread into localBrowserLaunchOptions, so
cdpHeaders is preserved.
- packages/server/src/lib/InMemorySessionStore.ts:240 passes
localBrowserLaunchOptions straight into new V3(...).
- packages/core/lib/v3/v3.ts:750 passes lbo.cdpHeaders into
V3Context.create(...).
- packages/core/lib/v3/understudy/context.ts:167 finally uses it in
CdpConnection.connect(wsUrl, { headers: opts?.cdpHeaders }).
# what changed
# test plan
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Added the missing `cdpHeaders` field to the v3 server OpenAPI spec so
clients can send custom Chrome DevTools Protocol headers. This aligns
the spec with server launch options and prevents client
codegen/validation errors.
<sup>Written for commit 39ee7372e2e0ae29fc52a8868675f4673a592ac6.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1797">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
# why
After the build migration, `pnpm build:cli` was no longer linking or
preserving overriden configs
# what changed
- Added bin field in `package.json` to enable npm linking
- Implemented smart config merging in the build script that updates
tasks/benchmarks from source while preserving user-customized defaults
- Added auto-linking via npm link --force at the end of the build
process with graceful fallback, for whenever users run `pnpm build:cli`
- Set `serverCache: false` in initV3 for consistent eval behavior on API
# test plan
---------
Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>
## Summary
- Adds support for CDP (Chrome DevTools Protocol) extra HTTP headers
when connecting to browser sessions
- Passes `extraHTTPHeaders` from the Stagehand config through to the CDP
connection layer
- Warns when `cdpHeaders` provided without `cdpUrl`
- Includes integration test for the new functionality
Related: #1737
Co-authored-by: aditya-silna <aditya@silnahealth.com>
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: aditya-silna <aditya@silnahealth.com>
# why
- to allow for setting HTTP headers at the page level
# what changed
- added new function `page.setExtraHTTPHeaders()` , which sets HTTP
headers for the CDP session of the page, and all of its child sessions
(eg, iframes)
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Adds page.setExtraHTTPHeaders() to set per-page HTTP headers on all
requests from the page and its iframes. Applies to pipeline sessions
immediately and replays on newly adopted child sessions. Addresses ST
LaurensG- NB: STG-1316.
<sup>Written for commit cf677c219f48302427af40921f02ce90c2399692.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1774">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
# why
Init script injection was racing with Debugger.resume() sometimes,
causing frames to load without init scripts running sometimes. This led
to flaky init script tests, which were legitimately catching the issue.
-
https://github.com/browserbase/stagehand/actions/runs/22233062982/job/64336364420?pr=1580
<img width="1613" height="987" alt="image"
src="https://github.com/user-attachments/assets/e836cd65-ed3b-41c8-8f8e-152fd70f30f4"
/>
# what changed
- queues calls on page load to run before we resume
- catches oopifs and lazy frames and click-triggered popups the same way
playwright does
- removes flaky timeout/retry based prior approach
https://deepwiki.com/search/how-does-playwright-guarantee_8cf2339b-c060-4cfc-bc62-f3baaf57b229?mode=deep
# test plan
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Fixes the init‑script race by guaranteeing pre‑resume setup and
correcting popup attach order. Init scripts now run reliably in same‑
and cross‑process popups, OOPIF iframes, and across reloads; race tests
verify addScript is sent before resume per session.
- **Bug Fixes**
- Enforce pre‑resume ordering: per‑session dispatch waiters ensure
Page/Runtime enables, Target.setAutoAttach(waitForDebuggerOnStart),
Network.enable/setExtraHTTPHeaders, and
Page.addScriptToEvaluateOnNewDocument(runImmediately) are sent before
Runtime.runIfWaitingForDebugger; resume only after dispatch; log
ordering issues only for top‑level pages.
- Stabilize attach and evaluation: fix popup attach ordering; fan out
Target.* events to root listeners; retry Runtime.evaluate once on stale
context ids; pre‑register the piercer script before resume and
lazy‑install if needed.
- Harden lifecycle: convert detach errors to PageNotFoundError and
propagate; treat Page.enable/lifecycle acks as best‑effort; never drop
top‑level Page.create due to local timeouts.
- Expand tests and deflake: add delayed‑CDP‑send popup/iframe race repro
with real URLs; assert addScript precedes resume per session; cover
in‑process and cross‑process popups, window.open, OOPIF iframes, and
reload persistence; update detach expectations and timeouts.
<sup>Written for commit 6f464d377a74c8430c526d06d2d3def005416e28.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1719">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
## Summary
Restructures the caching best practices docs page into two clear
sections:
### Changes
- **Removed** the disclaimer/note about server-side caching only working
with `env: "BROWSERBASE"` — this is now naturally conveyed in the
section description
- **Renamed** "Server-side Caching" → **"Browserbase Cache"** with a
clear description of what it is (managed, server-side, automatic,
zero-config)
- **Renamed** "Local Caching" → **"Local Cache"** with a clear
description of what it is (file-based, works everywhere, portable)
- **Added** use-case bullets to the Local Cache section explaining when
to reach for it (agent workflows, CI/CD, local dev, cross-machine
sharing)
- **Preserved** all existing code snippets, configuration examples, and
best practices
### What stays the same
- All code examples (disabling on constructor, disabling per call,
inspecting cache status, act/agent caching, cache directory
organization)
- The limitations section for Browserbase Cache
- The best practices accordion (descriptive dirs, clearing cache,
committing for CI/CD)
- The blog link for deeper technical details
Only modifies `packages/docs/v3/best-practices/caching.mdx`.
Linear: https://linear.app/browserbase/issue/STG-1482
## Summary
- expose `headers` on `GoogleVertexProviderSettings` in Stagehand public model types
- add a public API type test proving model configs with headers are accepted for google/openai/anthropic
- add a patch changeset
## Context
Runtime already forwards provider options to `createVertex()`, but TypeScript rejected `headers` in model config. This aligns public types with runtime behavior.
## Validation
- `pnpm -C packages/core run typecheck`
- `pnpm -C packages/core run build:esm`
- `pnpm -C packages/core run test:core -- packages/core/dist/esm/tests/unit/public-api/llm-and-agents.test.js`
- `pnpm -C packages/core run test:core -- packages/core/dist/esm/tests/unit/llm-provider.test.js`
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Expose the headers field on GoogleVertexProviderSettings in the public model config types so custom provider headers (e.g., X-Goog-Priority) are accepted without TypeScript errors. Updated the public API type test to cover Vertex headers and align the model config check with the public API style, keeping types consistent with runtime behavior.
<sup>Written for commit bf4907dcf6ee3e1ec2991527a74d554c72867cc9. Summary will update on new commits. <a href="https://cubic.dev/pr/browserbase/stagehand/pull/1764">Review in cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
Fixes CE-731
## Summary
- Remove Claude 3.5 Sonnet (`claude-3-5-sonnet-latest`, `-20241022`, `-20240620`) and Claude 3.7 Sonnet (`claude-3-7-sonnet-latest`, `-20250219`) from all supported model lists
- These models are **retired** by Anthropic — API calls to them will fail
- Replace with `claude-sonnet-4-20250514` across evals, CI, docs, and examples
## What changed (27 files)
- **Core types**: Removed from `model.ts` type union, `agent.ts` CUA models list
- **Provider mappings**: Removed from `LLMProvider.ts`, `AgentProvider.ts`, server `utils.ts`, server `model.ts`
- **Evals/CI**: Updated `taskConfig.ts`, `initV3.ts`, `ci.yml`, `.env.example` to use `claude-sonnet-4-20250514`
- **Tests**: Updated `model-deprecation.test.ts` and `llm-and-agents.test.ts` (513/513 pass)
- **Docs**: Updated all v2 and v3 documentation references (11 `.mdx` files)
- **Other**: Issue template, MCP example
## Context
Per [Anthropic's model deprecations page](https://docs.anthropic.com/en/docs/resources/model-deprecations):
| Model | Retired |
|-------|---------|
| `claude-3-5-sonnet-20240620` | Oct 28, 2025 |
| `claude-3-5-sonnet-20241022` | Oct 28, 2025 |
| `claude-3-7-sonnet-20250219` | Feb 19, 2026 |
## Test plan
- [x] All 513 unit tests pass (`pnpm exec turbo run test:core`)
- [x] `grep` confirms zero remaining references outside CHANGELOG.md (historical)
- [ ] Verify CI passes
🤖 Generated with [Claude Code](https://claude.com/claude-code)
# what changed
- added documentation for the `context.setExtraHTTPHeaders()` function
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Add v3 docs for context.setExtraHTTPHeaders(), including API,
context-wide behavior (applies to all pages, replaces not merges, clear
via {}), examples, and error docs. Also updates the V3Context interface
to include this method; addresses Linear STG-1414.
<sup>Written for commit c6f64eed49a8d6abed34e1784d8f1626cb294e0e.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1762">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
# why
- this function was from legacy stagehand which only operated on one
page
- presently, it was only being used to produce a log which:
- at best, misinformed users on whether the page had actually navigated,
and,
- at worst, resulted in a noisy error log
- the error log would happen if `clickElement()` triggered page closure.
this means that the frame.evaluate() to get the URL would attempt
`.evaluate()` on a frame that no longer existed
# what changed
- removed `handlePossibleNavigation()`
# test plan
- existing tests are fine here
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Removed the legacy handlePossibleNavigation() that tried to detect
navigation by URL and produced misleading logs. This also prevents
errors when clicks close the page and evaluate runs on a non-existent
frame, reducing log noise.
<sup>Written for commit 1d2c3d68280d8a686e806a3b55bbbbb766a1ea25.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1761">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
## Summary
- Adds `"bedrock"` to the `provider` enum in `ModelConfigObjectSchema` and `AgentConfigSchema` (Zod schemas in `packages/core/lib/v3/types/public/api.ts`)
- Regenerates `packages/server/openapi.v3.yaml` via `pnpm gen:openapi`
## Context
Bedrock was added to `AISDK_PROVIDERS` and `LLMProvider` in PRs #1604 and #1617, but the Zod schemas that feed the OpenAPI spec (and ultimately the Stainless-generated SDKs) were never updated. This means the Python/Go/etc. SDK type definitions don't include `"bedrock"` as a valid provider option.
Companion PR in bb/core: https://github.com/browserbase/core/pull/7668
## Test plan
- [x] `pnpm gen:openapi` produces updated spec with `bedrock` in all 4 provider enum locations
- [ ] Stainless picks up the OpenAPI change and regenerates SDKs with `bedrock` in the `provider` literal type
🤖 Generated with [Claude Code](https://claude.com/claude-code)
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Add "bedrock" to provider enums in ModelConfigObjectSchema/AgentConfigSchema and regenerate the OpenAPI spec so SDKs accept it and stay in sync with AISDK_PROVIDERS/LLMProvider. Also update AgentType to include "bedrock" to fix a server build type mismatch, and add a patch changeset to publish and unblock Python/Go SDK type generation.
<sup>Written for commit 88e33724c8a08af594dafb86d90fd3fced952520. Summary will update on new commits. <a href="https://cubic.dev/pr/browserbase/stagehand/pull/1759">Review in cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
# why
Stagehand API failures were caused on all routes `/act`, `/observe`,
etc. when session init failed because a page was closed. This adds a
fallback to open about:blank so at least the session remains usable
instead of just crashing on init.
# what changed
# test plan
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Fixes session init when connecting to a browser with zero pages by
auto-creating an about:blank tab. Keeps Stagehand routes working after
the last page closes and surfaces lint failures via a dedicated
cancellation job. Addresses STG-1450.
- **Bug Fixes**
- Replace waitForFirstTopLevelPage with ensureFirstTopLevelPage: check
for an existing page, wait with timeout, then create about:blank if
none.
- Simplify errors to a TimeoutError with clearer context; improve
logging and add an integration test for zero-page init.
- **CI**
- Run cancellation in a separate job only when lint fails, so failures
are visible instead of marked skipped.
<sup>Written for commit 45ed6dc059d44f07c338dc8f36e72eb0702a2cfd.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1749">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
<!-- mintlify-editor-comments:start -->
Mintlify
---
0 threads from 0 users in Mintlify
- No unresolved comments
<!-- mintlify-editor-comments:end -->
<!-- mintlify-comment-->
<a
href="https://dashboard.mintlify.com/browserbase/stagehand/editor/session-init-fixes?source=pr_comment"
target="_blank" rel="noopener noreferrer"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://d3gk2c5xim1je2.cloudfront.net/assets/open-mintlify-editor-dark.svg"><source
media="(prefers-color-scheme: light)"
srcset="https://d3gk2c5xim1je2.cloudfront.net/assets/open-mintlify-editor-light.svg"><img
src="https://d3gk2c5xim1je2.cloudfront.net/assets/open-mintlify-editor-light.svg"
alt="Open in Mintlify Editor"></picture></a>
<!-- /mintlify-comment -->
# why
- adds documentation for the new `keepAlive` param
### note:
- hold off on merging until after release
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Add keepAlive docs to Stagehand, detailing behavior in Browserbase and
Local, close() semantics, defaults/overrides, and how to reconnect via
browserbaseSessionID. Addresses Linear STG-1380.
<sup>Written for commit 6eaa9cdd7e1fbb5052f30d8c2b4578965e4a3039.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1747">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
# why
- adds documentation for the following new functions:
- `context.addCookies()`
- `context.clearCookies()`
- `context.cookies()`
### note:
- hold off on merging until after release
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Add V3 docs for cookie management in context: cookies(), addCookies(),
and clearCookies, with examples and type definitions to help users
manage auth and state. Connects to Linear STG-1409; merge after the
release that includes these APIs.
<sup>Written for commit 4ad34e1ab83fda4a4119889dfbca650a788fbc48.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1748">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
# why
Once API-side caching is deployed, the feature will be opt-out. Users
should have a way to disable the cache from the client.
# what changed
Added a `serverCache` parameter to the constructor which adds the
`x-bb-skip-cache` header to all outbound API requests. This parameter is
also present on act, extract, and observe functions to allow for further
configuration.
# test plan
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Adds global and per-request control of server-side caching for
act/extract/observe in Browserbase mode. Caching is on by default; you
can opt out. HIT/MISS is logged, and results include cacheStatus (Linear
STG-1182).
- **New Features**
- Added serverCache to V3Options and act/extract/observe options
(default true). Sends browserbase-cache-bypass when false, reads
browserbase-cache-status and SSE cacheHit, logs HIT/MISS, and sets
cacheStatus on ActResult/ExtractResult/ObserveResult. Observe now
returns ObserveResult (Action[] with optional cacheStatus).
- Updated public types and docs. Expanded tests with server integration
checks for bypass header behavior and cache-status semantics (including
HIT on repeated identical requests), plus ActCache variable-key
handling/replay.
- **Bug Fixes**
- Fixed cache miss logging when variables are missing during ActCache
replay, and suppressed cache status logging when a request explicitly
bypasses the cache.
<sup>Written for commit b35d29ea042f1314e7a9cc0366b87ceb9aa29118.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1581">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
<!-- CURSOR_SUMMARY -->
---
> [!NOTE]
> **Medium Risk**
> Touches the Browserbase API request/response path (new headers, SSE
parsing behavior, and result type shape), which could affect caching
behavior or backwards compatibility for consumers relying on exact
response objects.
>
> **Overview**
> Adds **server-side caching support for Browserbase API mode** with a
new `serverCache` flag on `V3Options` (instance default) and per-call
overrides in `act()`, `extract()`, and `observe()`.
>
> `StagehandAPIClient` now sends `browserbase-cache-bypass: true` when
caching is disabled, reads `browserbase-cache-status` (and SSE
`cacheHit`) to log HIT/MISS, and attaches `cacheStatus?: "HIT" | "MISS"`
onto `ActResult` and `ExtractResult`.
>
> Updates public types/tests, adds new unit tests for `ActCache`
variable-key behavior, and refreshes docs + changeset to announce
server-side caching and the opt-out mechanism.
>
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
b5ce9172a3c6e8c1adfcddceb42fea628852388f. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->
# why
- to enforce best practices in error handling by requiring the cause of
a given error to be included in the error that gets thrown
# what changed
- added the `preserve-caught-error` lint rule
- updated calls that were not preserving caught errors
- also bumped eslint version & typescript eslint for compatibility with
the new rule
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Adds an ESLint rule to require preserving the original error when
rethrowing, updates code to pass error causes, and fixes related linting
issues. This improves debugging by linking errors via the cause option.
- **Dependencies**
- ESLint → 10.0.2
- @eslint/js → 10.0.1
- typescript-eslint → 8.56.1
<sup>Written for commit b4cd5039b34b8156a1b55a88196d9aabc97c51d7.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1745">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
# why
- correctly implements what #1739 aimed to do
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Reverts the OpenAPI multi-region changes and returns the spec to a
single API endpoint. Cleans up generator logic and YAML formatting with
no runtime impact.
- **Refactors**
- Remove regional server URLs; keep only
https://api.stagehand.browserbase.com.
- Delete multi-region docs and markdown table from the OpenAPI
description.
- Drop table-formatting regex in the generator; keep version quoting
only.
- Normalize long YAML descriptions to single-line strings.
<sup>Written for commit bb3594875e3494f80c3bffded2438e572a5015f8.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1746">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
# why
we recommend people pin their zod version in docs which is no longer
necessary
# what changed
removed v3 pinning from zod imports in docs
update tool import to import from stagehand
# test plan
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Remove zod v3 pinning across docs and examples by importing from zod.
Switch tool imports to @browserbasehq/stagehand and update .cursorrules
and claude.md examples to match the current API.
<sup>Written for commit 0a047f8e4c035053459e1a6953531cfff796d2cb.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1743">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
# why
# what changed
# test plan
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Fixes the Windows SEA build and cross‑platform path resolution
(including when run via tsx). CI builds, launches, and smoke‑tests
Linux, macOS, and Windows binaries (x64/arm64); CJS/ESM outputs are
stable.
- Bug Fixes
- Reusable SEA build workflow with a full OS/arch matrix (incl. Ubuntu
24.04 ARM and Windows 11 ARM), same‑arch launch check against /healthz,
selective artifact upload, and an include_sourcemaps toggle (dev/test
only; releases exclude sourcemaps).
- Centralized runtimePaths helpers across core/server/evals/docs to
replace import.meta/fileURLToPath, fix tsx path resolution, normalize
absolute paths, and correct supervisorClient CLI resolution and Windows
spawning.
- Tooling: split DOM script builds into four Turbo tasks for Windows;
switch to in‑process esbuild and Node‑invoked turbo/postject; stabilize
CJS/ESM via tsc emits plus small CJS wrappers; refine tsconfig includes;
add default NODE_ENV/BB_ENV in server env.
<sup>Written for commit b0b191f7b0411b6590a79ce3f10b3fba9435b4d7.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1734">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
<!-- CURSOR_SUMMARY -->
---
> [!NOTE]
> **Medium Risk**
> Touches build/CI and packaging code (SEA generation, path resolution)
across multiple packages, so failures could break releases or CI on
specific platforms despite being largely tooling-focused.
>
> **Overview**
> Fixes cross-platform SEA building by moving `build-server-sea` to a
reusable workflow with a multi-OS/arch matrix (including ARM runners),
optional artifact/caching inputs, selective artifact upload, and a
same-arch smoke test that boots each binary and hits `/healthz`.
>
> Standardizes path/root resolution via new `runtimePaths` helpers
(core/server/evals/docs) and replaces ad-hoc
`fileURLToPath(import.meta.url)`/`__dirname` usage across scripts,
tests, and `supervisorClient` (also tightening CLI resolution and SEA
detection).
>
> Simplifies build/tooling: core CJS/ESM builds now rely on `tsc` emits
plus small CJS wrapper entrypoints (dropping esbuild bundling of
core/tests), DOM script generation is split into separate Turbo tasks,
server SEA build switches to in-process `esbuild` and Node-invoked
`turbo`/`postject`, and server env config now provides default
`NODE_ENV`/`BB_ENV` values.
>
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
2e4a07a6d0b54eddb7fea10d079c8062ecba1d6b. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->
# why
# what changed
# test plan
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Added a Note to the caching best-practices doc explaining server-side
caching when running env: "BROWSERBASE" (STG-1447). It’s enabled by
default for act(), extract(), and observe(); repeated calls with the
same inputs return instantly, and you can disable it via serverCache:
false or per call, with a blog link for details.
<sup>Written for commit 4b6181fbb16ae793ec01b0c274ab7b28495b5253.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1742">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
# why
From [1690](https://github.com/browserbase/stagehand/pull/1690/changes)
shoutout @huuyafwww !
This enables agent to connect to MCP servers that require Authorization
headers.
# what changed
connectToMCPServer was modified to accept options for
StreamableHTTPClientTransport as arguments.
# test plan
A public api test was added
<!-- CURSOR_SUMMARY -->
---
> [!NOTE]
> **Low Risk**
> Small additive API change that only affects MCP HTTP connection setup;
minimal behavior change unless callers opt into `requestOptions`.
>
> **Overview**
> `connectToMCPServer` now accepts `requestOptions` and forwards them to
`StreamableHTTPClientTransport`, enabling HTTP connections to MCP
servers that require request-header auth (e.g., `Authorization`).
>
> Updates the public API type test to include `requestOptions`, adds
docs showing a header-authenticated connection example, and publishes
patch changesets for `@browserbasehq/stagehand` and
`@browserbasehq/stagehand-docs`.
>
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
657b7d5fb2350ec2d171175b366b72b671a7315e. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Enable header-based auth for MCP HTTP connections. connectToMCPServer
now accepts requestOptions and forwards them to
StreamableHTTPClientTransport.
- **New Features**
- Added requestOptions to connectToMCPServer for HTTP transports to pass
headers like Authorization.
- Updated docs with an authenticated MCP server example, expanded the
public API type test, and limited the changeset bump to
@browserbasehq/stagehand (docs package bump removed).
<sup>Written for commit 6cee1df669b8011ebd54a164e3c7d5aee2b16dcd.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1735">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
---------
Co-authored-by: huuyafwww <huuya.yamauchi@3-shake.com>
Co-authored-by: ci-test <ci-test@example.com>
Reverts the documentation-related changes to the OpenAPI spec from PR
#1673, while preserving the functional multi-region server endpoints.
Changes reverted:
- Restored the info.description to the original format
- Simplified server descriptions back to "Production Browserbase Cloud
API"
- Removed multi-region documentation from the spec description
# why
# what changed
# test plan
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Reverts the OpenAPI spec docs changes from #1673 to restore a concise
info.description and simpler server labels, with no endpoint or behavior
changes.
- **Refactors**
- Removed the multi-region docs section and the local `disableAPI` note;
kept brief auth/SSE guidance.
- Simplified the default server description to "Production Browserbase
Cloud API"; regional servers remain labeled by region.
- No functional changes; multi-region endpoints and routing remain the
same.
<sup>Written for commit 3d650d8f8c071f5f67ca4ddf514ca4fde323f3f6.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1739">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
---------
Co-authored-by: Chromie Bot <chromie@browserbase.com>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Co-authored-by: Miguel <36487034+miguelg719@users.noreply.github.com>
# why
- these logs dont add much value if any
- they also didn't use the correct logging context, so they get logged
no matter what `verbose` level is defined in the stagehand constructor
# what changed
- removed the noisy logs
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Removed noisy debug logs in deepLocator that ignored the configured
verbose level. This reduces log spam during frame resolution with no
behavior changes.
<sup>Written for commit fa8b1f34771164287855268723849b62b212d737.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1731">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
## Summary
- `IFRAME_STEP_RE` regex only matched `iframe` steps, causing `act()` to
fail on legacy `<frameset>` pages where `observe()` returns XPaths
containing `frame[N]` (e.g.
`/html[1]/frameset[1]/frame[4]/html[1]/body[1]/...`)
- Changed regex from `/^iframe(?:\[\d+])?$/i` to
`/^i?frame(?:\[\d+])?$/i` so both `<iframe>` and `<frame>` are
recognized as frame boundaries
- Consolidated the duplicate `IFRAME_STEP_RE` constant (was defined in
both `deepLocator.ts` and `focusSelectors.ts`) into a single shared
export
## Test plan
- [x] Scratchpad repro confirms current regex misses `frame`,
`frame[4]`, `FRAME` — all pass with fix
- [x] 10 new unit tests added to
`snapshot-focus-selectors-utils.test.ts` covering:
- Regex matches `iframe`, `iframe[N]`, `frame`, `frame[N]`
(case-insensitive)
- Regex rejects `frameset`, `frameset[N]`, `div`, `body`, `html`
- Full XPath parse + walk for frameset page XPaths detects correct frame
boundary
- Standard iframe XPaths still detected correctly
- `frameset` is not false-positive detected as a frame boundary
- [x] All 15 tests pass, build + typecheck pass
🤖 Generated with [Claude Code](https://claude.com/claude-code)
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Adds support for <frame> in XPath frame boundary detection so navigation
works on legacy <frameset> pages. iframe and frame steps are treated as
frame boundaries.
- **Bug Fixes**
- Updated regex from /^iframe(?:\[\d+])?$/i to /^i?frame(?:\[\d+])?$/i
to match iframe and frame (case-insensitive) without matching frameset.
- Added focused tests for iframe/frame and frameset XPaths, including
parse + boundary detection; trimmed low-value cases.
- Added a changeset for a patch release.
- **Refactors**
- Consolidated IFRAME_STEP_RE into a shared export from focusSelectors
and used it in deepLocator.
<sup>Written for commit 4d09b02364a0b4f4bb745c3423fb210b5e0a733a.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1697">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
## Summary
- Claude Opus 4.6 and Sonnet 4.6 require the newer `computer_20251124`
tool type and `computer-use-2025-11-24` beta header for CUA mode
- The previous hardcoded `computer_20250124` is rejected by the
Anthropic API for these models
- Adds conditional tool version selection in
`AnthropicCUAClient.getAction()` — older models are unaffected
- Adds `claude-sonnet-4-6` to model maps (Opus 4.6 was already present)
## Test plan
- [x] Direct Anthropic API calls confirmed both Opus 4.6 and Sonnet 4.6
work with `computer_20251124`
- [x] Stagehand `env: "LOCAL"` CUA mode tested — both models
successfully completed tasks
- [x] Unit tests pass (18/18 in `llm-and-agents.test.ts`)
- [ ] Verify older models (Sonnet 4, Sonnet 4.5, Haiku 4.5) still work
with `computer_20250124`
🤖 Generated with [Claude Code](https://claude.com/claude-code)
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Adds CUA support for Claude Opus 4.6 and Sonnet 4.6 by switching to the
computer_20251124 tool and computer-use-2025-11-24 beta. Older models
continue using computer_20250124 to avoid API rejections.
- **Bug Fixes**
- Select tool/beta per model in AnthropicCUAClient.getAction(),
including prefixed names.
- Use new tool/beta for claude-opus-4-6, claude-sonnet-4-6, and
claude-opus-4-5-20251101.
- Add claude-sonnet-4-6 to modelToAgentProviderMap and
AVAILABLE_CUA_MODELS; update unit tests.
<sup>Written for commit 7c0a52c8021a4cffaefa523e72c8a6071abdb5be.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1729">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
# why
when running evals at high concurrency (~30) with the stagehand API
enabled in a region far from the client machine, browser sessions die
and the entire eval run hangs indefinitely. the process never exits
because `v3.close()` awaits a promise that never resolves.
the root cause is a race in the shutdown path between:
- the HTTP round-trip of `apiClient.end()` (client → API → client), and
- the CDP websocket close event arriving from the browser
race sequence:
1. `v3.close()` awaits `apiClient.end()` (HTTP request/response)
2. the API requests release immediately, and the browser closes the CDP
websocket
3. the websocket `"close"` event can reach the client before the HTTP
response returns
4. only after the HTTP response returns do we call `ctx.close()` →
`CdpConnection.close()`
if the close event wins the race and fires before step (4), then
`CdpConnection.close()` attaches its one-shot
`"close"` listener too late (the event already happened), so the promise
never resolves.
far regions make this more likely because the HTTP RTT is longer,
increasing the window where the close event can
beat the response.
two additional issues were found in the same shutdown path:
- inflight CDP calls are never rejected when the websocket closes
unexpectedly. pending `send()` promises hang forever alongside
`close()`, which compounds the original hang
- the `_onCdpClosed` transport handler was still registered when
`apiClient.end()` was called. the server-side websocket close would fire
`_onCdpClosed` -> `_immediateShutdown()` -> `close({ force: true })`,
re-entering the close path while the original `close()` was still in
progress
this bug only reproduced reliably with regions that are far away from
the client machine because:
- `apiClient.end()` awaits a full request/response to the hosted API;
higher client-region latency makes that await longer
- during that longer window, the server-side websocket close can arrive
and be processed before `CdpConnection.close()` is called
- if the client machine is close to the region, the timing often works
out and `close()` registers the `"close"` listener in time
# what changed
in`packages/core/lib/v3/understudy/cdp.ts`:
- updated `close()` to have an early return when `this.ws.readyState ===
WebSocket.CLOSED` so that calling `close()` on an already-closed
websocket resolves immediately instead of hanging.
- added `rejectAllInflight(why)`, which is a private method that
iterates the `inflight` map and rejects every pending CDP call with a
`CdpConnectionClosedError`, then clears the entry. this is called from
both the websocket `"close"` and `"error"` handlers in the constructor
- updated the `"close"` and `"error"` handlers to call
`this.rejectAllInflight(why)` before `this.emitTransportClosed(why)` to
make sure all pending promises are rejected when the ws dies
in `packages/core/lib/v3/v3.ts`:
- updated `v3.close()` such that `offTransportClosed` runs _before_
`apiClient.end()`
- this prevents `_onCdpClosed` from firing during the API teardown and
re-entering `close({ force: true })`
# test plan
- added unit tests in `cdp-connection-close.test.ts` which check that:
- `CdpConnection.close()` resolves when the websocket is already closed
- inflight `send()` calls reject when the websocket is terminated
- added an e2e test in `cdp-connection-close.spec.ts` which:
- terminates the underlying websocket, then calls `v3.close()` and
asserts it resolves
- terminates the websocket with an inflight CDP call and asserts the
pending promise rejects
- added another e2e test in `cdp-close-api-region.spec.ts` which:
- reproduces the full production trigger chain by creating a stagehand
instance with `disableAPI: false` and `region: "ap-southeast-1"`,
- calls `v3.close()` and asserts it resolves within 30 seconds
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Fixes a shutdown race that caused eval runs to hang when using the
Stagehand API in non-us-west-2 regions. v3.close() now resolves reliably
and inflight CDP requests reject on socket shutdown, addressing Linear
STG-1422.
- **Bug Fixes**
- CdpConnection.close(): return immediately if the WebSocket is already
CLOSED.
- Reject inflight CDP calls on "close"/"error" via new
CdpConnectionClosedError (exported in public error types).
- Unhook transport-close handler before apiClient.end() to prevent
double-close during API teardown.
- Added unit and e2e tests (incl. ap-southeast-1) verifying close
resolves and inflight requests reject.
<sup>Written for commit 699b48a8a75d0b7d33da83d11f7b133ef5673195.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1728">Review in
cubic</a></sup>
<!-- End of auto-generated description by cubic. -->