ruby_llm-mcp 0.8.0 → 1.0.0

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

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module MCP
+    module Handlers
+      # Promise implementation for async operations
+      class Promise
+        attr_reader :state, :value, :reason
+
+        # Initialize a new promise
+        def initialize
+          @state = :pending
+          @value = nil
+          @reason = nil
+          @mutex = Mutex.new
+          @condition = ConditionVariable.new
+          @then_callbacks = []
+          @catch_callbacks = []
+        end
+
+        # Register a callback for successful resolution
+        # @param callback [Proc] callback to execute on resolution
+        # @return [Promise] returns self for chaining
+        def then(&callback)
+          should_execute = false
+          value_to_use = nil
+
+          @mutex.synchronize do
+            if @state == :fulfilled
+              # Already fulfilled, will execute immediately
+              should_execute = true
+              value_to_use = @value
+            elsif @state == :pending
+              # Still pending, register callback
+              @then_callbacks << callback
+            end
+          end
+
+          # Execute outside mutex
+          execute_callback_sync(callback, value_to_use) if should_execute
+          self
+        end
+
+        # Register a callback for rejection
+        # @param callback [Proc] callback to execute on rejection
+        # @return [Promise] returns self for chaining
+        def catch(&callback)
+          should_execute = false
+          reason_to_use = nil
+
+          @mutex.synchronize do
+            if @state == :rejected
+              # Already rejected, will execute immediately
+              should_execute = true
+              reason_to_use = @reason
+            elsif @state == :pending
+              # Still pending, register callback
+              @catch_callbacks << callback
+            end
+          end
+
+          # Execute outside mutex
+          execute_callback_sync(callback, reason_to_use) if should_execute
+          self
+        end
+
+        # Resolve the promise with a value
+        # @param value [Object] the resolved value
+        def resolve(value)
+          callbacks_to_execute = nil
+
+          @mutex.synchronize do
+            return unless @state == :pending
+
+            @state = :fulfilled
+            @value = value
+
+            # Capture callbacks to execute outside mutex
+            callbacks_to_execute = @then_callbacks.dup
+            @then_callbacks.clear
+            @catch_callbacks.clear
+
+            # Signal waiting threads
+            @condition.broadcast
+          end
+
+          # Execute callbacks outside mutex to avoid deadlocks
+          # Use synchronous execution to maintain order and allow tests to work
+          callbacks_to_execute&.each do |callback|
+            execute_callback_sync(callback, value)
+          end
+        end
+
+        # Reject the promise with a reason
+        # @param reason [Object] the rejection reason
+        def reject(reason)
+          callbacks_to_execute = nil
+
+          @mutex.synchronize do
+            return unless @state == :pending
+
+            @state = :rejected
+            @reason = reason
+
+            # Capture callbacks to execute outside mutex
+            callbacks_to_execute = @catch_callbacks.dup
+            @then_callbacks.clear
+            @catch_callbacks.clear
+
+            # Signal waiting threads
+            @condition.broadcast
+          end
+
+          # Execute callbacks outside mutex to avoid deadlocks
+          # Use synchronous execution to maintain order and allow tests to work
+          callbacks_to_execute&.each do |callback|
+            execute_callback_sync(callback, reason)
+          end
+        end
+
+        # Check if promise is pending
+        def pending?
+          @state == :pending
+        end
+
+        # Check if promise is fulfilled
+        def fulfilled?
+          @state == :fulfilled
+        end
+
+        # Check if promise is rejected
+        def rejected?
+          @state == :rejected
+        end
+
+        # Check if promise is settled (fulfilled or rejected)
+        def settled?
+          !pending?
+        end
+
+        # Wait for promise to settle with optional timeout
+        # @param timeout [Numeric, nil] timeout in seconds
+        # @return [Object] resolved value or raises error
+        def wait(timeout: nil)
+          @mutex.synchronize do
+            # Wait until promise is settled
+            if timeout
+              deadline = Time.now + timeout
+              while pending?
+                remaining = deadline - Time.now
+                if remaining <= 0
+                  raise Timeout::Error, "Promise timed out after #{timeout} seconds"
+                end
+
+                @condition.wait(@mutex, remaining)
+              end
+            else
+              @condition.wait(@mutex) while pending?
+            end
+
+            # Return value or raise error
+            return @value if fulfilled?
+            raise @reason if rejected?
+          end
+        end
+
+        private
+
+        # Execute a callback safely
+        # Note: Executes in background thread to avoid blocking
+        def execute_callback(callback, arg)
+          Thread.new do
+            callback.call(arg)
+          rescue StandardError => e
+            RubyLLM::MCP.logger.error(
+              "Error in promise callback: #{e.message}\n#{e.backtrace.join("\n")}"
+            )
+          end
+        end
+
+        # Execute a callback synchronously (for testing and immediate execution)
+        def execute_callback_sync(callback, arg)
+          callback.call(arg)
+        rescue StandardError => e
+          RubyLLM::MCP.logger.error(
+            "Error in promise callback: #{e.message}\n#{e.backtrace.join("\n")}"
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module MCP
+    module Handlers
+      # Base class for sampling request handlers
+      # Provides access to sample object, guards, and helper methods
+      #
+      # @example Basic sampling handler
+      #   class MySamplingHandler < RubyLLM::MCP::Handlers::SamplingHandler
+      #     def execute
+      #       response = default_chat_completion("gpt-4")
+      #       accept(response)
+      #     end
+      #   end
+      #
+      # @example Sampling handler with guards
+      #   class GuardedSamplingHandler < RubyLLM::MCP::Handlers::SamplingHandler
+      #     allow_models "gpt-4", "claude-3-opus"
+      #
+      #     guard :check_model
+      #     guard :check_token_limit
+      #
+      #     def execute
+      #       response = default_chat_completion(sample.model)
+      #       accept(response)
+      #     end
+      #
+      #     private
+      #
+      #     def check_model
+      #       return true if model_allowed?(sample.model)
+      #       "Model not allowed"
+      #     end
+      #
+      #     def check_token_limit
+      #       return true if sample.max_tokens <= 4000
+      #       "Too many tokens"
+      #     end
+      #   end
+      class SamplingHandler
+        include Concerns::Options
+        include Concerns::Lifecycle
+        include Concerns::Logging
+        include Concerns::ErrorHandling
+        include Concerns::GuardChecks
+        include Concerns::ModelFiltering
+        include Concerns::SamplingActions
+
+        attr_reader :coordinator
+
+        # Initialize sampling handler
+        # @param sample [RubyLLM::MCP::Sample] the sampling request
+        # @param coordinator [Object] the coordinator managing the request
+        # @param options [Hash] handler-specific options
+        def initialize(sample:, coordinator:, **options)
+          @sample = sample
+          @coordinator = coordinator
+          super(**options)
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/mcp/handlers.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module MCP
+    module Handlers
+      # Detect if a handler is a class (vs a block/proc/lambda)
+      # @param handler [Object] the handler to check
+      # @return [Boolean] true if handler is a class
+      def self.handler_class?(handler)
+        handler.is_a?(Class) || (handler.respond_to?(:new) && !handler.respond_to?(:call))
+      end
+    end
+  end
+end

data/lib/ruby_llm/mcp/native/cancellable_operation.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module MCP
+    module Native
+      # Wraps server-initiated requests to support cancellation.
+      # The operation tracks terminal state so cancellation outcomes are explicit.
+      class CancellableOperation
+        attr_reader :request_id, :thread, :state
+
+        def initialize(request_id)
+          @request_id = request_id
+          @state = :pending
+          @mutex = Mutex.new
+          @thread = nil
+          @result = nil
+          @error = nil
+        end
+
+        def cancelled?
+          @mutex.synchronize { %i[cancelling cancelled].include?(@state) }
+        end
+
+        # @return [Symbol] :cancelled, :already_cancelled, :already_completed
+        def cancel
+          thread_to_cancel = nil
+
+          @mutex.synchronize do
+            case @state
+            when :cancelled, :cancelling
+              return :already_cancelled
+            when :completed
+              return :already_completed
+            when :pending
+              @state = :cancelled
+              return :cancelled
+            when :running
+              @state = :cancelling
+              thread_to_cancel = @thread
+            end
+          end
+
+          if thread_to_cancel&.alive?
+            thread_to_cancel.raise(
+              Errors::RequestCancelled.new(
+                message: "Request #{@request_id} was cancelled",
+                request_id: @request_id
+              )
+            )
+          else
+            @mutex.synchronize do
+              @state = :cancelled if @state == :cancelling
+            end
+          end
+
+          :cancelled
+        end
+
+        # Execute a block in a separate thread so cancellation can interrupt execution.
+        # Returns the block result or re-raises non-cancellation exceptions.
+        def execute(&)
+          return nil if cancelled?
+
+          @mutex.synchronize do
+            return nil if %i[cancelled cancelling].include?(@state)
+
+            @state = :running
+          end
+
+          @thread = Thread.new do
+            Thread.current.abort_on_exception = false
+            begin
+              @result = yield
+            rescue Errors::RequestCancelled, StandardError => e
+              @error = e
+            end
+          end
+
+          @thread.join
+          raise @error if @error && !@error.is_a?(Errors::RequestCancelled)
+
+          @result
+        ensure
+          @mutex.synchronize do
+            if @state == :running || @state == :cancelling
+              @state = @error.is_a?(Errors::RequestCancelled) ? :cancelled : :completed
+            end
+            @thread = nil
+          end
+        end
+      end
+    end
+  end
+end