Add cua to mode by tkattkat · Pull Request #1432 · browserbase/stagehand

tkattkat · 2025-12-18T01:40:23Z

why

Move cua to mode enum for consistency across modes

what changed

deprecated cua: true, in favor of mode: "cua"

test plan

tested locally

Summary by cubic

Move CUA config from a boolean flag to the mode enum for consistency across agent modes. Use mode: "cua"; cua: true is deprecated and now emits a runtime warning.

Refactors
- Added "cua" to AgentToolMode and updated public types/tests.
- Deprecated AgentConfig.cua with a deprecation warning.
- Centralized CUA detection (mode: "cua" or legacy cua: true) in validation, cache, and agent creation.
- Improved agent logging to include mode and unified CUA feature checks.
Migration
- Replace AgentConfig cua: true with mode: "cua".

^{Written for commit 1f1b807. Summary will update automatically on new commits.}

changeset-bot · 2025-12-18T01:40:26Z

🦋 Changeset detected

Latest commit: 1f1b807

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@browserbasehq/stagehand	Patch
@browserbasehq/stagehand-evals	Patch
@browserbasehq/stagehand-server	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

cubic-dev-ai

No issues found across 5 files

cubic-dev-ai

No issues found across 5 files

greptile-apps · 2025-12-18T18:28:24Z

Greptile Summary

Moves CUA configuration from a boolean cua: true flag to the mode enum as mode: "cua" for consistency with existing "dom" and "hybrid" modes. The deprecated cua boolean is still supported with runtime warnings to ensure backward compatibility.

Key changes:

Added "cua" to the AgentToolMode union type
Deprecated AgentConfig.cua property with @deprecated JSDoc annotation
Updated validation logic to detect CUA via mode === "cua" || cua === true
Added deprecation warnings (logger + console.warn) when cua: true is used
Included proper changeset for patch release

Issues found:

AgentCache.buildConfigSignature() only checks the deprecated cua boolean flag and doesn't account for mode: "cua", which will cause cache mismatches when users adopt the new API (lines 115, 117 in packages/core/lib/v3/cache/AgentCache.ts)

Migration path:
Users should replace { cua: true } with { mode: "cua" }. Examples and tests still use the old API but emit warnings.

Confidence Score: 3/5

Safe to merge after fixing cache signature bug—deprecation path is sound but cache will misbehave
The refactoring is well-structured with proper deprecation warnings and backward compatibility. However, the cache signature generation has a critical bug that doesn't account for mode: "cua", only checking the deprecated cua boolean. This will cause cache misses/hits to behave incorrectly when users switch to the new API. The validation logic is correctly updated everywhere else.
Pay close attention to packages/core/lib/v3/cache/AgentCache.ts - the cache signature must be fixed to recognize both the new and deprecated CUA configurations

Important Files Changed

Filename	Overview
packages/core/lib/v3/types/public/agent.ts	Added "cua" to AgentToolMode enum and deprecated the cua boolean property with proper JSDoc annotations
packages/core/lib/v3/v3.ts	Implements backward compatibility by detecting both mode: "cua" and deprecated cua: true, with deprecation warnings logged
packages/core/lib/v3/agent/utils/validateExperimentalFeatures.ts	Updated validation logic to check both mode: "cua" and deprecated cua: true flag consistently across all validation checks

Sequence Diagram

sequenceDiagram
    participant User
    participant V3Agent
    participant Validator
    participant CuaHandler
    participant Cache

    User->>V3Agent: agent({ mode: "cua" })
    Note over V3Agent: Detect CUA mode
    V3Agent->>V3Agent: isCuaMode = mode === "cua" || cua === true
    
    alt cua: true (deprecated)
        V3Agent->>V3Agent: Log deprecation warning
        V3Agent->>User: console.warn()
    end
    
    V3Agent->>Validator: validateExperimentalFeatures(agentConfig)
    Validator->>Validator: isCuaMode = mode === "cua" || cua === true
    
    alt CUA mode enabled
        Validator->>Validator: Check unsupported features (streaming, abort, messages)
        alt Unsupported features found
            Validator-->>V3Agent: throw StagehandInvalidArgumentError
        end
    end
    
    alt Not experimental mode
        Validator->>Validator: Check experimental features (integrations, tools)
        alt Experimental features found
            Validator-->>V3Agent: throw ExperimentalNotConfiguredError
        end
    end
    
    V3Agent->>Cache: buildConfigSignature(agentConfig)
    Note over Cache: Should check both mode and cua flag
    Cache-->>V3Agent: configSignature
    
    V3Agent->>CuaHandler: Create CUA agent handler
    CuaHandler-->>V3Agent: agent instance
    V3Agent-->>User: return agent

greptile-apps

Additional Comments (2)

packages/core/lib/v3/cache/AgentCache.ts, line 115 (link)

logic: cache signature doesn't account for mode: "cua"—only checks deprecated cua boolean
packages/core/lib/v3/cache/AgentCache.ts, line 117 (link)

logic: should also check mode === "cua" to match the pattern used elsewhere

_{Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!}

_{4 files reviewed, 2 comments}

_{Edit Code Review Agent Settings | Greptile}

@tkattkat

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.0.7 ### Patch Changes - [#1461](#1461) [`0f3991e`](0f3991e) Thanks [@tkattkat](https://github.com/tkattkat)! - Move hybrid mode out of experimental - [#1433](#1433) [`e0e22e0`](e0e22e0) Thanks [@tkattkat](https://github.com/tkattkat)! - Put hybrid mode behind experimental - [#1456](#1456) [`f261051`](f261051) Thanks [@shrey150](https://github.com/shrey150)! - Invoke page.hover for agent move action - [#1473](#1473) [`e021674`](e021674) Thanks [@shrey150](https://github.com/shrey150)! - Add safety confirmation support for OpenAI + Google CUA - [#1399](#1399) [`6a5496f`](6a5496f) Thanks [@tkattkat](https://github.com/tkattkat)! - Ensure cua agent is killed when stagehand.close is called - [#1436](#1436) [`fea1700`](fea1700) Thanks [@miguelg719](https://github.com/miguelg719)! - Fix auto-load key for act/extract/observe parametrized models on api - [#1439](#1439) [`5b288d9`](5b288d9) Thanks [@tkattkat](https://github.com/tkattkat)! - Remove base64 from agent actions array ( still present in messages object ) - [#1408](#1408) [`e822f5a`](e822f5a) Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - allow for act() cache hit when variable values change - [#1472](#1472) [`638efc7`](638efc7) Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - fix: agent cache not refreshed on action failure - [#1424](#1424) [`a890f16`](a890f16) Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - fix: "Error: -32000 Failed to convert response to JSON: CBOR: stack limit exceeded" - [#1418](#1418) [`934f492`](934f492) Thanks [@miguelg719](https://github.com/miguelg719)! - Cleanup handlers and bus listeners on close - [#1430](#1430) [`bd2db92`](bd2db92) Thanks [@shrey150](https://github.com/shrey150)! - Fix CUA model coordinate translation - [#1465](#1465) [`51e0170`](51e0170) Thanks [@miguelg719](https://github.com/miguelg719)! - Add media resolution high provider option to gemini 3 hybrid agent - [#1431](#1431) [`05f5580`](05f5580) Thanks [@tkattkat](https://github.com/tkattkat)! - Update the cache handling for agent - [#1432](#1432) [`f56a9c2`](f56a9c2) Thanks [@tkattkat](https://github.com/tkattkat)! - Deprecate cua: true in favor of mode: "cua" - [#1406](#1406) [`b40ae11`](b40ae11) Thanks [@tkattkat](https://github.com/tkattkat)! - Add support for hovering with coordinates ( page.hover ) - [#1407](#1407) [`0d2b398`](0d2b398) Thanks [@tkattkat](https://github.com/tkattkat)! - Clean up page methods - [#1412](#1412) [`cd01f29`](cd01f29) Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - fix: load GOOGLE_API_KEY from .env - [#1462](#1462) [`a734fca`](a734fca) Thanks [@shrey150](https://github.com/shrey150)! - fix: correctly pass userDataDir to chrome launcher - [#1466](#1466) [`b342acf`](b342acf) Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - move playwright to optional dependencies - [#1440](#1440) [`2987cd1`](2987cd1) Thanks [@tkattkat](https://github.com/tkattkat)! - [Feature] support excluding tools from agent - [#1455](#1455) [`dfab1d5`](dfab1d5) Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - update aisdk client to better enforce structured output with deepseek models - [#1428](#1428) [`4d71162`](4d71162) Thanks [@tkattkat](https://github.com/tkattkat)! - Add "hybrid" mode to stagehand agent ## @browserbasehq/stagehand-server@3.2.0 ### Minor Changes - [#1459](#1459) [`abb3469`](abb3469) Thanks [@monadoid](https://github.com/monadoid)! - Added building of binaries - [#1457](#1457) [`5fc1281`](5fc1281) Thanks [@monadoid](https://github.com/monadoid)! - First changeset for stagehand-server - [#1469](#1469) [`d634d45`](d634d45) Thanks [@monadoid](https://github.com/monadoid)! - Bump to test binary builds ### Patch Changes - Updated dependencies \[[`0f3991e`](0f3991e), [`e0e22e0`](e0e22e0), [`f261051`](f261051), [`e021674`](e021674), [`6a5496f`](6a5496f), [`fea1700`](fea1700), [`5b288d9`](5b288d9), [`e822f5a`](e822f5a), [`638efc7`](638efc7), [`a890f16`](a890f16), [`934f492`](934f492), [`bd2db92`](bd2db92), [`51e0170`](51e0170), [`05f5580`](05f5580), [`f56a9c2`](f56a9c2), [`b40ae11`](b40ae11), [`0d2b398`](0d2b398), [`cd01f29`](cd01f29), [`a734fca`](a734fca), [`b342acf`](b342acf), [`2987cd1`](2987cd1), [`dfab1d5`](dfab1d5), [`4d71162`](4d71162)]: - @browserbasehq/stagehand@3.0.7 ## @browserbasehq/stagehand-evals@1.1.6 ### Patch Changes - [#1373](#1373) [`cadd192`](cadd192) Thanks [@tkattkat](https://github.com/tkattkat)! - Update screenshot collector in agent evals cli - Updated dependencies \[[`0f3991e`](0f3991e), [`e0e22e0`](e0e22e0), [`f261051`](f261051), [`e021674`](e021674), [`6a5496f`](6a5496f), [`fea1700`](fea1700), [`5b288d9`](5b288d9), [`e822f5a`](e822f5a), [`638efc7`](638efc7), [`a890f16`](a890f16), [`934f492`](934f492), [`bd2db92`](bd2db92), [`51e0170`](51e0170), [`05f5580`](05f5580), [`f56a9c2`](f56a9c2), [`b40ae11`](b40ae11), [`0d2b398`](0d2b398), [`cd01f29`](cd01f29), [`a734fca`](a734fca), [`b342acf`](b342acf), [`2987cd1`](2987cd1), [`dfab1d5`](dfab1d5), [`4d71162`](4d71162)]: - @browserbasehq/stagehand@3.0.7 Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

# why Move cua to mode enum for consistency across modes # what changed deprecated cua: true, in favor of mode: "cua" # test plan tested locally  --- ## Summary by cubic Move CUA config from a boolean flag to the mode enum for consistency across agent modes. Use mode: "cua"; cua: true is deprecated and now emits a runtime warning. - **Refactors** - Added "cua" to AgentToolMode and updated public types/tests. - Deprecated AgentConfig.cua with a deprecation warning. - Centralized CUA detection (mode: "cua" or legacy cua: true) in validation, cache, and agent creation. - Improved agent logging to include mode and unified CUA feature checks. - **Migration** - Replace AgentConfig cua: true with mode: "cua". <sup>Written for commit 1f1b807. Summary will update automatically on new commits.</sup>

@tkattkat

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.0.7 ### Patch Changes - [browserbase#1461](browserbase#1461) [`0f3991e`](browserbase@0f3991e) Thanks [@tkattkat](https://github.com/tkattkat)! - Move hybrid mode out of experimental - [browserbase#1433](browserbase#1433) [`e0e22e0`](browserbase@e0e22e0) Thanks [@tkattkat](https://github.com/tkattkat)! - Put hybrid mode behind experimental - [browserbase#1456](browserbase#1456) [`f261051`](browserbase@f261051) Thanks [@shrey150](https://github.com/shrey150)! - Invoke page.hover for agent move action - [browserbase#1473](browserbase#1473) [`e021674`](browserbase@e021674) Thanks [@shrey150](https://github.com/shrey150)! - Add safety confirmation support for OpenAI + Google CUA - [browserbase#1399](browserbase#1399) [`6a5496f`](browserbase@6a5496f) Thanks [@tkattkat](https://github.com/tkattkat)! - Ensure cua agent is killed when stagehand.close is called - [browserbase#1436](browserbase#1436) [`fea1700`](browserbase@fea1700) Thanks [@miguelg719](https://github.com/miguelg719)! - Fix auto-load key for act/extract/observe parametrized models on api - [browserbase#1439](browserbase#1439) [`5b288d9`](browserbase@5b288d9) Thanks [@tkattkat](https://github.com/tkattkat)! - Remove base64 from agent actions array ( still present in messages object ) - [browserbase#1408](browserbase#1408) [`e822f5a`](browserbase@e822f5a) Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - allow for act() cache hit when variable values change - [browserbase#1472](browserbase#1472) [`638efc7`](browserbase@638efc7) Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - fix: agent cache not refreshed on action failure - [browserbase#1424](browserbase#1424) [`a890f16`](browserbase@a890f16) Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - fix: "Error: -32000 Failed to convert response to JSON: CBOR: stack limit exceeded" - [browserbase#1418](browserbase#1418) [`934f492`](browserbase@934f492) Thanks [@miguelg719](https://github.com/miguelg719)! - Cleanup handlers and bus listeners on close - [browserbase#1430](browserbase#1430) [`bd2db92`](browserbase@bd2db92) Thanks [@shrey150](https://github.com/shrey150)! - Fix CUA model coordinate translation - [browserbase#1465](browserbase#1465) [`51e0170`](browserbase@51e0170) Thanks [@miguelg719](https://github.com/miguelg719)! - Add media resolution high provider option to gemini 3 hybrid agent - [browserbase#1431](browserbase#1431) [`05f5580`](browserbase@05f5580) Thanks [@tkattkat](https://github.com/tkattkat)! - Update the cache handling for agent - [browserbase#1432](browserbase#1432) [`f56a9c2`](browserbase@f56a9c2) Thanks [@tkattkat](https://github.com/tkattkat)! - Deprecate cua: true in favor of mode: "cua" - [browserbase#1406](browserbase#1406) [`b40ae11`](browserbase@b40ae11) Thanks [@tkattkat](https://github.com/tkattkat)! - Add support for hovering with coordinates ( page.hover ) - [browserbase#1407](browserbase#1407) [`0d2b398`](browserbase@0d2b398) Thanks [@tkattkat](https://github.com/tkattkat)! - Clean up page methods - [browserbase#1412](browserbase#1412) [`cd01f29`](browserbase@cd01f29) Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - fix: load GOOGLE_API_KEY from .env - [browserbase#1462](browserbase#1462) [`a734fca`](browserbase@a734fca) Thanks [@shrey150](https://github.com/shrey150)! - fix: correctly pass userDataDir to chrome launcher - [browserbase#1466](browserbase#1466) [`b342acf`](browserbase@b342acf) Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - move playwright to optional dependencies - [browserbase#1440](browserbase#1440) [`2987cd1`](browserbase@2987cd1) Thanks [@tkattkat](https://github.com/tkattkat)! - [Feature] support excluding tools from agent - [browserbase#1455](browserbase#1455) [`dfab1d5`](browserbase@dfab1d5) Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - update aisdk client to better enforce structured output with deepseek models - [browserbase#1428](browserbase#1428) [`4d71162`](browserbase@4d71162) Thanks [@tkattkat](https://github.com/tkattkat)! - Add "hybrid" mode to stagehand agent ## @browserbasehq/stagehand-server@3.2.0 ### Minor Changes - [browserbase#1459](browserbase#1459) [`abb3469`](browserbase@abb3469) Thanks [@monadoid](https://github.com/monadoid)! - Added building of binaries - [browserbase#1457](browserbase#1457) [`5fc1281`](browserbase@5fc1281) Thanks [@monadoid](https://github.com/monadoid)! - First changeset for stagehand-server - [browserbase#1469](browserbase#1469) [`d634d45`](browserbase@d634d45) Thanks [@monadoid](https://github.com/monadoid)! - Bump to test binary builds ### Patch Changes - Updated dependencies \[[`0f3991e`](browserbase@0f3991e), [`e0e22e0`](browserbase@e0e22e0), [`f261051`](browserbase@f261051), [`e021674`](browserbase@e021674), [`6a5496f`](browserbase@6a5496f), [`fea1700`](browserbase@fea1700), [`5b288d9`](browserbase@5b288d9), [`e822f5a`](browserbase@e822f5a), [`638efc7`](browserbase@638efc7), [`a890f16`](browserbase@a890f16), [`934f492`](browserbase@934f492), [`bd2db92`](browserbase@bd2db92), [`51e0170`](browserbase@51e0170), [`05f5580`](browserbase@05f5580), [`f56a9c2`](browserbase@f56a9c2), [`b40ae11`](browserbase@b40ae11), [`0d2b398`](browserbase@0d2b398), [`cd01f29`](browserbase@cd01f29), [`a734fca`](browserbase@a734fca), [`b342acf`](browserbase@b342acf), [`2987cd1`](browserbase@2987cd1), [`dfab1d5`](browserbase@dfab1d5), [`4d71162`](browserbase@4d71162)]: - @browserbasehq/stagehand@3.0.7 ## @browserbasehq/stagehand-evals@1.1.6 ### Patch Changes - [browserbase#1373](browserbase#1373) [`cadd192`](browserbase@cadd192) Thanks [@tkattkat](https://github.com/tkattkat)! - Update screenshot collector in agent evals cli - Updated dependencies \[[`0f3991e`](browserbase@0f3991e), [`e0e22e0`](browserbase@e0e22e0), [`f261051`](browserbase@f261051), [`e021674`](browserbase@e021674), [`6a5496f`](browserbase@6a5496f), [`fea1700`](browserbase@fea1700), [`5b288d9`](browserbase@5b288d9), [`e822f5a`](browserbase@e822f5a), [`638efc7`](browserbase@638efc7), [`a890f16`](browserbase@a890f16), [`934f492`](browserbase@934f492), [`bd2db92`](browserbase@bd2db92), [`51e0170`](browserbase@51e0170), [`05f5580`](browserbase@05f5580), [`f56a9c2`](browserbase@f56a9c2), [`b40ae11`](browserbase@b40ae11), [`0d2b398`](browserbase@0d2b398), [`cd01f29`](browserbase@cd01f29), [`a734fca`](browserbase@a734fca), [`b342acf`](browserbase@b342acf), [`2987cd1`](browserbase@2987cd1), [`dfab1d5`](browserbase@dfab1d5), [`4d71162`](browserbase@4d71162)]: - @browserbasehq/stagehand@3.0.7

tkattkat added 2 commits December 17, 2025 17:39

Add cua to mode

6264a36

format

f4922d0

cubic-dev-ai Bot reviewed Dec 18, 2025

View reviewed changes

tkattkat marked this pull request as draft December 18, 2025 02:35

tkattkat marked this pull request as ready for review December 18, 2025 18:23

cubic-dev-ai Bot reviewed Dec 18, 2025

View reviewed changes

greptile-apps Bot reviewed Dec 18, 2025

View reviewed changes

pirate approved these changes Dec 18, 2025

View reviewed changes

tkattkat and others added 3 commits December 18, 2025 11:00

Merge branch 'main' into Add-cua-to-mode

d8035c0

Merge branch 'main' into Add-cua-to-mode

2591f94

update agent cache

1f1b807

tkattkat merged commit f56a9c2 into main Dec 18, 2025
16 checks passed

This was referenced Dec 18, 2025

Version Packages #1414

Merged

Release Stagehand packages CloudEngineHub/stagehand#1

Open

Version Packages kenchikuliu/stagehand#1

Open

Version Packages shaneholloman/stagehand#1

Open

Navigation Menu

Add cua to mode - #1432

Add cua to mode#1432
tkattkat merged 5 commits into
mainfrom
Add-cua-to-mode

tkattkat commented Dec 18, 2025 •

edited by cubic-dev-ai Bot

Loading

Uh oh!

changeset-bot Bot commented Dec 18, 2025 •

edited

Loading

Uh oh!

cubic-dev-ai Bot left a comment

Uh oh!

cubic-dev-ai Bot left a comment

Uh oh!

greptile-apps Bot commented Dec 18, 2025

Uh oh!

greptile-apps Bot left a comment •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

tkattkat commented Dec 18, 2025 • edited by cubic-dev-ai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

why

what changed

test plan

Summary by cubic

Uh oh!

changeset-bot Bot commented Dec 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

cubic-dev-ai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

greptile-apps Bot commented Dec 18, 2025

Greptile Summary

Confidence Score: 3/5

Important Files Changed

Sequence Diagram

Uh oh!

greptile-apps Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Additional Comments (2)

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

tkattkat commented Dec 18, 2025 •

edited by cubic-dev-ai Bot

Loading

changeset-bot Bot commented Dec 18, 2025 •

edited

Loading

greptile-apps Bot left a comment •

edited

Loading