stagehand 3.7.1 → 3.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 87ccf4bfcfc723469ff68db45b650d9f2702c6692905a8f6a42e7456d6d37b63
-  data.tar.gz: dbcfc350b71c0a0d89cad72696fcde9fc3f506d425fedd56e2e611b176070a73
+  metadata.gz: 74284602dc9bdaf010605da5b97177bfa1335a28e7e2048f924a0025298f5a8d
+  data.tar.gz: 45de340a9ce93503b5cd851e87ebc862311fd7c59e5940c5b2b507b8d67ab56a
 SHA512:
-  metadata.gz: 1bafc8973dd2a0844797e67c0ecb04fdf0a3b8245ff0639af4f9334da95cdfbc6701f00ab8519ae07a998478383b14c633c8e3bd823c991caa4623ac5b9ace0d
-  data.tar.gz: 2e35f3d9adace66379d78c8631d271932d040ccc2aa190a793f074e37e1ea737c766424f21ebd2e6bfbd49687d9073e223615db052b624ff7488c641e3dedf81
+  metadata.gz: f50f38f6542f249eb99c63399f8d963f37b447e78d40d641c9f535076f671a04c70a9850d31c9f7533dd105d0fa20bf6305b5fdb3928fc38f839f9524285cd00
+  data.tar.gz: cc10728334054f28603904751f0a4b69a773ea6b4445dfd3b336e9a4eae0a029a8b819208b925cb317a1499bbf298f97233355e0c07d59b9a82f6ea3d2facc72

data/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 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/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

@@ -490,6 +490,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]

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}]

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.18.0"
 end

data/rbi/stagehand/internal/util.rbi

@@ -301,6 +301,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
           }
         )