stagehand 3.7.0 → 3.18.0

data/rbi/stagehand/models/session_act_params.rbi

@@ -11,6 +11,10 @@ module Stagehand
           T.any(Stagehand::SessionActParams, Stagehand::Internal::AnyHash)
         end
 
+      # Unique session identifier
+      sig { returns(String) }
+      attr_accessor :id
+
       # Natural language instruction or Action object
       sig { returns(T.any(String, Stagehand::Action)) }
       attr_accessor :input
@@ -43,6 +47,7 @@ module Stagehand
 
       sig do
         params(
+          id: String,
           input: T.any(String, Stagehand::Action::OrHash),
           frame_id: T.nilable(String),
           options: Stagehand::SessionActParams::Options::OrHash,
@@ -52,6 +57,8 @@ module Stagehand
         ).returns(T.attached_class)
       end
       def self.new(
+        # Unique session identifier
+        id:,
         # Natural language instruction or Action object
         input:,
         # Target frame ID for the action
@@ -66,6 +73,7 @@ module Stagehand
       sig do
         override.returns(
           {
+            id: String,
             input: T.any(String, Stagehand::Action),
             frame_id: T.nilable(String),
             options: Stagehand::SessionActParams::Options,
@@ -118,18 +126,55 @@ module Stagehand
         sig { params(timeout: Float).void }
         attr_writer :timeout
 
-        # Variables to substitute in the action instruction
-        sig { returns(T.nilable(T::Hash[Symbol, String])) }
+        # Variables to substitute in the action instruction. Accepts flat primitives or {
+        # value, description? } objects.
+        sig do
+          returns(
+            T.nilable(
+              T::Hash[
+                Symbol,
+                T.any(
+                  String,
+                  Float,
+                  T::Boolean,
+                  Stagehand::SessionActParams::Options::Variable::UnionMember3
+                )
+              ]
+            )
+          )
+        end
         attr_reader :variables
 
-        sig { params(variables: T::Hash[Symbol, String]).void }
+        sig do
+          params(
+            variables:
+              T::Hash[
+                Symbol,
+                T.any(
+                  String,
+                  Float,
+                  T::Boolean,
+                  Stagehand::SessionActParams::Options::Variable::UnionMember3::OrHash
+                )
+              ]
+          ).void
+        end
         attr_writer :variables
 
         sig do
           params(
             model: T.any(Stagehand::ModelConfig::OrHash, String),
             timeout: Float,
-            variables: T::Hash[Symbol, String]
+            variables:
+              T::Hash[
+                Symbol,
+                T.any(
+                  String,
+                  Float,
+                  T::Boolean,
+                  Stagehand::SessionActParams::Options::Variable::UnionMember3::OrHash
+                )
+              ]
           ).returns(T.attached_class)
         end
         def self.new(
@@ -137,7 +182,8 @@ module Stagehand
           model: nil,
           # Timeout in ms for the action
           timeout: nil,
-          # Variables to substitute in the action instruction
+          # Variables to substitute in the action instruction. Accepts flat primitives or {
+          # value, description? } objects.
           variables: nil
         )
         end
@@ -147,7 +193,16 @@ module Stagehand
             {
               model: T.any(Stagehand::ModelConfig, String),
               timeout: Float,
-              variables: T::Hash[Symbol, String]
+              variables:
+                T::Hash[
+                  Symbol,
+                  T.any(
+                    String,
+                    Float,
+                    T::Boolean,
+                    Stagehand::SessionActParams::Options::Variable::UnionMember3
+                  )
+                ]
             }
           )
         end
@@ -168,6 +223,89 @@ module Stagehand
           def self.variants
           end
         end
+
+        module Variable
+          extend Stagehand::Internal::Type::Union
+
+          Variants =
+            T.type_alias do
+              T.any(
+                String,
+                Float,
+                T::Boolean,
+                Stagehand::SessionActParams::Options::Variable::UnionMember3
+              )
+            end
+
+          class UnionMember3 < Stagehand::Internal::Type::BaseModel
+            OrHash =
+              T.type_alias do
+                T.any(
+                  Stagehand::SessionActParams::Options::Variable::UnionMember3,
+                  Stagehand::Internal::AnyHash
+                )
+              end
+
+            sig do
+              returns(
+                Stagehand::SessionActParams::Options::Variable::UnionMember3::Value::Variants
+              )
+            end
+            attr_accessor :value
+
+            sig { returns(T.nilable(String)) }
+            attr_reader :description
+
+            sig { params(description: String).void }
+            attr_writer :description
+
+            sig do
+              params(
+                value:
+                  Stagehand::SessionActParams::Options::Variable::UnionMember3::Value::Variants,
+                description: String
+              ).returns(T.attached_class)
+            end
+            def self.new(value:, description: nil)
+            end
+
+            sig do
+              override.returns(
+                {
+                  value:
+                    Stagehand::SessionActParams::Options::Variable::UnionMember3::Value::Variants,
+                  description: String
+                }
+              )
+            end
+            def to_hash
+            end
+
+            module Value
+              extend Stagehand::Internal::Type::Union
+
+              Variants = T.type_alias { T.any(String, Float, T::Boolean) }
+
+              sig do
+                override.returns(
+                  T::Array[
+                    Stagehand::SessionActParams::Options::Variable::UnionMember3::Value::Variants
+                  ]
+                )
+              end
+              def self.variants
+              end
+            end
+          end
+
+          sig do
+            override.returns(
+              T::Array[Stagehand::SessionActParams::Options::Variable::Variants]
+            )
+          end
+          def self.variants
+          end
+        end
       end
 
       # Whether to stream the response via SSE

data/rbi/stagehand/models/session_end_params.rbi

@@ -11,6 +11,10 @@ module Stagehand
           T.any(Stagehand::SessionEndParams, Stagehand::Internal::AnyHash)
         end
 
+      # Unique session identifier
+      sig { returns(String) }
+      attr_accessor :id
+
       # Whether to stream the response via SSE
       sig do
         returns(
@@ -29,12 +33,15 @@ module Stagehand
 
       sig do
         params(
+          id: String,
           x_stream_response:
             Stagehand::SessionEndParams::XStreamResponse::OrSymbol,
           request_options: Stagehand::RequestOptions::OrHash
         ).returns(T.attached_class)
       end
       def self.new(
+        # Unique session identifier
+        id:,
         # Whether to stream the response via SSE
         x_stream_response: nil,
         request_options: {}
@@ -44,6 +51,7 @@ module Stagehand
       sig do
         override.returns(
           {
+            id: String,
             x_stream_response:
               Stagehand::SessionEndParams::XStreamResponse::OrSymbol,
             request_options: Stagehand::RequestOptions

data/rbi/stagehand/models/session_execute_params.rbi

@@ -11,6 +11,10 @@ module Stagehand
           T.any(Stagehand::SessionExecuteParams, Stagehand::Internal::AnyHash)
         end
 
+      # Unique session identifier
+      sig { returns(String) }
+      attr_accessor :id
+
       sig { returns(Stagehand::SessionExecuteParams::AgentConfig) }
       attr_reader :agent_config
 
@@ -61,6 +65,7 @@ module Stagehand
 
       sig do
         params(
+          id: String,
           agent_config: Stagehand::SessionExecuteParams::AgentConfig::OrHash,
           execute_options:
             Stagehand::SessionExecuteParams::ExecuteOptions::OrHash,
@@ -72,6 +77,8 @@ module Stagehand
         ).returns(T.attached_class)
       end
       def self.new(
+        # Unique session identifier
+        id:,
         agent_config:,
         execute_options:,
         # Target frame ID for the agent
@@ -87,6 +94,7 @@ module Stagehand
       sig do
         override.returns(
           {
+            id: String,
             agent_config: Stagehand::SessionExecuteParams::AgentConfig,
             execute_options: Stagehand::SessionExecuteParams::ExecuteOptions,
             frame_id: T.nilable(String),
@@ -379,11 +387,27 @@ module Stagehand
         sig { params(max_steps: Float).void }
         attr_writer :max_steps
 
+        # Timeout in milliseconds for each agent tool call
+        sig { returns(T.nilable(Float)) }
+        attr_reader :tool_timeout
+
+        sig { params(tool_timeout: Float).void }
+        attr_writer :tool_timeout
+
+        # Whether to enable the web search tool powered by Browserbase Search API
+        sig { returns(T.nilable(T::Boolean)) }
+        attr_reader :use_search
+
+        sig { params(use_search: T::Boolean).void }
+        attr_writer :use_search
+
         sig do
           params(
             instruction: String,
             highlight_cursor: T::Boolean,
-            max_steps: Float
+            max_steps: Float,
+            tool_timeout: Float,
+            use_search: T::Boolean
           ).returns(T.attached_class)
         end
         def self.new(
@@ -392,7 +416,11 @@ module Stagehand
           # Whether to visually highlight the cursor during execution
           highlight_cursor: nil,
           # Maximum number of steps the agent can take
-          max_steps: nil
+          max_steps: nil,
+          # Timeout in milliseconds for each agent tool call
+          tool_timeout: nil,
+          # Whether to enable the web search tool powered by Browserbase Search API
+          use_search: nil
         )
         end
 
@@ -401,7 +429,9 @@ module Stagehand
             {
               instruction: String,
               highlight_cursor: T::Boolean,
-              max_steps: Float
+              max_steps: Float,
+              tool_timeout: Float,
+              use_search: T::Boolean
             }
           )
         end

data/rbi/stagehand/models/session_extract_params.rbi

@@ -11,6 +11,10 @@ module Stagehand
           T.any(Stagehand::SessionExtractParams, Stagehand::Internal::AnyHash)
         end
 
+      # Unique session identifier
+      sig { returns(String) }
+      attr_accessor :id
+
       # Target frame ID for the extraction
       sig { returns(T.nilable(String)) }
       attr_accessor :frame_id
@@ -55,6 +59,7 @@ module Stagehand
 
       sig do
         params(
+          id: String,
           frame_id: T.nilable(String),
           instruction: String,
           options: Stagehand::SessionExtractParams::Options::OrHash,
@@ -65,6 +70,8 @@ module Stagehand
         ).returns(T.attached_class)
       end
       def self.new(
+        # Unique session identifier
+        id:,
         # Target frame ID for the extraction
         frame_id: nil,
         # Natural language instruction for what to extract
@@ -81,6 +88,7 @@ module Stagehand
       sig do
         override.returns(
           {
+            id: String,
             frame_id: T.nilable(String),
             instruction: String,
             options: Stagehand::SessionExtractParams::Options,

data/rbi/stagehand/models/session_navigate_params.rbi

@@ -11,6 +11,10 @@ module Stagehand
           T.any(Stagehand::SessionNavigateParams, Stagehand::Internal::AnyHash)
         end
 
+      # Unique session identifier
+      sig { returns(String) }
+      attr_accessor :id
+
       # URL to navigate to
       sig { returns(String) }
       attr_accessor :url
@@ -52,6 +56,7 @@ module Stagehand
 
       sig do
         params(
+          id: String,
           url: String,
           frame_id: T.nilable(String),
           options: Stagehand::SessionNavigateParams::Options::OrHash,
@@ -62,6 +67,8 @@ module Stagehand
         ).returns(T.attached_class)
       end
       def self.new(
+        # Unique session identifier
+        id:,
         # URL to navigate to
         url:,
         # Target frame ID for the navigation
@@ -78,6 +85,7 @@ module Stagehand
       sig do
         override.returns(
           {
+            id: String,
             url: String,
             frame_id: T.nilable(String),
             options: Stagehand::SessionNavigateParams::Options,

data/rbi/stagehand/models/session_observe_params.rbi

@@ -11,6 +11,10 @@ module Stagehand
           T.any(Stagehand::SessionObserveParams, Stagehand::Internal::AnyHash)
         end
 
+      # Unique session identifier
+      sig { returns(String) }
+      attr_accessor :id
+
       # Target frame ID for the observation
       sig { returns(T.nilable(String)) }
       attr_accessor :frame_id
@@ -48,6 +52,7 @@ module Stagehand
 
       sig do
         params(
+          id: String,
           frame_id: T.nilable(String),
           instruction: String,
           options: Stagehand::SessionObserveParams::Options::OrHash,
@@ -57,6 +62,8 @@ module Stagehand
         ).returns(T.attached_class)
       end
       def self.new(
+        # Unique session identifier
+        id:,
         # Target frame ID for the observation
         frame_id: nil,
         # Natural language instruction for what actions to find
@@ -71,6 +78,7 @@ module Stagehand
       sig do
         override.returns(
           {
+            id: String,
             frame_id: T.nilable(String),
             instruction: String,
             options: Stagehand::SessionObserveParams::Options,
@@ -115,11 +123,57 @@ module Stagehand
         sig { params(timeout: Float).void }
         attr_writer :timeout
 
+        # Variables whose names are exposed to the model so observe() returns
+        # %variableName% placeholders in suggested action arguments instead of literal
+        # values. Accepts flat primitives or { value, description? } objects.
+        sig do
+          returns(
+            T.nilable(
+              T::Hash[
+                Symbol,
+                T.any(
+                  String,
+                  Float,
+                  T::Boolean,
+                  Stagehand::SessionObserveParams::Options::Variable::UnionMember3
+                )
+              ]
+            )
+          )
+        end
+        attr_reader :variables
+
+        sig do
+          params(
+            variables:
+              T::Hash[
+                Symbol,
+                T.any(
+                  String,
+                  Float,
+                  T::Boolean,
+                  Stagehand::SessionObserveParams::Options::Variable::UnionMember3::OrHash
+                )
+              ]
+          ).void
+        end
+        attr_writer :variables
+
         sig do
           params(
             model: T.any(Stagehand::ModelConfig::OrHash, String),
             selector: String,
-            timeout: Float
+            timeout: Float,
+            variables:
+              T::Hash[
+                Symbol,
+                T.any(
+                  String,
+                  Float,
+                  T::Boolean,
+                  Stagehand::SessionObserveParams::Options::Variable::UnionMember3::OrHash
+                )
+              ]
           ).returns(T.attached_class)
         end
         def self.new(
@@ -128,7 +182,11 @@ module Stagehand
           # CSS selector to scope observation to a specific element
           selector: nil,
           # Timeout in ms for the observation
-          timeout: nil
+          timeout: nil,
+          # Variables whose names are exposed to the model so observe() returns
+          # %variableName% placeholders in suggested action arguments instead of literal
+          # values. Accepts flat primitives or { value, description? } objects.
+          variables: nil
         )
         end
 
@@ -137,7 +195,17 @@ module Stagehand
             {
               model: T.any(Stagehand::ModelConfig, String),
               selector: String,
-              timeout: Float
+              timeout: Float,
+              variables:
+                T::Hash[
+                  Symbol,
+                  T.any(
+                    String,
+                    Float,
+                    T::Boolean,
+                    Stagehand::SessionObserveParams::Options::Variable::UnionMember3
+                  )
+                ]
             }
           )
         end
@@ -160,6 +228,91 @@ module Stagehand
           def self.variants
           end
         end
+
+        module Variable
+          extend Stagehand::Internal::Type::Union
+
+          Variants =
+            T.type_alias do
+              T.any(
+                String,
+                Float,
+                T::Boolean,
+                Stagehand::SessionObserveParams::Options::Variable::UnionMember3
+              )
+            end
+
+          class UnionMember3 < Stagehand::Internal::Type::BaseModel
+            OrHash =
+              T.type_alias do
+                T.any(
+                  Stagehand::SessionObserveParams::Options::Variable::UnionMember3,
+                  Stagehand::Internal::AnyHash
+                )
+              end
+
+            sig do
+              returns(
+                Stagehand::SessionObserveParams::Options::Variable::UnionMember3::Value::Variants
+              )
+            end
+            attr_accessor :value
+
+            sig { returns(T.nilable(String)) }
+            attr_reader :description
+
+            sig { params(description: String).void }
+            attr_writer :description
+
+            sig do
+              params(
+                value:
+                  Stagehand::SessionObserveParams::Options::Variable::UnionMember3::Value::Variants,
+                description: String
+              ).returns(T.attached_class)
+            end
+            def self.new(value:, description: nil)
+            end
+
+            sig do
+              override.returns(
+                {
+                  value:
+                    Stagehand::SessionObserveParams::Options::Variable::UnionMember3::Value::Variants,
+                  description: String
+                }
+              )
+            end
+            def to_hash
+            end
+
+            module Value
+              extend Stagehand::Internal::Type::Union
+
+              Variants = T.type_alias { T.any(String, Float, T::Boolean) }
+
+              sig do
+                override.returns(
+                  T::Array[
+                    Stagehand::SessionObserveParams::Options::Variable::UnionMember3::Value::Variants
+                  ]
+                )
+              end
+              def self.variants
+              end
+            end
+          end
+
+          sig do
+            override.returns(
+              T::Array[
+                Stagehand::SessionObserveParams::Options::Variable::Variants
+              ]
+            )
+          end
+          def self.variants
+          end
+        end
       end
 
       # Whether to stream the response via SSE

data/rbi/stagehand/models/session_replay_params.rbi

@@ -11,6 +11,10 @@ module Stagehand
           T.any(Stagehand::SessionReplayParams, Stagehand::Internal::AnyHash)
         end
 
+      # Unique session identifier
+      sig { returns(String) }
+      attr_accessor :id
+
       # Whether to stream the response via SSE
       sig do
         returns(
@@ -29,12 +33,15 @@ module Stagehand
 
       sig do
         params(
+          id: String,
           x_stream_response:
             Stagehand::SessionReplayParams::XStreamResponse::OrSymbol,
           request_options: Stagehand::RequestOptions::OrHash
         ).returns(T.attached_class)
       end
       def self.new(
+        # Unique session identifier
+        id:,
         # Whether to stream the response via SSE
         x_stream_response: nil,
         request_options: {}
@@ -44,6 +51,7 @@ module Stagehand
       sig do
         override.returns(
           {
+            id: String,
             x_stream_response:
               Stagehand::SessionReplayParams::XStreamResponse::OrSymbol,
             request_options: Stagehand::RequestOptions

data/rbi/stagehand/models/session_start_params.rbi

@@ -281,6 +281,12 @@ module Stagehand
           sig { params(args: T::Array[String]).void }
           attr_writer :args
 
+          sig { returns(T.nilable(T::Hash[Symbol, String])) }
+          attr_reader :cdp_headers
+
+          sig { params(cdp_headers: T::Hash[Symbol, String]).void }
+          attr_writer :cdp_headers
+
           sig { returns(T.nilable(String)) }
           attr_reader :cdp_url
 
@@ -420,6 +426,7 @@ module Stagehand
             params(
               accept_downloads: T::Boolean,
               args: T::Array[String],
+              cdp_headers: T::Hash[Symbol, String],
               cdp_url: String,
               chromium_sandbox: T::Boolean,
               connect_timeout_ms: Float,
@@ -445,6 +452,7 @@ module Stagehand
           def self.new(
             accept_downloads: nil,
             args: nil,
+            cdp_headers: nil,
             cdp_url: nil,
             chromium_sandbox: nil,
             connect_timeout_ms: nil,
@@ -470,6 +478,7 @@ module Stagehand
               {
                 accept_downloads: T::Boolean,
                 args: T::Array[String],
+                cdp_headers: T::Hash[Symbol, String],
                 cdp_url: String,
                 chromium_sandbox: T::Boolean,
                 connect_timeout_ms: Float,

data/rbi/stagehand/models/stream_event.rbi

@@ -20,7 +20,8 @@ module Stagehand
       attr_accessor :type
 
       # Server-Sent Event emitted during streaming responses. Events are sent as
-      # `data: <JSON>\n\n`. Key order: data (with status first), type, id.
+      # `event: <status>\ndata: <JSON>\n\n`, where the JSON payload has the shape
+      # `{ data, type, id }`.
       sig do
         params(
           id: String,