default agent to hybrid mode

[tkattkat]

why

Dom mode has been deprecated for a while, and is now being replaced with hybrid as a default

what changed

• When a hybrid capable model is provided, it is used with hybrid mode by default
• When a non hybrid capable model is provided, it is used with dom mode
• if dom or hybrid is explicitly provided, it will use the provided mode

test plan

tested locally + wrote tests

---

Summary by cubic

Set the default v3 agent mode to hybrid, with automatic routing to dom for models that aren’t hybrid-capable. Explicit mode settings are always respected; CUA behavior is unchanged.

• New Features
  • Auto-selects "hybrid" for models matching HYBRID_CAPABLE_MODEL_PATTERNS (gemini-3, claude, gpt-5.4, gpt-5.5); otherwise uses "dom".
  • Routes using the provided agent model (string or config), or falls back to the Stagehand-level model when undefined.
  • Honors explicit mode (dom, hybrid, cua); if mode is unset, deprecated cua: true enables CUA.
  • Logs the resolved mode and warns when "hybrid" is used with non-hybrid-capable models.
  • Adds unit tests for routing and handler fallbacks.

^{Written for commit 01e7d69. Summary will update on new commits. Review in cubic}

[changeset-bot]

🦋 Changeset detected

Latest commit: 4280a2b

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

This PR includes changesets to release 4 packages

Name	Type
@browserbasehq/stagehand	Patch
@browserbasehq/stagehand-evals	Patch
@browserbasehq/stagehand-server-v3	Patch
@browserbasehq/stagehand-server-v4	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]

2 issues found across 5 files

Confidence score: 3/5

• There is a concrete regression risk in packages/core/lib/v3/v3.ts: isCuaMode now appears to let deprecated cua: true override an explicit mode, which can change behavior for inputs like { mode: "dom", cua: true } and break prior expectations.
• packages/core/lib/v3/types/public/agent.ts introduces a hardcoded model-name allowlist for hybrid routing, which conflicts with the stated rule against fixed allowed-model checks and could cause brittle routing as models evolve.
• Given the high confidence and user-facing behavior change in mode resolution, this carries some merge risk until precedence is clarified/fixed.
• Pay close attention to packages/core/lib/v3/v3.ts and packages/core/lib/v3/types/public/agent.ts - mode precedence and hardcoded model allowlisting need validation before merge.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/core/lib/v3/types/public/agent.ts">

<violation number="1" location="packages/core/lib/v3/types/public/agent.ts:654">
P2: Custom agent: **Ensure we never check against hardcoded lists of allowed LLM model names**

Hardcoded model-name pattern allowlist introduced for hybrid routing; this conflicts with the rule to avoid new allowed-model checks and accept arbitrary model names unless guarding known-bad models.</violation>
</file>

<file name="packages/core/lib/v3/v3.ts">

<violation number="1" location="packages/core/lib/v3/v3.ts:1955">
P1: `isCuaMode` ignores an explicit `mode` when the deprecated `cua: true` is also present. With `{ mode: "dom", cua: true }`, the old logic respected the explicit mode (`isCuaMode = false`), but the new `|| options?.cua === true` clause unconditionally forces CUA mode. Since `effectiveMode` already accounts for the `cua: true` fallback, the extra disjunct is redundant in the happy path and wrong in the conflict path.</violation>
</file>

Architecture diagram

sequenceDiagram
    participant Client
    participant V3 as V3 (Core)
    participant Patterns as Agent Constants
    participant Handler as V3AgentHandler

    Client->>V3: act() / extract() (with options)

    Note over V3,Patterns: Resolve Effective Agent Mode
    
    alt Explicit mode in options
        V3->>V3: Use provided mode (dom|hybrid|cua)
    else NEW: Auto-routing (no mode provided)
        V3->>V3: Resolve model (agent-specific OR global default)
        V3->>Patterns: Check model against HYBRID_CAPABLE_MODEL_PATTERNS
        Patterns-->>V3: Match found?
        
        alt Model is hybrid-capable (e.g., Claude, Gemini-3, GPT-5)
            V3->>V3: NEW: Default to "hybrid"
        else Model is legacy (e.g., GPT-4o)
            V3->>V3: NEW: Default to "dom"
        end
    else Legacy CUA Flag
        V3->>V3: Set mode to "cua" (if cua: true)
    end

    V3->>V3: CHANGED: Log resolved mode and model context

    V3->>Handler: Initialize(resolvedMode, model, tools)

    Note over Handler: Validation Logic
    
    Handler->>Patterns: CHANGED: Check isHybridCapable(model)
    
    opt NEW: Mode is "hybrid" but model not in capable list
        Handler->>Handler: Log performance warning for non-recommended model
    end

    Handler-->>V3: Handler instance
    V3-->>Client: Execution result / stream

Loading

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review, or fix all with cubic.}

[cubic-dev-ai]

No issues found across 5 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

Architecture diagram

sequenceDiagram
    participant Client
    participant V3 as V3 (Main Orchestrator)
    participant Patterns as HYBRID_CAPABLE_MODEL_PATTERNS
    participant Handler as V3AgentHandler
    participant Logger

    Note over Client,Handler: Agent Initialization & Mode Routing

    Client->>V3: act(options)
    
    V3->>V3: resolveAgentMode()
    
    alt options.mode is explicitly set
        Note over V3: Respects user choice (dom | hybrid | cua)
    else NEW: options.mode is undefined
        opt options.cua is true (deprecated)
            V3->>V3: Set mode to "cua"
        end
        
        Note over V3,Patterns: NEW: Dynamic Default Resolution
        V3->>Patterns: Match model name against patterns
        Patterns-->>V3: isHybridCapable?
        
        alt isHybridCapable is true
            V3->>V3: CHANGED: Default to "hybrid"
        else
            V3->>V3: Default to "dom"
        end
    end

    V3->>Logger: NEW: Log resolved mode (dom/hybrid/cua)

    V3->>Handler: init(resolvedMode, model)
    
    Note over Handler: Agent Runtime Validation

    Handler->>Patterns: CHANGED: Check compatibility for warning
    Patterns-->>Handler: isHybridCapable?

    opt Handler.mode == "hybrid" AND NOT isHybridCapable
        Handler->>Logger: CHANGED: Log performance warning
    end

    Handler-->>V3: Ready
    V3-->>Client: Execution Result

Loading