move hybrid mode behind experimental (#1433)

tkattkat · web-flow · commit e0e22e06bc75 · 2025-12-18T10:56:44.000-08:00
# why put hybrid mode behind experimental flag # what changed added experimental to jsdoc & experimental feature validation # test plan  --- ## Summary by cubic Moved hybrid mode behind the experimental flag to prevent accidental use. Using mode: 'hybrid' now requires experimental: true; otherwise validation will fail. - **Migration** - If you use mode: 'hybrid', set experimental: true in the Stagehand constructor. <sup>Written for commit ae648ab. Summary will update automatically on new commits.</sup>
diff --git a/.changeset/curly-webs-fetch.md b/.changeset/curly-webs-fetch.md
@@ -0,0 +1,5 @@
+---
+"@browserbasehq/stagehand": patch
+---
+
+Put hybrid mode behind experimental
diff --git a/packages/core/lib/v3/agent/utils/validateExperimentalFeatures.ts b/packages/core/lib/v3/agent/utils/validateExperimentalFeatures.ts
@@ -23,6 +23,7 @@ export interface AgentValidationOptions {
  * This utility consolidates all validation checks for both CUA and non-CUA agent paths:
  * - Invalid argument errors for CUA (streaming, abort signal, message continuation are not supported)
  * - Experimental feature checks for integrations and tools (both CUA and non-CUA)
+ * - Experimental feature checks for hybrid mode (requires experimental: true)
  * - Experimental feature checks for non-CUA only (callbacks, signal, messages, streaming)
  *
  * Throws StagehandInvalidArgumentError for invalid/unsupported configurations.
@@ -67,6 +68,9 @@ export function validateExperimentalFeatures(
   if (hasIntegrations || hasTools) {
     features.push("MCP integrations and custom tools");
   }
+  if (agentConfig?.mode === "hybrid") {
+    features.push("hybrid mode");
+  }
 
   // Check streaming mode (either explicit or derived from config) - only for non-CUA
   if (!agentConfig?.cua && (isStreaming || agentConfig?.stream)) {
diff --git a/packages/core/lib/v3/types/public/agent.ts b/packages/core/lib/v3/types/public/agent.ts
@@ -442,6 +442,7 @@ export type AgentConfig = {
    * - 'dom' (default): Uses DOM-based tools (act, fillForm) for structured interactions
    * - 'hybrid': Uses coordinate-based tools (click, type, dragAndDrop, clickAndHold, fillFormVision)
    *             for visual/screenshot-based interactions
+   * @experimental hybrid mode requires `experimental: true` in Stagehand constructor
    */
   mode?: AgentToolMode;
 };

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"@browserbasehq/stagehand": patch
 +---
++
 +Put hybrid mode behind experimental