1156 Commits

Author SHA1 Message Date
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>
@browserbasehq/browse-cli@0.2.0 @browserbasehq/stagehand@3.2.0
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
Sam F
5c3c38d597
Add server-v4 stubs (#1840)
# 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. -->
2026-03-18 13:42:05 -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
Sam F
5981f91713
Rename server package to server-v3 (#1839)
# 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. -->
2026-03-17 15:38:37 -07:00
Nick Sweeting
424efa1800
Real FlowLogger PR (several big commits were missing from #1824) (#1836)
# 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>
2026-03-17 15:02:12 -07:00
Sean McGuire
f56befe480
[chore]: bump "langchain/core" optional dep (#1841)
# 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. -->
2026-03-17 14:52:46 -07:00
Nick Sweeting
af9c92558f
Revert "[STG-1566] Flow logger schema and collection cleanup to prepare for Observability" (#1837)
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. -->
2026-03-17 02:07:28 -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
Nick Sweeting
a3001a623b
[STG-1566] Flow logger schema and collection cleanup to prepare for Observability (#1824)
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>
2026-03-16 16:04:01 -07:00
Sam F
6b19b8ceb9
[STG-1576] Sync MCP docs into Stagehand docs (#1818)
# 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>
2026-03-13 11:28:00 -07:00
Sean McGuire
ac4539ab6b
[chore]: refactor & fix lint for browse CLI (#1821) 2026-03-12 17:44:59 -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
tkattkat
9f02cc222d
fix formatting on cli package (#1819)
# 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. -->
2026-03-12 14:20:29 -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
Nick Sweeting
ab2a05b041
Fix GITHUB_TOKEN usage in external PR approval flow (#1812)
# why

bug in previous approach

# what changed

# test plan

<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Fixes the external PR approval flow by switching to the correct
`GITHUB_TOKEN`, stabilizing the mirror/refresh behavior, and ignoring
third‑party bot comments when parsing claim markers. Also improves the
`claude` workflow to build the repo before edits and allow rerunning
failed jobs.

- **Bug Fixes**
- Use `GITHUB_TOKEN` for branch pushes and API calls; remove the GitHub
App token path.
  - Enable `persist-credentials: true` during checkout to allow pushes.
- Keep the mirrored PR open and mark it stale when new commits land on
the external PR; relabel both PRs consistently.
- Auto-handle reopen/close transitions across external and mirrored PRs.
- Ignore comments from non-managed bots (e.g., Greptile, Cubic); only
parse claim markers from `github-actions[bot]` to avoid false triggers.

- **Refactors**
- Inline a small JS lib (`ECPR_LIB`) to manage labels, comments,
lifecycle, and claims; jobs run in clear phases (external lifecycle →
claim prep → branch refresh → claim finalize).
- Refresh internal branches by rebasing onto the approved external ref;
report conflicts cleanly for manual follow-up.
- Improve `claude.yml`: upgrade to `actions/checkout@v6`, set `actions:
write`, run `pnpm`/`turbo` build via `setup-node-pnpm-turbo`, enable
`track_progress`, and use an explicit tool allowlist for
`anthropics/claude-code-action@v1`.

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

<!-- End of auto-generated description by cubic. -->
2026-03-11 16:59:14 -07:00
Nick Sweeting
4b71374827
[STG-1518] Add Github Action that allows claiming external contributor PRs to run CI with secrets (#1794)
# why

- External contributor PRs currently fail CI because they cant run with
secrets
- We dont want to allow them to run with secrets until a team member
"claims" them and reviews for any secrets exfiltration / sketchy code
- Once claimed, we want to run the full CI suite with secrets

# what changed

# test plan

<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Adds two GitHub Actions that let maintainers claim external contributor
PRs by mirroring the approved head SHA to a maintainer-owned branch so
full CI can run with secrets. Claims come from an approving review by a
team member with write access on the latest commit and are
auto-invalidated on new commits (Linear STG-1518).

- **New Features**
- Detects forked PRs and posts claim instructions; manages labels:
`external-contributor`, `external-contributor:awaiting-approval`,
`external-contributor:mirrored`, `external-contributor:stale`,
`external-contributor:completed`.
- On approving review of the latest commit, verifies reviewer
permission, mirrors that exact SHA to
`external-contributor-pr-<PR#>-<12sha>`, and creates/reopens a “[Claimed
#X]” PR assigned to the approver.
- Closes and links the original PR with marker comments; keeps
labels/status in sync on both PRs.
- Auto-closes the mirror when new commits land on the external PR and
comments with next steps; if the mirror closes without merge, reopens
and relabels the original PR; if the external PR is reopened with the
same approved SHA while the mirror is open, it is closed again to keep
discussion on the mirror.
- Implemented via `external-contributor-pr-approval-handoff.yml`
(captures approved reviews, uploads artifact) and
`external-contributor-pr.yml` (consumes artifact, performs mirroring);
uses `actions/github-script@v7`, `actions/create-github-app-token@v1`,
`actions/checkout@v4`, `actions/download-artifact@v4`,
`actions/upload-artifact@v4`; concurrency scoped per PR/workflow run.

- **Migration**
- Create a GitHub App with `contents:write`, `pull_requests:write`, and
`issues:write`; add `EXTERNAL_CONTRIBUTOR_PR_APP_ID` and
`EXTERNAL_CONTRIBUTOR_PR_APP_PRIVATE_KEY` secrets.
- To claim: submit an approving review on the latest commit of a forked
PR. If new commits are pushed, approve again to re-claim and rerun CI.

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

<!-- End of auto-generated description by cubic. -->
2026-03-11 14:59:39 -07:00
Shrey Pandya
c85222c36b
Make BROWSERBASE_PROJECT_ID optional in CLI (#1803)
## 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>
2026-03-10 14:45:02 -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
Shrey Pandya
2abf5b90f1
Make projectId optional for Browserbase sessions (#1800) 2026-03-09 19:39:05 -07:00
Nick Sweeting
a9424ff2eb
fix(CI): fix changeset reference to stale server package name blocking CI (#1801)
# why

# what changed

# test plan


<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Corrects the changeset package reference from
`@browserbasehq/stagehand-server` to
`@browserbasehq/stagehand-server-v3` to unblock CI and ensure the
correct package receives the patch release.

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

<!-- End of auto-generated description by cubic. -->
stagehand-server-v3/v3.6.1
2026-03-09 18:24:30 -07:00
Shrey Pandya
e38c13b752
[feat]: add browse CLI package (#1793)
## Summary
- Adds the `@browserbasehq/browse-cli` package (`packages/cli`) to the
stagehand monorepo, open-sourcing browser automation for AI agents
- CLI provides stateful browser control via a daemon architecture —
navigation, clicking, typing, screenshots, accessibility snapshots,
multi-tab, network capture, and env switching (local/remote)
- Uses `@browserbasehq/stagehand` as a workspace dependency (bundled
into the CLI binary via tsup)
- Includes full test suite and documentation

## Changes
- `packages/cli/` — all CLI source code, config, tests, and docs
- `pnpm-workspace.yaml` — added `packages/cli` to workspace
- `.github/workflows/ci.yml` — added CLI path filters and build artifact
uploads
- `.changeset/open-source-browse-cli.md` — changeset for initial release
- `pnpm-lock.yaml` — updated lockfile

## Test plan
- [x] CLI builds successfully (`pnpm --filter @browserbasehq/browse-cli
run build`)
- [x] Full monorepo build passes (`turbo run build` — 9/9 tasks)
- [x] `browse --help` and `browse --version` output correctly
- [x] `browse status` returns valid JSON
- [x] Lint passes clean (`pnpm --filter @browserbasehq/browse-cli run
lint`)
- [x] Source verified identical to stagent-cli (only import path
changed)
- [x] Empirically tested Browserbase credential requirements match core
- [ ] Run `pnpm --filter @browserbasehq/browse-cli run test` (requires
Chrome/browser environment)

## Known issues (pre-existing from stagent-cli, not introduced by this
PR)
- Network capture `response.json` always writes `status: 0` — response
metadata from `responseReceived` CDP event is not persisted to
`loadingFinished` handler
- Ref-based `click` command silently ignores
`--button`/`--count`/`--force` flags (coordinate-based `click_xy`
handles them correctly)

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

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-09 17:56:45 -07:00
Nick Sweeting
e36ddd6f29
[STG-1536] Split packages/stagehand/server into separate server-v3 and server-v4 dirs (#1796)
# 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. -->
2026-03-09 17:32:57 -07:00
Nick Sweeting
4d23d06e5f
Add missing cdpHeaders field to v3 server openapi spec (#1797)
# 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. -->
2026-03-09 14:27:55 -07:00
tkattkat
7817fcc315
[feat]: add configurable timeout to agent tools (#1766) 2026-03-04 18:56:58 -08:00
Nick Sweeting
9df8fe66ad
Revert "[fix]: skip CI jobs requiring secrets on fork PRs" (#1787)
Reverts browserbase/stagehand#1780

<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Reverts the change that skipped CI on forked PRs. Integration tests,
evals, and the Stainless preview now run for all PRs by removing the
head-repo equality checks in ci.yml and stainless.yml.

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

<!-- End of auto-generated description by cubic. -->
2026-03-04 17:25:46 -08:00
Nick Sweeting
748a673d17
Revert "Allow outside contributors to run CI with secrets when approved" (#1786)
Reverts browserbase/stagehand#1782

<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Reverts the approval-based CI for external contributors. CI now runs on
pull_request and blocks secrets for forked PRs by skipping integration,
E2E, and eval jobs.

- **Refactors**
  - Removed the “Ensure Contributor Is Trusted to Run CI” workflow.
  - Switched CI trigger to pull_request; removed workflow_run logic.
  - Read labels from github.event.pull_request; removed API calls.
  - Simplified checkouts; dropped explicit head_sha refs.
  - Updated concurrency group to use github.ref.
  - Ignored docs-only changes in CI.

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

<!-- End of auto-generated description by cubic. -->
2026-03-04 17:20:32 -08:00
Nick Sweeting
02c31ef87e
Allow outside contributors to run CI with secrets when approved (#1782)
PSA potential hackers: dont get excited, we don't have any real secrets
in CI worth stealing, and our CI does not autodeploy anything to prod.
All important secrets and CD processes are kept in our closed-source
repos.

# why

# what changed

# test plan


<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Add a gating workflow that blocks CI until a maintainer approves running
secrets on forked PRs. CI now triggers from that gate, resolves labels
and path filters under workflow_run, removes same-repo guards so
integration/e2e/evals run on approved forks, and checks out the PR
commit consistently across jobs.

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

<!-- End of auto-generated description by cubic. -->
2026-03-04 16:55:51 -08:00
Shrey Pandya
37aeb68738
[fix]: skip CI jobs requiring secrets on fork PRs (#1780)
## Summary
- Server integration tests, evals, and Stainless preview builds require repo secrets that GitHub doesn't expose to fork PRs
- These jobs were running and failing with missing env var errors on every fork PR
- Add the same fork guard (`head.repo.full_name == github.repository`) that e2e tests already use

### Jobs fixed:
- `server-integration-tests` in `ci.yml`
- `run-evals` in `ci.yml`
- `preview` in `stainless.yml`

## Test plan
- [ ] Verify existing (non-fork) PRs still run all CI jobs
- [ ] Verify fork PRs skip the guarded jobs gracefully

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

<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Skip CI jobs that require repo secrets on fork PRs to prevent missing env errors. These jobs now run only when the PR comes from this repo.

- **Bug Fixes**
  - Guarded server integration tests in ci.yml.
  - Guarded eval runs in ci.yml.
  - Guarded Stainless preview builds in stainless.yml.

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

<!-- End of auto-generated description by cubic. -->
2026-03-04 10:42:44 -08:00
Miguel
de03030899
fix: evals CLI link and preserve config (#1755)
# 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>
2026-03-03 21:19:50 -08:00
Shrey Pandya
2f43ffac11
[feat]: add cdpHeaders option for custom CDP connection headers (#1779)
## 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>
2026-03-03 17:55:52 -08:00
Sean McGuire
521a10e369
[feat]: add page.setExtraHTTPHeaders() (#1774)
# 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. -->
2026-03-03 16:54:01 -08:00
Nick Sweeting
aa504cc396
Solve init script race with Debugger.resume at frame init script injection time (#1719)
# 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. -->
2026-03-03 16:00:41 -08:00
Derek
3e28a6b2ba
[STG-1482] Update caching docs: split into Browserbase Cache and Local Cache sections (#1770)
## 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
2026-03-03 13:47:46 -08:00
Shrey Pandya
6ba0a1db7f
fix: expose Vertex headers in public model config types (#1764)
## 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. -->
2026-03-03 10:30:05 -08:00
Shrey Pandya
a110e39265
chore: remove retired Claude 3.5 and 3.7 Sonnet models (#1775)
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)
2026-03-03 10:29:50 -08:00
Sameel
54ea8ba5d7
[STG-1458] server cache docs (#1753) 2026-02-27 23:57:34 -08:00
Sean McGuire
87ae1874b2
[docs]: add docs for context.setExtraHTTPHeaders() (#1762)
# 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. -->
2026-02-26 11:10:24 -08:00
Sean McGuire
611f43ac8d
[fix]: rm legacy handlePossibleNavigation() (#1761)
# 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. -->
2026-02-25 19:38:45 -08:00
Shrey Pandya
505e8c6736
[fix]: Add bedrock to provider enum in Zod schemas and OpenAPI spec (#1759)
## 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. -->
stagehand-server/v3.6.1
2026-02-25 15:03:48 -08:00
Sam F
4633f009db
STG-1307: set Sonatype portal for Java/Kotlin (#1757)
# why
Allows java / kotlin publishing
# what changed
minimal stainless config change as per stainless docs
# test plan
none

<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Configured Stainless to publish Java and Kotlin packages to Maven
Central via Sonatype Portal. Moves STG-1307 forward by enabling
publishing for these two languages.

- **New Features**
- Set maven.sonatype_platform: portal for Java and Kotlin in
stainless.yml.

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

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

Co-authored-by: ci-test <ci-test@example.com>
2026-02-25 13:07:06 -07:00
Nick Sweeting
73905088c5
[STG-1450] Fix Session init failing when no pages are open, falls back to opening about:blank (#1749)
# 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 -->
2026-02-24 17:42:42 -08:00
Sean McGuire
ae953708a4
[docs]: add keepAlive docs (#1747)
# 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. -->
2026-02-24 16:17:22 -08:00
Sean McGuire
86fb6cbebd
[docs]: add docs for cookie handling (#1748)
# 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. -->
2026-02-24 16:17:04 -08:00
github-actions[bot]
73fd6722f7
Version Packages (#1598)
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.1.0

### Minor Changes

- [#1681](https://github.com/browserbase/stagehand/pull/1681)
[`e3db9aa`](e3db9aa863)
Thanks [@tkattkat](https://github.com/tkattkat)! - Add cookie management
APIs: `context.addCookies()`, `context.clearCookies()`, &
`context.cookies()`

- [#1672](https://github.com/browserbase/stagehand/pull/1672)
[`b65756e`](b65756e9e8)
Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - add boolean
keepAlive parameter to allow for configuring whether the browser should
be closed when stagehand.close() is called.

- [#1708](https://github.com/browserbase/stagehand/pull/1708)
[`176d420`](176d42002c)
Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - add
context.setExtraHTTPHeaders()

- [#1611](https://github.com/browserbase/stagehand/pull/1611)
[`8a3c066`](8a3c06600a)
Thanks [@monadoid](https://github.com/monadoid)! - Using `mode` enum
instead of old `cua` boolean in openapi spec

### Patch Changes

- [#1683](https://github.com/browserbase/stagehand/pull/1683)
[`7584f3e`](7584f3e92e)
Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - fix:
include shadow DOM in .count() & .nth() & support xpath predicates

- [#1644](https://github.com/browserbase/stagehand/pull/1644)
[`1e1c9c1`](1e1c9c1577)
Thanks [@monadoid](https://github.com/monadoid)! - Fix unhandled CDP
detaches by returning the original sendCDP promise

- [#1729](https://github.com/browserbase/stagehand/pull/1729)
[`6bef890`](6bef89090e)
Thanks [@shrey150](https://github.com/shrey150)! - fix: support Claude
4.6 (Opus and Sonnet) in CUA mode by using the correct
`computer_20251124` tool version and `computer-use-2025-11-24` beta
header

- [#1647](https://github.com/browserbase/stagehand/pull/1647)
[`ffd4b33`](ffd4b335a8)
Thanks [@tkattkat](https://github.com/tkattkat)! - Fix [Agent] - Address
bug causing issues with continuing a conversation from past messages in
dom mode

- [#1614](https://github.com/browserbase/stagehand/pull/1614)
[`677bff5`](677bff5834)
Thanks [@miguelg719](https://github.com/miguelg719)! - Enforce
<number>-<number> regex validation on act/observe for elementId

- [#1580](https://github.com/browserbase/stagehand/pull/1580)
[`65ff464`](65ff464bc1)
Thanks [@tkattkat](https://github.com/tkattkat)! - Add unified variables
support across act and agent with a single VariableValue type

- [#1666](https://github.com/browserbase/stagehand/pull/1666)
[`101bcf2`](101bcf2da8)
Thanks [@Kylejeong2](https://github.com/Kylejeong2)! - add support for
codex models

- [#1728](https://github.com/browserbase/stagehand/pull/1728)
[`0a94301`](0a94301caa)
Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - handle
potential race condition on `.close()` when using the Stagehand API

- [#1664](https://github.com/browserbase/stagehand/pull/1664)
[`b27c04d`](b27c04d278)
Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - fixes issue
with context.addInitScript() where scripts were not being applied to out
of process iframes (OOPIFs), and popup pages with same process iframes
(SPIFs)

- [#1632](https://github.com/browserbase/stagehand/pull/1632)
[`afbd08b`](afbd08bb63)
Thanks [@pirate](https://github.com/pirate)! - Remove automatic `.env`
loading via `dotenv`.

If your app relies on `.env` files, install `dotenv` and load it
explicitly in your code:

    ```ts
    import dotenv from "dotenv";
    dotenv.config({ path: ".env" });
    ```

- [#1624](https://github.com/browserbase/stagehand/pull/1624)
[`0e8d569`](0e8d5695f6)
Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - fix issue
where screenshot masks were not being applied to dialog elements

- [#1596](https://github.com/browserbase/stagehand/pull/1596)
[`ff0f979`](ff0f9795f3)
Thanks [@tkattkat](https://github.com/tkattkat)! - Update usage/metrics
handling in agent

- [#1631](https://github.com/browserbase/stagehand/pull/1631)
[`2d89d2b`](2d89d2b35c)
Thanks [@miguelg719](https://github.com/miguelg719)! - Add right and
middle click support to act and observe

- [#1697](https://github.com/browserbase/stagehand/pull/1697)
[`aac9a19`](aac9a19bdf)
Thanks [@shrey150](https://github.com/shrey150)! - fix: support
`<frame>` elements in XPath frame boundary detection so `act()` works on
legacy `<frameset>` pages

- [#1692](https://github.com/browserbase/stagehand/pull/1692)
[`06de50f`](06de50ff37)
Thanks [@shrey150](https://github.com/shrey150)! - fix: skip piercer
injection for chrome-extension:// and other non-HTML targets

- [#1613](https://github.com/browserbase/stagehand/pull/1613)
[`aa4d981`](aa4d981e44)
Thanks [@miguelg719](https://github.com/miguelg719)! -
SupportedUnderstudyAction Enum validation for 'method' on act/observe
inference

- [#1652](https://github.com/browserbase/stagehand/pull/1652)
[`18b1e3b`](18b1e3bd2b)
Thanks [@miguelg719](https://github.com/miguelg719)! - Add support for
gemini 3 flash and pro in hybrid/cua agent

- [#1706](https://github.com/browserbase/stagehand/pull/1706)
[`957d82b`](957d82b984)
Thanks [@chrisreadsf](https://github.com/chrisreadsf)! - Add GLM to
prompt-based JSON fallback for models without native structured output
support

- [#1633](https://github.com/browserbase/stagehand/pull/1633)
[`22e371a`](22e371ae4c)
Thanks [@tkattkat](https://github.com/tkattkat)! - Add warning when
incorrect models are used with agents hybrid mode

- [#1673](https://github.com/browserbase/stagehand/pull/1673)
[`d29b91f`](d29b91fa50)
Thanks [@miguelg719](https://github.com/miguelg719)! - Add multi-region
support for Stagehand API with region-specific endpoints

- [#1695](https://github.com/browserbase/stagehand/pull/1695)
[`7b4f817`](7b4f817caf)
Thanks [@tkattkat](https://github.com/tkattkat)! - Fix: zod bug when
pinning zod to v3 and using structured output in agent

- [#1609](https://github.com/browserbase/stagehand/pull/1609)
[`3f9ca4d`](3f9ca4d9ac)
Thanks [@miguelg719](https://github.com/miguelg719)! - Add
SupportedUnderstudyActions to observe system prompt

- [#1581](https://github.com/browserbase/stagehand/pull/1581)
[`49ead1e`](49ead1e1e8)
Thanks [@sameelarif](https://github.com/sameelarif)! - **Server-side
caching is now available.**

When running `env: "BROWSERBASE"`, Stagehand automatically caches
`act()`, `extract()`, and `observe()` results server-side — repeated
calls with the same inputs return instantly without consuming LLM
tokens.

Caching is enabled by default and can be disabled via `serverCache:
false` on the Stagehand instance or per individual call. Check out the
[browserbase blog](https://www.browserbase.com/blog/stagehand-caching)
for more details.

- [#1642](https://github.com/browserbase/stagehand/pull/1642)
[`3673369`](36733691f9)
Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - fix issue
where scripts added via context.addInitScripts() were not being injected
into new pages that were opened via popups (eg, clicking a link that
opens a new page) and/or calling context.newPage(url)

- [#1735](https://github.com/browserbase/stagehand/pull/1735)
[`c465e87`](c465e87ab4)
Thanks [@monadoid](https://github.com/monadoid)! - Supports request
header authentication with connectToMCPServer

- [#1705](https://github.com/browserbase/stagehand/pull/1705)
[`ae533e4`](ae533e4019)
Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - include
error cause in UnderstudyCommandException

- [#1636](https://github.com/browserbase/stagehand/pull/1636)
[`ea33052`](ea330520a3)
Thanks [@miguelg719](https://github.com/miguelg719)! - Include
executionModel on the AgentConfigSchema

- [#1679](https://github.com/browserbase/stagehand/pull/1679)
[`5764ede`](5764edee7a)
Thanks [@shrey150](https://github.com/shrey150)! - fix issue where
locator.count() was not working with xpaths that have attribute
predicates

- [#1646](https://github.com/browserbase/stagehand/pull/1646)
[`f09b184`](f09b184cc5)
Thanks [@miguelg719](https://github.com/miguelg719)! - Add user-agent to
CDP connections

- [#1637](https://github.com/browserbase/stagehand/pull/1637)
[`a7d29de`](a7d29decee)
Thanks [@miguelg719](https://github.com/miguelg719)! - Improve error and
warning message for legacy model format

- [#1685](https://github.com/browserbase/stagehand/pull/1685)
[`d334399`](d334399004)
Thanks [@tkattkat](https://github.com/tkattkat)! - Bump ai sdk & google
provider version

- [#1662](https://github.com/browserbase/stagehand/pull/1662)
[`44416da`](44416da7ff)
Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - fix issue
where locator.fill() was not working on elements that require direct
value setting

- [#1612](https://github.com/browserbase/stagehand/pull/1612)
[`bdd8b4e`](bdd8b4ee3c)
Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - fix issue
where screenshot mask was only being applied to the first element that
the locator resolved to. masks now apply to all matching elements.

## @browserbasehq/stagehand-server@3.6.0

### Minor Changes

- [#1611](https://github.com/browserbase/stagehand/pull/1611)
[`8a3c066`](8a3c06600a)
Thanks [@monadoid](https://github.com/monadoid)! - Using `mode` enum
instead of old `cua` boolean in openapi spec

### Patch Changes

- [#1604](https://github.com/browserbase/stagehand/pull/1604)
[`4753078`](4753078cc9)
Thanks [@miguelg719](https://github.com/miguelg719)! - Enable bedrock

- [#1636](https://github.com/browserbase/stagehand/pull/1636)
[`ea33052`](ea330520a3)
Thanks [@miguelg719](https://github.com/miguelg719)! - Include
executionModel on the AgentConfigSchema

- [#1602](https://github.com/browserbase/stagehand/pull/1602)
[`22a0502`](22a0502e8b)
Thanks [@miguelg719](https://github.com/miguelg719)! - Include vertex as
a supported provider

- Updated dependencies
\[[`7584f3e`](7584f3e92e),
[`1e1c9c1`](1e1c9c1577),
[`6bef890`](6bef89090e),
[`ffd4b33`](ffd4b335a8),
[`677bff5`](677bff5834),
[`65ff464`](65ff464bc1),
[`101bcf2`](101bcf2da8),
[`0a94301`](0a94301caa),
[`b27c04d`](b27c04d278),
[`afbd08b`](afbd08bb63),
[`e3db9aa`](e3db9aa863),
[`0e8d569`](0e8d5695f6),
[`ff0f979`](ff0f9795f3),
[`2d89d2b`](2d89d2b35c),
[`aac9a19`](aac9a19bdf),
[`06de50f`](06de50ff37),
[`aa4d981`](aa4d981e44),
[`18b1e3b`](18b1e3bd2b),
[`957d82b`](957d82b984),
[`b65756e`](b65756e9e8),
[`22e371a`](22e371ae4c),
[`d29b91f`](d29b91fa50),
[`7b4f817`](7b4f817caf),
[`176d420`](176d42002c),
[`3f9ca4d`](3f9ca4d9ac),
[`8a3c066`](8a3c06600a),
[`49ead1e`](49ead1e1e8),
[`3673369`](36733691f9),
[`c465e87`](c465e87ab4),
[`ae533e4`](ae533e4019),
[`ea33052`](ea330520a3),
[`5764ede`](5764edee7a),
[`f09b184`](f09b184cc5),
[`a7d29de`](a7d29decee),
[`d334399`](d334399004),
[`44416da`](44416da7ff),
[`bdd8b4e`](bdd8b4ee3c)]:
    -   @browserbasehq/stagehand@3.1.0

## @browserbasehq/stagehand-evals@1.1.8

### Patch Changes

- Updated dependencies
\[[`7584f3e`](7584f3e92e),
[`1e1c9c1`](1e1c9c1577),
[`6bef890`](6bef89090e),
[`ffd4b33`](ffd4b335a8),
[`677bff5`](677bff5834),
[`65ff464`](65ff464bc1),
[`101bcf2`](101bcf2da8),
[`0a94301`](0a94301caa),
[`b27c04d`](b27c04d278),
[`afbd08b`](afbd08bb63),
[`e3db9aa`](e3db9aa863),
[`0e8d569`](0e8d5695f6),
[`ff0f979`](ff0f9795f3),
[`2d89d2b`](2d89d2b35c),
[`aac9a19`](aac9a19bdf),
[`06de50f`](06de50ff37),
[`aa4d981`](aa4d981e44),
[`18b1e3b`](18b1e3bd2b),
[`957d82b`](957d82b984),
[`b65756e`](b65756e9e8),
[`22e371a`](22e371ae4c),
[`d29b91f`](d29b91fa50),
[`7b4f817`](7b4f817caf),
[`176d420`](176d42002c),
[`3f9ca4d`](3f9ca4d9ac),
[`8a3c066`](8a3c06600a),
[`49ead1e`](49ead1e1e8),
[`3673369`](36733691f9),
[`c465e87`](c465e87ab4),
[`ae533e4`](ae533e4019),
[`ea33052`](ea330520a3),
[`5764ede`](5764edee7a),
[`f09b184`](f09b184cc5),
[`a7d29de`](a7d29decee),
[`d334399`](d334399004),
[`44416da`](44416da7ff),
[`bdd8b4e`](bdd8b4ee3c)]:
    -   @browserbasehq/stagehand@3.1.0

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
@browserbasehq/stagehand@3.1.0
2026-02-24 15:23:27 -08:00
Sameel
49ead1e1e8
[STG-1182] cache config (#1581)
# 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 -->
2026-02-24 14:58:30 -08:00
Sean McGuire
93bbf026e9
[chore]: add error cause lint rule (#1745)
# 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. -->
2026-02-24 14:03:33 -08:00
Sean McGuire
1e7b7e98e5
[docs]: revert openapi spec gen changes (#1746)
# 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. -->
2026-02-24 12:35:17 -08:00