browserbase/stagehand @browserbasehq/stagehand@3.1.0

on GitHub

Minor Changes

• #1681 e3db9aa Thanks @tkattkat! - Add cookie management APIs: context.addCookies(), context.clearCookies(), & context.cookies()

• #1672 b65756e Thanks @seanmcguire12! - add boolean keepAlive parameter to allow for configuring whether the browser should be closed when stagehand.close() is called.

• #1708 176d420 Thanks @seanmcguire12! - add context.setExtraHTTPHeaders()

• #1611 8a3c066 Thanks @monadoid! - Using mode enum instead of old cua boolean in openapi spec

• #1632 afbd08b Thanks @pirate! - Remove automatic .env loading via dotenv.

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

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

Patch Changes

• #1683 7584f3e Thanks @seanmcguire12! - fix: include shadow DOM in .count() & .nth() & support xpath predicates

• #1644 1e1c9c1 Thanks @monadoid! - Fix unhandled CDP detaches by returning the original sendCDP promise

• #1729 6bef890 Thanks @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 ffd4b33 Thanks @tkattkat! - Fix [Agent] - Address bug causing issues with continuing a conversation from past messages in dom mode

• #1614 677bff5 Thanks @miguelg719! - Enforce - regex validation on act/observe for elementId

• #1580 65ff464 Thanks @tkattkat! - Add unified variables support across act and agent with a single VariableValue type

• #1666 101bcf2 Thanks @Kylejeong2! - add support for codex models

• #1728 0a94301 Thanks @seanmcguire12! - handle potential race condition on .close() when using the Stagehand API

• #1664 b27c04d Thanks @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)

• #1624 0e8d569 Thanks @seanmcguire12! - fix issue where screenshot masks were not being applied to dialog elements

• #1596 ff0f979 Thanks @tkattkat! - Update usage/metrics handling in agent

• #1631 2d89d2b Thanks @miguelg719! - Add right and middle click support to act and observe

• #1697 aac9a19 Thanks @shrey150! - fix: support <frame> elements in XPath frame boundary detection so act() works on legacy <frameset> pages

• #1692 06de50f Thanks @shrey150! - fix: skip piercer injection for chrome-extension:// and other non-HTML targets

• #1613 aa4d981 Thanks @miguelg719! - SupportedUnderstudyAction Enum validation for 'method' on act/observe inference

• #1652 18b1e3b Thanks @miguelg719! - Add support for gemini 3 flash and pro in hybrid/cua agent

• #1706 957d82b Thanks @chrisreadsf! - Add GLM to prompt-based JSON fallback for models without native structured output support

• #1633 22e371a Thanks @tkattkat! - Add warning when incorrect models are used with agents hybrid mode

• #1673 d29b91f Thanks @miguelg719! - Add multi-region support for Stagehand API with region-specific endpoints

• #1695 7b4f817 Thanks @tkattkat! - Fix: zod bug when pinning zod to v3 and using structured output in agent

• #1609 3f9ca4d Thanks @miguelg719! - Add SupportedUnderstudyActions to observe system prompt

• #1581 49ead1e Thanks @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 for more details.

• #1642 3673369 Thanks @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 c465e87 Thanks @monadoid! - Supports request header authentication with connectToMCPServer

• #1705 ae533e4 Thanks @seanmcguire12! - include error cause in UnderstudyCommandException

• #1636 ea33052 Thanks @miguelg719! - Include executionModel on the AgentConfigSchema

• #1679 5764ede Thanks @shrey150! - fix issue where locator.count() was not working with xpaths that have attribute predicates

• #1646 f09b184 Thanks @miguelg719! - Add user-agent to CDP connections

• #1637 a7d29de Thanks @miguelg719! - Improve error and warning message for legacy model format

• #1685 d334399 Thanks @tkattkat! - Bump ai sdk & google provider version

• #1662 44416da Thanks @seanmcguire12! - fix issue where locator.fill() was not working on elements that require direct value setting

• #1612 bdd8b4e Thanks @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.