ruby_llm-browser 0.1.0

data/lib/ruby_llm/browser/redactor.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+require "uri"
+
+module RubyLLM
+  module Browser
+    # Sanitization and bounding helpers for anything that could reach a model message,
+    # tool result, log line or error.
+    #
+    # Page text, model output and provider metadata are untrusted. They are redacted by
+    # key name, scrubbed of known secrets, stripped of DevTools URLs, and bounded by
+    # size and depth before they leave a backend.
+    module Redactor
+      # The replacement for redacted values.
+      REDACTED = "[REDACTED]"
+
+      # JSON preview marker when a value is too large to return whole.
+      TRUNCATED = "[TRUNCATED]"
+
+      # Maximum nesting depth kept while redacting.
+      MAX_DEPTH = 12
+
+      # Keys whose values are always treated as secrets. Matching is case-insensitive
+      # and applies to `snake_case`, `kebab-case` and `camelCase` spellings.
+      SECRET_KEY = /
+        api[-_]?key | apikey |
+        access[-_]?token | refresh[-_]?token | id[-_]?token |
+        client[-_]?secret | private[-_]?key |
+        authorization | bearer |
+        password | passwd | credential |
+        cookie | set[-_]?cookie |
+        secret | token |
+        cdp[-_]?url | devtools |
+        x[-_]bb[-_]api[-_]key | x[-_]model[-_]api[-_]key
+      /xi
+
+      # A DevTools WebSocket URL anywhere in a string. Full browser control, so it is
+      # always removed.
+      DEVTOOLS_URL = %r{ws{1,2}://[^\s"']*}i
+
+      # Secrets shorter than this are not treated as replaceable literals; replacing
+      # very short strings would corrupt ordinary text.
+      MIN_LITERAL_SECRET = 8
+
+      module_function
+
+      # Returns a redacted, depth-bounded copy of +value+.
+      #
+      # @param value [Object]
+      # @param secrets [Array<String>] exact secret values to remove from strings
+      # @param max_depth [Integer] nesting depth at which content is replaced entirely
+      def redact(value, secrets: [], depth: 0, max_depth: MAX_DEPTH)
+        return REDACTED if depth > max_depth
+
+        case value
+        when Hash
+          value.each_with_object({}) do |(key, nested), result|
+            safe_key = scrub_string(key.to_s, secrets: secrets)
+            result[safe_key] = secret_key?(key) ? REDACTED : redact(nested, secrets: secrets, depth: depth + 1, max_depth: max_depth)
+          end
+        when Array
+          value.map { |item| redact(item, secrets: secrets, depth: depth + 1, max_depth: max_depth) }
+        when String
+          scrub_string(value, secrets: secrets)
+        when Symbol
+          scrub_string(value.to_s, secrets: secrets)
+        else
+          value
+        end
+      end
+
+      # Redacts and then bounds +value+ to +max_bytes+ of JSON.
+      #
+      # @return [Array(Object, Boolean)] the bounded value and whether it was truncated
+      def bound(value, max_bytes:, secrets: [])
+        unless max_bytes.is_a?(Integer) && max_bytes.positive?
+          raise InvalidInput, "max_bytes must be a positive integer"
+        end
+        redacted = redact(value, secrets: secrets)
+        json = canonical_json(redacted)
+        return [ redacted, false ] if json.bytesize <= max_bytes
+
+        # Count encoded bytes, not characters: JSON escaping can expand a preview.
+        envelope = { "truncated" => true, "preview" => "", "note" => TRUNCATED }
+        return [ "", true ] if max_bytes < canonical_json(envelope).bytesize && max_bytes >= 2
+        return [ 0, true ] if max_bytes == 1
+
+        low = 0
+        high = [ json.length, max_bytes ].min
+        while low < high
+          midpoint = (low + high + 1) / 2
+          envelope["preview"] = json[0, midpoint]
+          if canonical_json(envelope).bytesize <= max_bytes
+            low = midpoint
+          else
+            high = midpoint - 1
+          end
+        end
+        envelope["preview"] = json[0, low]
+        [ envelope, true ]
+      end
+
+      # Stable JSON for digests: object keys sorted, no insignificant whitespace.
+      def canonical_json(value)
+        JSON.generate(sort_keys(value))
+      end
+
+      # SHA-256 hex digest of the canonical JSON of +value+.
+      def digest(value)
+        Digest::SHA256.hexdigest(canonical_json(value))
+      end
+
+      # True when a key name denotes a secret value.
+      def secret_key?(key)
+        SECRET_KEY.match?(key.to_s)
+      end
+
+      # Removes userinfo, fragments and credential-like query values from provenance.
+      def url(value, secrets: [])
+        uri = URI.parse(value.to_s)
+        uri.userinfo = nil if uri.respond_to?(:userinfo=)
+        uri.fragment = nil
+        if uri.query
+          uri.query = URI.encode_www_form(URI.decode_www_form(uri.query).map do |key, nested|
+            [ key, secret_key?(key) ? REDACTED : nested ]
+          end)
+        end
+        scrub_string(uri.to_s, secrets: secrets)
+      rescue URI::Error, ArgumentError
+        "[REDACTED URL]"
+      end
+
+      def sort_keys(value)
+        case value
+        when Hash
+          value.keys.map(&:to_s).sort.to_h do |key|
+            [ key, sort_keys(value.key?(key) ? value[key] : value[key.to_sym]) ]
+          end
+        when Array
+          value.map { |item| sort_keys(item) }
+        else
+          value
+        end
+      end
+
+      def scrub_string(string, secrets:)
+        scrubbed = string.dup.force_encoding(Encoding::UTF_8).scrub
+        (secrets || []).each do |secret|
+          next if secret.to_s.length < MIN_LITERAL_SECRET
+
+          scrubbed = scrubbed.gsub(secret.to_s, REDACTED)
+        end
+        scrubbed.gsub(DEVTOOLS_URL, REDACTED)
+      end
+    end
+  end
+end

data/lib/ruby_llm/browser/result.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+
+module RubyLLM
+  module Browser
+    # Bounded, sanitized output of a browser operation, with provenance.
+    #
+    # A Result is untrusted evidence with provenance: it records where content came from
+    # and when, but an `ok` status never verifies that an extracted claim is true. It
+    # never carries API keys, cookies, provider session IDs, `cdp_url` values, raw page
+    # dumps or screenshots.
+    class Result
+      # Machine-readable outcome.
+      #
+      # - `:ok`              completed with confirmed session closure
+      # - `:truncated`       completed but content hit a byte/step limit
+      # - `:error`           a typed, safe error stopped the operation
+      # - `:unknown`         a remote outcome could not be confirmed
+      # - `:cleanup_pending` cleanup was attempted but not confirmed
+      STATUSES = %i[ok truncated error unknown cleanup_pending].freeze
+
+      attr_reader :status, :operation_id, :final_url, :captured_at, :locator, :digest,
+                  :data, :error_code, :error_message
+
+      def initialize(status:, operation_id: nil, final_url: nil, captured_at: nil, locator: nil,
+                     digest: nil, data: nil, truncated: false, error_code: nil, error_message: nil)
+        @status = normalize_status(status)
+        @operation_id = operation_id
+        @final_url = Immutable.copy(final_url)
+        @captured_at = Immutable.copy(captured_at)
+        @locator = Immutable.copy(locator)
+        @digest = Immutable.copy(digest)
+        @data = Immutable.copy(data)
+        @truncated = truncated ? true : false
+        @error_code = error_code
+        @error_message = error_message
+        freeze
+      end
+
+      # A successful result. `truncated:` marks a bounded-but-complete outcome.
+      def self.ok(data: nil, operation_id: nil, final_url: nil, captured_at: nil, locator: nil,
+                  digest: nil, truncated: false)
+        new(status: truncated ? :truncated : :ok, data: data, operation_id: operation_id,
+            final_url: final_url, captured_at: captured_at, locator: locator, digest: digest,
+            truncated: truncated)
+      end
+
+      # A typed failure. Used for `error`, `unknown` and `cleanup_pending` outcomes.
+      def self.failure(status, error_code:, message:, operation_id: nil, final_url: nil,
+                       captured_at: nil, data: nil)
+        new(status: status, error_code: error_code, error_message: message,
+            operation_id: operation_id, final_url: final_url, captured_at: captured_at, data: data)
+      end
+
+      def truncated? = @truncated
+      def ok? = status == :ok || status == :truncated
+
+      # A model-safe Hash. Times are ISO 8601 UTC strings.
+      def to_h
+        {
+          status: status.to_s,
+          operation_id: operation_id,
+          final_url: final_url,
+          captured_at: captured_at&.getutc&.iso8601,
+          locator: locator,
+          digest: digest,
+          truncated: @truncated,
+          data: data,
+          error: error_code ? { code: error_code.to_s, message: error_message } : nil
+        }.compact
+      end
+
+      def to_json(*args)
+        JSON.generate(to_h, *args)
+      end
+
+      def deconstruct_keys(_keys)
+        to_h
+      end
+
+      def ==(other)
+        other.is_a?(Result) && to_h == other.to_h
+      end
+      alias eql? ==
+
+      def inspect
+        "#<#{self.class} status=#{status} operation_id=#{operation_id.inspect} url=#{final_url.inspect}>"
+      end
+
+      private
+
+      def normalize_status(status)
+        status = status.to_sym
+        return status if STATUSES.include?(status)
+
+        raise InvalidInput, "unknown result status: #{status.inspect}"
+      end
+    end
+  end
+end

data/lib/ruby_llm/browser/stagehand_backend.rb

@@ -0,0 +1,332 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Browser
+    # An experimental {Backend} adapter for the official `stagehand` Ruby SDK.
+    #
+    # It is a thin, fail-closed translation layer, not a browser engine. It:
+    #
+    # - constructs `Stagehand::Client` with **every** argument explicit, so the SDK's
+    #   environment defaults (`STAGEHAND_API_URL`/`STAGEHAND_BASE_URL`,
+    #   `BROWSERBASE_API_KEY`, `MODEL_API_KEY`) can never redirect or authenticate a call
+    # - requires `max_retries: 0`, both at the client and per effectful request, because
+    #   the SDK otherwise retries errors and timeouts
+    # - never returns `cdp_url`, cookies or credentials, and reports the pinned API keys
+    #   as secret literals so they are scrubbed from page text and results
+    # - refuses to construct a live client in local mode unless a host-pinned server
+    #   binary or version is present, so it never triggers the SDK's runtime download
+    #
+    # The SDK is required lazily, inside {#client}, so requiring this Gem never reads
+    # Stagehand environment variables and never starts or downloads a server.
+    #
+    # This adapter is unsupported for live operations in the first release. Its
+    # capabilities always report unverified egress, so callers cannot enable it by
+    # passing a host assertion. Provider egress and cleanup need qualification first.
+    class StagehandBackend < Backend
+      DEFAULT_BASE_URL = "https://api.stagehand.browserbase.com"
+      CUSTOM_HEADERS_ENV = "STAGEHAND_CUSTOM_HEADERS"
+      PINNED_BINARY_ENV = "STAGEHAND_SEA_BINARY"
+      PINNED_VERSION_ENV = "STAGEHAND_SERVER_VERSION"
+      ENV_OVERRIDE_KEYS = %w[STAGEHAND_API_URL STAGEHAND_BASE_URL].freeze
+
+      attr_reader :model_name, :server, :base_url
+
+      # @param browserbase_api_key [String] the Browserbase key
+      # @param model_api_key [String] the model provider key
+      # @param model_name [String] the model the provider uses for AI browser steps
+      # @param server [Symbol, String] `:remote` or `:local`
+      # @param base_url [String, nil] explicit endpoint; defaults to the official remote
+      #   endpoint. Never read from the environment.
+      # @param timeout [Numeric] per-request timeout in seconds
+      # @param custom_headers_approved [Boolean] whether the host approved the SDK's
+      #   always-merged `STAGEHAND_CUSTOM_HEADERS`
+      # @param env [Hash] environment to inspect; injectable for tests
+      # @param client [Object, nil] an already-built client (tests/advanced hosts)
+      def initialize(browserbase_api_key:, model_api_key:, model_name:,
+                     server: :remote, base_url: nil, timeout: 60.0,
+                     custom_headers_approved: false, env: ENV, client: nil)
+        super()
+        @browserbase_api_key = presence!(browserbase_api_key, :browserbase_api_key)
+        @model_api_key = presence!(model_api_key, :model_api_key)
+        @model_name = presence!(model_name, :model_name)
+        @server = server_mode!(server)
+        @base_url = base_url.nil? ? default_base_url : presence!(base_url, :base_url)
+        @timeout = positive_number!(timeout, :timeout)
+        @env = env
+        @environment_snapshot = relevant_environment(env)
+        @process_environment_snapshot = relevant_environment(ENV)
+        @custom_headers_present = !env[CUSTOM_HEADERS_ENV].to_s.empty? || !ENV[CUSTOM_HEADERS_ENV].to_s.empty?
+        @custom_headers_approved = !!custom_headers_approved
+        @local_binary_pinned = local? && pinned_binary?
+        @client_mutex = Mutex.new
+        @client = client
+        @capabilities = Capabilities.new(
+          server_mode: local? ? :local : :remote,
+          egress_isolation: :unverified,
+          local_binary_pinned: @local_binary_pinned,
+          custom_headers_present: @custom_headers_present,
+          custom_headers_approved: @custom_headers_approved,
+          act_supported: false
+        )
+      end
+
+      # The pinned credential literals, so the redactor scrubs them from any page text
+      # or provider payload that reaches a result.
+      def secrets = [ @browserbase_api_key, @model_api_key ]
+
+      def capabilities
+        return @capabilities if environment_unchanged?
+
+        Capabilities.new(server_mode: local? ? :local : :remote, egress_isolation: :unverified,
+                         custom_headers_present: true, custom_headers_approved: false,
+                         act_supported: false)
+      end
+
+      def local? = server == "local"
+
+      def start(context:, operation:, now:)
+        ensure_qualified!
+        response = effectful do
+          client.sessions.start(model_name: model_name, self_heal: false, verbose: 0,
+                                wait_for_captcha_solves: false,
+                                browserbase_session_create_params: {
+                                  keep_alive: false, timeout: operation.budget.max_seconds.ceil,
+                                  browser_settings: { solve_captchas: false, record_session: false, log_session: false }
+                                },
+                                request_options: effectful_options(operation, now: now))
+        end
+        session_id = response.data&.session_id.to_s
+        unless response.success == true && !session_id.empty?
+          partial = Session.new(id: session_id, started_at: now) unless session_id.empty?
+          raise SessionUnknown.new("browser provider did not confirm a session identity", session: partial)
+        end
+
+        Session.new(id: session_id, url: nil, started_at: now)
+      end
+
+      def navigate(session, url:, operation:, now:)
+        ensure_qualified!
+        response = effectful do
+          client.sessions.navigate(session.id, url: url, request_options: effectful_options(operation, now: now))
+        end
+        raise SessionUnknown, "browser navigation outcome is unconfirmed" unless response.success == true
+
+        destination = final_url(response)
+        unless destination.is_a?(String) && !destination.empty?
+          raise SessionUnknown, "browser provider did not verify the final destination URL"
+        end
+        Session.new(id: session.id, url: destination, started_at: session.started_at)
+      end
+
+      def observe(session, instruction:, operation:, now:)
+        ensure_qualified!
+        response = read do
+          client.sessions.observe(session.id, instruction: instruction,
+                                             request_options: read_options(operation, now: now))
+        end
+        raise ProviderError, "browser observation was unsuccessful" unless response.success == true
+        Array(response.data&.result).map { |action| observed_action(action) }
+      end
+
+      def extract(session, schema:, instruction:, operation:, now:)
+        ensure_qualified!
+        response = read do
+          client.sessions.extract(session.id, schema: schema, instruction: instruction,
+                                             request_options: read_options(operation, now: now))
+        end
+        raise ProviderError, "browser extraction was unsuccessful" unless response.success == true
+        dump(response.data&.result)
+      end
+
+      def act(session, action:, operation:, now:)
+        ensure_qualified!
+        raise UnsupportedSecurityCapability, "backend Act is disabled" unless capabilities.act_supported?
+        response = effectful do
+          client.sessions.act(session.id, input: action_input(action),
+                                         request_options: effectful_options(operation, now: now))
+        end
+        raise SessionUnknown, "browser action outcome is unconfirmed" unless response.success == true
+        dump(response.data&.result)
+      end
+
+      # Stagehand is unsupported for this release. Do not send even a best-effort
+      # cleanup request: the response cannot prove terminal closure, and the owner
+      # declined all live provider calls. Keep the operation `cleanup_pending`.
+      def end_session(_session, operation:, now:)
+        false
+      end
+
+      # No provider correlation endpoint is exposed by the SDK, so an unresolved
+      # operation cannot be proven closed or active here.
+      def reconcile(_operation, now:)
+        :unknown
+      end
+
+      def inspect
+        "#<#{self.class} server=#{server}>"
+      end
+
+      private
+
+      def client
+        return @client if @client
+
+        @client_mutex.synchronize do
+          @client ||= build_client
+        end
+      end
+
+      def build_client
+        raise UnsupportedSecurityCapability, "Stagehand environment changed; rebuild the backend" unless environment_unchanged?
+        if local? && ENV[PINNED_BINARY_ENV].to_s.empty? && ENV[PINNED_VERSION_ENV].to_s.empty?
+          raise UnsupportedSecurityCapability, "local mode requires a process-level server pin"
+        end
+        require "stagehand"
+        Stagehand::Client.new(
+          browserbase_api_key: @browserbase_api_key,
+          model_api_key: @model_api_key,
+          server: @server,
+          base_url: @base_url,
+          max_retries: 0,
+          timeout: @timeout
+        )
+      end
+
+      # Effectful calls never retry and, when the outcome is ambiguous, never claim
+      # success: a connection error or a 5xx becomes {SessionUnknown}.
+      def effectful
+        yield
+      rescue Stagehand::Errors::APIConnectionError
+        raise SessionUnknown, "browser provider connection outcome is unconfirmed", cause: nil
+      rescue Stagehand::Errors::APIStatusError => e
+        raise translate_status(e), cause: nil
+      rescue Stagehand::Errors::Error => e
+        raise SessionUnknown, "browser provider outcome is unconfirmed: #{e.class.name.split("::").last}", cause: nil
+      end
+
+      # Read-only calls never retry; an ambiguous failure is a plain provider error.
+      def read
+        yield
+      rescue Stagehand::Errors::Error => e
+        raise ProviderError, "browser provider error: #{e.class.name.split("::").last}", cause: nil
+      end
+
+      def translate_status(error)
+        status = error.status.to_i
+        if status >= 500 || status == 408
+          return SessionUnknown.new("browser provider returned #{status}; outcome unconfirmed")
+        end
+
+        ProviderError.new("browser provider rejected the request (status #{status})")
+      end
+
+      def effectful_options(operation, now:)
+        # The SDK has no configured idempotency header. The durable store, not an
+        # ignored request option, prevents duplicate starts and actions.
+        read_options(operation, now: now)
+      end
+
+      def read_options(operation, now:)
+        remaining = operation.budget.max_seconds - operation.elapsed_seconds(now)
+        raise BudgetExhausted, "operation wall-clock budget exhausted" unless remaining.positive?
+
+        { max_retries: 0, timeout: [ @timeout, remaining ].min }
+      end
+
+      def action_input(action)
+        {
+          "description" => action["description"],
+          "selector" => action["selector"],
+          "method" => action["method"],
+          "arguments" => Array(action["arguments"])
+        }
+      end
+
+      def observed_action(action)
+        {
+          "description" => attribute(action, :description),
+          "method" => attribute(action, :method_) || attribute(action, :method),
+          "selector" => attribute(action, :selector),
+          "arguments" => Array(attribute(action, :arguments))
+        }
+      end
+
+      def attribute(action, name)
+        if action.respond_to?(name)
+          action.public_send(name)
+        elsif action.is_a?(Hash)
+          action[name.to_s] || action[name]
+        end
+      end
+
+      # Converts SDK model objects into plain, string-keyed JSON-safe data.
+      def dump(value)
+        case value
+        when Hash
+          value.to_h { |key, nested| [ key.to_s, dump(nested) ] }
+        when Array
+          value.map { |item| dump(item) }
+        else
+          value.respond_to?(:to_h) && !value.is_a?(String) ? dump(value.to_h) : value
+        end
+      end
+
+      def final_url(response)
+        result = response.data&.result
+        return nil unless result.is_a?(Hash)
+
+        result["url"] || result[:url]
+      end
+
+      def pinned_binary?
+        !@env[PINNED_BINARY_ENV].to_s.empty? || !@env[PINNED_VERSION_ENV].to_s.empty?
+      end
+
+      def default_base_url
+        local? ? "http://127.0.0.1" : DEFAULT_BASE_URL
+      end
+
+      def presence!(value, name)
+        raise InvalidInput, "#{name} must be a non-empty String" unless value.is_a?(String) && !value.empty?
+
+        value.dup.freeze
+      end
+
+      def positive_number!(value, name)
+        unless value.is_a?(Numeric) && value.finite? && value.positive?
+          raise InvalidInput, "#{name} must be a positive finite number"
+        end
+
+        value
+      end
+
+      def server_mode!(value)
+        mode = value.to_s
+        return mode if %w[remote local].include?(mode)
+
+        raise InvalidInput, "server must be :remote or :local"
+      end
+
+      def relevant_environment(env)
+        Immutable.copy([ CUSTOM_HEADERS_ENV, PINNED_BINARY_ENV, PINNED_VERSION_ENV ].to_h { |key| [ key, env[key] ] })
+      end
+
+      def environment_unchanged?
+        relevant_environment(@env) == @environment_snapshot &&
+          relevant_environment(ENV) == @process_environment_snapshot
+      end
+
+      def ensure_qualified!
+        current = capabilities
+        unless current.enforced_egress? && (!current.local_mode? || current.local_binary_pinned?) &&
+            (!current.custom_headers_present? || current.custom_headers_approved?)
+          raise UnsupportedSecurityCapability,
+                "Stagehand backend is unsupported until provider egress and cleanup are qualified"
+        end
+        if !ENV[CUSTOM_HEADERS_ENV].to_s.empty? && !@custom_headers_approved
+          raise UnsupportedSecurityCapability, "Stagehand process custom headers are not approved"
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/browser/tool.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Browser
+    # Base class for the Gem's RubyLLM tools.
+    #
+    # A tool is a thin, policy-free adapter. The host injects exactly one trusted
+    # {Context}; the tool forwards model-supplied arguments to an {Engine}, and the
+    # engine enforces egress qualification, destination/schema/action policy, budgets,
+    # operation lifecycle and result redaction. A tool never invents an actor, a
+    # backend, a schema or an approval, and it never turns a typed failure into an
+    # untyped exception that would abort the chat.
+    #
+    # Model-facing names are declared explicitly so they stay stable across releases.
+    class Tool < RubyLLM::Tool
+      class << self
+        # Declares or returns the stable, model-facing tool name.
+        #
+        #   tool_name "browser_inspect"
+        def tool_name(value = nil)
+          return @tool_name if value.nil?
+
+          @tool_name = value
+        end
+      end
+
+      attr_reader :context
+
+      # @param context [Context] the host-supplied, trusted execution context
+      def initialize(context:)
+        super()
+        @context = context!(context)
+        @engine = Engine.new(context: @context)
+      end
+
+      private
+
+      # Reports coarse progress when the host's RubyLLM exposes the 2.1+ API.
+      #
+      # The Gem's floor stays at RubyLLM 2.0, where {RubyLLM::Tool#progress} does not
+      # exist, so the call is feature-detected rather than assumed.
+      def report(message = nil, value: nil, total: nil)
+        return unless respond_to?(:progress)
+
+        progress(message, value: value, total: total)
+      end
+
+      # Converts a typed engine error into a model-safe tool result. The stable error
+      # code is preserved; the message is Gem-authored and never contains secrets.
+      def failure(error)
+        message = Redactor.scrub_string(error.message, secrets: context.secrets)
+        Result.failure(:error, error_code: error.code, message: message).to_h
+      end
+
+      def unexpected_failure
+        failure(ProviderError.new("browser operation could not be completed"))
+      end
+
+      def engine = @engine
+
+      def context!(value)
+        unless value.is_a?(Context)
+          raise InvalidInput, "context must be a RubyLLM::Browser::Context"
+        end
+
+        value
+      end
+    end
+  end
+end