stagehand 3.7.1 → 3.19.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 87ccf4bfcfc723469ff68db45b650d9f2702c6692905a8f6a42e7456d6d37b63
-  data.tar.gz: dbcfc350b71c0a0d89cad72696fcde9fc3f506d425fedd56e2e611b176070a73
+  metadata.gz: f3995180e65110d8a64695b7be8cb095b24e8d6fb3bc2627f13df4c0acaa15f2
+  data.tar.gz: a0b8bcd2648d2429b55c13b50d60fb7ec46da97118390900d1acfe0989e728d4
 SHA512:
-  metadata.gz: 1bafc8973dd2a0844797e67c0ecb04fdf0a3b8245ff0639af4f9334da95cdfbc6701f00ab8519ae07a998478383b14c633c8e3bd823c991caa4623ac5b9ace0d
-  data.tar.gz: 2e35f3d9adace66379d78c8631d271932d040ccc2aa190a793f074e37e1ea737c766424f21ebd2e6bfbd49687d9073e223615db052b624ff7488c641e3dedf81
+  metadata.gz: 83eae8bebac5087cda9551141db3d62bff7a0caa065ff675799610237d3ebf5114b62bb519403a3063e147b9384721d6bc0fdca28ce222c08691326f0a8b5e82
+  data.tar.gz: 7461914b6798606c6f0a672074ed3eaba504a82794e97becf1974de15cf701ce25ceec987d6969bb833d2ef098a5562da41f7faad6b1e871c75bba3ed4b4cda9

data/CHANGELOG.md

@@ -1,5 +1,50 @@
 # Changelog
 
+## 3.19.3 (2026-04-03)
+
+Full Changelog: [v3.18.0...v3.19.3](https://github.com/browserbase/stagehand-ruby/compare/v3.18.0...v3.19.3)
+
+### Features
+
+* Replace default model used in server-v3 api spec examples ([0460af2](https://github.com/browserbase/stagehand-ruby/commit/0460af273ab6ba521a01847fe943032b619f7922))
+
+
+### Bug Fixes
+
+* align path encoding with RFC 3986 section 3.3 ([4f07e2e](https://github.com/browserbase/stagehand-ruby/commit/4f07e2eb4439a53ed1d830f0471b563656f19832))
+* **internal:** correct multipart form field name encoding ([2478726](https://github.com/browserbase/stagehand-ruby/commit/247872691f0c955d19b06cdfac5a4feb13477c1f))
+* variable name typo ([41c9b71](https://github.com/browserbase/stagehand-ruby/commit/41c9b719de177dc28c3f5b167bb96a136336866d))
+
+
+### Chores
+
+* **ci:** support opting out of skipping builds on metadata-only commits ([cb20c91](https://github.com/browserbase/stagehand-ruby/commit/cb20c91371c9be0282616f9137e51a2414b8a969))
+
+## 3.18.0 (2026-03-25)
+
+Full Changelog: [v3.7.1...v3.18.0](https://github.com/browserbase/stagehand-ruby/compare/v3.7.1...v3.18.0)
+
+### Features
+
+* [fix]: add `useSearch` & `toolTimeout` to stainless types ([e5bedb8](https://github.com/browserbase/stagehand-ruby/commit/e5bedb88ac67d34a6db440e470e3eb964205e558))
+* [STG-1607] Yield finished SSE event instead of silently dropping it ([d5ffd2d](https://github.com/browserbase/stagehand-ruby/commit/d5ffd2d0ed6495673ef80ba0e1649bd1c1afa815))
+* Add explicit SSE event names for local v3 streaming ([5be6d12](https://github.com/browserbase/stagehand-ruby/commit/5be6d1293763ecb7f0268884784475986de2915c))
+* Add missing cdpHeaders field to v3 server openapi spec ([de6457f](https://github.com/browserbase/stagehand-ruby/commit/de6457f121764ffbadac51ec2a6103c27dbde338))
+* Include LLM headers in ModelConfig ([23cb4ea](https://github.com/browserbase/stagehand-ruby/commit/23cb4ea1319287992f1174c2b8fa2eff5fdfc5c4))
+* Revert broken finished SSE yield config ([1de4c00](https://github.com/browserbase/stagehand-ruby/commit/1de4c00c0b72936813fcd3e0499b51b1f135f33d))
+* variables for observe ([a9d6970](https://github.com/browserbase/stagehand-ruby/commit/a9d6970e7f43f1d69eddb42a14f09fb7f9158b29))
+
+
+### Chores
+
+* **ci:** add build step ([ed6573f](https://github.com/browserbase/stagehand-ruby/commit/ed6573f2ddab4f5f51d1262480cb663da5e003d0))
+* **ci:** skip lint on metadata-only changes ([079a802](https://github.com/browserbase/stagehand-ruby/commit/079a8028edf4e9dd09517363b0c1a3b16ed86865))
+* **ci:** skip uploading artifacts on stainless-internal branches ([3a7e90b](https://github.com/browserbase/stagehand-ruby/commit/3a7e90bc8dd9f983dbbc7be16f997dd2dc02c3c0))
+* **internal:** codegen related update ([f714af2](https://github.com/browserbase/stagehand-ruby/commit/f714af2d7d5b9b822362aa10f6f6facab3332eaf))
+* **internal:** codegen related update ([ed9fab1](https://github.com/browserbase/stagehand-ruby/commit/ed9fab1f726c05ef48d4a55507b09212d7ced713))
+* **internal:** tweak CI branches ([85b5b46](https://github.com/browserbase/stagehand-ruby/commit/85b5b4656c921f0784d05b27a3c4773b05b51cc6))
+* **internal:** update gitignore ([b4bc8a8](https://github.com/browserbase/stagehand-ruby/commit/b4bc8a8ae60ff252080d4bfcd0fc6af26dc95e74))
+
 ## 3.7.1 (2026-02-27)
 
 Full Changelog: [v3.7.0...v3.7.1](https://github.com/browserbase/stagehand-ruby/compare/v3.7.0...v3.7.1)

data/README.md

@@ -213,7 +213,7 @@ When the library is unable to connect to the API, or if the API returns a non-su
 
 ```ruby
 begin
-  session = stagehand.sessions.start(model_name: "anthropic/claude-sonnet-4-6")
+  session = stagehand.sessions.start(model_name: "openai/gpt-5.4-mini")
 rescue Stagehand::Errors::APIConnectionError => e
   puts("The server could not be reached")
   puts(e.cause)  # an underlying Exception, likely raised within `net/http`
@@ -256,7 +256,7 @@ stagehand = Stagehand::Client.new(
 )
 
 # Or, configure per-request:
-stagehand.sessions.start(model_name: "anthropic/claude-sonnet-4-6", request_options: {max_retries: 5})
+stagehand.sessions.start(model_name: "openai/gpt-5.4-mini", request_options: {max_retries: 5})
 ```
 
 ### Timeouts
@@ -270,7 +270,7 @@ stagehand = Stagehand::Client.new(
 )
 
 # Or, configure per-request:
-stagehand.sessions.start(model_name: "anthropic/claude-sonnet-4-6", request_options: {timeout: 5})
+stagehand.sessions.start(model_name: "openai/gpt-5.4-mini", request_options: {timeout: 5})
 ```
 
 On timeout, `Stagehand::Errors::APITimeoutError` is raised.

data/lib/stagehand/internal/stream.rb

@@ -15,18 +15,10 @@ module Stagehand
       #
       # @return [Enumerable<generic<Elem>>]
       private def iterator
-        # rubocop:disable Metrics/BlockLength
         @iterator ||= Stagehand::Internal::Util.chain_fused(@stream) do |y|
-          consume = false
-
           @stream.each do |msg|
-            next if consume
-
             case msg
-            in {data: String => data} if data.start_with?("{\"data\":{\"status\":\"finished\"")
-              consume = true
-              next
-            in {data: String => data} if data.start_with?("error")
+            in {event: "error", data: String => data}
               decoded = Kernel.then do
                 JSON.parse(data, symbolize_names: true)
               rescue JSON::ParserError
@@ -41,7 +33,7 @@ module Stagehand
                 response: @response
               )
               raise err
-            in {event: nil, data: String => data}
+            in {event: "starting" | "connected" | "running" | "finished", data: String => data}
               decoded = JSON.parse(data, symbolize_names: true)
               unwrapped = Stagehand::Internal::Util.dig(decoded, @unwrap)
               y << Stagehand::Internal::Type::Converter.coerce(@model, unwrapped)
@@ -49,7 +41,6 @@ module Stagehand
             end
           end
         end
-        # rubocop:enable Metrics/BlockLength
       end
     end
   end

data/lib/stagehand/internal/util.rb

@@ -157,7 +157,7 @@ module Stagehand
           in Hash | nil => coerced
             coerced
           else
-            message = "Expected a #{Hash} or #{Stagehand::Internal::Type::BaseModel}, got #{data.inspect}"
+            message = "Expected a #{Hash} or #{Stagehand::Internal::Type::BaseModel}, got #{input.inspect}"
             raise ArgumentError.new(message)
           end
         end
@@ -237,6 +237,11 @@ module Stagehand
         end
       end
 
+      # @type [Regexp]
+      #
+      # https://www.rfc-editor.org/rfc/rfc3986.html#section-3.3
+      RFC_3986_NOT_PCHARS = /[^A-Za-z0-9\-._~!$&'()*+,;=:@]+/
+
       class << self
         # @api private
         #
@@ -247,6 +252,15 @@ module Stagehand
           "#{uri.scheme}://#{uri.host}#{":#{uri.port}" unless uri.port == uri.default_port}"
         end
 
+        # @api private
+        #
+        # @param path [String, Integer]
+        #
+        # @return [String]
+        def encode_path(path)
+          path.to_s.gsub(Stagehand::Internal::Util::RFC_3986_NOT_PCHARS) { ERB::Util.url_encode(_1) }
+        end
+
         # @api private
         #
         # @param path [String, Array<String>]
@@ -259,7 +273,7 @@ module Stagehand
           in []
             ""
           in [String => p, *interpolations]
-            encoded = interpolations.map { ERB::Util.url_encode(_1) }
+            encoded = interpolations.map { encode_path(_1) }
             format(p, *encoded)
           end
         end
@@ -490,6 +504,37 @@ module Stagehand
       JSONL_CONTENT = %r{^application/(:?x-(?:n|l)djson)|(:?(?:x-)?jsonl)}
 
       class << self
+        # @api private
+        #
+        # @param query [Hash{Symbol=>Object}]
+        #
+        # @return [Hash{Symbol=>Object}]
+        def encode_query_params(query)
+          out = {}
+          query.each { write_query_param_element!(out, _1, _2) }
+          out
+        end
+
+        # @api private
+        #
+        # @param collection [Hash{Symbol=>Object}]
+        # @param key [String]
+        # @param element [Object]
+        #
+        # @return [nil]
+        private def write_query_param_element!(collection, key, element)
+          case element
+          in Hash
+            element.each do |name, value|
+              write_query_param_element!(collection, "#{key}[#{name}]", value)
+            end
+          in Array
+            collection[key] = element.map(&:to_s).join(",")
+          else
+            collection[key] = element.to_s
+          end
+        end
+
         # @api private
         #
         # @param y [Enumerator::Yielder]
@@ -540,16 +585,15 @@ module Stagehand
           y << "Content-Disposition: form-data"
 
           unless key.nil?
-            name = ERB::Util.url_encode(key.to_s)
-            y << "; name=\"#{name}\""
+            y << "; name=\"#{key}\""
           end
 
           case val
           in Stagehand::FilePart unless val.filename.nil?
-            filename = ERB::Util.url_encode(val.filename)
+            filename = encode_path(val.filename)
             y << "; filename=\"#{filename}\""
           in Pathname | IO
-            filename = ERB::Util.url_encode(::File.basename(val.to_path))
+            filename = encode_path(::File.basename(val.to_path))
             y << "; filename=\"#{filename}\""
           else
           end

data/lib/stagehand/local.rb

@@ -85,7 +85,7 @@ module Stagehand
 
       def binary_filename
         platform, arch = platform_tag
-        name = "stagehand-server-#{platform}-#{arch}"
+        name = "stagehand-server-v3-#{platform}-#{arch}"
         name += ".exe" if platform == "win32"
         name
       end
@@ -131,9 +131,9 @@ module Stagehand
 
       def resolve_version(version)
         return fetch_latest_tag if version.empty? || version == "latest"
-        return version if version.start_with?("stagehand-server/")
+        return version if version.start_with?("stagehand-server-v3/")
 
-        "stagehand-server/#{version}"
+        "stagehand-server-v3/#{version}"
       end
 
       def fetch_latest_tag
@@ -148,9 +148,9 @@ module Stagehand
         releases = JSON.parse(response.body.to_s)
         releases.each do |release|
           tag = release["tag_name"]
-          return tag if tag.is_a?(String) && tag.start_with?("stagehand-server/")
+          return tag if tag.is_a?(String) && tag.start_with?("stagehand-server-v3/")
         end
-        raise "Failed to find stagehand-server release tag"
+        raise "Failed to find stagehand-server-v3 release tag"
       end
 
       def download_binary(tag, dest_path)

data/lib/stagehand/models/model_config.rb

@@ -21,19 +21,27 @@ module Stagehand
       #   @return [String, nil]
       optional :base_url, String, api_name: :baseURL
 
+      # @!attribute headers
+      #   Custom headers sent with every request to the model provider
+      #
+      #   @return [Hash{Symbol=>String}, nil]
+      optional :headers, Stagehand::Internal::Type::HashOf[String]
+
       # @!attribute provider
       #   AI provider for the model (or provide a baseURL endpoint instead)
       #
       #   @return [Symbol, Stagehand::Models::ModelConfig::Provider, nil]
       optional :provider, enum: -> { Stagehand::ModelConfig::Provider }
 
-      # @!method initialize(model_name:, api_key: nil, base_url: nil, provider: nil)
+      # @!method initialize(model_name:, api_key: nil, base_url: nil, headers: nil, provider: nil)
       #   @param model_name [String] Model name string with provider prefix (e.g., 'openai/gpt-5-nano')
       #
       #   @param api_key [String] API key for the model provider
       #
       #   @param base_url [String] Base URL for the model provider
       #
+      #   @param headers [Hash{Symbol=>String}] Custom headers sent with every request to the model provider
+      #
       #   @param provider [Symbol, Stagehand::Models::ModelConfig::Provider] AI provider for the model (or provide a baseURL endpoint instead)
 
       # AI provider for the model (or provide a baseURL endpoint instead)

data/lib/stagehand/models/session_act_params.rb

@@ -9,6 +9,12 @@ module Stagehand
       extend Stagehand::Internal::Type::RequestParameters::Converter
       include Stagehand::Internal::Type::RequestParameters
 
+      # @!attribute id
+      #   Unique session identifier
+      #
+      #   @return [String]
+      required :id, String
+
       # @!attribute input
       #   Natural language instruction or Action object
       #
@@ -32,7 +38,9 @@ module Stagehand
       #   @return [Symbol, Stagehand::Models::SessionActParams::XStreamResponse, nil]
       optional :x_stream_response, enum: -> { Stagehand::SessionActParams::XStreamResponse }
 
-      # @!method initialize(input:, frame_id: nil, options: nil, x_stream_response: nil, request_options: {})
+      # @!method initialize(id:, input:, frame_id: nil, options: nil, x_stream_response: nil, request_options: {})
+      #   @param id [String] Unique session identifier
+      #
       #   @param input [String, Stagehand::Models::Action] Natural language instruction or Action object
       #
       #   @param frame_id [String, nil] Target frame ID for the action
@@ -70,17 +78,22 @@ module Stagehand
         optional :timeout, Float
 
         # @!attribute variables
-        #   Variables to substitute in the action instruction
+        #   Variables to substitute in the action instruction. Accepts flat primitives or {
+        #   value, description? } objects.
         #
-        #   @return [Hash{Symbol=>String}, nil]
-        optional :variables, Stagehand::Internal::Type::HashOf[String]
+        #   @return [Hash{Symbol=>String, Float, Boolean, Stagehand::Models::SessionActParams::Options::Variable::UnionMember3}, nil]
+        optional :variables,
+                 -> { Stagehand::Internal::Type::HashOf[union: Stagehand::SessionActParams::Options::Variable] }
 
         # @!method initialize(model: nil, timeout: nil, variables: nil)
+        #   Some parameter documentations has been truncated, see
+        #   {Stagehand::Models::SessionActParams::Options} for more details.
+        #
         #   @param model [Stagehand::Models::ModelConfig, String] Model configuration object or model name string (e.g., 'openai/gpt-5-nano')
         #
         #   @param timeout [Float] Timeout in ms for the action
         #
-        #   @param variables [Hash{Symbol=>String}] Variables to substitute in the action instruction
+        #   @param variables [Hash{Symbol=>String, Float, Boolean, Stagehand::Models::SessionActParams::Options::Variable::UnionMember3}] Variables to substitute in the action instruction. Accepts flat primitives or {
 
         # Model configuration object or model name string (e.g., 'openai/gpt-5-nano')
         #
@@ -95,6 +108,51 @@ module Stagehand
           # @!method self.variants
           #   @return [Array(Stagehand::Models::ModelConfig, String)]
         end
+
+        module Variable
+          extend Stagehand::Internal::Type::Union
+
+          variant String
+
+          variant Float
+
+          variant Stagehand::Internal::Type::Boolean
+
+          variant -> { Stagehand::SessionActParams::Options::Variable::UnionMember3 }
+
+          class UnionMember3 < Stagehand::Internal::Type::BaseModel
+            # @!attribute value
+            #
+            #   @return [String, Float, Boolean]
+            required :value, union: -> { Stagehand::SessionActParams::Options::Variable::UnionMember3::Value }
+
+            # @!attribute description
+            #
+            #   @return [String, nil]
+            optional :description, String
+
+            # @!method initialize(value:, description: nil)
+            #   @param value [String, Float, Boolean]
+            #   @param description [String]
+
+            # @see Stagehand::Models::SessionActParams::Options::Variable::UnionMember3#value
+            module Value
+              extend Stagehand::Internal::Type::Union
+
+              variant String
+
+              variant Float
+
+              variant Stagehand::Internal::Type::Boolean
+
+              # @!method self.variants
+              #   @return [Array(String, Float, Boolean)]
+            end
+          end
+
+          # @!method self.variants
+          #   @return [Array(String, Float, Boolean, Stagehand::Models::SessionActParams::Options::Variable::UnionMember3)]
+        end
       end
 
       # Whether to stream the response via SSE

data/lib/stagehand/models/session_end_params.rb

@@ -7,13 +7,21 @@ module Stagehand
       extend Stagehand::Internal::Type::RequestParameters::Converter
       include Stagehand::Internal::Type::RequestParameters
 
+      # @!attribute id
+      #   Unique session identifier
+      #
+      #   @return [String]
+      required :id, String
+
       # @!attribute x_stream_response
       #   Whether to stream the response via SSE
       #
       #   @return [Symbol, Stagehand::Models::SessionEndParams::XStreamResponse, nil]
       optional :x_stream_response, enum: -> { Stagehand::SessionEndParams::XStreamResponse }
 
-      # @!method initialize(x_stream_response: nil, request_options: {})
+      # @!method initialize(id:, x_stream_response: nil, request_options: {})
+      #   @param id [String] Unique session identifier
+      #
       #   @param x_stream_response [Symbol, Stagehand::Models::SessionEndParams::XStreamResponse] Whether to stream the response via SSE
       #
       #   @param request_options [Stagehand::RequestOptions, Hash{Symbol=>Object}]

data/lib/stagehand/models/session_execute_params.rb

@@ -9,6 +9,12 @@ module Stagehand
       extend Stagehand::Internal::Type::RequestParameters::Converter
       include Stagehand::Internal::Type::RequestParameters
 
+      # @!attribute id
+      #   Unique session identifier
+      #
+      #   @return [String]
+      required :id, String
+
       # @!attribute agent_config
       #
       #   @return [Stagehand::Models::SessionExecuteParams::AgentConfig]
@@ -39,7 +45,9 @@ module Stagehand
       #   @return [Symbol, Stagehand::Models::SessionExecuteParams::XStreamResponse, nil]
       optional :x_stream_response, enum: -> { Stagehand::SessionExecuteParams::XStreamResponse }
 
-      # @!method initialize(agent_config:, execute_options:, frame_id: nil, should_cache: nil, x_stream_response: nil, request_options: {})
+      # @!method initialize(id:, agent_config:, execute_options:, frame_id: nil, should_cache: nil, x_stream_response: nil, request_options: {})
+      #   @param id [String] Unique session identifier
+      #
       #   @param agent_config [Stagehand::Models::SessionExecuteParams::AgentConfig]
       #
       #   @param execute_options [Stagehand::Models::SessionExecuteParams::ExecuteOptions]
@@ -190,12 +198,28 @@ module Stagehand
         #   @return [Float, nil]
         optional :max_steps, Float, api_name: :maxSteps
 
-        # @!method initialize(instruction:, highlight_cursor: nil, max_steps: nil)
+        # @!attribute tool_timeout
+        #   Timeout in milliseconds for each agent tool call
+        #
+        #   @return [Float, nil]
+        optional :tool_timeout, Float, api_name: :toolTimeout
+
+        # @!attribute use_search
+        #   Whether to enable the web search tool powered by Browserbase Search API
+        #
+        #   @return [Boolean, nil]
+        optional :use_search, Stagehand::Internal::Type::Boolean, api_name: :useSearch
+
+        # @!method initialize(instruction:, highlight_cursor: nil, max_steps: nil, tool_timeout: nil, use_search: nil)
         #   @param instruction [String] Natural language instruction for the agent
         #
         #   @param highlight_cursor [Boolean] Whether to visually highlight the cursor during execution
         #
         #   @param max_steps [Float] Maximum number of steps the agent can take
+        #
+        #   @param tool_timeout [Float] Timeout in milliseconds for each agent tool call
+        #
+        #   @param use_search [Boolean] Whether to enable the web search tool powered by Browserbase Search API
       end
 
       # Whether to stream the response via SSE

data/lib/stagehand/models/session_extract_params.rb

@@ -9,6 +9,12 @@ module Stagehand
       extend Stagehand::Internal::Type::RequestParameters::Converter
       include Stagehand::Internal::Type::RequestParameters
 
+      # @!attribute id
+      #   Unique session identifier
+      #
+      #   @return [String]
+      required :id, String
+
       # @!attribute frame_id
       #   Target frame ID for the extraction
       #
@@ -38,7 +44,9 @@ module Stagehand
       #   @return [Symbol, Stagehand::Models::SessionExtractParams::XStreamResponse, nil]
       optional :x_stream_response, enum: -> { Stagehand::SessionExtractParams::XStreamResponse }
 
-      # @!method initialize(frame_id: nil, instruction: nil, options: nil, schema: nil, x_stream_response: nil, request_options: {})
+      # @!method initialize(id:, frame_id: nil, instruction: nil, options: nil, schema: nil, x_stream_response: nil, request_options: {})
+      #   @param id [String] Unique session identifier
+      #
       #   @param frame_id [String, nil] Target frame ID for the extraction
       #
       #   @param instruction [String] Natural language instruction for what to extract

data/lib/stagehand/models/session_navigate_params.rb

@@ -7,6 +7,12 @@ module Stagehand
       extend Stagehand::Internal::Type::RequestParameters::Converter
       include Stagehand::Internal::Type::RequestParameters
 
+      # @!attribute id
+      #   Unique session identifier
+      #
+      #   @return [String]
+      required :id, String
+
       # @!attribute url
       #   URL to navigate to
       #
@@ -36,7 +42,9 @@ module Stagehand
       #   @return [Symbol, Stagehand::Models::SessionNavigateParams::XStreamResponse, nil]
       optional :x_stream_response, enum: -> { Stagehand::SessionNavigateParams::XStreamResponse }
 
-      # @!method initialize(url:, frame_id: nil, options: nil, stream_response: nil, x_stream_response: nil, request_options: {})
+      # @!method initialize(id:, url:, frame_id: nil, options: nil, stream_response: nil, x_stream_response: nil, request_options: {})
+      #   @param id [String] Unique session identifier
+      #
       #   @param url [String] URL to navigate to
       #
       #   @param frame_id [String, nil] Target frame ID for the navigation

data/lib/stagehand/models/session_observe_params.rb

@@ -9,6 +9,12 @@ module Stagehand
       extend Stagehand::Internal::Type::RequestParameters::Converter
       include Stagehand::Internal::Type::RequestParameters
 
+      # @!attribute id
+      #   Unique session identifier
+      #
+      #   @return [String]
+      required :id, String
+
       # @!attribute frame_id
       #   Target frame ID for the observation
       #
@@ -32,7 +38,9 @@ module Stagehand
       #   @return [Symbol, Stagehand::Models::SessionObserveParams::XStreamResponse, nil]
       optional :x_stream_response, enum: -> { Stagehand::SessionObserveParams::XStreamResponse }
 
-      # @!method initialize(frame_id: nil, instruction: nil, options: nil, x_stream_response: nil, request_options: {})
+      # @!method initialize(id:, frame_id: nil, instruction: nil, options: nil, x_stream_response: nil, request_options: {})
+      #   @param id [String] Unique session identifier
+      #
       #   @param frame_id [String, nil] Target frame ID for the observation
       #
       #   @param instruction [String] Natural language instruction for what actions to find
@@ -62,12 +70,26 @@ module Stagehand
         #   @return [Float, nil]
         optional :timeout, Float
 
-        # @!method initialize(model: nil, selector: nil, timeout: nil)
+        # @!attribute variables
+        #   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.
+        #
+        #   @return [Hash{Symbol=>String, Float, Boolean, Stagehand::Models::SessionObserveParams::Options::Variable::UnionMember3}, nil]
+        optional :variables,
+                 -> { Stagehand::Internal::Type::HashOf[union: Stagehand::SessionObserveParams::Options::Variable] }
+
+        # @!method initialize(model: nil, selector: nil, timeout: nil, variables: nil)
+        #   Some parameter documentations has been truncated, see
+        #   {Stagehand::Models::SessionObserveParams::Options} for more details.
+        #
         #   @param model [Stagehand::Models::ModelConfig, String] Model configuration object or model name string (e.g., 'openai/gpt-5-nano')
         #
         #   @param selector [String] CSS selector to scope observation to a specific element
         #
         #   @param timeout [Float] Timeout in ms for the observation
+        #
+        #   @param variables [Hash{Symbol=>String, Float, Boolean, Stagehand::Models::SessionObserveParams::Options::Variable::UnionMember3}] Variables whose names are exposed to the model so observe() returns %variableNam
 
         # Model configuration object or model name string (e.g., 'openai/gpt-5-nano')
         #
@@ -82,6 +104,51 @@ module Stagehand
           # @!method self.variants
           #   @return [Array(Stagehand::Models::ModelConfig, String)]
         end
+
+        module Variable
+          extend Stagehand::Internal::Type::Union
+
+          variant String
+
+          variant Float
+
+          variant Stagehand::Internal::Type::Boolean
+
+          variant -> { Stagehand::SessionObserveParams::Options::Variable::UnionMember3 }
+
+          class UnionMember3 < Stagehand::Internal::Type::BaseModel
+            # @!attribute value
+            #
+            #   @return [String, Float, Boolean]
+            required :value, union: -> { Stagehand::SessionObserveParams::Options::Variable::UnionMember3::Value }
+
+            # @!attribute description
+            #
+            #   @return [String, nil]
+            optional :description, String
+
+            # @!method initialize(value:, description: nil)
+            #   @param value [String, Float, Boolean]
+            #   @param description [String]
+
+            # @see Stagehand::Models::SessionObserveParams::Options::Variable::UnionMember3#value
+            module Value
+              extend Stagehand::Internal::Type::Union
+
+              variant String
+
+              variant Float
+
+              variant Stagehand::Internal::Type::Boolean
+
+              # @!method self.variants
+              #   @return [Array(String, Float, Boolean)]
+            end
+          end
+
+          # @!method self.variants
+          #   @return [Array(String, Float, Boolean, Stagehand::Models::SessionObserveParams::Options::Variable::UnionMember3)]
+        end
       end
 
       # Whether to stream the response via SSE

data/lib/stagehand/models/session_replay_params.rb

@@ -7,13 +7,21 @@ module Stagehand
       extend Stagehand::Internal::Type::RequestParameters::Converter
       include Stagehand::Internal::Type::RequestParameters
 
+      # @!attribute id
+      #   Unique session identifier
+      #
+      #   @return [String]
+      required :id, String
+
       # @!attribute x_stream_response
       #   Whether to stream the response via SSE
       #
       #   @return [Symbol, Stagehand::Models::SessionReplayParams::XStreamResponse, nil]
       optional :x_stream_response, enum: -> { Stagehand::SessionReplayParams::XStreamResponse }
 
-      # @!method initialize(x_stream_response: nil, request_options: {})
+      # @!method initialize(id:, x_stream_response: nil, request_options: {})
+      #   @param id [String] Unique session identifier
+      #
       #   @param x_stream_response [Symbol, Stagehand::Models::SessionReplayParams::XStreamResponse] Whether to stream the response via SSE
       #
       #   @param request_options [Stagehand::RequestOptions, Hash{Symbol=>Object}]