release: 3.8.0

.github/workflows/ci.yml

@@ -13,6 +13,44 @@ on:
       - 'stl-preview-base/**'
 
 jobs:
+  build:
+    timeout-minutes: 10
+    name: build
+    permissions:
+      contents: read
+      id-token: write
+    runs-on: ${{ github.repository == 'stainless-sdks/stagehand-ruby' && 'depot-ubuntu-24.04' || 'ubuntu-latest' }}
+    if: |-
+      github.repository == 'stainless-sdks/stagehand-ruby' &&
+      (github.event_name == 'push' || github.event.pull_request.head.repo.fork)
+    steps:
+      - uses: actions/checkout@v6
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          bundler-cache: false
+      - run: |-
+          bundle install
+
+      - name: Get GitHub OIDC Token
+        if: |-
+          github.repository == 'stainless-sdks/stagehand-ruby' &&
+          !startsWith(github.ref, 'refs/heads/stl/')
+        id: github-oidc
+        uses: actions/github-script@v8
+        with:
+          script: core.setOutput('github_token', await core.getIDToken());
+
+      - name: Build and upload gem artifacts
+        if: |-
+          github.repository == 'stainless-sdks/stagehand-ruby' &&
+          !startsWith(github.ref, 'refs/heads/stl/')
+        env:
+          URL: https://pkg.stainless.com/s
+          AUTH: ${{ steps.github-oidc.outputs.github_token }}
+          SHA: ${{ github.sha }}
+          PACKAGE_NAME: stagehand
+        run: ./scripts/utils/upload-artifact.sh
   lint:
     timeout-minutes: 10
     name: lint

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "3.7.1"
+  ".": "3.8.0"
 }

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 8
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/browserbase%2Fstagehand-a4e672f457dd99336f4b2a113fd7c7c6c9db0941b38d57cff6e3641549a6c4ed.yml
-openapi_spec_hash: eae9c8561e420db8e4d238c1e59617fb
-config_hash: 2a565ad6662259a2e90fa5f1f5095525
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/browserbase%2Fstagehand-573d364768ac1902ee5ed8b2485d3b293bda0ea8ff7898aef1a3fd6be79b594a.yml
+openapi_spec_hash: 107ec840f4330885dd2232a05a66fed7
+config_hash: 0209737a4ab2a71afececb0ff7459998

CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 3.8.0 (2026-03-11)
+
+Full Changelog: [v3.7.1...v3.8.0](https://github.com/browserbase/stagehand-ruby/compare/v3.7.1...v3.8.0)
+
+### Features
+
+* Add missing cdpHeaders field to v3 server openapi spec ([de6457f](https://github.com/browserbase/stagehand-ruby/commit/de6457f121764ffbadac51ec2a6103c27dbde338))
+
+
+### Chores
+
+* **ci:** add build step ([ed6573f](https://github.com/browserbase/stagehand-ruby/commit/ed6573f2ddab4f5f51d1262480cb663da5e003d0))
+* **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))
+
 ## 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)

Gemfile.lock

@@ -11,7 +11,7 @@ GIT
 PATH
   remote: .
   specs:
-    stagehand (3.7.1)
+    stagehand (3.8.0)
       cgi
       connection_pool
 

lib/stagehand/internal/util.rb

@@ -490,6 +490,37 @@ def writable_enum(&blk)
       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]

lib/stagehand/local.rb

@@ -85,7 +85,7 @@ def platform_tag
 
       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 @@ def home_dir
 
       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 @@ def fetch_latest_tag
         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)

lib/stagehand/models/session_act_params.rb

@@ -9,6 +9,12 @@ class SessionActParams < Stagehand::Internal::Type::BaseModel
       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 @@ class SessionActParams < Stagehand::Internal::Type::BaseModel
       #   @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

lib/stagehand/models/session_end_params.rb

@@ -7,13 +7,21 @@ class SessionEndParams < Stagehand::Internal::Type::BaseModel
       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}]

lib/stagehand/models/session_execute_params.rb

@@ -9,6 +9,12 @@ class SessionExecuteParams < Stagehand::Internal::Type::BaseModel
       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 @@ class SessionExecuteParams < Stagehand::Internal::Type::BaseModel
       #   @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]

lib/stagehand/models/session_extract_params.rb

@@ -9,6 +9,12 @@ class SessionExtractParams < Stagehand::Internal::Type::BaseModel
       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 @@ class SessionExtractParams < Stagehand::Internal::Type::BaseModel
       #   @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

lib/stagehand/models/session_navigate_params.rb

@@ -7,6 +7,12 @@ class SessionNavigateParams < Stagehand::Internal::Type::BaseModel
       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 @@ class SessionNavigateParams < Stagehand::Internal::Type::BaseModel
       #   @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

lib/stagehand/models/session_observe_params.rb

@@ -9,6 +9,12 @@ class SessionObserveParams < Stagehand::Internal::Type::BaseModel
       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 @@ class SessionObserveParams < Stagehand::Internal::Type::BaseModel
       #   @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

lib/stagehand/models/session_replay_params.rb

@@ -7,13 +7,21 @@ class SessionReplayParams < Stagehand::Internal::Type::BaseModel
       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}]

lib/stagehand/models/session_start_params.rb

@@ -144,6 +144,11 @@ class LaunchOptions < Stagehand::Internal::Type::BaseModel
           #   @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 @@ class LaunchOptions < Stagehand::Internal::Type::BaseModel
           #   @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]

lib/stagehand/version.rb

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

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(