ruby_llm 2.1.0 → 2.2.0

data/lib/ruby_llm/mcp/resource.rb

@@ -14,6 +14,7 @@ module RubyLLM
     # their content is needed.
     class Resource
       include Support::Inspectable
+      include Files::Saving
 
       # The URI that identifies the resource on its server.
       attr_reader :uri
@@ -61,17 +62,19 @@ module RubyLLM
         content.b
       end
 
+      ##
+      # :method: save
+      # :call-seq:
+      #   save(path)
+      #
       # Writes the content to +path+, expanding it first. Returns +path+.
-      def save(path)
-        File.binwrite(File.expand_path(path), to_blob)
-        path
-      end
 
       # Returns the resource as an Attachment, which is how chats take it
-      # through +with:+.
+      # through +with:+. The attachment has the MIME type the server reports
+      # when the URI has no file extension.
       def to_attachment
         filename = Content.filename(uri)
-        Attachment.new(StringIO.new(to_blob), filename: filename.empty? ? name : filename)
+        Content.file(to_blob, mime_type, filename.empty? ? name : filename)
       end
 
       private

data/lib/ruby_llm/mcp/resource_template.rb

@@ -56,9 +56,10 @@ module RubyLLM
       def self.expand_variable(spec, operator, separator, reserved, variables) # :nodoc:
         explode = spec.end_with?('*')
         name, length = spec.delete_suffix('*').split(':')
-        return unless variables.key?(name)
+        values = Array(variables[name])
+        return if values.empty?
 
-        parts = Array(variables[name]).map { |part| encode(length ? part.to_s[0, length.to_i] : part.to_s, reserved) }
+        parts = values.map { |part| encode(length ? part.to_s[0, length.to_i] : part.to_s, reserved) }
         named = NAMED_OPERATORS.include?(operator)
         return parts.map { |part| named ? "#{name}=#{part}" : part }.join(separator) if explode
 

data/lib/ruby_llm/mcp/session_expired.rb

@@ -4,7 +4,15 @@ module RubyLLM
   class MCP
     # Raised by a transport when the session of a server that predates
     # 2026-07-28 has ended, so the client starts a new one: the server
-    # answered 404, or its stdio process exited.
-    class SessionExpired < Error; end # :nodoc:
+    # answered 404, or its stdio process exited. +session+ is the session
+    # that ended, as the transport's +session+ reader returned it.
+    class SessionExpired < Error # :nodoc:
+      attr_reader :session
+
+      def initialize(message = nil, session: nil, **)
+        @session = session
+        super(message, **)
+      end
+    end
   end
 end

data/lib/ruby_llm/mcp/stdio.rb

@@ -12,6 +12,11 @@ module RubyLLM
     # time. Its stderr is the parent's. A server that predates 2026-07-28
     # keeps its session for the life of its process, so after a restart its
     # requests raise SessionExpired until the client initializes it again.
+    # The process inherits only INHERITED_ENV from the application, and +env+
+    # adds to and overrides those: a Hash, or a callable that returns one,
+    # called each time the process starts. Where the platform has process
+    # groups the server leads its own, so stopping it reaches the processes
+    # it started.
     #
     # Subscriptions share the channel, so whichever thread reads a message
     # that belongs to one hands it to the subscription's listener: a
@@ -19,9 +24,20 @@ module RubyLLM
     # request reads. A listener stops when CancelledError is raised in its
     # thread, so it reads and writes with that deferred.
     class Stdio # :nodoc:
+      # Raised when the server's process exits or does not answer in time.
+      class Unavailable < Error # :nodoc:
+      end
+
       SHUTDOWN_GRACE = 2
+      SHUTDOWN_CHECK = 0.05
       CHECK_INTERVAL = 0.5
       SUBSCRIPTION_ID = 'io.modelcontextprotocol/subscriptionId'
+      INHERITED_ENV = %w[
+        GEM_HOME GEM_PATH HOME LANG LC_ALL LC_CTYPE LOGNAME PATH SHELL TERM TMPDIR USER
+        APPDATA COMSPEC HOMEDRIVE HOMEPATH LOCALAPPDATA PATHEXT PROCESSOR_ARCHITECTURE
+        PROGRAMDATA PROGRAMFILES PROGRAMFILES(X86) PROGRAMW6432 SYSTEMDRIVE SYSTEMROOT
+        TEMP TMP USERNAME USERPROFILE WINDIR
+      ].freeze
 
       # The messages of the subscription opened by request +id+, or with no
       # +id+, the changes a server that predates subscriptions announces.
@@ -39,9 +55,12 @@ module RubyLLM
         end
       end
 
+      # The session of a server that predates 2026-07-28: the process it was initialized in, or +nil+.
+      attr_reader :session
+
       def initialize(command, env: {}, directory: nil, timeout: nil, config: RubyLLM.config)
         @command = Array(command).map(&:to_s)
-        @env = env.to_h { |key, value| [key.to_s, value.to_s] }
+        @env = env
         @directory = directory&.to_s
         @timeout = timeout || config.request_timeout
         @lock = Mutex.new
@@ -76,12 +95,10 @@ module RubyLLM
 
             yield reply
           end
-          raise Error, "#{name} exited" unless @process.equal?(process)
+          raise Unavailable, "#{name} exited" unless @process.equal?(process)
 
           receive(subscription)
         end
-      rescue IOError
-        raise Error, "#{name} exited"
       ensure
         uninterrupted { @lock.synchronize { @subscriptions.delete(subscription) } }
       end
@@ -95,11 +112,11 @@ module RubyLLM
       def check_session(version)
         return if version.nil? || version == Client::VERSION || (@process&.alive? && @process.equal?(@session))
 
-        raise SessionExpired, "#{name} exited"
+        raise SessionExpired.new("#{name} exited", session: @session)
       end
 
       def subscribe(subscription, message)
-        raise Error, "#{name} exited" unless message || @process&.alive?
+        raise Unavailable, "#{name} exited" unless message || @process&.alive?
 
         @subscriptions << subscription
         write(message) if message
@@ -120,6 +137,8 @@ module RubyLLM
         return sleep(CHECK_INTERVAL) unless read
 
         @stdout.wait_readable(CHECK_INTERVAL) if subscription.messages.empty?
+      rescue IOError
+        raise Unavailable, "#{name} exited"
       end
 
       def drain
@@ -164,11 +183,13 @@ module RubyLLM
 
       def write(message)
         start unless @process&.alive?
-        @stdin.puts JSON.generate(message)
-        @stdin.flush
-      rescue Errno::EPIPE, IOError
-        stop
-        raise Error, "#{name} exited"
+        begin
+          @stdin.puts JSON.generate(message)
+          @stdin.flush
+        rescue Errno::EPIPE, IOError
+          stop
+          raise Unavailable, "#{name} exited"
+        end
       end
 
       def read(deadline)
@@ -194,7 +215,7 @@ module RubyLLM
           return line if line
 
           remaining = deadline - monotonic_now
-          raise Error, "#{name} did not answer in time" unless remaining.positive?
+          raise Unavailable, "#{name} did not answer in time" unless remaining.positive?
 
           Support::Cancellation.check
           next unless @stdout.wait_readable([remaining, CHECK_INTERVAL].min)
@@ -209,7 +230,7 @@ module RubyLLM
 
       def exited
         stop
-        raise Error, "#{name} exited"
+        raise Unavailable, "#{name} exited"
       end
 
       def answer(request)
@@ -218,26 +239,53 @@ module RubyLLM
 
       def start
         options = @directory ? { chdir: @directory } : {}
-        @stdin, @stdout, @process = Open3.popen2(@env, *@command, **options)
+        options[:pgroup] = true if groups?
+        env = ENV.slice(*INHERITED_ENV).merge(environment)
+        @stdin, @stdout, @process = Open3.popen2(env, *@command, unsetenv_others: true, **options)
         @buffer = +''
       end
 
+      def environment
+        variables = @env.respond_to?(:call) ? @env.call : @env
+        variables.to_h { |key, value| [key.to_s, value.to_s] }
+      end
+
       def stop
         return unless @process
 
         @stdin.close unless @stdin.closed?
         @stdout.close unless @stdout.closed?
-        terminate unless @process.join(SHUTDOWN_GRACE)
+        @process.join(SHUTDOWN_GRACE)
+        terminate if groups? || @process.alive?
         @process = nil
       end
 
       def terminate
-        Process.kill('TERM', @process.pid)
-        Process.kill('KILL', @process.pid) unless @process.join(SHUTDOWN_GRACE)
-      rescue Errno::ESRCH
+        signal('TERM')
+        signal('KILL') unless exited?
+      rescue Errno::ESRCH, Errno::EPERM
         nil
       end
 
+      def exited?
+        deadline = monotonic_now + SHUTDOWN_GRACE
+        while monotonic_now < deadline
+          signal(0)
+          sleep SHUTDOWN_CHECK
+        end
+        false
+      rescue Errno::ESRCH, Errno::EPERM
+        true
+      end
+
+      def signal(signal)
+        Process.kill(signal, groups? ? -@process.pid : @process.pid)
+      end
+
+      def groups?
+        !Gem.win_platform?
+      end
+
       def name
         File.basename(@command.first.to_s)
       end

data/lib/ruby_llm/mcp/task.rb

@@ -18,30 +18,22 @@ module RubyLLM
     #   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
-
+    class Task < RubyLLM::Task
       # 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:
+      attr_reader :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:
+        super(tool_call:)
         @mcp = mcp
         @data = data
         @id = data['taskId']
         @answered = Array(answered)
-        @tool_call = tool_call
       end
 
       # The task's state: +:working+, +:input_required+, +:completed+,
@@ -68,43 +60,23 @@ module RubyLLM
         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
+      # Returns the MCP::Result once the task #succeeded?, 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?
+        Result.new(data['result']) if succeeded?
       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?.
+      # the task is #complete? and how soon to check again. Does nothing once
+      # the task is #complete?.
       def refresh
-        @data = connected.poll_task(id) unless done?
+        @data = connected.poll_task(id) unless complete?
         self
       end
 
-      # Checks on the task until it is #done?, sleeping #poll_interval
+      # Checks on the task until it is #complete?, 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
@@ -119,14 +91,15 @@ module RubyLLM
       # 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?
+        connected.cancel_task(id) unless complete?
         self
       end
 
       def error # :nodoc:
         details = data['error'] || {}
-        Error.new(details['message'] || status_message || "Task #{id} was #{status}",
-                  code: details['code'], data: details['data'])
+        reported = details['message'] || status_message
+        Error.new(("Task #{id} was #{status}" unless reported), provider_message: reported,
+                                                                code: details['code'], data: details['data'])
       end
 
       def record_answers(keys) # :nodoc:

data/lib/ruby_llm/mcp/tool.rb

@@ -45,6 +45,11 @@ module RubyLLM
 
       attr_reader :fixed_arguments, :wrap # :nodoc:
 
+      # The fixed arguments, with lambdas called on the MCP instance.
+      def resolved_fixed_arguments # :nodoc:
+        fixed_arguments.transform_values { |value| value.is_a?(Proc) ? @mcp.instance_exec(&value) : value }
+      end
+
       def initialize(mcp, definition, prefix: nil, as: nil, description: nil, fixed_arguments: {}, wrap: nil) # :nodoc:
         super()
         @mcp = mcp
@@ -53,7 +58,7 @@ module RubyLLM
         @description = description || definition['description']
         @fixed_arguments = fixed_arguments.transform_keys(&:to_sym)
         @wrap = wrap
-        @annotations = definition['annotations'] || {}
+        @annotations = definition['annotations'].is_a?(Hash) ? definition['annotations'] : {}
         @meta = definition['_meta'] || {}
         @ui_uri = Apps.uri(meta)
         @visibility = Apps.visibility(meta)
@@ -73,7 +78,8 @@ module RubyLLM
       end
 
       # Returns whether calling the tool again with the same arguments has
-      # no further effect.
+      # no further effect. Only these calls are sent again when a stream
+      # breaks before the answer.
       def idempotent?
         @annotations['idempotentHint'] == true
       end
@@ -85,32 +91,49 @@ module RubyLLM
 
       # Returns whether the tool pauses for approval, as declared with
       # MCP.requires_approval.
-      def requires_approval?
+      def requires_approval?(_tool_call = nil)
         @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.
+      # failed, or when the server failed the call: it could not be
+      # reached, answered HTTP 429 or a 5xx status, or answered with a
+      # JSON-RPC error. A server that could not be reached sits out the
+      # chat's next requests, as when listing its tools. A refusal, such as
+      # missing credentials, still raises. A tool with a UI returns its
+      # failed MCP::Result instead, so your app can still render the UI. 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:)
+      # Resumes a call that paused on +task+, which it checks on once.
+      def resume(task, **arguments)
+        @mcp.run(self, arguments, input: task.to_h)
       end
 
       # Returns the MCP::Task a call paused on, from its saved state.
-      def task(state, tool_call: nil) # :nodoc:
+      def task(state, tool_call: nil)
         Task.load(@mcp, state, tool_call:)
       end
 
+      def resume_call(state, arguments, **) # :nodoc:
+        @mcp.run(self, arguments, input: state)
+      end
+
+      # Runs the handler the MCP class declares for +exception+, or else
+      # one declared on this class.
+      def rescue_with_handler(exception) # :nodoc:
+        return super unless @mcp.class.rescue_handler_for(exception)
+
+        @mcp.rescue_with_handler(exception)
+      end
+
       private
 
       def model_schema(schema)