ruby_llm-browser 0.1.0

data/lib/ruby_llm/browser/configuration.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module RubyLLM
+  module Browser
+    # Process-wide defaults. Per-call behaviour belongs on {Context}, {Policy} and the
+    # backend; this object only holds values that are safe to share.
+    #
+    # Requiring the Gem never reads credentials or environment variables; configuration
+    # is explicit.
+    class Configuration
+      DEFAULT_MAX_RESULT_BYTES = 65_536 # 64 KiB of sanitized result data
+
+      # Reserved host configuration slot. Context still requires an explicit backend;
+      # setting this never enables a fallback or changes an existing tool's backend.
+      attr_accessor :backend
+
+      attr_reader :clock, :default_budget, :max_result_bytes
+
+      def initialize
+        @backend = nil
+        @logger = nil
+        @clock = -> { Time.now.utc }
+        @default_budget = Budget.new
+        @max_result_bytes = DEFAULT_MAX_RESULT_BYTES
+      end
+
+      # The logger used for audit lines. Falls back to RubyLLM's logger when present.
+      def logger
+        @logger || default_logger
+      end
+
+      attr_writer :logger
+
+      def clock=(callable)
+        unless callable.respond_to?(:call)
+          raise InvalidInput, "clock must respond to #call and return a Time"
+        end
+
+        @clock = callable
+      end
+
+      def default_budget=(budget)
+        raise InvalidInput, "default_budget must be a RubyLLM::Browser::Budget" unless budget.is_a?(Budget)
+
+        @default_budget = budget
+      end
+
+      def max_result_bytes=(value)
+        unless value.is_a?(Integer) && value.positive?
+          raise InvalidInput, "max_result_bytes must be a positive integer"
+        end
+
+        @max_result_bytes = value
+      end
+
+      # Current UTC time from the configured clock.
+      def now
+        clock.call
+      end
+
+      private
+
+      def default_logger
+        if defined?(RubyLLM) && RubyLLM.respond_to?(:logger) && RubyLLM.logger
+          RubyLLM.logger
+        else
+          Logger.new($stderr, level: Logger::WARN)
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/browser/context.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Browser
+    # Trusted, host-supplied execution context.
+    #
+    # Context is created by the host application — not the model and not page text — and
+    # carries identity, the source policy, the backend, stores, budgets and the data-
+    # sharing consent decision. Tools never invent any of it.
+    class Context
+      attr_reader :actor_id, :run_id, :backend, :source_policy, :operation_store,
+                  :approval_store, :budget, :consent, :metadata, :logger
+
+      # @param source_policy [Policy] the host's URL/schema/action/egress policy
+      # @param backend [Backend] an egress-qualified backend
+      # @param operation_store [OperationStore] durable operation bookkeeping
+      # @param approval_store [ApprovalStore, nil] required only for Act
+      # @param budget [Budget, nil] defaults to the process default budget
+      # @param clock [#call, nil] returns the current UTC Time
+      # @param logger [Logger, nil]
+      # @param consent [Object, nil] host record of the remote-processing consent
+      def initialize(actor_id:, run_id:, backend:, source_policy:, operation_store:,
+                     approval_store: nil, budget: nil, clock: nil, logger: nil, consent: nil,
+                     metadata: {})
+        @actor_id = presence!(actor_id, :actor_id)
+        @run_id = presence!(run_id, :run_id)
+        @backend = backend!(backend)
+        @source_policy = policy!(source_policy)
+        @operation_store = store!(operation_store)
+        @approval_store = approval_store!(approval_store)
+        @budget = budget.nil? ? RubyLLM::Browser.configuration.default_budget : budget!(budget)
+        @clock = clock || RubyLLM::Browser.clock
+        @logger = logger || RubyLLM::Browser.logger
+        @consent = consent
+        @metadata = Immutable.copy(metadata || {})
+        freeze
+      end
+
+      # The host policy.
+      def policy = source_policy
+
+      def capabilities
+        backend.capabilities
+      end
+
+      # Current UTC time from the context clock.
+      def now
+        @clock.call
+      end
+
+      # Exact secret values the backend wants scrubbed from page text and results.
+      def secrets
+        backend.respond_to?(:secrets) ? Array(backend.secrets) : []
+      end
+
+      # An audit-safe summary. Never includes backend credentials.
+      def to_h
+        {
+          actor_id: actor_id,
+          run_id: run_id,
+          budget: budget.to_h,
+          consent: !consent.nil?,
+          capabilities: capabilities.respond_to?(:to_h) ? capabilities.to_h : capabilities
+        }
+      end
+
+      def inspect
+        "#<#{self.class} actor=#{actor_id} run=#{run_id} backend=#{backend.class}>"
+      end
+
+      private
+
+      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 backend!(value)
+        unless value.is_a?(Backend)
+          raise InvalidInput, "backend must be a RubyLLM::Browser::Backend"
+        end
+
+        value
+      end
+
+      def policy!(value)
+        raise InvalidInput, "source_policy must be a RubyLLM::Browser::Policy" unless value.is_a?(Policy)
+
+        value
+      end
+
+      def store!(value)
+        unless value.is_a?(OperationStore)
+          raise InvalidInput, "operation_store must be a RubyLLM::Browser::OperationStore"
+        end
+
+        value
+      end
+
+      def approval_store!(value)
+        return nil if value.nil?
+        unless value.is_a?(ApprovalStore)
+          raise InvalidInput, "approval_store must be a RubyLLM::Browser::ApprovalStore"
+        end
+
+        value
+      end
+
+      def budget!(value)
+        raise InvalidInput, "budget must be a RubyLLM::Browser::Budget" unless value.is_a?(Budget)
+
+        value
+      end
+    end
+  end
+end

data/lib/ruby_llm/browser/doctor.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Browser
+    # Read-only preflight diagnostics for a live browser deployment.
+    #
+    # The Doctor never makes a network call, never starts a session and never prints a
+    # credential. It reports the version pins, the environment overrides that the SDK
+    # would otherwise honour, and whether the configured backend is qualified to start a
+    # session. A `:fail` check means live use must not proceed.
+    #
+    #   report = RubyLLM::Browser::Doctor.new(backend: backend).report
+    #   raise report[:summary] unless report[:ok]
+    class Doctor
+      STATUSES = %i[pass warn info fail].freeze
+
+      attr_reader :backend, :env
+
+      # @param backend [Backend, nil]
+      # @param env [Hash] environment to inspect; injectable for tests
+      def initialize(backend: nil, env: ENV)
+        @backend = backend
+        @env = env
+      end
+
+      # @return [Hash] `{ ok:, summary:, checks: [...] }`, safe to log
+      def report
+        checks = [
+          ruby_llm_check, stagehand_check, egress_check, local_binary_check,
+          custom_headers_check, base_url_check, credentials_check
+        ].compact
+        {
+          ok: checks.none? { |check| check[:status] == :fail },
+          summary: summary_for(checks),
+          checks: checks
+        }
+      end
+
+      def ok? = report[:ok]
+
+      private
+
+      def ruby_llm_check
+        version = Gem::Version.new(RubyLLM::VERSION)
+        required = Gem::Version.new("2.0.0")
+        ceiling = Gem::Version.new("3.0.0")
+        if version >= required && version < ceiling
+          check(:ruby_llm, :pass, "RubyLLM #{RubyLLM::VERSION} is within >= 2.0, < 3")
+        else
+          check(:ruby_llm, :fail, "RubyLLM #{RubyLLM::VERSION} is outside the supported range >= 2.0, < 3")
+        end
+      rescue StandardError => e
+        check(:ruby_llm, :warn, "could not determine the RubyLLM version: #{e.class}")
+      end
+
+      def stagehand_check
+        require "stagehand/version"
+        unless Gem::Requirement.new("~> 3.21.0").satisfied_by?(Gem::Version.new(Stagehand::VERSION))
+          return check(:stagehand, :fail, "Stagehand version is outside the tested 3.21.x series")
+        end
+        check(:stagehand, :pass, "stagehand #{Stagehand::VERSION} is available")
+      rescue LoadError
+        check(:stagehand, :warn, "the stagehand SDK is not installed; only fake backends can start")
+      end
+
+      def egress_check
+        return check(:egress_isolation, :fail, "no backend was supplied") unless backend
+
+        capabilities = backend.capabilities
+        if backend.is_a?(StagehandBackend)
+          return check(:egress_isolation, :fail,
+                       "Stagehand backend is unsupported until provider egress and cleanup are qualified")
+        end
+        if capabilities.enforced_egress?
+          check(:egress_isolation, :pass, "the backend asserts enforced, browser-side egress isolation")
+        else
+          check(:egress_isolation, :fail,
+                "the backend does not assert enforced egress isolation; live sessions are refused")
+        end
+      end
+
+      def local_binary_check
+        return nil unless backend&.capabilities&.local_mode?
+
+        if backend.capabilities.local_binary_pinned?
+          check(:local_binary, :pass, "local mode uses a host-pinned server binary or version")
+        else
+          check(:local_binary, :fail,
+                "local mode has no host-pinned #{StagehandBackend::PINNED_BINARY_ENV} or " \
+                "#{StagehandBackend::PINNED_VERSION_ENV}; the SDK would download a binary")
+        end
+      end
+
+      def custom_headers_check
+        return nil unless backend&.capabilities&.custom_headers_present?
+
+        if backend.capabilities.custom_headers_approved?
+          check(:custom_headers, :pass, "#{StagehandBackend::CUSTOM_HEADERS_ENV} is set and host-approved")
+        else
+          check(:custom_headers, :fail,
+                "#{StagehandBackend::CUSTOM_HEADERS_ENV} is set but not host-approved; the SDK always merges it")
+        end
+      end
+
+      def base_url_check
+        present = StagehandBackend::ENV_OVERRIDE_KEYS.select { |key| !env[key].to_s.empty? }
+        return nil if present.empty?
+
+        check(:base_url_override, :warn,
+              "#{present.join(", ")} set; the adapter passes an explicit base_url so the override is ignored")
+      end
+
+      def credentials_check
+        missing = %w[BROWSERBASE_API_KEY MODEL_API_KEY].reject { |key| !env[key].to_s.empty? }
+        return check(:credentials, :info, "both provider credentials are present in the environment") if missing.empty?
+
+        check(:credentials, :warn, "#{missing.join(", ")} not set in the environment")
+      end
+
+      def check(name, status, detail)
+        raise ArgumentError, "unknown status #{status.inspect}" unless STATUSES.include?(status)
+
+        { name: name, status: status, detail: detail }
+      end
+
+      def summary_for(checks)
+        failed = checks.select { |check| check[:status] == :fail }
+        return "configuration checks passed; live provider guarantees are not verified" if failed.empty?
+
+        "blocked: #{failed.map { |check| check[:name] }.join(", ")}"
+      end
+    end
+  end
+end

data/lib/ruby_llm/browser/engine.rb

@@ -0,0 +1,326 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Browser
+    # Orchestrates one bounded browser operation.
+    #
+    # The engine enforces, in order: egress qualification (before anything remote),
+    # destination policy, budget reservation and the actor concurrency slot, the
+    # operation lifecycle, step/byte/time limits, result redaction and bounding, and a
+    # best-effort cleanup that never reports unconfirmed closure as success.
+    #
+    # Pre-flight failures (policy, budget, input) raise a typed {Error}. Failures after a
+    # session exists are returned as a {Result} with a typed status so the operation's
+    # durable state is recorded first.
+    class Engine
+      Attempt = Struct.new(:operation, :session, :uri, keyword_init: true)
+
+      attr_reader :context
+
+      def initialize(context:)
+        @context = context
+      end
+
+      # Read-only observation of an allowlisted page.
+      #
+      # @param operation [Operation, nil] a caller-reserved, caller-leased operation to
+      #   drive. Used by the optional Rails job so a duplicate delivery attaches to the
+      #   stored operation instead of reserving a second one. When nil the engine
+      #   reserves its own operation.
+      def inspect(url:, instruction: nil, max_bytes: nil, operation: nil)
+        max_bytes = optional_positive_integer!(max_bytes, :max_bytes)
+        execute(url: url, operation: operation) do |attempt|
+          attempt.operation = next_step(attempt.operation)
+          observed = backend.observe(attempt.session, instruction: instruction,
+                                     operation: attempt.operation, now: now)
+          ok_result(
+            attempt.operation, observed, session: attempt.session,
+            locator: { "url" => current_url(attempt), "scope" => "observe" },
+            max_bytes: max_bytes
+          )
+        end
+      end
+
+      # Schema-bounded extraction from an allowlisted page.
+      def extract(url:, schema:, instruction: nil, max_bytes: nil, operation: nil)
+        max_bytes = optional_positive_integer!(max_bytes, :max_bytes)
+        validated = policy.authorize_schema!(schema)
+        execute(url: url, operation: operation) do |attempt|
+          attempt.operation = next_step(attempt.operation)
+          data = backend.extract(attempt.session, schema: validated, instruction: instruction,
+                                  operation: attempt.operation, now: now)
+          policy.authorize_extraction!(data, schema: validated)
+          ok_result(
+            attempt.operation, data, session: attempt.session,
+            locator: { "url" => current_url(attempt), "scope" => "extract",
+                       "schema_digest" => Redactor.digest(validated) },
+            max_bytes: max_bytes
+          )
+        end
+      end
+
+      # One human-approved action. Disabled unless an approval store is configured and an
+      # active, exactly-bound, single-use approval exists.
+      def act(url:, approval_id:, action:, page_revision: nil, operation: nil)
+        unless capabilities.server_mode == :fake
+          raise UnsupportedSecurityCapability, "live Act is unavailable until same-session approval is implemented"
+        end
+        unless capabilities.act_supported?
+          raise UnsupportedSecurityCapability, "backend does not support qualified Act"
+        end
+        normalized = policy.authorize_action!(action)
+        require_approval_store!
+        execute(url: url, operation: operation) do |attempt|
+          ensure_no_redirect!(attempt)
+          attempt.operation = next_step(attempt.operation)
+          observed = backend.observe(attempt.session, instruction: nil,
+                                     operation: attempt.operation, now: now)
+          revision = Approval.page_revision(observed)
+          if page_revision && page_revision != revision
+            raise ApprovalStale, "the current page does not match the requested revision"
+          end
+          approval = consume_approval!(approval_id, attempt: attempt, action: normalized,
+                                       page_revision: revision)
+          attempt.operation = next_step(attempt.operation)
+          data = backend.act(attempt.session, action: normalized, operation: attempt.operation, now: now)
+          ok_result(
+            attempt.operation, data, session: attempt.session,
+            locator: { "url" => attempt.uri.to_s, "scope" => "act",
+                       "approval_id" => approval.id, "action_digest" => approval.action_digest },
+            max_bytes: nil
+          )
+        end
+      end
+
+      private
+
+      def execute(url:, operation: nil)
+        policy.authorize_egress!(capabilities)
+        uri = policy.authorize_destination!(url, actor_id: context.actor_id)
+        operation = reserve(uri, operation)
+        operation = store.claim_start(operation, now: now)
+        attempt = Attempt.new(operation: operation, uri: uri)
+        outcome = nil
+
+        begin
+          begin
+            attempt.session = backend.start(context: context, operation: operation, now: now)
+          rescue ProviderError => e
+            safe_transition(operation, :closed, error_code: e.code)
+            return Result.failure(:error, error_code: e.code, message: "browser provider rejected session start",
+                                  operation_id: operation.id, final_url: safe_url(uri.to_s))
+          rescue StandardError => e
+            error = e.is_a?(SessionUnknown) ? e : SessionUnknown.new("session start outcome is unconfirmed")
+            if error.session
+              attempt.session = error.session
+              attempt.operation = store.record_session(operation, session_id: error.session.id, now: now)
+              raise error
+            end
+            safe_transition(operation, :unknown, error_code: error.code)
+            return Result.failure(:unknown, error_code: error.code, message: error.message,
+                                  operation_id: operation.id, final_url: safe_url(uri.to_s))
+          end
+
+          stored = store.record_session(operation, session_id: attempt.session.id, now: now)
+          if stored.fence != operation.fence
+            raise InvalidInput, "starting worker was fenced or cancelled"
+          end
+          attempt.operation = stored
+          attempt.operation = next_step(attempt.operation)
+          attempt.session = navigate(attempt)
+          outcome = yield attempt
+          attempt.operation = store.fetch!(attempt.operation.id)
+        rescue Error => e
+          outcome = failure_result(e, attempt)
+        rescue StandardError
+          outcome = failure_result(ProviderError.new("browser backend or bookkeeping failed"), attempt)
+        ensure
+          outcome = finish(attempt, outcome) if attempt.session
+        end
+        outcome
+      end
+
+      def reserve(uri, provided = nil)
+        return validate_provided!(provided) if provided
+
+        now = self.now
+        operation = Operation.new(
+          id: Operation.generate_id, actor_id: context.actor_id, run_id: context.run_id,
+          budget: context.budget, state: :reserved, created_at: now, updated_at: now
+        )
+        store.reserve(operation)
+      end
+
+      # Accepts a caller-reserved operation only when it belongs to this exact
+      # actor/run and uses this context's budget. A mismatched operation is refused
+      # before any remote call.
+      def validate_provided!(operation)
+        raise InvalidInput, "reserved operation must be a RubyLLM::Browser::Operation" unless operation.is_a?(Operation)
+        unless operation.actor_id == context.actor_id && operation.run_id == context.run_id
+          raise NotAuthorized, "reserved operation belongs to a different actor or run"
+        end
+        unless operation.budget == context.budget
+          raise InvalidInput, "reserved operation budget does not match the context budget"
+        end
+        raise InvalidInput, "operation must be reserved" unless operation.state == :reserved
+
+        operation
+      end
+
+      # Records one provider round-trip, refusing once a limit is reached.
+      def next_step(operation)
+        timestamp = now
+        raise BudgetExhausted, "operation wall-clock budget exhausted" if operation.expired?(timestamp)
+
+        store.update(operation.consume_step!(now: timestamp))
+      end
+
+      def ok_result(operation, data, session:, locator:, max_bytes:)
+        raise BudgetExhausted, "operation wall-clock budget exhausted" if operation.expired?(now)
+        limit = [ max_bytes || policy.max_result_bytes, policy.max_result_bytes, operation.remaining_bytes ].min
+        raise BudgetExhausted, "operation byte budget exhausted" unless limit.positive?
+        bounded, truncated = policy.authorize_result!(
+          data, max_bytes: limit, secrets: context.secrets
+        )
+        stored = store.update(operation.add_bytes!(Redactor.canonical_json(bounded).bytesize, now: now))
+        Result.ok(
+          data: bounded, operation_id: stored.id, final_url: safe_url(session.url.to_s),
+          captured_at: now, locator: locator.merge("url" => safe_url(session.url.to_s)),
+          digest: Redactor.digest(bounded), truncated: truncated
+        )
+      end
+
+      def failure_result(error, attempt)
+        status = status_for(error)
+        recorded =
+          if status == :error
+            safe_transition(attempt.operation, attempt.operation.state, error_code: error.code)
+          else
+            safe_transition(attempt.operation, status, error_code: error.code)
+          end
+        attempt.operation = recorded
+        Result.failure(
+          status, error_code: error.code, message: Redactor.scrub_string(error.message, secrets: context.secrets),
+          operation_id: recorded.id, final_url: safe_url(attempt.uri.to_s)
+        )
+      end
+
+      def finish(attempt, outcome)
+        closing = safe_transition(attempt.operation, :closing)
+        closed =
+          begin
+            backend.end_session(attempt.session, operation: closing, now: now)
+          rescue StandardError
+            false
+          end
+
+        if closed
+          begin
+            store.confirm_closed(closing, session_id: attempt.session.id, now: now)
+          rescue StandardError
+            return cleanup_failure(attempt)
+          end
+          outcome
+        else
+          safe_transition(closing, :cleanup_pending, error_code: CleanupPending.code)
+          cleanup_failure(attempt)
+        end
+      end
+
+      def cleanup_failure(attempt)
+        Result.failure(:cleanup_pending, error_code: CleanupPending.code,
+                       message: "browser session cleanup could not be confirmed",
+                       operation_id: attempt.operation.id, final_url: safe_url(attempt.uri.to_s))
+      end
+
+      # Navigates the freshly started session to the requested URL and re-checks the
+      # final destination against policy. A browser-initiated redirect may only land
+      # inside the approved destinations.
+      def navigate(attempt)
+        session = backend.navigate(attempt.session, url: attempt.uri.to_s,
+                                   operation: attempt.operation, now: now)
+        ensure_within_policy!(session, attempt.uri)
+        session
+      end
+
+      def ensure_within_policy!(session, uri)
+        final = session.url.to_s
+        raise ProviderError, "browser did not report a destination URL" if final.empty?
+        return if final == uri.to_s
+
+        policy.authorize_destination!(final, actor_id: context.actor_id)
+      rescue NotAuthorized, InvalidInput => e
+        raise NotAuthorized, "the browser left the approved destinations: #{e.message}"
+      end
+
+      def ensure_no_redirect!(attempt)
+        return if attempt.session.url.to_s == attempt.uri.to_s
+
+        raise ApprovalStale, "the page changed to a different URL; the approval no longer applies"
+      end
+
+      def consume_approval!(approval_id, attempt:, action:, page_revision:)
+        context.approval_store.consume_once(
+          approval_id,
+          actor_id: context.actor_id, run_id: context.run_id, url: attempt.uri.to_s,
+          action_digest: Approval.action_digest(action), page_revision: page_revision,
+          operation_id: attempt.operation.id, session_id: attempt.session.id, now: now
+        )
+      end
+
+      def require_approval_store!
+        return unless context.approval_store.nil?
+
+        raise ApprovalRequired, "Act requires a configured approval store"
+      end
+
+      def transition(operation, target, session_id: :keep, error_code: nil)
+        updated = operation.advance(target, now: now, session_id: session_id,
+                                    error_code: error_code.nil? ? :keep : error_code)
+        store.update(updated)
+      end
+
+      # A transition that tolerates a store refusing the write.
+      #
+      # When a host cancels an operation or a newer worker takes the lease (fencing),
+      # the store rejects this worker's bookkeeping by design. Cleanup must still be
+      # attempted, so bookkeeping failure is logged and the last known operation is
+      # kept; the durable reaper reconciles the row.
+      def safe_transition(operation, target, session_id: :keep, error_code: nil)
+        transition(operation, target, session_id: session_id, error_code: error_code)
+      rescue StandardError
+        context.logger&.warn { "browser bookkeeping write rejected" }
+        operation
+      end
+
+      def safe_url(url)
+        Redactor.url(url, secrets: context.secrets)
+      end
+
+      def status_for(error)
+        case error
+        when SessionUnknown then :unknown
+        when CleanupPending then :cleanup_pending
+        else :error
+        end
+      end
+
+      def current_url(attempt)
+        attempt.session.url.to_s
+      end
+
+      def optional_positive_integer!(value, name)
+        return nil if value.nil?
+        raise InvalidInput, "#{name} must be a positive Integer" unless value.is_a?(Integer) && value.positive?
+
+        value
+      end
+
+      def backend = context.backend
+      def policy = context.policy
+      def store = context.operation_store
+      def capabilities = context.capabilities
+      def now = context.now
+    end
+  end
+end