Add cua to mode #1432

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

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

Version Packages CloudEngineHub/stagehand#1

Open

Version Packages kenchikuliu/stagehand#1

Open

Version Packages shaneholloman/stagehand#1

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add cua to mode #1432

Add cua to mode #1432

Uh oh!

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!

3 participants

Add cua to mode #1432

Add cua to mode #1432

Uh oh!

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!

3 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