ruby_llm 2.0.0 → 2.1.0

data/lib/ruby_llm/mcp/task.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  class MCP
+    # A tool call that an MCP server runs in the background, as the Tasks
+    # extension describes. Declare MCP.extension :tasks, and a server may
+    # answer a long call with a task instead of a result.
+    #
+    # A chat never waits for a task. It pauses the tool call, and
+    # Chat#pending_tasks returns the tasks it waits on. #refresh checks on
+    # a task once; Chat#complete checks on every one again and resumes the
+    # chat once they are done:
+    #
+    #   task = chat.pending_tasks.first
+    #   task.refresh
+    #   task.status         # => :working
+    #   task.status_message # => "Rendering page 3 of 12"
+    #   task.poll_interval  # => 5.0
+    #
+    # MCP#call waits for the task of a tool you call directly.
+    class Task
+      include Support::Inspectable
+
+      DONE = %i[completed failed cancelled].freeze
+      private_constant :DONE
+
+      # The task's id on its server.
+      attr_reader :id
+
+      # The ToolCall paused on the task, when it came from a chat.
+      attr_reader :tool_call
+
+      attr_reader :data, :answered # :nodoc:
+
+      def self.load(mcp, state, tool_call: nil) # :nodoc:
+        new(mcp, state['task'], answered: state['answered'], tool_call:)
+      end
+
+      def initialize(mcp, data, answered: nil, tool_call: nil) # :nodoc:
+        @mcp = mcp
+        @data = data
+        @id = data['taskId']
+        @answered = Array(answered)
+        @tool_call = tool_call
+      end
+
+      # The task's state: +:working+, +:input_required+, +:completed+,
+      # +:failed+, or +:cancelled+.
+      def status
+        data['status'].to_sym
+      end
+
+      # What the server says about the task's state, such as how far it
+      # got, or +nil+.
+      def status_message
+        data['statusMessage']
+      end
+
+      # How many seconds the server asks you to wait before checking on the
+      # task again, or +nil+.
+      def poll_interval
+        data['pollIntervalMs'] / 1000.0 if data['pollIntervalMs']
+      end
+
+      # When the server may forget the task, as a Time, or +nil+ when it
+      # keeps the task for good.
+      def expires_at
+        Time.iso8601(data['createdAt']) + (data['ttlMs'] / 1000.0) if data['ttlMs'] && data['createdAt']
+      end
+
+      # Returns +true+ once the task completed, failed, or was cancelled.
+      def done?
+        DONE.include?(status)
+      end
+
+      # Returns +true+ when the task finished with a #result.
+      def completed?
+        status == :completed
+      end
+
+      # Returns +true+ when the task failed with an error.
+      def failed?
+        status == :failed
+      end
+
+      # Returns +true+ when the task was cancelled before it finished.
+      def cancelled?
+        status == :cancelled
+      end
+
+      # Returns the MCP::Result once the task #completed?, and +nil+ until
+      # then. Raises MCP::Error when the task failed or was cancelled.
+      def result
+        raise error if failed? || cancelled?
+
+        Result.new(data['result']) if completed?
+      end
+
+      # Checks on the task once and returns +self+, which now tells whether
+      # the task is #done? and how soon to check again. Does nothing once
+      # the task is #done?.
+      def refresh
+        @data = connected.poll_task(id) unless done?
+        self
+      end
+
+      # Checks on the task until it is #done?, sleeping #poll_interval
+      # seconds in between, and returns +self+. Answers the server's
+      # requests for input with MCP.before_input_request callbacks.
+      # +timeout+ defaults to the server's MCP.timeout, and the task is
+      # cancelled when it runs out or the chat is cancelled.
+      #
+      # Raises MCP::Error when the task fails or the time runs out, and
+      # MCP::InputRequiredError when no callback answers a request.
+      def wait(timeout: nil, interval: nil)
+        connected.await_task(self, timeout:, interval:)
+      end
+
+      # Asks the server to cancel the task, and returns +self+. The server
+      # may still finish it, so check with #refresh.
+      def cancel
+        connected.cancel_task(id) unless done?
+        self
+      end
+
+      def error # :nodoc:
+        details = data['error'] || {}
+        Error.new(details['message'] || status_message || "Task #{id} was #{status}",
+                  code: details['code'], data: details['data'])
+      end
+
+      def record_answers(keys) # :nodoc:
+        @answered |= keys
+      end
+
+      def to_h # :nodoc:
+        { 'task' => data, 'answered' => (answered unless answered.empty?) }.compact
+      end
+
+      private
+
+      def connected
+        @mcp or raise ConfigurationError, "Connect the MCP that runs task #{id} with with_mcp to reach it"
+      end
+
+      def inspect_attributes
+        { id:, status:, status_message: }
+      end
+    end
+  end
+end

data/lib/ruby_llm/mcp/tool.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  class MCP
+    # A tool offered by an MCP server. It works anywhere a Tool does: a
+    # chat renders its name, description, and schema for the model, and
+    # calling it calls the server.
+    #
+    #   tool = linear.tools.first
+    #   tool.read_only?  # => true
+    #   chat.with_tools(tool)
+    #
+    # The behavior predicates read the server's annotations. They are hints
+    # from the server, so trust them only as far as you trust the server.
+    class Tool < RubyLLM::Tool
+      include Support::Inspectable
+
+      # The name the model calls this tool by.
+      attr_reader :name
+
+      # The description the model sees.
+      attr_reader :description
+
+      # The JSON Schema for the arguments the model provides.
+      attr_reader :parameters_schema
+
+      # The tool's name on the server.
+      attr_reader :server_name
+
+      # The tool's +_meta+ as the server sent it: a Hash with String keys,
+      # empty when there is none. Extensions keep their own vocabulary
+      # there.
+      attr_reader :meta
+
+      # The URI of the tool's UI, the +ui://+ resource an MCP App renders
+      # next to the tool's results, or +nil+ for a tool without one. Read
+      # it with MCP#resource.
+      attr_reader :ui_uri
+
+      # Who may call the tool, as Symbols: +:model+ when chats offer it to
+      # the model, +:app+ when a UI from the same server may call it. Tools
+      # say nothing about it unless they belong to an MCP App, which makes
+      # them <tt>[:model, :app]</tt>.
+      attr_reader :visibility
+
+      attr_reader :fixed_arguments, :wrap # :nodoc:
+
+      def initialize(mcp, definition, prefix: nil, as: nil, description: nil, fixed_arguments: {}, wrap: nil) # :nodoc:
+        super()
+        @mcp = mcp
+        @server_name = definition['name']
+        @name = (as || [prefix, server_name].compact.join('_')).to_s
+        @description = description || definition['description']
+        @fixed_arguments = fixed_arguments.transform_keys(&:to_sym)
+        @wrap = wrap
+        @annotations = definition['annotations'] || {}
+        @meta = definition['_meta'] || {}
+        @ui_uri = Apps.uri(meta)
+        @visibility = Apps.visibility(meta)
+        @parameters_schema = model_schema(definition['inputSchema'] || {})
+      end
+
+      # Returns whether the server says the tool only reads.
+      def read_only?
+        @annotations['readOnlyHint'] == true
+      end
+
+      # Returns whether the tool may destroy or overwrite data. Tools that
+      # are not read-only count as destructive unless the server says
+      # otherwise.
+      def destructive?
+        !read_only? && @annotations['destructiveHint'] != false
+      end
+
+      # Returns whether calling the tool again with the same arguments has
+      # no further effect.
+      def idempotent?
+        @annotations['idempotentHint'] == true
+      end
+
+      # Returns whether the tool reaches beyond the server, such as the web.
+      def open_world?
+        @annotations['openWorldHint'] != false
+      end
+
+      # Returns whether the tool pauses for approval, as declared with
+      # MCP.requires_approval.
+      def requires_approval?
+        @mcp.requires_approval?(self)
+      end
+
+      # Calls the tool on the server and returns its MCP::Result, what the
+      # +wrap:+ method made of it, or <tt>{ error: }</tt> when the tool
+      # failed. A chat sends the model the result's content. When the
+      # server runs the call as a task, returns the MCP::Task without
+      # waiting, and a chat pauses the tool call until the task is done.
+      # Raises MCP::InputRequiredError when the server needs input that no
+      # MCP.before_input_request callback gave.
+      def call(**arguments)
+        @mcp.run(self, arguments.except(:tool_call))
+      end
+
+      # Resumes a call that paused on input requests, now answered, or on a
+      # task, which it checks on once.
+      def resume(input, arguments) # :nodoc:
+        @mcp.run(self, arguments, input:)
+      end
+
+      # Returns the MCP::Task a call paused on, from its saved state.
+      def task(state, tool_call: nil) # :nodoc:
+        Task.load(@mcp, state, tool_call:)
+      end
+
+      private
+
+      def model_schema(schema)
+        schema = SchemaDefinition.new(schema:).json_schema
+        return schema if fixed_arguments.empty? || !schema.key?('properties')
+
+        hidden = fixed_arguments.keys.map(&:to_s)
+        schema.merge('properties' => schema['properties'].except(*hidden),
+                     'required' => Array(schema['required']) - hidden)
+      end
+
+      def inspect_attributes
+        { name:, from: (server_name unless server_name == name), read_only: read_only? || nil }
+      end
+    end
+  end
+end