stagehand 3.7.1 → 3.19.3

data/lib/stagehand/models/session_start_params.rb

@@ -144,6 +144,11 @@ module Stagehand
           #   @return [Array<String>, nil]
           optional :args, Stagehand::Internal::Type::ArrayOf[String]
 
+          # @!attribute cdp_headers
+          #
+          #   @return [Hash{Symbol=>String}, nil]
+          optional :cdp_headers, Stagehand::Internal::Type::HashOf[String], api_name: :cdpHeaders
+
           # @!attribute cdp_url
           #
           #   @return [String, nil]
@@ -231,9 +236,10 @@ module Stagehand
           #   @return [Stagehand::Models::SessionStartParams::Browser::LaunchOptions::Viewport, nil]
           optional :viewport, -> { Stagehand::SessionStartParams::Browser::LaunchOptions::Viewport }
 
-          # @!method initialize(accept_downloads: nil, args: nil, cdp_url: nil, chromium_sandbox: nil, connect_timeout_ms: nil, device_scale_factor: nil, devtools: nil, downloads_path: nil, executable_path: nil, has_touch: nil, headless: nil, ignore_default_args: nil, ignore_https_errors: nil, locale: nil, port: nil, preserve_user_data_dir: nil, proxy: nil, user_data_dir: nil, viewport: nil)
+          # @!method initialize(accept_downloads: nil, args: nil, cdp_headers: nil, cdp_url: nil, chromium_sandbox: nil, connect_timeout_ms: nil, device_scale_factor: nil, devtools: nil, downloads_path: nil, executable_path: nil, has_touch: nil, headless: nil, ignore_default_args: nil, ignore_https_errors: nil, locale: nil, port: nil, preserve_user_data_dir: nil, proxy: nil, user_data_dir: nil, viewport: nil)
           #   @param accept_downloads [Boolean]
           #   @param args [Array<String>]
+          #   @param cdp_headers [Hash{Symbol=>String}]
           #   @param cdp_url [String]
           #   @param chromium_sandbox [Boolean]
           #   @param connect_timeout_ms [Float]

data/lib/stagehand/models/stream_event.rb

@@ -22,7 +22,8 @@ module Stagehand
 
       # @!method initialize(id:, data:, 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 }`.
       #
       #   @param id [String] Unique identifier for this event
       #

data/lib/stagehand/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Stagehand
-  VERSION = "3.7.1"
+  VERSION = "3.19.3"
 end

data/rbi/stagehand/internal/util.rbi

@@ -148,12 +148,20 @@ module Stagehand
         end
       end
 
+      # https://www.rfc-editor.org/rfc/rfc3986.html#section-3.3
+      RFC_3986_NOT_PCHARS = T.let(/[^A-Za-z0-9\-._~!$&'()*+,;=:@]+/, Regexp)
+
       class << self
         # @api private
         sig { params(uri: URI::Generic).returns(String) }
         def uri_origin(uri)
         end
 
+        # @api private
+        sig { params(path: T.any(String, Integer)).returns(String) }
+        def encode_path(path)
+        end
+
         # @api private
         sig { params(path: T.any(String, T::Array[String])).returns(String) }
         def interpolate_path(path)
@@ -301,6 +309,26 @@ module Stagehand
         T.let(%r{^application/(:?x-(?:n|l)djson)|(:?(?:x-)?jsonl)}, Regexp)
 
       class << self
+        # @api private
+        sig do
+          params(query: Stagehand::Internal::AnyHash).returns(
+            Stagehand::Internal::AnyHash
+          )
+        end
+        def encode_query_params(query)
+        end
+
+        # @api private
+        sig do
+          params(
+            collection: Stagehand::Internal::AnyHash,
+            key: String,
+            element: T.anything
+          ).void
+        end
+        private def write_query_param_element!(collection, key, element)
+        end
+
         # @api private
         sig do
           params(

data/rbi/stagehand/models/model_config.rbi

@@ -26,6 +26,13 @@ module Stagehand
       sig { params(base_url: String).void }
       attr_writer :base_url
 
+      # Custom headers sent with every request to the model provider
+      sig { returns(T.nilable(T::Hash[Symbol, String])) }
+      attr_reader :headers
+
+      sig { params(headers: T::Hash[Symbol, String]).void }
+      attr_writer :headers
+
       # AI provider for the model (or provide a baseURL endpoint instead)
       sig { returns(T.nilable(Stagehand::ModelConfig::Provider::OrSymbol)) }
       attr_reader :provider
@@ -38,6 +45,7 @@ module Stagehand
           model_name: String,
           api_key: String,
           base_url: String,
+          headers: T::Hash[Symbol, String],
           provider: Stagehand::ModelConfig::Provider::OrSymbol
         ).returns(T.attached_class)
       end
@@ -48,6 +56,8 @@ module Stagehand
         api_key: nil,
         # Base URL for the model provider
         base_url: nil,
+        # Custom headers sent with every request to the model provider
+        headers: nil,
         # AI provider for the model (or provide a baseURL endpoint instead)
         provider: nil
       )
@@ -59,6 +69,7 @@ module Stagehand
             model_name: String,
             api_key: String,
             base_url: String,
+            headers: T::Hash[Symbol, String],
             provider: Stagehand::ModelConfig::Provider::OrSymbol
           }
         )

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,