ruby_llm-browser 0.1.0

data/lib/ruby_llm/browser/errors.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Browser
+    # Base class for every error this Gem raises deliberately.
+    #
+    # Each subclass carries a stable, machine-readable +code+ from the documented safe
+    # set. Messages are constructed by the Gem and never contain credentials, cookies,
+    # +cdp_url+ values or raw page dumps.
+    class Error < StandardError
+      # The stable code for this error class.
+      def self.code
+        const_defined?(:CODE, false) ? const_get(:CODE) : "ERROR"
+      end
+
+      # The stable code for this error instance, e.g. "INVALID_INPUT".
+      def code
+        self.class.code
+      end
+
+      # A model-safe representation. Callers may hand this straight back to a tool
+      # result without leaking internals.
+      def to_h
+        { code: code, message: message }
+      end
+    end
+
+    # The caller supplied malformed or out-of-range input.
+    class InvalidInput < Error
+      CODE = "INVALID_INPUT"
+    end
+
+    # The destination, actor, schema or action is not permitted by the host policy.
+    class NotAuthorized < Error
+      CODE = "NOT_AUTHORIZED"
+    end
+
+    # The backend cannot enforce a security capability this Gem requires, so no session
+    # may start. Returned *before* any remote call.
+    class UnsupportedSecurityCapability < Error
+      CODE = "UNSUPPORTED_SECURITY_CAPABILITY"
+    end
+
+    # A rendered, step, byte, concurrency or cost budget is exhausted.
+    class BudgetExhausted < Error
+      CODE = "BUDGET_EXHAUSTED"
+    end
+
+    # A remote start or action has no confirmed outcome. Never treated as success and
+    # never automatically retried into a second session.
+    class SessionUnknown < Error
+      CODE = "SESSION_UNKNOWN"
+
+      # A returned identity must still be tracked/closed after a partial start failure.
+      # It is internal bookkeeping and is deliberately absent from Error#to_h.
+      attr_reader :session
+
+      def initialize(message = nil, session: nil)
+        @session = session
+        super(message)
+      end
+    end
+
+    # Cleanup was attempted but is not confirmed. The reservation is held until closure
+    # or expiry is proven.
+    class CleanupPending < Error
+      CODE = "CLEANUP_PENDING"
+    end
+
+    # An action requires a host-issued approval that is missing.
+    class ApprovalRequired < Error
+      CODE = "APPROVAL_REQUIRED"
+    end
+
+    # An approval exists but is expired, revoked, cross-actor, replayed or bound to a
+    # different page revision or action digest.
+    class ApprovalStale < Error
+      CODE = "APPROVAL_STALE"
+    end
+
+    # The remote provider returned an error, timed out or is otherwise unavailable.
+    class ProviderError < Error
+      CODE = "PROVIDER_ERROR"
+    end
+  end
+end

data/lib/ruby_llm/browser/fake_backend.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Browser
+    # Offline reference backend.
+    #
+    # It performs no network I/O at all, so it can honestly claim enforced egress
+    # isolation, and it never opens a paid session. Tests script its responses and
+    # inspect the recorded calls; it is the required default in CI.
+    #
+    # It does **not** prove anything about a real provider's network isolation, TTL or
+    # billing.
+    class FakeBackend < Backend
+      DEFAULT_OBSERVE = [
+        { "description" => "Open the documentation link", "method" => "click",
+          "selector" => "a#docs", "arguments" => [] }
+      ].freeze
+
+      DEFAULT_EXTRACT = { "title" => "Example" }.freeze
+      DEFAULT_ACT = { "success" => true, "message" => "clicked", "actions" => [] }.freeze
+
+      attr_reader :calls
+
+      # @param capabilities [Capabilities] defaults to an egress-qualified fake backend
+      # @param start_error [Exception, nil] raised by {#start}
+      # @param navigate_error [Exception, nil]
+      # @param observe_error [Exception, nil]
+      # @param extract_error [Exception, nil]
+      # @param act_error [Exception, nil]
+      # @param end_error [Exception, nil]
+      # @param redirect_to [String, nil] simulate an in-provider redirect on navigate
+      # @param end_confirmed [Boolean] whether {#end_session} confirms closure
+      # @param reconcile_state [Symbol] what {#reconcile} reports
+      # @param session_id [String] the id returned by {#start}
+      def initialize(capabilities: nil, observe: nil, extract: nil, act: nil,
+                     start_error: nil, navigate_error: nil, observe_error: nil,
+                     extract_error: nil, act_error: nil, end_error: nil,
+                     redirect_to: nil, end_confirmed: true, reconcile_state: :closed,
+                     session_id: "fake-session-1")
+        super()
+        @capabilities = capabilities || Capabilities.new(
+          server_mode: :fake, egress_isolation: :enforced, act_supported: true
+        )
+        @observe = observe || DEFAULT_OBSERVE
+        @extract = extract || DEFAULT_EXTRACT
+        @act = act || DEFAULT_ACT
+        @start_error = start_error
+        @navigate_error = navigate_error
+        @observe_error = observe_error
+        @extract_error = extract_error
+        @act_error = act_error
+        @end_error = end_error
+        @redirect_to = redirect_to
+        @end_confirmed = end_confirmed
+        @reconcile_state = reconcile_state
+        @session_id = session_id
+        @calls = []
+        @started = 0
+      end
+
+      attr_reader :capabilities
+
+      def start(context:, operation:, now:)
+        record(:start, actor_id: context.actor_id, run_id: context.run_id, operation_id: operation.id)
+        raise @start_error if @start_error
+
+        @started += 1
+        Session.new(id: @started > 1 ? "#{@session_id}-#{@started}" : @session_id, started_at: now)
+      end
+
+      def navigate(session, url:, operation:, now:)
+        record(:navigate, url: url, operation_id: operation.id)
+        raise @navigate_error if @navigate_error
+
+        session.with_url(@redirect_to || url)
+      end
+
+      def observe(_session, instruction:, operation:, now:)
+        record(:observe, instruction: instruction, operation_id: operation.id)
+        raise @observe_error if @observe_error
+
+        deep_dup(@observe)
+      end
+
+      def extract(_session, schema:, instruction:, operation:, now:)
+        record(:extract, schema: schema, instruction: instruction, operation_id: operation.id)
+        raise @extract_error if @extract_error
+
+        deep_dup(@extract)
+      end
+
+      def act(_session, action:, operation:, now:)
+        record(:act, action: action, operation_id: operation.id)
+        raise @act_error if @act_error
+
+        deep_dup(@act)
+      end
+
+      def end_session(_session, operation:, now:)
+        record(:end_session, operation_id: operation.id)
+        raise @end_error if @end_error
+
+        @end_confirmed
+      end
+
+      def reconcile(_operation, now:)
+        @reconcile_state
+      end
+
+      def called?(method_name)
+        @calls.any? { |call| call[:method] == method_name.to_sym }
+      end
+
+      def call_count(method_name)
+        @calls.count { |call| call[:method] == method_name.to_sym }
+      end
+
+      private
+
+      def record(method_name, **payload)
+        @calls << { method: method_name, **payload }
+      end
+
+      def deep_dup(value)
+        case value
+        when Hash then value.to_h { |key, nested| [ key, deep_dup(nested) ] }
+        when Array then value.map { |item| deep_dup(item) }
+        when String then value.dup
+        else value
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/browser/immutable.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Browser
+    # Copies host-owned input before freezing it. Never freezes the caller's objects.
+    module Immutable
+      module_function
+
+      def copy(value)
+        case value
+        when Hash then value.to_h { |key, nested| [ copy(key), copy(nested) ] }.freeze
+        when Array then value.map { |nested| copy(nested) }.freeze
+        when String, Time then value.dup.freeze
+        else value
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/browser/in_memory_approval_store.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Browser
+    # Thread-safe, in-process {ApprovalStore}.
+    #
+    # A fixture for a single process. Production use needs a durable store so an
+    # approval survives a worker restart and cannot be replayed by a second process.
+    class InMemoryApprovalStore < ApprovalStore
+      def initialize
+        super()
+        @mutex = Mutex.new
+        @approvals = {}
+      end
+
+      def issue(approval)
+        synchronize do
+          raise InvalidInput, "approval #{approval.id} already exists" if @approvals.key?(approval.id)
+
+          @approvals[approval.id] = approval
+        end
+      end
+
+      def fetch(id)
+        synchronize { @approvals[id] }
+      end
+
+      def consume_once(id, actor_id:, run_id:, url:, action_digest:, now:, page_revision: nil,
+                       operation_id: nil, session_id: nil)
+        synchronize do
+          approval = @approvals[id]
+          raise ApprovalRequired, "no approval #{id.inspect} was issued" if approval.nil?
+          raise ApprovalStale, "approval #{id} was already consumed" if approval.consumed?
+          raise ApprovalStale, "approval #{id} was revoked" if approval.revoked?
+          raise ApprovalStale, "approval #{id} has expired" if approval.expired?(now)
+
+          unless approval.binding_matches?(
+            actor_id: actor_id, run_id: run_id, url: url, action_digest: action_digest,
+            page_revision: page_revision, operation_id: operation_id, session_id: session_id
+          )
+            raise ApprovalStale, "approval #{id} does not authorize this actor, URL, page or action"
+          end
+
+          consumed = approval.consume!(now: now)
+          @approvals[id] = consumed
+        end
+      end
+
+      def revoke(id)
+        synchronize do
+          approval = @approvals.fetch(id) { raise ApprovalRequired, "no approval #{id.inspect} was issued" }
+          @approvals[id] = approval.revoke!
+        end
+      end
+
+      def all
+        synchronize { @approvals.values.dup }
+      end
+
+      private
+
+      def synchronize(&block)
+        @mutex.synchronize(&block)
+      end
+    end
+  end
+end

data/lib/ruby_llm/browser/in_memory_operation_store.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Browser
+    # Thread-safe, in-process {OperationStore}.
+    #
+    # This is a fixture for tests and single-process demos. It is **not** production
+    # ready: state disappears on restart and cannot synchronize across workers or
+    # hosts. Use a durable store for anything long-running.
+    class InMemoryOperationStore < OperationStore
+      def initialize(clock: nil)
+        super()
+        @mutex = Mutex.new
+        @operations = {}
+        @clock = clock
+      end
+
+      def reserve(operation)
+        synchronize do
+          if @operations.key?(operation.id)
+            raise InvalidInput, "operation #{operation.id} is already reserved"
+          end
+
+          enforce_concurrency!(operation)
+          @operations[operation.id] = operation
+        end
+      end
+
+      def attach_or_reserve(operation)
+        synchronize do
+          existing = find_by_idempotency_key(operation.actor_id, operation.run_id, operation.idempotency_key)
+          if existing
+            raise InvalidInput, "idempotency key belongs to a different request" unless existing.request_digest == operation.request_digest
+
+            return existing
+          end
+
+          reserve_locked(operation)
+        end
+      end
+
+      def fetch(id)
+        synchronize { @operations[id] }
+      end
+
+      def fetch!(id)
+        fetch(id) || raise(InvalidInput, "unknown operation #{id.inspect}")
+      end
+
+      def lease(id, actor_id:, run_id:, now:)
+        synchronize do
+          operation = @operations.fetch(id) { raise InvalidInput, "unknown operation #{id.inspect}" }
+          assert_actor!(operation, actor_id, run_id)
+          if operation.terminal?
+            raise InvalidInput, "operation #{id} is already #{operation.state}"
+          end
+
+          leased = operation.with_fence(operation.fence + 1, now: now)
+          @operations[id] = leased
+        end
+      end
+
+      def update(operation)
+        synchronize do
+          stored = @operations.fetch(operation.id) { raise InvalidInput, "unknown operation #{operation.id.inspect}" }
+          operation.validate_update!(stored)
+          @operations[operation.id] = operation
+        end
+      end
+
+      def claim_start(operation, now:)
+        synchronize do
+          stored = @operations.fetch(operation.id)
+          operation.validate_update!(stored)
+          raise InvalidInput, "operation was already started" unless stored.state == :reserved
+          raise BudgetExhausted, "operation wall-clock budget exhausted" if stored.expired?(now)
+
+          @operations[operation.id] = stored.advance(:starting, now: now)
+        end
+      end
+
+      def record_session(operation, session_id:, now:)
+        synchronize do
+          stored = @operations.fetch(operation.id)
+          assert_actor!(stored, operation.actor_id, operation.run_id)
+          raise InvalidInput, "operation session cannot change" if stored.session_id && stored.session_id != session_id
+
+          target = stored.fence == operation.fence ? :active : :cleanup_pending
+          @operations[operation.id] = stored.advance(target, session_id: session_id, now: now)
+        end
+      end
+
+      def confirm_closed(operation, session_id:, now:)
+        synchronize do
+          stored = @operations.fetch(operation.id)
+          assert_actor!(stored, operation.actor_id, operation.run_id)
+          raise InvalidInput, "operation session cannot change" unless stored.session_id == session_id
+
+          target = stored.cancel_requested? ? :cancelled : :closed
+          @operations[operation.id] = stored.advance(target, now: now)
+        end
+      end
+
+      def cancel(id, actor_id:, run_id:, now:)
+        synchronize do
+          operation = @operations.fetch(id) { raise InvalidInput, "unknown operation" }
+          assert_actor!(operation, actor_id, run_id)
+          return operation if operation.terminal? || operation.cancel_requested?
+
+          @operations[id] = operation.with_fence(operation.fence + 1, now: now).request_cancel(now: now)
+        end
+      end
+
+      def mark_cleanup_pending(id, actor_id:, run_id:, error_code: nil, now:)
+        synchronize do
+          operation = @operations.fetch(id) { raise InvalidInput, "unknown operation #{id.inspect}" }
+          assert_actor!(operation, actor_id, run_id)
+          updated = operation.advance(:cleanup_pending, now: now, error_code: error_code)
+          @operations[id] = updated
+        end
+      end
+
+      def open_for(actor_id)
+        synchronize { @operations.values.select { |operation| operation.actor_id == actor_id && operation.open? } }
+      end
+
+      def open_operations
+        synchronize { @operations.values.select(&:open?) }
+      end
+
+      # Snapshot for tests and diagnostics.
+      def all
+        synchronize { @operations.values.dup }
+      end
+
+      private
+
+      def synchronize(&block)
+        @mutex.synchronize(&block)
+      end
+
+      def reserve_locked(operation)
+        if @operations.key?(operation.id)
+          raise InvalidInput, "operation #{operation.id} is already reserved"
+        end
+
+        enforce_concurrency!(operation)
+        @operations[operation.id] = operation
+      end
+
+      def find_by_idempotency_key(actor_id, run_id, key)
+        return nil if key.nil?
+
+        @operations.values.find do |operation|
+          operation.actor_id == actor_id && operation.run_id == run_id && operation.idempotency_key == key
+        end
+      end
+
+      def enforce_concurrency!(operation)
+        open = @operations.values.count { |existing| existing.actor_id == operation.actor_id && existing.open? }
+        return if open < operation.budget.max_concurrent
+
+        raise BudgetExhausted,
+              "actor #{operation.actor_id.inspect} already holds #{open} open browser operation(s)"
+      end
+
+      def assert_actor!(operation, actor_id, run_id)
+        return if operation.actor_id == actor_id && operation.run_id == run_id
+
+        raise NotAuthorized, "operation #{operation.id} belongs to a different actor or run"
+      end
+    end
+  end
+end

data/lib/ruby_llm/browser/operation.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module RubyLLM
+  module Browser
+    # Durable identity and lifecycle of one browser operation.
+    #
+    # An operation is reserved *before* the first remote call and is the anchor for
+    # duplicate-job attachment, concurrency, budgets, fencing and cleanup. It never
+    # reports an unresolved outcome as success: an ambiguous start or action is
+    # +unknown+ and unsuccessful cleanup is +cleanup_pending+, and both keep their
+    # budget reservation until closure or expiry is confirmed.
+    #
+    # Instances are immutable; each transition returns a new operation.
+    class Operation
+      STATES = %i[reserved starting active closing closed unknown cleanup_pending cancelled].freeze
+
+      # States that keep the reservation open.
+      OPEN_STATES = %i[reserved starting active closing unknown cleanup_pending].freeze
+
+      # The only confirmed-finished states.
+      TERMINAL_STATES = %i[closed cancelled].freeze
+
+      # Allowed transitions. A state may always advance to itself (refresh/fence bump).
+      TRANSITIONS = {
+        reserved: %i[starting unknown cleanup_pending closed cancelled],
+        starting: %i[active unknown cleanup_pending closed cancelled],
+        active: %i[closing unknown cleanup_pending closed cancelled],
+        closing: %i[closed unknown cleanup_pending cancelled],
+        unknown: %i[active closing cleanup_pending closed cancelled],
+        cleanup_pending: %i[closed unknown cancelled],
+        closed: [],
+        cancelled: []
+      }.freeze
+
+      attr_reader :id, :actor_id, :run_id, :state, :budget, :session_id,
+                  :idempotency_key, :steps, :bytes, :fence, :error_code,
+                  :created_at, :updated_at, :request_digest
+
+      def self.generate_id(prefix: "op")
+        "#{prefix}_#{SecureRandom.uuid}"
+      end
+
+      def initialize(id:, actor_id:, run_id:, budget:, state: :reserved, session_id: nil,
+                     idempotency_key: nil, steps: 0, bytes: 0, fence: 0, error_code: nil,
+                     created_at: nil, updated_at: nil, cancel_requested: false, request_digest: nil)
+        @id = string!(id, :id)
+        @actor_id = string!(actor_id, :actor_id)
+        @run_id = string!(run_id, :run_id)
+        @budget = budget!(budget)
+        @state = state!(state)
+        @session_id = Immutable.copy(session_id)
+        @idempotency_key = Immutable.copy(idempotency_key)
+        @steps = count!(steps, :steps)
+        @bytes = count!(bytes, :bytes)
+        @fence = count!(fence, :fence)
+        @error_code = error_code
+        @created_at = Immutable.copy(created_at)
+        @updated_at = Immutable.copy(updated_at || created_at)
+        @cancel_requested = !!cancel_requested
+        @request_digest = Immutable.copy(request_digest)
+        freeze
+      end
+
+      def open? = OPEN_STATES.include?(state)
+      def terminal? = TERMINAL_STATES.include?(state)
+      def unknown? = state == :unknown
+      def cleanup_pending? = state == :cleanup_pending
+      def cancel_requested? = @cancel_requested
+
+      # Cancellation of a dispatched operation holds quota until cleanup is confirmed.
+      def request_cancel(now:)
+        target = state == :reserved ? :cancelled : :cleanup_pending
+        self.class.new(**advance(target, now: now).to_h.merge(cancel_requested: true))
+      end
+
+      def elapsed_seconds(now)
+        return 0.0 if created_at.nil?
+
+        (now - created_at).to_f
+      end
+
+      # True when the operation has outlived its wall-clock budget.
+      def expired?(now)
+        elapsed_seconds(now) >= budget.max_seconds
+      end
+
+      def remaining_steps = [ budget.max_steps - steps, 0 ].max
+      def remaining_bytes = [ budget.max_bytes - bytes, 0 ].max
+      def bytes_exhausted? = bytes >= budget.max_bytes
+      def steps_exhausted? = steps >= budget.max_steps
+
+      # Advances to +target+, refusing illegal transitions.
+      #
+      # @param now [Time] timestamp for +updated_at+
+      # @param session_id [String, nil] set or clear the provider session id
+      # @param error_code [String, nil] record a typed failure code
+      def advance(target, now:, session_id: :keep, error_code: :keep)
+        target = state!(target)
+        validate_transition!(target)
+        self.class.new(
+          id: id, actor_id: actor_id, run_id: run_id, budget: budget,
+          state: target,
+          session_id: session_id == :keep ? @session_id : session_id,
+          idempotency_key: idempotency_key,
+          steps: steps, bytes: bytes, fence: fence,
+          error_code: error_code == :keep ? @error_code : error_code,
+          created_at: created_at, updated_at: now, cancel_requested: cancel_requested?, request_digest: request_digest
+        )
+      end
+
+      # Records one provider round-trip, refusing to exceed the step budget.
+      def consume_step!(now:)
+        raise BudgetExhausted, "operation step budget exhausted" if steps_exhausted?
+
+        self.class.new(**to_h.merge(steps: steps + 1, updated_at: now))
+      end
+
+      # Records bytes returned by the provider. Bounding/truncation is decided by the
+      # caller from {#remaining_bytes}; this never silently drops data.
+      def add_bytes!(amount, now:)
+        raise InvalidInput, "bytes must be a non-negative integer" unless amount.is_a?(Integer) && amount >= 0
+        raise BudgetExhausted, "operation byte budget exhausted" if amount > remaining_bytes
+
+        self.class.new(**to_h.merge(bytes: bytes + amount, updated_at: now))
+      end
+
+      # Returns a copy carrying a new fence token.
+      def with_fence(value, now: nil)
+        raise InvalidInput, "fence must be a non-negative Integer" unless value.is_a?(Integer) && value >= 0
+
+        self.class.new(**to_h.merge(fence: value, updated_at: now || updated_at))
+      end
+
+      # True when every field matches except possibly timestamps/fence.
+      def same_identity?(other)
+        other.is_a?(Operation) && id == other.id && actor_id == other.actor_id && run_id == other.run_id
+      end
+
+      def to_h
+        {
+          id: id, actor_id: actor_id, run_id: run_id, state: state, budget: budget,
+          session_id: session_id, idempotency_key: idempotency_key, steps: steps,
+          bytes: bytes, fence: fence, error_code: error_code,
+          created_at: created_at, updated_at: updated_at, cancel_requested: cancel_requested?, request_digest: request_digest
+        }
+      end
+
+      # An audit-safe summary. Omits the provider session id.
+      def summary
+        to_h.except(:session_id, :budget, :idempotency_key)
+      end
+
+      def ==(other)
+        other.is_a?(Operation) && to_h == other.to_h
+      end
+      alias eql? ==
+
+      def hash = to_h.hash
+
+      def inspect
+        "#<#{self.class} id=#{id} state=#{state} actor=#{actor_id} steps=#{steps}/#{budget.max_steps}>"
+      end
+
+      # Checks a normal worker write against the authoritative stored version.
+      def validate_update!(stored)
+        raise NotAuthorized, "operation identity cannot change" unless same_identity?(stored)
+        raise InvalidInput, "stale operation writer (fenced)" unless fence == stored.fence
+        raise InvalidInput, "operation budget cannot change" unless budget == stored.budget
+        unless idempotency_key == stored.idempotency_key && request_digest == stored.request_digest && created_at == stored.created_at
+          raise InvalidInput, "operation reservation cannot change"
+        end
+        raise InvalidInput, "operation cancellation cannot change" unless cancel_requested? == stored.cancel_requested?
+        raise InvalidInput, "operation accounting cannot go backwards" if steps < stored.steps || bytes < stored.bytes
+        if stored.session_id && session_id != stored.session_id
+          raise InvalidInput, "operation session cannot change"
+        end
+        stored.advance(state, now: updated_at)
+        true
+      end
+
+      private
+
+      def validate_transition!(target)
+        return if target == state
+        return if TRANSITIONS.fetch(state).include?(target)
+
+        raise InvalidInput, "illegal operation transition #{state} -> #{target}"
+      end
+
+      def string!(value, name)
+        raise InvalidInput, "#{name} must be a non-empty String" unless value.is_a?(String) && !value.empty?
+
+        value.dup.freeze
+      end
+
+      def budget!(value)
+        raise InvalidInput, "budget must be a RubyLLM::Browser::Budget" unless value.is_a?(Budget)
+
+        value
+      end
+
+      def state!(value)
+        symbol = value.to_sym
+        return symbol if STATES.include?(symbol)
+
+        raise InvalidInput, "unknown operation state #{symbol.inspect}"
+      end
+
+      def count!(value, name)
+        raise InvalidInput, "#{name} must be a non-negative Integer" unless value.is_a?(Integer) && value >= 0
+
+        value
+      end
+    end
+  end
+end