stagehand 0.0.4 → 3.6.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 50f660b2c567e5cc200d36aedaebafd5de79c1d41f9402a73a5f7c1ebb539f8a
+  data.tar.gz: 70f5dd300c85f94fd3ef9e6e083bb12e6469d6cb2dce31e08d8e1610e532618f
+SHA512:
+  metadata.gz: 955bb2a558c4167c28d8ea9d14ba9fe0ba4b520d9828018faa57c0ea3795535214d4838f9010ffab06c3553469ceb518ce7a11d2bac35ab6f7b3d9b81db9457b
+  data.tar.gz: fd0464bc25e63eeb06c9799631d527fe5239214024eab2f2faef41a556716644c460f517d250470659c53dd3d69e21f100beda01f21e4bef548ac3bbee94865b

data/.ignore

@@ -0,0 +1,2 @@
+rbi/*
+sig/*

data/CHANGELOG.md

@@ -0,0 +1,193 @@
+# Changelog
+
+## 3.6.0 (2026-02-18)
+
+Full Changelog: [v3.5.2...v3.6.0](https://github.com/browserbase/stagehand-ruby/compare/v3.5.2...v3.6.0)
+
+### Features
+
+* randomize region used for evals, split out pnpm and turbo cache, veri… ([a68a9d2](https://github.com/browserbase/stagehand-ruby/commit/a68a9d2705b2c3b3b35dcaab4b5693184194774b))
+
+## 3.5.2 (2026-02-07)
+
+Full Changelog: [v3.5.1...v3.5.2](https://github.com/browserbase/stagehand-ruby/compare/v3.5.1...v3.5.2)
+
+### Bug Fixes
+
+* **client:** loosen json header parsing ([ea4142c](https://github.com/browserbase/stagehand-ruby/commit/ea4142cc5973c9207a81c7336c8425c9dbe63a30))
+
+
+### Chores
+
+* **docs:** remove www prefix ([8498bdd](https://github.com/browserbase/stagehand-ruby/commit/8498bdd34e0288b8a1c28e789d35dcecf91cd8b7))
+
+## 3.5.1 (2026-02-03)
+
+Full Changelog: [v3.5.0...v3.5.1](https://github.com/browserbase/stagehand-ruby/compare/v3.5.0...v3.5.1)
+
+### Bug Fixes
+
+* **client:** always add content-length to post body, even when empty ([7c7c43e](https://github.com/browserbase/stagehand-ruby/commit/7c7c43e51dd621d74dab8d1fa47de0dcc9bc0a28))
+
+## 3.5.0 (2026-02-03)
+
+Full Changelog: [v3.4.0...v3.5.0](https://github.com/browserbase/stagehand-ruby/compare/v3.4.0...v3.5.0)
+
+### Features
+
+* Removed MCP from readme for now ([ad8d58e](https://github.com/browserbase/stagehand-ruby/commit/ad8d58ef0e542592e9001b32ef3e921f480218da))
+
+## 3.4.0 (2026-01-29)
+
+Full Changelog: [v3.3.0...v3.4.0](https://github.com/browserbase/stagehand-ruby/compare/v3.3.0...v3.4.0)
+
+### Features
+
+* Add executionModel serialization to api client ([2042742](https://github.com/browserbase/stagehand-ruby/commit/20427425012c9ee785d18a74596808471be2dc7b))
+
+## 3.3.0 (2026-01-29)
+
+Full Changelog: [v3.2.1...v3.3.0](https://github.com/browserbase/stagehand-ruby/compare/v3.2.1...v3.3.0)
+
+### Features
+
+* Update stainless.yml for project and publish settings ([c55365a](https://github.com/browserbase/stagehand-ruby/commit/c55365a3bbc0ba0bdea32a10e13c58e5863e3ce4))
+
+
+### Bug Fixes
+
+* **docs:** fix mcp installation instructions for remote servers ([cd5418d](https://github.com/browserbase/stagehand-ruby/commit/cd5418d7b003862fcee89f5723a1e6449bdee8fa))
+
+## 3.2.1 (2026-01-27)
+
+Full Changelog: [v3.2.0...v3.2.1](https://github.com/browserbase/stagehand-ruby/compare/v3.2.0...v3.2.1)
+
+## 3.2.0 (2026-01-27)
+
+Full Changelog: [v3.1.0...v3.2.0](https://github.com/browserbase/stagehand-ruby/compare/v3.1.0...v3.2.0)
+
+### Features
+
+* add auto-bedrock support based on bedrock/provider.model-name ([fb3762b](https://github.com/browserbase/stagehand-ruby/commit/fb3762b610c4f3049bc74790424556c770bffcf4))
+
+## 3.1.0 (2026-01-27)
+
+Full Changelog: [v3.0.3...v3.1.0](https://github.com/browserbase/stagehand-ruby/compare/v3.0.3...v3.1.0)
+
+### Features
+
+* **api:** manual updates ([eb975f5](https://github.com/browserbase/stagehand-ruby/commit/eb975f5fa5718d2b8e715e8315ea66f898a0dfdc))
+
+## 3.0.3 (2026-01-27)
+
+Full Changelog: [v3.0.2...v3.0.3](https://github.com/browserbase/stagehand-ruby/compare/v3.0.2...v3.0.3)
+
+## 3.0.2 (2026-01-22)
+
+Full Changelog: [v3.0.1...v3.0.2](https://github.com/browserbase/stagehand-ruby/compare/v3.0.1...v3.0.2)
+
+### Chores
+
+* remove custom code ([3943364](https://github.com/browserbase/stagehand-ruby/commit/394336419ed210704639af03445858f44f03ba13))
+
+## 3.0.1 (2026-01-15)
+
+Full Changelog: [v0.6.2...v3.0.1](https://github.com/browserbase/stagehand-ruby/compare/v0.6.2...v3.0.1)
+
+## 0.6.2 (2026-01-13)
+
+Full Changelog: [v0.6.1...v0.6.2](https://github.com/browserbase/stagehand-ruby/compare/v0.6.1...v0.6.2)
+
+## 0.6.1 (2026-01-06)
+
+Full Changelog: [v0.6.0...v0.6.1](https://github.com/browserbase/stagehand-ruby/compare/v0.6.0...v0.6.1)
+
+### Documentation
+
+* add full example and update examples in README ([#8](https://github.com/browserbase/stagehand-ruby/issues/8)) ([3d8b897](https://github.com/browserbase/stagehand-ruby/commit/3d8b8978c4623f906fd809fdd44c91539098fe00))
+* prominently feature MCP server setup in root SDK readmes ([f9a368b](https://github.com/browserbase/stagehand-ruby/commit/f9a368b0508862cd3ee53198ac92fe1265c5050f))
+
+## 0.6.0 (2026-01-05)
+
+Full Changelog: [v0.5.0...v0.6.0](https://github.com/browserbase/stagehand-ruby/compare/v0.5.0...v0.6.0)
+
+### Features
+
+* **api:** manual updates ([ffa5258](https://github.com/browserbase/stagehand-ruby/commit/ffa5258d23db78c2aa398289bc4d775fd5d145f0))
+
+## 0.5.0 (2025-12-23)
+
+Full Changelog: [v0.4.0...v0.5.0](https://github.com/browserbase/stagehand-ruby/compare/v0.4.0...v0.5.0)
+
+### Features
+
+* [STG-1053] [server] Use fastify-zod-openapi + zod v4 for openapi generation ([926a819](https://github.com/browserbase/stagehand-ruby/commit/926a819a4bbe2b260d3dbd46b860c444f60857bf))
+* **api:** manual updates ([0619302](https://github.com/browserbase/stagehand-ruby/commit/061930217b3efce30e29cf8b2511970b21c86c57))
+
+
+### Documentation
+
+* add more examples ([3e81eba](https://github.com/browserbase/stagehand-ruby/commit/3e81eba0b962a3ec0c9a8b13fc9ae30f0961663e))
+
+## 0.4.0 (2025-12-19)
+
+Full Changelog: [v0.3.0...v0.4.0](https://github.com/browserbase/stagehand-ruby/compare/v0.3.0...v0.4.0)
+
+### Features
+
+* **api:** manual updates ([c93a988](https://github.com/browserbase/stagehand-ruby/commit/c93a988374918f841643a84145b3008970b665a7))
+
+
+### Bug Fixes
+
+* issue where json.parse errors when receiving HTTP 204 with nobody ([fc3e31e](https://github.com/browserbase/stagehand-ruby/commit/fc3e31e00944a7fdf89e367e281bc0510847d15e))
+
+## 0.3.0 (2025-12-17)
+
+Full Changelog: [v0.2.0...v0.3.0](https://github.com/browserbase/stagehand-ruby/compare/v0.2.0...v0.3.0)
+
+### Features
+
+* **api:** manual updates ([7dcf75c](https://github.com/browserbase/stagehand-ruby/commit/7dcf75cc0c580743b8bb0bbdb41077a6a7aa6dfb))
+* **api:** manual updates ([3162ca0](https://github.com/browserbase/stagehand-ruby/commit/3162ca00c75b37ccb869d7a082f25b263e15d93d))
+* **api:** manual updates ([a972ef7](https://github.com/browserbase/stagehand-ruby/commit/a972ef7dc9040af201ee8e87db013fc077a7ab3f))
+* **api:** manual updates ([be169eb](https://github.com/browserbase/stagehand-ruby/commit/be169ebb8a61b86f4d1caee63aeded39139f10aa))
+* **api:** manual updates ([2a98da9](https://github.com/browserbase/stagehand-ruby/commit/2a98da9563a1ab4e33d6bf3398083d772b61e07f))
+* **api:** manual updates ([05879da](https://github.com/browserbase/stagehand-ruby/commit/05879da16a92ae6199ca2c4e323a6602fbc5d841))
+* **api:** manual updates ([69e4183](https://github.com/browserbase/stagehand-ruby/commit/69e418398b943df8b7454b50ab02d17ba3feb212))
+* **api:** manual updates ([9176bca](https://github.com/browserbase/stagehand-ruby/commit/9176bcaf88f115335199a44a52c8e1d697920822))
+* **api:** manual updates ([36f0681](https://github.com/browserbase/stagehand-ruby/commit/36f0681452a11e25da7126e0270855bbdd3fe8df))
+
+
+### Bug Fixes
+
+* calling `break` out of streams should be instantaneous ([369b9d0](https://github.com/browserbase/stagehand-ruby/commit/369b9d0d37390d96fa673d08e64594cefc6a04fa))
+
+## 0.2.0 (2025-12-16)
+
+Full Changelog: [v0.1.0...v0.2.0](https://github.com/browserbase/stagehand-ruby/compare/v0.1.0...v0.2.0)
+
+### Features
+
+* **api:** manual updates ([d660a3a](https://github.com/browserbase/stagehand-ruby/commit/d660a3ad9cd54238d2bc6598b576e7677ebf120f))
+* **api:** manual updates ([c21cb20](https://github.com/browserbase/stagehand-ruby/commit/c21cb20650bbad1ba8f6a89ad33dcf5ddfc53c81))
+* **api:** manual updates ([f04453c](https://github.com/browserbase/stagehand-ruby/commit/f04453c6c2050b7815e3f62d14343dee4698879d))
+
+## 0.1.0 (2025-12-16)
+
+Full Changelog: [v0.0.1...v0.1.0](https://github.com/browserbase/stagehand-ruby/compare/v0.0.1...v0.1.0)
+
+### Features
+
+* **api:** manual updates ([5deaf8f](https://github.com/browserbase/stagehand-ruby/commit/5deaf8ff2011a2808dcfe66ef14470029bb3590e))
+* **api:** manual updates ([87ce5f3](https://github.com/browserbase/stagehand-ruby/commit/87ce5f320056fb34770be2f0c87985960e995e92))
+* **api:** manual updates ([2a8b9e7](https://github.com/browserbase/stagehand-ruby/commit/2a8b9e7d219360a5e783c650fc7c9544a9a6fbb5))
+* **api:** manual updates ([0bcedba](https://github.com/browserbase/stagehand-ruby/commit/0bcedbaf26918822abdc958e6020f68b263ffee0))
+* **api:** manual updates ([8355d5e](https://github.com/browserbase/stagehand-ruby/commit/8355d5e6b83f6c31f6494f771fba51b6e31023e7))
+* **api:** manual updates ([655f517](https://github.com/browserbase/stagehand-ruby/commit/655f51718008b4c512eed1ce65660dae80039e49))
+* **api:** tweak branding and fix some config fields ([c48f36e](https://github.com/browserbase/stagehand-ruby/commit/c48f36e307aafd9a2d6ac59d9857be789f29eaa1))
+
+
+### Chores
+
+* configure new SDK language ([3be44a3](https://github.com/browserbase/stagehand-ruby/commit/3be44a344d5bc49e7c2e16129c2b24db175f4eb6))

data/README.md

@@ -1,31 +1,403 @@
-Stagehand
-=========
-
-Stagehand is a client-side library for manipulating RESTful resources provided by Personas, a Rails + Backbone user managment service.
-
-Usage
-=====
-
-    YourApp::Application.configure do           
-      config.stagehand.client_id = 'YOUR_APP_CLIENT_ID'
-      config.stagehand.client_secret = 'YOUR_APP_CLIENT_SECRET'
-      config.stagehand.resource_host = 'YOUR_APP_RESOURCE_HOST'
-      config.stagehand.client_host = 'YOUR_APP_HOST_WITH_PORT'
-    end                          
-    
-    class SessionsController < ApplicationController
-      # stagehand.authorize_url is an OAuth 2.0 url created by the 
-      # configuration variables above. After the user is authenticated
-      # and grants the client app access, the resource host performs
-      # a callback setting the session[:access_token] and redirects
-      # to the client app's root_url.
-      def new  
-        redirect_to Stagehand.authorize_url
-      end  
-      
-      # Destroy the access_token (but leave the OAuth host cookie intact)  
-      def destroy
-        session[:access_token] = nil
-        redirect_to root_url, :notice => "Logged out!"
-      end
-    end
+# Stagehand Ruby API library
+
+<!-- x-stagehand-custom-start -->
+<div id="toc" align="center" style="margin-bottom: 0;">
+  <ul style="list-style: none; margin: 0; padding: 0;">
+    <a href="https://stagehand.dev">
+      <picture>
+        <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/browserbase/stagehand/main/media/dark_logo.png" />
+        <img alt="Stagehand" src="https://raw.githubusercontent.com/browserbase/stagehand/main/media/light_logo.png" width="200" style="margin-right: 30px;" />
+      </picture>
+    </a>
+  </ul>
+</div>
+<p align="center">
+  <strong>The AI Browser Automation Framework</strong><br>
+  <a href="https://docs.stagehand.dev/v3/sdk/ruby">Read the Docs</a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/browserbase/stagehand/tree/main?tab=MIT-1-ov-file#MIT-1-ov-file">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/browserbase/stagehand/main/media/dark_license.svg" />
+      <img alt="MIT License" src="https://raw.githubusercontent.com/browserbase/stagehand/main/media/light_license.svg" />
+    </picture>
+  </a>
+  <a href="https://stagehand.dev/discord">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/browserbase/stagehand/main/media/dark_discord.svg" />
+      <img alt="Discord Community" src="https://raw.githubusercontent.com/browserbase/stagehand/main/media/light_discord.svg" />
+    </picture>
+  </a>
+</p>
+
+<p align="center">
+	<a href="https://trendshift.io/repositories/12122" target="_blank"><img src="https://trendshift.io/api/badge/repositories/12122" alt="browserbase%2Fstagehand | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
+</p>
+
+<p align="center">
+If you're looking for other languages, you can find them
+<a href="https://docs.stagehand.dev/v3/first-steps/introduction"> here</a>
+</p>
+
+<div align="center" style="display: flex; align-items: center; justify-content: center; gap: 4px; margin-bottom: 0;">
+  <b>Vibe code</b>
+  <span style="font-size: 1.05em;"> Stagehand with </span>
+  <a href="https://director.ai" style="display: flex; align-items: center;">
+    <span>Director</span>
+  </a>
+  <span> </span>
+  <picture>
+    <img alt="Director" src="https://raw.githubusercontent.com/browserbase/stagehand/main/media/director_icon.svg" width="25" />
+  </picture>
+</div>
+<!-- x-stagehand-custom-end -->
+
+The Stagehand Ruby library provides convenient access to the Stagehand REST API from any Ruby 3.2.0+ application. It ships with comprehensive types & docstrings in Yard, RBS, and RBI – [see below](https://github.com/browserbase/stagehand-ruby#Sorbet) for usage with Sorbet. The standard library's `net/http` is used as the HTTP transport, with connection pooling via the `connection_pool` gem.
+
+It is generated with [Stainless](https://www.stainless.com/).
+
+## Documentation
+
+Documentation for releases of this gem can be found [on RubyDoc](https://gemdocs.org/gems/stagehand).
+
+The REST API documentation can be found on [docs.stagehand.dev](https://docs.stagehand.dev).
+
+## Installation
+
+To use this gem, install via Bundler by adding the following to your application's `Gemfile`:
+
+<!-- x-release-please-start-version -->
+
+```ruby
+gem "stagehand", :git => "git://github.com/browserbase/stagehand-ruby.git"
+```
+
+<!-- x-release-please-end -->
+
+## Usage
+
+This mirrors `examples/remote_browser_playwright_example.rb`.
+
+```ruby
+require "bundler/setup"
+require "stagehand"
+
+require_relative "examples/env"
+ExampleEnv.load!
+
+require "playwright"
+
+client = Stagehand::Client.new(
+  browserbase_api_key: ENV["BROWSERBASE_API_KEY"],
+  browserbase_project_id: ENV["BROWSERBASE_PROJECT_ID"],
+  model_api_key: ENV["MODEL_API_KEY"],
+  server: "remote"
+)
+
+start_response = client.sessions.start(
+  model_name: "anthropic/claude-sonnet-4-6",
+  browser: { type: :browserbase }
+)
+
+session_id = start_response.data.session_id
+cdp_url = start_response.data.cdp_url
+raise "No CDP URL returned for this session." if cdp_url.to_s.empty?
+
+Playwright.create(playwright_cli_executable_path: "./node_modules/.bin/playwright") do |playwright|
+  browser = playwright.chromium.connect_over_cdp(cdp_url)
+  context = browser.contexts.first || browser.new_context
+  page = context.pages.first || context.new_page
+
+  client.sessions.navigate(session_id, url: "https://news.ycombinator.com")
+  page.wait_for_load_state(state: "domcontentloaded")
+
+  observe_stream = client.sessions.observe_streaming(
+    session_id,
+    instruction: "find the link to view comments for the top post"
+  )
+  observe_stream.each { |_event| }
+
+  act_stream = client.sessions.act_streaming(
+    session_id,
+    input: "Click the comments link for the top post"
+  )
+  act_stream.each { |_event| }
+
+  extract_stream = client.sessions.extract_streaming(
+    session_id,
+    instruction: "extract the text of the top comment on this page",
+    schema: {
+      type: "object",
+      properties: {
+        commentText: {type: "string"},
+        author: {type: "string"}
+      },
+      required: ["commentText"]
+    }
+  )
+  extract_stream.each { |_event| }
+
+  execute_stream = client.sessions.execute_streaming(
+    session_id,
+    execute_options: {
+      instruction: "Click the 'Learn more' link if available",
+      max_steps: 3
+    },
+    agent_config: {
+      model: Stagehand::ModelConfig.new(
+        model_name: "anthropic/claude-opus-4-6",
+        api_key: ENV["MODEL_API_KEY"]
+      ),
+      cua: false
+    }
+  )
+  execute_stream.each { |_event| }
+end
+
+client.sessions.end_(session_id)
+```
+
+## Running the Example
+
+Set your environment variables (from `examples/.env.example`):
+
+- `STAGEHAND_API_URL`
+- `MODEL_API_KEY`
+- `BROWSERBASE_API_KEY`
+- `BROWSERBASE_PROJECT_ID`
+
+```bash
+cp examples/.env.example examples/.env
+# Edit examples/.env with your credentials.
+```
+
+The examples load `examples/.env` automatically.
+
+Examples and dependencies:
+
+- `examples/remote_browser_example.rb`: stagehand only
+- `examples/local_browser_example.rb`: stagehand only
+- `examples/remote_browser_playwright_example.rb`: `playwright-ruby-client` + Playwright browsers
+- `examples/local_browser_playwright_example.rb`: `playwright-ruby-client` + Playwright browsers
+- `examples/local_playwright_example.rb`: `playwright-ruby-client` + Playwright browsers
+- `examples/local_watir_example.rb`: `watir`
+
+Install dependencies for the example you want to run, then execute it:
+
+```bash
+bundle install
+bundle exec ruby examples/remote_browser_playwright_example.rb
+```
+
+### Streaming
+
+We provide support for streaming responses using Server-Sent Events (SSE).
+
+```ruby
+stream = stagehand.sessions.act_streaming(
+  "00000000-your-session-id-000000000000",
+  input: "click the first link on the page"
+)
+
+stream.each do |session|
+  puts(session.data)
+end
+```
+
+### Handling errors
+
+When the library is unable to connect to the API, or if the API returns a non-success status code (i.e., 4xx or 5xx response), a subclass of `Stagehand::Errors::APIError` will be thrown:
+
+```ruby
+begin
+  session = stagehand.sessions.start(model_name: "anthropic/claude-sonnet-4-6")
+rescue Stagehand::Errors::APIConnectionError => e
+  puts("The server could not be reached")
+  puts(e.cause)  # an underlying Exception, likely raised within `net/http`
+rescue Stagehand::Errors::RateLimitError => e
+  puts("A 429 status code was received; we should back off a bit.")
+rescue Stagehand::Errors::APIStatusError => e
+  puts("Another non-200-range status code was received")
+  puts(e.status)
+end
+```
+
+Error codes are as follows:
+
+| Cause            | Error Type                 |
+| ---------------- | -------------------------- |
+| HTTP 400         | `BadRequestError`          |
+| HTTP 401         | `AuthenticationError`      |
+| HTTP 403         | `PermissionDeniedError`    |
+| HTTP 404         | `NotFoundError`            |
+| HTTP 409         | `ConflictError`            |
+| HTTP 422         | `UnprocessableEntityError` |
+| HTTP 429         | `RateLimitError`           |
+| HTTP >= 500      | `InternalServerError`      |
+| Other HTTP error | `APIStatusError`           |
+| Timeout          | `APITimeoutError`          |
+| Network error    | `APIConnectionError`       |
+
+### Retries
+
+Certain errors will be automatically retried 2 times by default, with a short exponential backoff.
+
+Connection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict, 429 Rate Limit, >=500 Internal errors, and timeouts will all be retried by default.
+
+You can use the `max_retries` option to configure or disable this:
+
+```ruby
+# Configure the default for all requests:
+stagehand = Stagehand::Client.new(
+  max_retries: 0 # default is 2
+)
+
+# Or, configure per-request:
+stagehand.sessions.start(model_name: "anthropic/claude-sonnet-4-6", request_options: {max_retries: 5})
+```
+
+### Timeouts
+
+By default, requests will time out after 60 seconds. You can use the timeout option to configure or disable this:
+
+```ruby
+# Configure the default for all requests:
+stagehand = Stagehand::Client.new(
+  timeout: nil # default is 60
+)
+
+# Or, configure per-request:
+stagehand.sessions.start(model_name: "anthropic/claude-sonnet-4-6", request_options: {timeout: 5})
+```
+
+On timeout, `Stagehand::Errors::APITimeoutError` is raised.
+
+Note that requests that time out are retried by default.
+
+## Advanced concepts
+
+### BaseModel
+
+All parameter and response objects inherit from `Stagehand::Internal::Type::BaseModel`, which provides several conveniences, including:
+
+1. All fields, including unknown ones, are accessible with `obj[:prop]` syntax, and can be destructured with `obj => {prop: prop}` or pattern-matching syntax.
+
+2. Structural equivalence for equality; if two API calls return the same values, comparing the responses with == will return true.
+
+3. Both instances and the classes themselves can be pretty-printed.
+
+4. Helpers such as `#to_h`, `#deep_to_h`, `#to_json`, and `#to_yaml`.
+
+### Making custom or undocumented requests
+
+#### Undocumented properties
+
+You can send undocumented parameters to any endpoint, and read undocumented response properties, like so:
+
+Note: the `extra_` parameters of the same name overrides the documented parameters.
+
+```ruby
+response =
+  stagehand.sessions.start(
+    model_name: "anthropic/claude-sonnet-4-6",
+    request_options: {
+      extra_query: {my_query_parameter: value},
+      extra_body: {my_body_parameter: value},
+      extra_headers: {"my-header": value}
+    }
+  )
+
+puts(response[:my_undocumented_property])
+```
+
+#### Undocumented request params
+
+If you want to explicitly send an extra param, you can do so with the `extra_query`, `extra_body`, and `extra_headers` under the `request_options:` parameter when making a request, as seen in the examples above.
+
+#### Undocumented endpoints
+
+To make requests to undocumented endpoints while retaining the benefit of auth, retries, and so on, you can make requests using `client.request`, like so:
+
+```ruby
+response = client.request(
+  method: :post,
+  path: '/undocumented/endpoint',
+  query: {"dog": "woof"},
+  headers: {"useful-header": "interesting-value"},
+  body: {"hello": "world"}
+)
+```
+
+### Concurrency & connection pooling
+
+The `Stagehand::Client` instances are threadsafe, but are only are fork-safe when there are no in-flight HTTP requests.
+
+Each instance of `Stagehand::Client` has its own HTTP connection pool with a default size of 99. As such, we recommend instantiating the client once per application in most settings.
+
+When all available connections from the pool are checked out, requests wait for a new connection to become available, with queue time counting towards the request timeout.
+
+Unless otherwise specified, other classes in the SDK do not have locks protecting their underlying data structure.
+
+## Sorbet
+
+This library provides comprehensive [RBI](https://sorbet.org/docs/rbi) definitions, and has no dependency on sorbet-runtime.
+
+You can provide typesafe request parameters like so:
+
+```ruby
+stagehand.sessions.act("00000000-your-session-id-000000000000", input: "click the first link on the page")
+```
+
+Or, equivalently:
+
+```ruby
+# Hashes work, but are not typesafe:
+stagehand.sessions.act("00000000-your-session-id-000000000000", input: "click the first link on the page")
+
+# You can also splat a full Params class:
+params = Stagehand::SessionActParams.new(input: "click the first link on the page")
+stagehand.sessions.act("00000000-your-session-id-000000000000", **params)
+```
+
+### Enums
+
+Since this library does not depend on `sorbet-runtime`, it cannot provide [`T::Enum`](https://sorbet.org/docs/tenum) instances. Instead, we provide "tagged symbols" instead, which is always a primitive at runtime:
+
+```ruby
+# :true
+puts(Stagehand::SessionActParams::XStreamResponse::TRUE)
+
+# Revealed type: `T.all(Stagehand::SessionActParams::XStreamResponse, Symbol)`
+T.reveal_type(Stagehand::SessionActParams::XStreamResponse::TRUE)
+```
+
+Enum parameters have a "relaxed" type, so you can either pass in enum constants or their literal value:
+
+```ruby
+# Using the enum constants preserves the tagged type information:
+stagehand.sessions.act(
+  x_stream_response: Stagehand::SessionActParams::XStreamResponse::TRUE,
+  # …
+)
+
+# Literal values are also permissible:
+stagehand.sessions.act(
+  x_stream_response: :true,
+  # …
+)
+```
+
+## Versioning
+
+This package follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions. As the library is in initial development and has a major version of `0`, APIs may change at any time.
+
+This package considers improvements to the (non-runtime) `*.rbi` and `*.rbs` type definitions to be non-breaking changes.
+
+## Requirements
+
+Ruby 3.2.0 or higher.
+
+## Contributing
+
+See [the contributing documentation](https://github.com/browserbase/stagehand-ruby/tree/main/CONTRIBUTING.md).

data/SECURITY.md

@@ -0,0 +1,23 @@
+# Security Policy
+
+## Reporting Security Issues
+
+This SDK is generated by [Stainless Software Inc](http://stainless.com). Stainless takes security seriously, and encourages you to report any security vulnerability promptly so that appropriate action can be taken.
+
+To report a security issue, please contact the Stainless team at security@stainless.com.
+
+## Responsible Disclosure
+
+We appreciate the efforts of security researchers and individuals who help us maintain the security of
+SDKs we generate. If you believe you have found a security vulnerability, please adhere to responsible
+disclosure practices by allowing us a reasonable amount of time to investigate and address the issue
+before making any information public.
+
+## Reporting Non-SDK Related Security Issues
+
+If you encounter security issues that are not directly related to SDKs but pertain to the services
+or products provided by Stagehand, please follow the respective company's security reporting guidelines.
+
+---
+
+Thank you for helping us keep the SDKs and systems they interact with secure.