stagehand 3.18.0 → 3.20.0

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)

data/rbi/stagehand/models/session_execute_params.rbi

@@ -401,13 +401,57 @@ module Stagehand
         sig { params(use_search: T::Boolean).void }
         attr_writer :use_search
 
+        # Variables available to the agent via %variableName% syntax in supported tools
+        sig do
+          returns(
+            T.nilable(
+              T::Hash[
+                Symbol,
+                T.any(
+                  String,
+                  Float,
+                  T::Boolean,
+                  Stagehand::SessionExecuteParams::ExecuteOptions::Variable::UnionMember3
+                )
+              ]
+            )
+          )
+        end
+        attr_reader :variables
+
+        sig do
+          params(
+            variables:
+              T::Hash[
+                Symbol,
+                T.any(
+                  String,
+                  Float,
+                  T::Boolean,
+                  Stagehand::SessionExecuteParams::ExecuteOptions::Variable::UnionMember3::OrHash
+                )
+              ]
+          ).void
+        end
+        attr_writer :variables
+
         sig do
           params(
             instruction: String,
             highlight_cursor: T::Boolean,
             max_steps: Float,
             tool_timeout: Float,
-            use_search: T::Boolean
+            use_search: T::Boolean,
+            variables:
+              T::Hash[
+                Symbol,
+                T.any(
+                  String,
+                  Float,
+                  T::Boolean,
+                  Stagehand::SessionExecuteParams::ExecuteOptions::Variable::UnionMember3::OrHash
+                )
+              ]
           ).returns(T.attached_class)
         end
         def self.new(
@@ -420,7 +464,9 @@ module Stagehand
           # 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
+          use_search: nil,
+          # Variables available to the agent via %variableName% syntax in supported tools
+          variables: nil
         )
         end
 
@@ -431,12 +477,107 @@ module Stagehand
               highlight_cursor: T::Boolean,
               max_steps: Float,
               tool_timeout: Float,
-              use_search: T::Boolean
+              use_search: T::Boolean,
+              variables:
+                T::Hash[
+                  Symbol,
+                  T.any(
+                    String,
+                    Float,
+                    T::Boolean,
+                    Stagehand::SessionExecuteParams::ExecuteOptions::Variable::UnionMember3
+                  )
+                ]
             }
           )
         end
         def to_hash
         end
+
+        module Variable
+          extend Stagehand::Internal::Type::Union
+
+          Variants =
+            T.type_alias do
+              T.any(
+                String,
+                Float,
+                T::Boolean,
+                Stagehand::SessionExecuteParams::ExecuteOptions::Variable::UnionMember3
+              )
+            end
+
+          class UnionMember3 < Stagehand::Internal::Type::BaseModel
+            OrHash =
+              T.type_alias do
+                T.any(
+                  Stagehand::SessionExecuteParams::ExecuteOptions::Variable::UnionMember3,
+                  Stagehand::Internal::AnyHash
+                )
+              end
+
+            sig do
+              returns(
+                Stagehand::SessionExecuteParams::ExecuteOptions::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::SessionExecuteParams::ExecuteOptions::Variable::UnionMember3::Value::Variants,
+                description: String
+              ).returns(T.attached_class)
+            end
+            def self.new(value:, description: nil)
+            end
+
+            sig do
+              override.returns(
+                {
+                  value:
+                    Stagehand::SessionExecuteParams::ExecuteOptions::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::SessionExecuteParams::ExecuteOptions::Variable::UnionMember3::Value::Variants
+                  ]
+                )
+              end
+              def self.variants
+              end
+            end
+          end
+
+          sig do
+            override.returns(
+              T::Array[
+                Stagehand::SessionExecuteParams::ExecuteOptions::Variable::Variants
+              ]
+            )
+          end
+          def self.variants
+          end
+        end
       end
 
       # Whether to stream the response via SSE

data/rbi/stagehand/models/session_extract_params.rbi

@@ -111,6 +111,13 @@ module Stagehand
             )
           end
 
+        # Selectors for elements and subtrees that should be excluded from extraction
+        sig { returns(T.nilable(T::Array[String])) }
+        attr_reader :ignore_selectors
+
+        sig { params(ignore_selectors: T::Array[String]).void }
+        attr_writer :ignore_selectors
+
         # Model configuration object or model name string (e.g., 'openai/gpt-5-nano')
         sig { returns(T.nilable(T.any(Stagehand::ModelConfig, String))) }
         attr_reader :model
@@ -136,12 +143,15 @@ module Stagehand
 
         sig do
           params(
+            ignore_selectors: T::Array[String],
             model: T.any(Stagehand::ModelConfig::OrHash, String),
             selector: String,
             timeout: Float
           ).returns(T.attached_class)
         end
         def self.new(
+          # Selectors for elements and subtrees that should be excluded from extraction
+          ignore_selectors: nil,
           # Model configuration object or model name string (e.g., 'openai/gpt-5-nano')
           model: nil,
           # CSS selector to scope extraction to a specific element
@@ -154,6 +164,7 @@ module Stagehand
         sig do
           override.returns(
             {
+              ignore_selectors: T::Array[String],
               model: T.any(Stagehand::ModelConfig, String),
               selector: String,
               timeout: Float

data/rbi/stagehand/models/session_start_params.rbi

@@ -680,6 +680,8 @@ module Stagehand
         sig { params(keep_alive: T::Boolean).void }
         attr_writer :keep_alive
 
+        # Deprecated. Browserbase API keys are now project-scoped, so this field is no
+        # longer required.
         sig { returns(T.nilable(String)) }
         attr_reader :project_id
 
@@ -751,6 +753,8 @@ module Stagehand
           browser_settings: nil,
           extension_id: nil,
           keep_alive: nil,
+          # Deprecated. Browserbase API keys are now project-scoped, so this field is no
+          # longer required.
           project_id: nil,
           proxies: nil,
           region: nil,
@@ -800,6 +804,18 @@ module Stagehand
           sig { params(block_ads: T::Boolean).void }
           attr_writer :block_ads
 
+          sig { returns(T.nilable(String)) }
+          attr_reader :captcha_image_selector
+
+          sig { params(captcha_image_selector: String).void }
+          attr_writer :captcha_image_selector
+
+          sig { returns(T.nilable(String)) }
+          attr_reader :captcha_input_selector
+
+          sig { params(captcha_input_selector: String).void }
+          attr_writer :captcha_input_selector
+
           sig do
             returns(
               T.nilable(
@@ -846,6 +862,23 @@ module Stagehand
           sig { params(log_session: T::Boolean).void }
           attr_writer :log_session
 
+          sig do
+            returns(
+              T.nilable(
+                Stagehand::SessionStartParams::BrowserbaseSessionCreateParams::BrowserSettings::Os::OrSymbol
+              )
+            )
+          end
+          attr_reader :os
+
+          sig do
+            params(
+              os:
+                Stagehand::SessionStartParams::BrowserbaseSessionCreateParams::BrowserSettings::Os::OrSymbol
+            ).void
+          end
+          attr_writer :os
+
           sig { returns(T.nilable(T::Boolean)) }
           attr_reader :record_session
 
@@ -858,6 +891,12 @@ module Stagehand
           sig { params(solve_captchas: T::Boolean).void }
           attr_writer :solve_captchas
 
+          sig { returns(T.nilable(T::Boolean)) }
+          attr_reader :verified
+
+          sig { params(verified: T::Boolean).void }
+          attr_writer :verified
+
           sig do
             returns(
               T.nilable(
@@ -879,14 +918,19 @@ module Stagehand
             params(
               advanced_stealth: T::Boolean,
               block_ads: T::Boolean,
+              captcha_image_selector: String,
+              captcha_input_selector: String,
               context:
                 Stagehand::SessionStartParams::BrowserbaseSessionCreateParams::BrowserSettings::Context::OrHash,
               extension_id: String,
               fingerprint:
                 Stagehand::SessionStartParams::BrowserbaseSessionCreateParams::BrowserSettings::Fingerprint::OrHash,
               log_session: T::Boolean,
+              os:
+                Stagehand::SessionStartParams::BrowserbaseSessionCreateParams::BrowserSettings::Os::OrSymbol,
               record_session: T::Boolean,
               solve_captchas: T::Boolean,
+              verified: T::Boolean,
               viewport:
                 Stagehand::SessionStartParams::BrowserbaseSessionCreateParams::BrowserSettings::Viewport::OrHash
             ).returns(T.attached_class)
@@ -894,12 +938,16 @@ module Stagehand
           def self.new(
             advanced_stealth: nil,
             block_ads: nil,
+            captcha_image_selector: nil,
+            captcha_input_selector: nil,
             context: nil,
             extension_id: nil,
             fingerprint: nil,
             log_session: nil,
+            os: nil,
             record_session: nil,
             solve_captchas: nil,
+            verified: nil,
             viewport: nil
           )
           end
@@ -909,14 +957,19 @@ module Stagehand
               {
                 advanced_stealth: T::Boolean,
                 block_ads: T::Boolean,
+                captcha_image_selector: String,
+                captcha_input_selector: String,
                 context:
                   Stagehand::SessionStartParams::BrowserbaseSessionCreateParams::BrowserSettings::Context,
                 extension_id: String,
                 fingerprint:
                   Stagehand::SessionStartParams::BrowserbaseSessionCreateParams::BrowserSettings::Fingerprint,
                 log_session: T::Boolean,
+                os:
+                  Stagehand::SessionStartParams::BrowserbaseSessionCreateParams::BrowserSettings::Os::OrSymbol,
                 record_session: T::Boolean,
                 solve_captchas: T::Boolean,
+                verified: T::Boolean,
                 viewport:
                   Stagehand::SessionStartParams::BrowserbaseSessionCreateParams::BrowserSettings::Viewport
               }
@@ -1348,6 +1401,55 @@ module Stagehand
             end
           end
 
+          module Os
+            extend Stagehand::Internal::Type::Enum
+
+            TaggedSymbol =
+              T.type_alias do
+                T.all(
+                  Symbol,
+                  Stagehand::SessionStartParams::BrowserbaseSessionCreateParams::BrowserSettings::Os
+                )
+              end
+            OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+            WINDOWS =
+              T.let(
+                :windows,
+                Stagehand::SessionStartParams::BrowserbaseSessionCreateParams::BrowserSettings::Os::TaggedSymbol
+              )
+            MAC =
+              T.let(
+                :mac,
+                Stagehand::SessionStartParams::BrowserbaseSessionCreateParams::BrowserSettings::Os::TaggedSymbol
+              )
+            LINUX =
+              T.let(
+                :linux,
+                Stagehand::SessionStartParams::BrowserbaseSessionCreateParams::BrowserSettings::Os::TaggedSymbol
+              )
+            MOBILE =
+              T.let(
+                :mobile,
+                Stagehand::SessionStartParams::BrowserbaseSessionCreateParams::BrowserSettings::Os::TaggedSymbol
+              )
+            TABLET =
+              T.let(
+                :tablet,
+                Stagehand::SessionStartParams::BrowserbaseSessionCreateParams::BrowserSettings::Os::TaggedSymbol
+              )
+
+            sig do
+              override.returns(
+                T::Array[
+                  Stagehand::SessionStartParams::BrowserbaseSessionCreateParams::BrowserSettings::Os::TaggedSymbol
+                ]
+              )
+            end
+            def self.values
+            end
+          end
+
           class Viewport < Stagehand::Internal::Type::BaseModel
             OrHash =
               T.type_alias do

data/sig/stagehand/internal/util.rbs

@@ -45,8 +45,12 @@ module Stagehand
         -> top?
       } -> top?
 
+      RFC_3986_NOT_PCHARS: Regexp
+
       def self?.uri_origin: (URI::Generic uri) -> String
 
+      def self?.encode_path: (String | Integer path) -> String
+
       def self?.interpolate_path: (String | ::Array[String] path) -> String
 
       def self?.decode_query: (String? query) -> ::Hash[String, ::Array[String]]

data/sig/stagehand/models/session_execute_params.rbs

@@ -163,7 +163,8 @@ module Stagehand
           highlight_cursor: bool,
           max_steps: Float,
           tool_timeout: Float,
-          use_search: bool
+          use_search: bool,
+          variables: ::Hash[Symbol, Stagehand::Models::SessionExecuteParams::ExecuteOptions::variable]
         }
 
       class ExecuteOptions < Stagehand::Internal::Type::BaseModel
@@ -185,12 +186,19 @@ module Stagehand
 
         def use_search=: (bool) -> bool
 
+        attr_reader variables: ::Hash[Symbol, Stagehand::Models::SessionExecuteParams::ExecuteOptions::variable]?
+
+        def variables=: (
+          ::Hash[Symbol, Stagehand::Models::SessionExecuteParams::ExecuteOptions::variable]
+        ) -> ::Hash[Symbol, Stagehand::Models::SessionExecuteParams::ExecuteOptions::variable]
+
         def initialize: (
           instruction: String,
           ?highlight_cursor: bool,
           ?max_steps: Float,
           ?tool_timeout: Float,
-          ?use_search: bool
+          ?use_search: bool,
+          ?variables: ::Hash[Symbol, Stagehand::Models::SessionExecuteParams::ExecuteOptions::variable]
         ) -> void
 
         def to_hash: -> {
@@ -198,8 +206,53 @@ module Stagehand
           highlight_cursor: bool,
           max_steps: Float,
           tool_timeout: Float,
-          use_search: bool
+          use_search: bool,
+          variables: ::Hash[Symbol, Stagehand::Models::SessionExecuteParams::ExecuteOptions::variable]
         }
+
+        type variable =
+          String
+          | Float
+          | bool
+          | Stagehand::SessionExecuteParams::ExecuteOptions::Variable::UnionMember3
+
+        module Variable
+          extend Stagehand::Internal::Type::Union
+
+          type union_member3 =
+            {
+              value: Stagehand::Models::SessionExecuteParams::ExecuteOptions::Variable::UnionMember3::value,
+              description: String
+            }
+
+          class UnionMember3 < Stagehand::Internal::Type::BaseModel
+            attr_accessor value: Stagehand::Models::SessionExecuteParams::ExecuteOptions::Variable::UnionMember3::value
+
+            attr_reader description: String?
+
+            def description=: (String) -> String
+
+            def initialize: (
+              value: Stagehand::Models::SessionExecuteParams::ExecuteOptions::Variable::UnionMember3::value,
+              ?description: String
+            ) -> void
+
+            def to_hash: -> {
+              value: Stagehand::Models::SessionExecuteParams::ExecuteOptions::Variable::UnionMember3::value,
+              description: String
+            }
+
+            type value = String | Float | bool
+
+            module Value
+              extend Stagehand::Internal::Type::Union
+
+              def self?.variants: -> ::Array[Stagehand::Models::SessionExecuteParams::ExecuteOptions::Variable::UnionMember3::value]
+            end
+          end
+
+          def self?.variants: -> ::Array[Stagehand::Models::SessionExecuteParams::ExecuteOptions::variable]
+        end
       end
 
       type x_stream_response = :true | :false

data/sig/stagehand/models/session_extract_params.rbs

@@ -61,12 +61,17 @@ module Stagehand
 
       type options =
         {
+          ignore_selectors: ::Array[String],
           model: Stagehand::Models::SessionExtractParams::Options::model,
           selector: String,
           timeout: Float
         }
 
       class Options < Stagehand::Internal::Type::BaseModel
+        attr_reader ignore_selectors: ::Array[String]?
+
+        def ignore_selectors=: (::Array[String]) -> ::Array[String]
+
         attr_reader model: Stagehand::Models::SessionExtractParams::Options::model?
 
         def model=: (
@@ -82,12 +87,14 @@ module Stagehand
         def timeout=: (Float) -> Float
 
         def initialize: (
+          ?ignore_selectors: ::Array[String],
           ?model: Stagehand::Models::SessionExtractParams::Options::model,
           ?selector: String,
           ?timeout: Float
         ) -> void
 
         def to_hash: -> {
+          ignore_selectors: ::Array[String],
           model: Stagehand::Models::SessionExtractParams::Options::model,
           selector: String,
           timeout: Float

data/sig/stagehand/models/session_start_params.rbs

@@ -450,12 +450,16 @@ module Stagehand
           {
             advanced_stealth: bool,
             block_ads: bool,
+            captcha_image_selector: String,
+            captcha_input_selector: String,
             context: Stagehand::SessionStartParams::BrowserbaseSessionCreateParams::BrowserSettings::Context,
             extension_id: String,
             fingerprint: Stagehand::SessionStartParams::BrowserbaseSessionCreateParams::BrowserSettings::Fingerprint,
             log_session: bool,
+            os: Stagehand::Models::SessionStartParams::BrowserbaseSessionCreateParams::BrowserSettings::os,
             record_session: bool,
             solve_captchas: bool,
+            verified: bool,
             viewport: Stagehand::SessionStartParams::BrowserbaseSessionCreateParams::BrowserSettings::Viewport
           }
 
@@ -468,6 +472,14 @@ module Stagehand
 
           def block_ads=: (bool) -> bool
 
+          attr_reader captcha_image_selector: String?
+
+          def captcha_image_selector=: (String) -> String
+
+          attr_reader captcha_input_selector: String?
+
+          def captcha_input_selector=: (String) -> String
+
           attr_reader context: Stagehand::SessionStartParams::BrowserbaseSessionCreateParams::BrowserSettings::Context?
 
           def context=: (
@@ -488,6 +500,12 @@ module Stagehand
 
           def log_session=: (bool) -> bool
 
+          attr_reader os: Stagehand::Models::SessionStartParams::BrowserbaseSessionCreateParams::BrowserSettings::os?
+
+          def os=: (
+            Stagehand::Models::SessionStartParams::BrowserbaseSessionCreateParams::BrowserSettings::os
+          ) -> Stagehand::Models::SessionStartParams::BrowserbaseSessionCreateParams::BrowserSettings::os
+
           attr_reader record_session: bool?
 
           def record_session=: (bool) -> bool
@@ -496,6 +514,10 @@ module Stagehand
 
           def solve_captchas=: (bool) -> bool
 
+          attr_reader verified: bool?
+
+          def verified=: (bool) -> bool
+
           attr_reader viewport: Stagehand::SessionStartParams::BrowserbaseSessionCreateParams::BrowserSettings::Viewport?
 
           def viewport=: (
@@ -505,24 +527,32 @@ module Stagehand
           def initialize: (
             ?advanced_stealth: bool,
             ?block_ads: bool,
+            ?captcha_image_selector: String,
+            ?captcha_input_selector: String,
             ?context: Stagehand::SessionStartParams::BrowserbaseSessionCreateParams::BrowserSettings::Context,
             ?extension_id: String,
             ?fingerprint: Stagehand::SessionStartParams::BrowserbaseSessionCreateParams::BrowserSettings::Fingerprint,
             ?log_session: bool,
+            ?os: Stagehand::Models::SessionStartParams::BrowserbaseSessionCreateParams::BrowserSettings::os,
             ?record_session: bool,
             ?solve_captchas: bool,
+            ?verified: bool,
             ?viewport: Stagehand::SessionStartParams::BrowserbaseSessionCreateParams::BrowserSettings::Viewport
           ) -> void
 
           def to_hash: -> {
             advanced_stealth: bool,
             block_ads: bool,
+            captcha_image_selector: String,
+            captcha_input_selector: String,
             context: Stagehand::SessionStartParams::BrowserbaseSessionCreateParams::BrowserSettings::Context,
             extension_id: String,
             fingerprint: Stagehand::SessionStartParams::BrowserbaseSessionCreateParams::BrowserSettings::Fingerprint,
             log_session: bool,
+            os: Stagehand::Models::SessionStartParams::BrowserbaseSessionCreateParams::BrowserSettings::os,
             record_session: bool,
             solve_captchas: bool,
+            verified: bool,
             viewport: Stagehand::SessionStartParams::BrowserbaseSessionCreateParams::BrowserSettings::Viewport
           }
 
@@ -693,6 +723,20 @@ module Stagehand
             end
           end
 
+          type os = :windows | :mac | :linux | :mobile | :tablet
+
+          module Os
+            extend Stagehand::Internal::Type::Enum
+
+            WINDOWS: :windows
+            MAC: :mac
+            LINUX: :linux
+            MOBILE: :mobile
+            TABLET: :tablet
+
+            def self?.values: -> ::Array[Stagehand::Models::SessionStartParams::BrowserbaseSessionCreateParams::BrowserSettings::os]
+          end
+
           type viewport = { height: Float, width: Float }
 
           class Viewport < Stagehand::Internal::Type::BaseModel

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: stagehand
 version: !ruby/object:Gem::Version
-  version: 3.18.0
+  version: 3.20.0
 platform: ruby
 authors:
 - Stagehand
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-25 00:00:00.000000000 Z
+date: 2026-05-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cgi