Fix local cache handling and examples

Author: pirate

README.md

@@ -395,25 +395,25 @@ stagehand.sessions.act("00000000-your-session-id-000000000000", **params)
 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
-# :typescript
-puts(Stagehand::SessionActParams::XLanguage::TYPESCRIPT)
+# :true
+puts(Stagehand::SessionActParams::XStreamResponse::TRUE)
 
-# Revealed type: `T.all(Stagehand::SessionActParams::XLanguage, Symbol)`
-T.reveal_type(Stagehand::SessionActParams::XLanguage::TYPESCRIPT)
+# 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_language: Stagehand::SessionActParams::XLanguage::TYPESCRIPT,
+  x_stream_response: Stagehand::SessionActParams::XStreamResponse::TRUE,
   # …
 )
 
 # Literal values are also permissible:
 stagehand.sessions.act(
-  x_language: :typescript,
+  x_stream_response: :true,
   # …
 )
 ```

examples/local.rb

@@ -22,40 +22,40 @@
 begin
   start_response = client.sessions.start(
     model_name: "openai/gpt-5-nano",
-    browser: { type: :local }
+    browser: {type: :local}
   )
   session_id = start_response.data.session_id
-  puts "Session started: #{session_id}"
+  puts("Session started: #{session_id}")
 
   client.sessions.navigate(session_id, url: "https://example.com")
-  puts "Navigated to example.com"
+  puts("Navigated to example.com")
 
   observe_response = client.sessions.observe(
     session_id,
     instruction: "Find all clickable links on this page"
   )
-  puts "Found #{observe_response.data.result.length} possible actions"
+  puts("Found #{observe_response.data.result.length} possible actions")
 
   action = observe_response.data.result.first
   act_input = action ? action.to_h.merge(method: "click") : "Click the 'Learn more' link"
   act_response = client.sessions.act(
     session_id,
     input: act_input
   )
-  puts "Act completed: #{act_response.data.result[:message]}"
+  puts("Act completed: #{act_response.data.result[:message]}")
 
   extract_response = client.sessions.extract(
     session_id,
     instruction: "extract the main heading and any links on this page",
     schema: {
       type: "object",
       properties: {
-        heading: { type: "string" },
-        links: { type: "array", items: { type: "string" } }
+        heading: {type: "string"},
+        links: {type: "array", items: {type: "string"}}
       }
     }
   )
-  puts "Extracted: #{extract_response.data.result}"
+  puts("Extracted: #{extract_response.data.result}")
 
   execute_response = client.sessions.execute(
     session_id,
@@ -64,15 +64,15 @@
       max_steps: 3
     },
     agent_config: {
-      model: Stagehand::ModelConfig::ModelConfigObject.new(
+      model: Stagehand::ModelConfig.new(
         model_name: "openai/gpt-5-nano",
         api_key: model_key
       ),
       cua: false
     }
   )
-  puts "Agent completed: #{execute_response.data.result[:message]}"
-  puts "Agent success: #{execute_response.data.result[:success]}"
+  puts("Agent completed: #{execute_response.data.result[:message]}")
+  puts("Agent success: #{execute_response.data.result[:success]}")
 ensure
   client.sessions.end_(session_id) if session_id
   client.close

examples/playwright_local_example.rb

@@ -1,4 +1,5 @@
 #!/usr/bin/env ruby
+# typed: ignore
 # frozen_string_literal: true
 
 require "bundler/setup"
@@ -23,10 +24,10 @@
 #   bundle exec ruby examples/playwright_local_example.rb
 
 begin
-  require "playwright"
+  require("playwright")
 rescue LoadError
-  warn "Playwright is not installed. Run: gem install playwright-ruby-client"
-  exit 1
+  warn("Playwright is not installed. Run: gem install playwright-ruby-client")
+  exit(1)
 end
 
 DEBUG_PORT = 9222
@@ -74,6 +75,7 @@ def fetch_page_target_id(port, page_url)
   exit 1
 end
 
+# rubocop:disable Metrics/BlockLength
 Playwright.create(playwright_cli_executable_path: "./node_modules/.bin/playwright") do |playwright|
   browser = playwright.chromium.launch(
     headless: false,
@@ -106,14 +108,14 @@ def fetch_page_target_id(port, page_url)
       }
     )
     session_id = start_response.data.session_id
-    puts "Session started: #{session_id}"
+    puts("Session started: #{session_id}")
 
     observe_response = client.sessions.observe(
       session_id,
       frame_id: page_target_id,
       instruction: "Find all clickable links on this page"
     )
-    puts "Found #{observe_response.data.result.length} possible actions"
+    puts("Found #{observe_response.data.result.length} possible actions")
 
     action = observe_response.data.result.first
     act_input = action ? action.to_h.merge(method: "click") : "Click the 'Learn more' link"
@@ -122,7 +124,7 @@ def fetch_page_target_id(port, page_url)
       frame_id: page_target_id,
       input: act_input
     )
-    puts "Act completed: #{act_response.data.result[:message]}"
+    puts("Act completed: #{act_response.data.result[:message]}")
 
     extract_response = client.sessions.extract(
       session_id,
@@ -131,12 +133,12 @@ def fetch_page_target_id(port, page_url)
       schema: {
         type: "object",
         properties: {
-          heading: { type: "string" },
-          links: { type: "array", items: { type: "string" } }
+          heading: {type: "string"},
+          links: {type: "array", items: {type: "string"}}
         }
       }
     )
-    puts "Extracted: #{extract_response.data.result}"
+    puts("Extracted: #{extract_response.data.result}")
 
     execute_response = client.sessions.execute(
       session_id,
@@ -146,22 +148,23 @@ def fetch_page_target_id(port, page_url)
         max_steps: 3
       },
       agent_config: {
-        model: Stagehand::ModelConfig::ModelConfigObject.new(
+        model: Stagehand::ModelConfig.new(
           model_name: "openai/gpt-5-nano",
           api_key: model_key
         ),
         cua: false
       }
     )
-    puts "Agent completed: #{execute_response.data.result[:message]}"
-    puts "Agent success: #{execute_response.data.result[:success]}"
+    puts("Agent completed: #{execute_response.data.result[:message]}")
+    puts("Agent success: #{execute_response.data.result[:success]}")
 
     page.wait_for_load_state(state: "domcontentloaded")
     page.screenshot(path: "screenshot_local_playwright.png", fullPage: true)
-    puts "Screenshot saved to: screenshot_local_playwright.png"
+    puts("Screenshot saved to: screenshot_local_playwright.png")
   ensure
     client.sessions.end_(session_id) if session_id
     client.close
     browser.close
   end
 end
+# rubocop:enable Metrics/BlockLength

examples/watir_local_example.rb

@@ -1,4 +1,5 @@
 #!/usr/bin/env ruby
+# typed: ignore
 # frozen_string_literal: true
 
 require "bundler/setup"
@@ -21,10 +22,10 @@
 #   bundle exec ruby examples/watir_local_example.rb
 
 begin
-  require "watir"
+  require("watir")
 rescue LoadError
-  warn "Watir is not installed. Run: gem install watir"
-  exit 1
+  warn("Watir is not installed. Run: gem install watir")
+  exit(1)
 end
 
 DEBUG_PORT = 9222
@@ -65,7 +66,7 @@ def fetch_cdp_websocket_url(port)
   browser.goto("https://example.com")
 
   ws_url = fetch_cdp_websocket_url(DEBUG_PORT)
-  puts "Browser WebSocket URL: #{ws_url}"
+  puts("Browser WebSocket URL: #{ws_url}")
 
   start_response = client.sessions.start(
     model_name: "openai/gpt-5-nano",
@@ -77,36 +78,36 @@ def fetch_cdp_websocket_url(port)
     }
   )
   session_id = start_response.data.session_id
-  puts "Session started: #{session_id}"
+  puts("Session started: #{session_id}")
 
   client.sessions.navigate(session_id, url: "https://example.com")
 
   observe_response = client.sessions.observe(
     session_id,
     instruction: "Find all clickable links on this page"
   )
-  puts "Found #{observe_response.data.result.length} possible actions"
+  puts("Found #{observe_response.data.result.length} possible actions")
 
   action = observe_response.data.result.first
   act_input = action ? action.to_h.merge(method: "click") : "Click the 'Learn more' link"
   act_response = client.sessions.act(
     session_id,
     input: act_input
   )
-  puts "Act completed: #{act_response.data.result[:message]}"
+  puts("Act completed: #{act_response.data.result[:message]}")
 
   extract_response = client.sessions.extract(
     session_id,
     instruction: "Extract the main heading and any links on this page",
     schema: {
       type: "object",
       properties: {
-        heading: { type: "string" },
-        links: { type: "array", items: { type: "string" } }
+        heading: {type: "string"},
+        links: {type: "array", items: {type: "string"}}
       }
     }
   )
-  puts "Extracted: #{extract_response.data.result}"
+  puts("Extracted: #{extract_response.data.result}")
 
   execute_response = client.sessions.execute(
     session_id,
@@ -115,18 +116,18 @@ def fetch_cdp_websocket_url(port)
       max_steps: 3
     },
     agent_config: {
-      model: Stagehand::ModelConfig::ModelConfigObject.new(
+      model: Stagehand::ModelConfig.new(
         model_name: "openai/gpt-5-nano",
         api_key: model_key
       ),
       cua: false
     }
   )
-  puts "Agent completed: #{execute_response.data.result[:message]}"
-  puts "Agent success: #{execute_response.data.result[:success]}"
+  puts("Agent completed: #{execute_response.data.result[:message]}")
+  puts("Agent success: #{execute_response.data.result[:success]}")
 
   browser.screenshot.save("screenshot_local_watir.png")
-  puts "Screenshot saved to: screenshot_local_watir.png"
+  puts("Screenshot saved to: screenshot_local_watir.png")
 ensure
   client.sessions.end_(session_id) if session_id
   client.close

lib/stagehand/client.rb

@@ -92,16 +92,20 @@ def initialize(
       initial_retry_delay: self.class::DEFAULT_INITIAL_RETRY_DELAY,
       max_retry_delay: self.class::DEFAULT_MAX_RETRY_DELAY
     )
+      @server = server
       base_url ||= "https://api.stagehand.browserbase.com"
 
       if browserbase_api_key.nil?
-        raise ArgumentError.new("browserbase_api_key is required, and can be set via environ: \"BROWSERBASE_API_KEY\"")
+        raise ArgumentError,
+              "browserbase_api_key is required, and can be set via environ: \"BROWSERBASE_API_KEY\""
       end
       if browserbase_project_id.nil?
-        raise ArgumentError.new("browserbase_project_id is required, and can be set via environ: \"BROWSERBASE_PROJECT_ID\"")
+        raise ArgumentError,
+              "browserbase_project_id is required, and can be set via environ: \"BROWSERBASE_PROJECT_ID\""
       end
       if model_api_key.nil?
-        raise ArgumentError.new("model_api_key is required, and can be set via environ: \"MODEL_API_KEY\"")
+        raise ArgumentError,
+              "model_api_key is required, and can be set via environ: \"MODEL_API_KEY\""
       end
 
       @browserbase_api_key = browserbase_api_key.to_s