ruby_llm-mcp 0.7.1 → 1.0.0

data/lib/ruby_llm/mcp/handlers/elicitation_registry.rb

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module MCP
+    module Handlers
+      # Registry for tracking pending elicitations
+      # Provides thread-safe storage and retrieval for async completions
+      class ElicitationRegistry
+        class << self
+          # Get the singleton registry instance
+          def instance
+            @instance ||= new
+          end
+
+          # Delegate class methods to instance
+          def store(id, elicitation, schedule_timeout: true)
+            instance.store(id, elicitation, schedule_timeout: schedule_timeout)
+          end
+
+          def retrieve(id)
+            instance.retrieve(id)
+          end
+
+          def remove(id)
+            instance.remove(id)
+          end
+
+          def complete(id, response:)
+            instance.complete(id, response: response)
+          end
+
+          def cancel(id, reason: "Cancelled")
+            instance.cancel(id, reason: reason)
+          end
+
+          def clear
+            instance.clear
+          end
+
+          def size
+            instance.size
+          end
+        end
+
+        def initialize
+          @registry = {}
+          @timeouts = {}
+          @registry_mutex = Mutex.new
+          @timeouts_mutex = Mutex.new
+        end
+
+        # Store an elicitation in the registry
+        # @param id [String] elicitation ID
+        # @param elicitation [RubyLLM::MCP::Elicitation] elicitation object
+        def store(id, elicitation, schedule_timeout: true)
+          @registry_mutex.synchronize do
+            @registry[id] = elicitation
+          end
+
+          # Set up timeout if specified
+          if schedule_timeout && elicitation.timeout
+            schedule_timeout(id, elicitation.timeout)
+          end
+
+          RubyLLM::MCP.logger.debug("Stored elicitation #{id} in registry")
+        end
+
+        # Retrieve an elicitation from the registry
+        # @param id [String] elicitation ID
+        # @return [RubyLLM::MCP::Elicitation, nil] elicitation or nil if not found
+        def retrieve(id)
+          @registry_mutex.synchronize do
+            @registry[id]
+          end
+        end
+
+        # Remove an elicitation from the registry
+        # @param id [String] elicitation ID
+        # @return [RubyLLM::MCP::Elicitation, nil] removed elicitation or nil
+        def remove(id)
+          elicitation = nil
+
+          # Cancel timeout first (before removing from registry)
+          cancel_timeout(id)
+
+          # Remove from registry
+          elicitation = @registry_mutex.synchronize do
+            @registry.delete(id)
+          end
+
+          RubyLLM::MCP.logger.debug("Removed elicitation #{id} from registry") if elicitation
+          elicitation
+        ensure
+          # Ensure timeout thread is cleaned up even if removal fails
+          cancel_timeout(id) unless elicitation
+        end
+
+        # Complete a pending elicitation
+        # @param id [String] elicitation ID
+        # @param response [Hash] response data
+        def complete(id, response:)
+          elicitation = retrieve(id)
+
+          if elicitation
+            RubyLLM::MCP.logger.info("Completing elicitation #{id}")
+            elicitation.complete(response)
+            remove(id)
+          else
+            RubyLLM::MCP.logger.warn("Attempted to complete unknown elicitation #{id}")
+          end
+        end
+
+        # Cancel a pending elicitation
+        # @param id [String] elicitation ID
+        # @param reason [String] cancellation reason
+        def cancel(id, reason: "Cancelled")
+          elicitation = retrieve(id)
+
+          if elicitation
+            RubyLLM::MCP.logger.info("Cancelling elicitation #{id}: #{reason}")
+            elicitation.cancel_async(reason)
+            remove(id)
+          else
+            RubyLLM::MCP.logger.warn("Attempted to cancel unknown elicitation #{id}")
+          end
+        end
+
+        # Clear all pending elicitations
+        def clear
+          ids = @registry_mutex.synchronize { @registry.keys }
+          ids.each { |id| cancel_timeout(id) }
+          @registry_mutex.synchronize { @registry.clear }
+          RubyLLM::MCP.logger.debug("Cleared elicitation registry")
+        end
+
+        # Get number of pending elicitations
+        # @return [Integer] count of pending elicitations
+        def size
+          @registry_mutex.synchronize { @registry.size }
+        end
+
+        private
+
+        # Schedule timeout for an elicitation
+        def schedule_timeout(id, timeout_seconds)
+          timeout_thread = Thread.new do
+            sleep timeout_seconds
+            handle_timeout(id)
+          end
+
+          @timeouts_mutex.synchronize do
+            @timeouts[id] = timeout_thread
+          end
+        end
+
+        # Cancel scheduled timeout
+        # Ensures thread is properly terminated and resources are freed
+        def cancel_timeout(id)
+          timeout_thread = @timeouts_mutex.synchronize do
+            @timeouts.delete(id)
+          end
+
+          return unless timeout_thread
+
+          # Safely terminate the thread
+          begin
+            timeout_thread.kill if timeout_thread.alive?
+            timeout_thread.join(0.1) # Wait briefly for cleanup
+          rescue StandardError => e
+            RubyLLM::MCP.logger.debug("Error cancelling timeout thread for #{id}: #{e.message}")
+          end
+        end
+
+        # Handle timeout event
+        def handle_timeout(id)
+          elicitation = retrieve(id)
+
+          if elicitation
+            RubyLLM::MCP.logger.warn("Elicitation #{id} timed out")
+            elicitation.timeout!
+            # Remove from registry without cancelling timeout (we're IN the timeout thread)
+            remove_without_timeout_cancel(id)
+          end
+        end
+
+        # Remove from registry without cancelling timeout thread
+        # Used when called from within the timeout thread itself
+        def remove_without_timeout_cancel(id)
+          @registry_mutex.synchronize do
+            @registry.delete(id)
+          end
+
+          # Clean up timeout thread reference
+          @timeouts_mutex.synchronize do
+            @timeouts.delete(id)
+          end
+
+          RubyLLM::MCP.logger.debug("Removed elicitation #{id} from registry")
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/mcp/handlers/human_in_the_loop_handler.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module MCP
+    module Handlers
+      # Base class for human-in-the-loop approval handlers
+      # Provides access to tool details, guards, and async support
+      #
+      # @example Basic approval handler
+      #   class MyApprovalHandler < RubyLLM::MCP::Handlers::HumanInTheLoopHandler
+      #     def execute
+      #       if safe_tool?(tool_name)
+      #         approve
+      #       else
+      #         deny("Tool requires approval")
+      #       end
+      #     end
+      #
+      #     private
+      #
+      #     def safe_tool?(name)
+      #       ["read_file", "list_files"].include?(name)
+      #     end
+      #   end
+      #
+      # @example Approval handler with guards and filtering
+      #   class SecureApprovalHandler < RubyLLM::MCP::Handlers::HumanInTheLoopHandler
+      #     allow_tools "read_file", "list_files"
+      #     deny_tools "rm", "delete_all"
+      #
+      #     guard :check_tool_safety
+      #
+      #     def execute
+      #       return deny("Tool denied") if tool_denied?
+      #       approve
+      #     end
+      #
+      #     private
+      #
+      #     def check_tool_safety
+      #       return true if tool_allowed?
+      #       "Tool not in safe list"
+      #     end
+      #   end
+      #
+      # @example Async approval handler
+      #   class AsyncApprovalHandler < RubyLLM::MCP::Handlers::HumanInTheLoopHandler
+      #     async_execution timeout: 300
+      #
+      #     on_timeout :handle_timeout_event
+      #
+      #     def execute
+      #       notify_user(tool_name, parameters)
+      #       defer # Returns { status: :deferred, timeout: 300 }
+      #     end
+      #
+      #     private
+      #
+      #     def handle_timeout_event
+      #       deny("User did not respond in time")
+      #     end
+      #   end
+      class HumanInTheLoopHandler
+        include Concerns::Options
+        include Concerns::Lifecycle
+        include Concerns::Logging
+        include Concerns::ErrorHandling
+        include Concerns::AsyncExecution
+        include Concerns::Timeouts
+        include Concerns::GuardChecks
+        include Concerns::ToolFiltering
+        include Concerns::ApprovalActions
+        include Concerns::RegistryIntegration
+
+        attr_reader :coordinator
+
+        # Initialize human-in-the-loop handler
+        # @param tool_name [String] the tool name
+        # @param parameters [Hash] the tool parameters
+        # @param approval_id [String] unique identifier for this approval
+        # @param coordinator [Object] the coordinator managing the request
+        # @param options [Hash] handler-specific options
+        def initialize(tool_name:, parameters:, approval_id:, coordinator:, **options)
+          @tool_name = tool_name
+          @parameters = parameters
+          @approval_id = approval_id
+          @coordinator = coordinator
+          super(**options)
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/mcp/handlers/human_in_the_loop_registry.rb

@@ -0,0 +1,271 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module MCP
+    module Handlers
+      # Registry for tracking pending human-in-the-loop approvals.
+      # Registries are scoped per native client, with global ID routing so
+      # approval IDs can still be completed externally.
+      class HumanInTheLoopRegistry
+        GLOBAL_OWNER = "__global__"
+
+        class << self
+          def instance
+            for_owner(GLOBAL_OWNER)
+          end
+
+          def for_owner(owner_id)
+            key = owner_id.to_s
+            registries_mutex.synchronize do
+              @registries ||= {}
+              @registries[key] ||= new(owner_id: key)
+            end
+          end
+
+          def release(owner_id)
+            key = owner_id.to_s
+            registry = registries_mutex.synchronize { (@registries ||= {}).delete(key) }
+            registry&.shutdown
+          end
+
+          # Backward-compatible global store path.
+          def store(id, approval)
+            instance.store(id, approval)
+          end
+
+          def retrieve(id)
+            route_registry(id)&.retrieve(id)
+          end
+
+          def remove(id)
+            route_registry(id)&.remove(id)
+          end
+
+          def approve(id)
+            registry = route_registry(id)
+            if registry
+              registry.approve(id)
+            else
+              RubyLLM::MCP.logger.warn("Attempted to approve unknown approval #{id}")
+              false
+            end
+          end
+
+          def deny(id, reason: "Denied")
+            registry = route_registry(id)
+            if registry
+              registry.deny(id, reason: reason)
+            else
+              RubyLLM::MCP.logger.warn("Attempted to deny unknown approval #{id}")
+              false
+            end
+          end
+
+          def clear(owner_id: nil)
+            if owner_id
+              release(owner_id)
+            else
+              registries = registries_mutex.synchronize do
+                current = (@registries ||= {}).values
+                @registries = {}
+                current
+              end
+              registries.each(&:shutdown)
+            end
+          end
+
+          def size(owner_id: nil)
+            if owner_id
+              registry = registries_mutex.synchronize { (@registries ||= {})[owner_id.to_s] }
+              registry ? registry.size : 0
+            else
+              registries_mutex.synchronize { (@registries ||= {}).values.sum(&:size) }
+            end
+          end
+
+          def register_approval(id, owner_id)
+            approval_index_mutex.synchronize do
+              @approval_index ||= {}
+              @approval_index[id.to_s] = owner_id.to_s
+            end
+          end
+
+          def unregister_approval(id)
+            approval_index_mutex.synchronize do
+              (@approval_index ||= {}).delete(id.to_s)
+            end
+          end
+
+          def route_registry(id)
+            owner_id = approval_index_mutex.synchronize { (@approval_index ||= {})[id.to_s] }
+            if owner_id
+              registries_mutex.synchronize { (@registries ||= {})[owner_id] }
+            else
+              registries_mutex.synchronize { (@registries ||= {})[GLOBAL_OWNER] }
+            end
+          end
+
+          private
+
+          def registries_mutex
+            @registries_mutex ||= Mutex.new
+          end
+
+          def approval_index_mutex
+            @approval_index_mutex ||= Mutex.new
+          end
+        end
+
+        attr_reader :owner_id
+
+        def initialize(owner_id:)
+          @owner_id = owner_id
+          @registry = {}
+          @deadlines = {}
+          @registry_mutex = Mutex.new
+          @condition = ConditionVariable.new
+          @stopped = false
+          start_timeout_scheduler
+        end
+
+        # Store approval context: { promise:, timeout:, tool_name:, parameters: }
+        def store(id, approval_context)
+          key = id.to_s
+          timeout = approval_context[:timeout]
+
+          @registry_mutex.synchronize do
+            @registry[key] = approval_context
+            if timeout
+              @deadlines[key] = monotonic_now + timeout.to_f
+            else
+              @deadlines.delete(key)
+            end
+            @condition.signal
+          end
+
+          self.class.register_approval(key, owner_id)
+          RubyLLM::MCP.logger.debug("Stored approval #{key} in registry for #{owner_id}")
+        end
+
+        def retrieve(id)
+          @registry_mutex.synchronize { @registry[id.to_s] }
+        end
+
+        def remove(id)
+          key = id.to_s
+          approval = nil
+
+          @registry_mutex.synchronize do
+            approval = @registry.delete(key)
+            @deadlines.delete(key)
+            @condition.signal
+          end
+
+          self.class.unregister_approval(key) if approval
+          RubyLLM::MCP.logger.debug("Removed approval #{key} from registry for #{owner_id}") if approval
+          approval
+        end
+
+        def approve(id) # rubocop:disable Naming/PredicateMethod
+          approval = remove(id)
+          unless approval && approval[:promise]
+            RubyLLM::MCP.logger.warn("Attempted to approve unknown approval #{id}")
+            return false
+          end
+
+          RubyLLM::MCP.logger.info("Approving #{id}")
+          approval[:promise].resolve(true)
+          true
+        end
+
+        def deny(id, reason: "Denied") # rubocop:disable Naming/PredicateMethod
+          approval = remove(id)
+          unless approval && approval[:promise]
+            RubyLLM::MCP.logger.warn("Attempted to deny unknown approval #{id}")
+            return false
+          end
+
+          RubyLLM::MCP.logger.info("Denying #{id}: #{reason}")
+          approval[:promise].resolve(false)
+          true
+        end
+
+        def clear
+          approvals = @registry_mutex.synchronize do
+            current = @registry.dup
+            @registry.clear
+            @deadlines.clear
+            @condition.broadcast
+            current
+          end
+
+          approvals.each_key { |id| self.class.unregister_approval(id) }
+          RubyLLM::MCP.logger.debug("Cleared human-in-the-loop registry for #{owner_id}")
+        end
+
+        def size
+          @registry_mutex.synchronize { @registry.size }
+        end
+
+        def shutdown
+          clear
+          @registry_mutex.synchronize do
+            @stopped = true
+            @condition.broadcast
+          end
+          @scheduler_thread&.join(0.5)
+        rescue StandardError => e
+          RubyLLM::MCP.logger.debug("Error shutting down approval registry #{owner_id}: #{e.message}")
+        ensure
+          @scheduler_thread = nil
+        end
+
+        private
+
+        def start_timeout_scheduler
+          @scheduler_thread = Thread.new do
+            loop do
+              expired_ids = wait_for_expired_ids
+              break if expired_ids.nil?
+
+              expired_ids.each { |id| handle_timeout(id) }
+            end
+          end
+        end
+
+        def wait_for_expired_ids
+          @registry_mutex.synchronize do
+            loop do
+              return nil if @stopped
+
+              now = monotonic_now
+              expired_ids = @deadlines.each_with_object([]) do |(id, deadline), ids|
+                ids << id if deadline <= now
+              end
+              return expired_ids unless expired_ids.empty?
+
+              if @deadlines.empty?
+                @condition.wait(@registry_mutex)
+              else
+                wait_time = @deadlines.values.min - now
+                @condition.wait(@registry_mutex, wait_time) if wait_time.positive?
+              end
+            end
+          end
+        end
+
+        def handle_timeout(id)
+          approval = remove(id)
+          return unless approval && approval[:promise]
+
+          RubyLLM::MCP.logger.warn("Approval #{id} timed out")
+          approval[:promise].resolve(false)
+        end
+
+        def monotonic_now
+          Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        end
+      end
+    end
+  end
+end