ruby_llm 2.0.0 → 2.1.0

data/lib/ruby_llm/chat.rb

@@ -24,11 +24,14 @@ module RubyLLM
   class Chat # rubocop:disable Metrics/ClassLength
     include Enumerable
     include Support::Inspectable
+    include ToolSearch
 
     # The provider-neutral options #with_compaction accepts.
     COMPACTION_OPTIONS = %i[at instructions pause_after].freeze
     THINKING_OPTIONS = %i[effort budget display].freeze
-    private_constant :THINKING_OPTIONS
+    PAUSED = Object.new.freeze
+    UNFINISHED_TOOL_RESULT = { error: 'The tool call did not finish.' }.to_json.freeze
+    private_constant :THINKING_OPTIONS, :PAUSED, :UNFINISHED_TOOL_RESULT
 
     # The Model the chat sends requests to.
     attr_reader :model
@@ -39,8 +42,9 @@ module RubyLLM
     # The Message objects exchanged so far, including system instructions.
     attr_reader :messages
 
-    # The registered tools, as a Hash of tool name Symbols to Tool instances.
-    attr_reader :tools
+    # The MCP servers connected with #with_mcp, readable by name:
+    # <tt>chat.mcp.linear</tt>.
+    attr_reader :mcp
 
     # The provider tools enabled with #with_provider_tools, as an array of
     # normalized entry Hashes.
@@ -119,6 +123,9 @@ module RubyLLM
       @messages = []
       @usage_entries = []
       @tools = {}
+      @mcp = MCP::Collection.new
+      @tool_deferrals = {}
+      @mcp_deferrals = {}
       @provider_tools = []
       @tool_prefs = { choice: nil, calls: nil }
       @concurrency = normalize_tool_concurrency(@config.tool_concurrency)
@@ -133,16 +140,21 @@ module RubyLLM
       @fallbacks = []
       @fallback_errors = Fallback::DEFAULT_ERRORS
       @callbacks = Hash.new { |callbacks, name| callbacks[name] = [] }
+      @attachment_replacements = {}.compare_by_identity
       @cancelled = false
       @cancellation_checker = nil
       @tool_call_decisions = {}
       @approval_checker = nil
+      @tool_call_inputs = {}
+      @input_checker = nil
+      @input_recorder = nil
     end
 
     # Adds +message+ as a user message and runs the conversation loop,
     # executing tools until the model answers or a call needs approval.
-    # Returns the latest assistant Message; check #awaiting_approval? before
-    # treating it as a final answer. Attach files with +with:+.
+    # Returns the latest assistant Message; check #waiting? before
+    # treating it as a final answer. Attach files with +with:+. An
+    # MCP::Prompt adds its messages instead.
     # A given block receives streamed Chunk objects as they arrive.
     #
     # String attachments read local paths or fetch URLs. Only pass trusted,
@@ -153,6 +165,7 @@ module RubyLLM
     #   chat.ask "What's in this image?", with: "ruby_conf.jpg"
     #   chat.ask "Analyze these files", with: ["diagram.png", "report.pdf"]
     #   chat.ask("Tell me a story") { |chunk| print chunk.content }
+    #   chat.ask github.prompt(:code_review, code: diff)
     #
     def ask(message = nil, with: nil, &)
       ask_later(message, with: with)
@@ -174,7 +187,11 @@ module RubyLLM
     # decisions for calls that require approval.
     def ask_later(message = nil, with: nil)
       raise_if_pending_tool_calls!
-      add_message role: :user, content: message, attachments: with
+      if message.is_a?(MCP::Prompt)
+        message.messages.each { |prompt_message| add_message(prompt_message) }
+      else
+        add_message role: :user, content: message, attachments: with
+      end
       self
     end
 
@@ -198,20 +215,24 @@ module RubyLLM
     # was declared with Tool.requires_approval only execute once #approve
     # records a decision; denied calls receive a structured denial result,
     # and undecided calls stay pending. Does nothing when no tool calls
-    # are pending. The chat is then ready for the next #generate, or the
-    # next batch round. Returns +self+.
+    # are pending. Calls paused on an MCP::Task check on it once. The chat
+    # is then ready for the next #generate, or the next batch round.
+    # Returns +self+.
     def run_tools
       raise_if_cancelled!
 
       message = pending_tool_response
       execute_pending_tool_calls(message) if message
       self
+    rescue CancelledError
+      cancel_tasks
+      raise
     end
 
     # Advances the conversation by one move: runs the pending tool calls
     # if any are unanswered, otherwise generates the next response.
     # Returns the Message that move produced, and +nil+ once there is
-    # nothing left to do or the loop is parked on an approval.
+    # nothing left to do or the chat is #waiting?.
     def step(&)
       return if complete?
 
@@ -221,23 +242,32 @@ module RubyLLM
       before = messages.length
       run_tools
       messages.last if messages.length > before
+    rescue CancelledError
+      cancel_tasks
+      raise
     end
 
-    # Runs the conversation loop until #complete? or #awaiting_approval?
-    # is +true+. Returns the last conversation Message, or +nil+ for an
-    # empty chat. Used after #ask_later; #ask calls #complete for you.
+    # Runs the conversation loop until #complete? or #waiting? is +true+.
+    # Returns the last conversation Message, or +nil+ for an empty chat.
+    # Used after #ask_later; #ask calls #complete for you.
     #
     # When a pending tool call requires approval and no decision has been
-    # recorded, the loop pauses. Record #approve or #deny decisions, then
-    # call #complete again to continue.
+    # recorded, or waits on input for an MCP server, the loop pauses.
+    # Record #approve, #deny, #answer, or #decline decisions, then call
+    # #complete again to continue. A tool call that waits on an MCP::Task
+    # pauses the loop too, and each #complete checks on the task once,
+    # without waiting, and continues once it is done.
     def complete(&)
-      step(&) until complete? || awaiting_approval?
+      run_tools if awaiting_tasks?
+      step(&) until complete? || waiting?
       last_non_system_message || messages.last
     end
 
     # Returns whether the chat has no pending response or tool execution:
     # nothing is staged, or the model answered without requesting tools.
     def complete?
+      return false if pending_tool_response
+
       last = last_non_system_message
       case last&.role
       when nil then true
@@ -266,9 +296,27 @@ module RubyLLM
       record_tool_call_decision(tool_call, false)
     end
 
+    # Returns whether the conversation can't continue until something
+    # outside it happens: every remaining pending tool call waits on an
+    # approval decision, an answer to an MCP input request, or an MCP task.
+    # #complete stops here, and #awaiting_approval?, #awaiting_input?, and
+    # #awaiting_tasks? tell what it waits on. Stop a loop you drive with
+    # #step here too:
+    #
+    #   chat.step until chat.complete? || chat.waiting?
+    #
+    def waiting?
+      response = pending_tool_response
+      return false unless response
+
+      pending = pending_tool_calls(response).values
+      pending.any? && pending.all? { |tool_call| approval_pending?(tool_call) || paused?(tool_call) }
+    end
+
     # Returns whether the conversation can make no progress without an
     # approval decision: every remaining pending tool call requires
-    # approval and has none recorded. While +true+, #complete returns
+    # approval and has none recorded, or waits on input. While +true+,
+    # #complete returns
     # without executing them; record decisions with #approve or #deny,
     # then call #complete again. Tool calls that need no approval still
     # execute before the loop pauses.
@@ -276,11 +324,7 @@ module RubyLLM
     # Consults each pending tool's approval resolver when one is declared,
     # so resolvers must be idempotent reads.
     def awaiting_approval?
-      response = pending_tool_response
-      return false unless response
-
-      pending = pending_tool_calls(response)
-      pending.any? && pending.all? { |_, tool_call| approval_pending?(tool_call) }
+      waiting? && pending_approvals.any?
     end
 
     # Returns the tool calls from the latest response that require approval
@@ -297,9 +341,80 @@ module RubyLLM
       pending_tool_calls(response).values.select { |tool_call| approval_pending?(tool_call) }
     end
 
+    # Returns whether the conversation can make no progress until the user
+    # answers an MCP server: every remaining pending tool call waits on
+    # input or an approval decision, and at least one waits on input.
+    def awaiting_input?
+      waiting? && pending_inputs.any?
+    end
+
+    # Returns the unanswered requests for input that paused MCP tool calls,
+    # as MCP::InputRequest objects. Settle each with #answer or #decline,
+    # then call #complete to resume the calls.
+    #
+    #   chat.pending_inputs.each { |request| puts request.message }
+    #   chat.answer(chat.pending_inputs.first, environment: "staging")
+    #
+    def pending_inputs
+      response = pending_tool_response
+      return [] unless response
+
+      pending_tool_calls(response).values.flat_map do |tool_call|
+        Array(tool_call_input(tool_call)&.[]('requests'))
+          .map { |data| MCP::InputRequest.from_h(data, tool_call:) }
+          .reject(&:answered?)
+      end
+    end
+
+    # Returns whether the conversation can make no progress until MCP
+    # servers finish tasks: every remaining pending tool call waits on a
+    # task, input, or an approval decision, and at least one waits on a
+    # task. #complete checks on the tasks again.
+    #
+    #   chat.ask "Render the quarterly report"
+    #   chat.awaiting_tasks?  # => true
+    #   sleep chat.pending_tasks.first.poll_interval
+    #   chat.complete
+    #
+    def awaiting_tasks?
+      waiting? && pending_tasks.any?
+    end
+
+    # Returns the MCP::Task objects that MCP tool calls wait on, as they
+    # were when the chat last checked. MCP::Task#refresh checks on one
+    # without resuming the chat; #complete checks on all of them and
+    # resumes their calls once they are done.
+    #
+    #   chat.pending_tasks.each { |task| puts "#{task.tool_call.name}: #{task.status_message}" }
+    #
+    def pending_tasks
+      response = pending_tool_response
+      return [] unless response
+
+      pending_tool_calls(response).values.filter_map do |tool_call|
+        state = tool_call_input(tool_call)
+        task_for(tool_call, state) if state&.key?('task') && !unanswered?(state)
+      end
+    end
+
+    # Answers +request+, an MCP::InputRequest from #pending_inputs, with
+    # +values+ for a form, or none to accept a URL request. The next
+    # #complete resumes the call once its requests are settled. Returns
+    # +self+.
+    def answer(request, **values)
+      settle_input(request) { |pending| pending.answer(**values) }
+    end
+
+    # Declines +request+, an MCP::InputRequest from #pending_inputs.
+    # Returns +self+.
+    def decline(request)
+      settle_input(request, &:decline)
+    end
+
     # Cancels the current in-flight chat operation. The next cancellation
     # checkpoint raises CancelledError and clears the flag so the chat can be
-    # reused.
+    # reused. The MCP tasks that pending tool calls wait on are cancelled
+    # then too; see #pending_tasks.
     def cancel
       @cancelled = true
       self
@@ -313,17 +428,21 @@ module RubyLLM
     # Sets the system instructions for the conversation, replacing any
     # existing system messages. With <tt>append: true</tt> the instructions
     # are added alongside the existing ones. With <tt>cache_until_here:
-    # true</tt> the instruction becomes an explicit prompt cache boundary.
-    # Pass +nil+ to remove all system instructions. Returns +self+.
+    # true</tt> the instruction becomes an explicit prompt cache boundary;
+    # pass <tt>cache_until_here: { ttl: "1h" }</tt> to give that boundary its
+    # own lifetime, as Message#cache_until_here describes. Pass +nil+ to
+    # remove all system instructions. Returns +self+.
     #
     #   chat.with_instructions "You are a helpful Ruby tutor."
     #   chat.with_instructions "Use exactly one short paragraph.", append: true
+    #   chat.with_instructions policy, cache_until_here: { ttl: "1h" }
     #   chat.with_instructions nil
     #
     def with_instructions(instructions, append: false, cache_until_here: false)
+      boundary = Message.cache_boundary_options(cache_until_here) if cache_until_here
       @messages.reject! { |message| message.role == :system } unless append
       @messages << Message.new(role: :system, content: instructions) unless instructions.nil?
-      @messages.last.cache_until_here if instructions && cache_until_here
+      @messages.last.cache_until_here(**boundary) if instructions && boundary
       self
     end
 
@@ -334,15 +453,84 @@ module RubyLLM
     #   chat.with_tools(Weather, Search)
     #   chat.with_tools(Weather).with_tool_options(choice: :required)
     #
+    # Pass <tt>defer: true</tt> to keep the tools' definitions out of the
+    # model's context until the provider's tool search loads the ones it
+    # needs, or <tt>defer: false</tt> to offer a tool declared with
+    # Tool.defer up front. See #deferred_tools.
+    #
+    #   chat.with_tools(*Catalog.tools, defer: true)
+    #
     # To replace the registered tools, clear them first:
     #
     #   chat.with_tools(nil).with_tools(NewTool)
     #
-    def with_tools(*tools)
-      @tools.clear if tools == [nil]
+    def with_tools(*tools, defer: nil)
+      if tools == [nil]
+        @tools.clear
+        @tool_deferrals.clear
+      end
       tools.flatten.compact.each do |tool|
-        tool_instance = tool.is_a?(Class) ? tool.new : tool
-        @tools[tool_instance.name.to_sym] = tool_instance
+        tool = tool.new if tool.is_a?(Class)
+        name = tool.name.to_sym
+        @tools[name] = tool
+        @tool_deferrals[name] = defer.nil? ? tool.class.deferred? : defer
+      end
+      self
+    end
+
+    # Returns the tools the model can call, as a Hash of tool name Symbols
+    # to Tool instances: those registered with #with_tools and those of the
+    # MCP servers connected with #with_mcp. MCP tools that only the UI of
+    # an MCP App may call are left out; see MCP::Tool#visibility.
+    #
+    # Raises ArgumentError when two tools share a name.
+    def tools
+      offered = @tools.reject { |_, tool| hidden_from_model?(tool) }
+      mcp.flat_map(&:tools).each_with_object(offered) do |tool, tools|
+        next if hidden_from_model?(tool)
+
+        name = tool.name.to_sym
+        raise ArgumentError, "Two tools are named #{name}. Rename one with `tool :#{name}, as:`" if tools.key?(name)
+
+        tools[name] = tool
+      end
+    end
+
+    # Returns the tools whose definitions stay out of the model's context
+    # until the provider's tool search loads them, as a Hash like #tools.
+    # Providers without tool search receive them as ordinary tools.
+    #
+    #   chat.with_tools(Weather).with_mcp(GitHub, defer: true)
+    #   chat.deferred_tools.keys # => [:search_issues, :create_issue, ...]
+    #
+    def deferred_tools
+      tools.slice(*deferred_tool_names)
+    end
+
+    # Connects MCP servers, each an MCP instance or class, and gives the
+    # model their tools. The servers are contacted when the chat first
+    # needs their tools. Pass +nil+ to disconnect them all. Returns +self+.
+    #
+    #   chat.with_mcp(Linear.new(user: current_user), Files)
+    #   chat.mcp.linear
+    #
+    # Pass <tt>defer: true</tt> to keep every tool of these servers out of
+    # the model's context until the provider's tool search loads it, or
+    # <tt>defer: false</tt> to offer them up front despite MCP.defer. See
+    # #deferred_tools.
+    #
+    #   chat.with_mcp(GitHub, defer: true)
+    #
+    def with_mcp(*servers, defer: nil)
+      if servers == [nil]
+        @mcp = MCP::Collection.new
+        @mcp_deferrals.clear
+      else
+        servers.flatten.compact.each do |server|
+          server = server.new if server.is_a?(Class)
+          @mcp << server
+          @mcp_deferrals[server.name.to_sym] = defer
+        end
       end
       self
     end
@@ -686,6 +874,23 @@ module RubyLLM
       add_callback(:after_tool_result, &)
     end
 
+    # Registers a callback that receives the ToolCall and a Progress each
+    # time a running local tool reports what it is doing, with
+    # Tool#progress or, for MCP tools, through the server's progress
+    # notifications. Returns +self+.
+    #
+    #   chat.after_tool_progress do |tool_call, progress|
+    #     puts "#{tool_call.name}: #{progress.message}"
+    #   end
+    #
+    # The callback runs in the thread or fiber that reports, before the
+    # tool's result. On Ruby 3.2 and later, that includes threads and
+    # fibers the tool starts. With concurrent tool execution, callbacks for
+    # different tool calls can run at the same time.
+    def after_tool_progress(&)
+      add_callback(:after_tool_progress, &)
+    end
+
     # Registers a callback that receives the Fallback attempt after the
     # current model fails and before the fallback model is tried. Returns
     # +self+.
@@ -709,6 +914,22 @@ module RubyLLM
       add_callback(:before_request, &)
     end
 
+    # Converts attachments the current protocol cannot render with the
+    # given block. Returns +self+. The block receives an Attachment and
+    # returns a replacement Attachment, or +nil+ to keep the existing error.
+    # Blocks run in registration order until one returns a replacement.
+    # The transcript keeps the original file, even when the model changes.
+    # The chat converts each attachment once and reuses the replacement,
+    # and its upload, on later requests.
+    #
+    #   chat.convert_unsupported_attachments do |attachment|
+    #     text = TextExtraction.call(attachment)
+    #     Attachment.new(StringIO.new(text), filename: 'extracted.txt') if text
+    #   end
+    def convert_unsupported_attachments(&)
+      add_callback(:unsupported_attachment, &)
+    end
+
     # Yields each Message in the conversation. Returns an Enumerator when
     # no block is given. Chat includes Enumerable, so the usual collection
     # methods are available.
@@ -751,7 +972,7 @@ module RubyLLM
       @provider.count_tokens(
         preprocessed_messages(request_messages),
         model: @model,
-        tools: @tools,
+        tools: request_tools,
         tool_prefs: @tool_prefs,
         thinking: resolved_thinking,
         schema: @schema,
@@ -802,7 +1023,7 @@ module RubyLLM
     end
 
     # Hooks installed by the Rails integration.
-    attr_writer :cancellation_checker, :usage_recorder, :approval_checker # :nodoc:
+    attr_writer :cancellation_checker, :usage_recorder, :approval_checker, :input_checker, :input_recorder # :nodoc:
 
     # Appends a message to the conversation and returns it as a Message.
     # Accepts a Message, an attribute Hash, or a record responding to
@@ -817,14 +1038,18 @@ module RubyLLM
     end
 
     # Marks the latest message as an explicit prompt cache boundary, asking
-    # the provider to cache everything up to this point. Returns +self+.
+    # the provider to cache everything up to this point. Pass +ttl:+ to give
+    # this boundary its own cache lifetime, as Message#cache_until_here
+    # describes. Returns +self+.
+    #
+    #   chat.with_instructions(policy).cache_until_here(ttl: "1h")
     #
     # Raises ArgumentError if the chat has no messages.
-    def cache_until_here
+    def cache_until_here(ttl: nil)
       message = messages.last
       raise ArgumentError, 'No messages to cache' unless message
 
-      message.cache_until_here
+      message.cache_until_here(ttl:)
       self
     end
 
@@ -848,7 +1073,7 @@ module RubyLLM
     def render
       @provider.render(
         preprocessed_messages,
-        tools: @tools,
+        tools: request_tools,
         provider_tools: @provider_tools,
         tool_prefs: @tool_prefs,
         temperature: @temperature,
@@ -877,7 +1102,7 @@ module RubyLLM
       raise PendingToolCallsError,
             "The last response has unanswered tool calls (#{names.join(', ')}). " \
             'Run complete, recording approve or deny decisions for calls that ' \
-            'require approval, before asking again.'
+            'require approval, answering pending inputs, and waiting for tasks, before asking again.'
     end
 
     private
@@ -983,9 +1208,12 @@ module RubyLLM
 
       RubyLLM.instrument('chat.ruby_llm', payload, config: @config) do |event|
         result = provider_completion(usage_recorder: method(:record_usage_entry), stream_tracker:, &block)
+        event[:response_tokens] = result.tokens
         record_out_of_band_usage(result) if usage_entries.length == entries_before
         record_generated_message(result, usage_start, streaming: block_given?)
         record_completion_event(event, result)
+      ensure
+        event[:response_tokens] ||= Tokens.aggregate(usage_entries[entries_before..].map(&:tokens))
       end
       result
     end
@@ -1134,50 +1362,121 @@ module RubyLLM
     # Preprocessing builds a per-request view of the conversation: the
     # provider can change through fallbacks or with_model, so history keeps
     # the original attachments while each provider's upload is memoized on
-    # them. Reloaded Rails chats rebuild history from rows and upload again.
+    # them. An attachment's store keeps its uploads for later processes.
     def preprocessed_messages(list = messages)
+      list = request_history(list)
       return list unless @provider
 
-      list.map { |message| @provider.preprocess_message(message, model: @model, protocol: @protocol) }
+      @provider.preprocess_messages(list, model: @model, protocol: @protocol,
+                                          unsupported_attachment: unsupported_attachment_handler)
+    end
+
+    def unsupported_attachment_handler
+      callbacks = @callbacks[:unsupported_attachment]
+      return if callbacks.empty?
+
+      lambda do |attachment|
+        @attachment_replacements[attachment] ||= callbacks.lazy.filter_map { |handler| handler.call(attachment) }.first
+      end
+    end
+
+    # A process that dies mid-round leaves a blank assistant placeholder,
+    # or tool calls without results, and providers refuse both. A request
+    # leaves blank messages out and answers the calls of a round the
+    # conversation moved past as unfinished. The latest round stays as it
+    # is: the loop runs its calls or waits on them.
+    def request_history(list)
+      kept = list.reject { |message| blank_response?(message) }
+      answered = kept.filter_map { |message| message.tool_call_id if message.tool_result? }
+      current = latest_response(kept)
+      kept.slice_before { |message| !message.tool_result? }.flat_map do |response, *results|
+        abandoned = response.tool_call? && !response.equal?(current)
+        [response, *results, *(abandoned ? unfinished_results(response, answered) : [])]
+      end
+    end
+
+    def unfinished_results(response, answered)
+      response.tool_calls.values.reject { |tool_call| answered.include?(tool_call.id) }
+              .map { |tool_call| unfinished_result(tool_call) }
+    end
+
+    def unfinished_result(tool_call)
+      (remote_refusal(tool_call) if tool_call.remote?) ||
+        Message.new(role: :tool, content: UNFINISHED_TOOL_RESULT, tool_call_id: tool_call.id)
+    end
+
+    # A provider-executed call is closed with the refusal its provider
+    # expects. Another provider takes it as an ordinary tool call.
+    def remote_refusal(tool_call)
+      @provider.tool_approval_response(tool_call, approved: false, model: @model, protocol: @protocol)
+    rescue Error
+      nil
     end
 
     def provider_completion(usage_recorder:, stream_tracker: nil, &)
       raise_if_cancelled!
 
-      @provider.complete(
-        preprocessed_messages,
-        tools: @tools,
-        provider_tools: @provider_tools,
-        tool_prefs: @tool_prefs,
-        temperature: @temperature,
-        max_output_tokens: @max_output_tokens,
-        model: @model,
-        provider_options: Support::Utils.deep_dup(@provider_options),
-        headers: @headers,
-        schema: @schema,
-        thinking: resolved_thinking,
-        citations: @citations,
-        caching: @caching,
-        compaction: @compaction,
-        end_user: @end_user,
-        protocol: @protocol,
-        before_request: @callbacks[:before_request],
-        usage_recorder: usage_recorder,
-        &wrap_streaming_block(stream_tracker:, &)
-      )
+      request_messages = preprocessed_messages
+      streamed = false
+      tracker = proc do |chunk|
+        streamed = true
+        stream_tracker&.call(chunk)
+      end
+      on_chunk = wrap_streaming_block(stream_tracker: tracker, &)
+
+      replacing_missing_uploads(request_messages, -> { streamed }) do |sent_messages|
+        @provider.complete(
+          sent_messages,
+          tools: request_tools,
+          provider_tools: @provider_tools,
+          tool_prefs: @tool_prefs,
+          temperature: @temperature,
+          max_output_tokens: @max_output_tokens,
+          model: @model,
+          provider_options: Support::Utils.deep_dup(@provider_options),
+          headers: @headers,
+          schema: @schema,
+          thinking: resolved_thinking,
+          citations: @citations,
+          caching: @caching,
+          compaction: @compaction,
+          end_user: @end_user,
+          protocol: @protocol,
+          before_request: @callbacks[:before_request],
+          usage_recorder: usage_recorder,
+          &on_chunk
+        )
+      end
     end
 
     def provider_compaction
-      @provider.compact(
-        preprocessed_messages, model: @model, protocol: @protocol,
-                               headers: @headers, before_request: @callbacks[:before_request],
-                               usage_recorder: method(:record_usage_entry)
-      )
+      replacing_missing_uploads(preprocessed_messages) do |sent_messages|
+        @provider.compact(
+          sent_messages, model: @model, protocol: @protocol,
+                         headers: @headers, before_request: @callbacks[:before_request],
+                         usage_recorder: method(:record_usage_entry)
+        )
+      end
+    end
+
+    # A provider can delete a file RubyLLM uploaded for an attachment. A
+    # request that fails over such a file before streaming anything uploads
+    # the file again and runs once more; one that streamed is not repeated.
+    def replacing_missing_uploads(request_messages, streamed = -> { false })
+      yield request_messages
+    rescue Error => e
+      raise if streamed.call || discard_missing_uploads(e).empty?
+
+      yield preprocessed_messages
+    end
+
+    def discard_missing_uploads(error)
+      @provider.discard_missing_uploads(messages, error, model: @model, protocol: @protocol)
     end
 
     def record_usage_entry(entry)
       usage_entries << entry
-      @usage_recorder&.call(entry)
+      @usage_recorder ? @usage_recorder.call(entry) : Accounting::Usage.record(entry)
       entry
     end
 
@@ -1193,7 +1492,8 @@ module RubyLLM
         status: :succeeded,
         tokens: response.tokens,
         cost: response.cost,
-        message: response
+        message: response,
+        owner: Accounting::Usage.owner
       )
       response.ruby_llm_usage_entries = [entry]
       Accounting::Usage.instrument(entry, config: @config)
@@ -1249,22 +1549,20 @@ module RubyLLM
     def partition_pending_tool_calls(pending)
       executable = {}
       denied = {}
-      pending.each do |id, tool_call|
-        tool = tools[tool_call.name.to_sym]
-        if tool&.requires_approval?
-          decision = tool_call_approval(tool, tool_call)
-          next if decision.nil?
-
-          (decision ? executable : denied)[id] = tool_call
-        elsif @tool_call_decisions[tool_call.id] == false
-          denied[id] = tool_call
-        else
-          executable[id] = tool_call
-        end
+      pending.reject { |_, tool_call| input_pending?(tool_call) }.each do |id, tool_call|
+        decision = execution_decision(tool_call)
+        (decision ? executable : denied)[id] = tool_call unless decision.nil?
       end
       [executable, denied]
     end
 
+    def execution_decision(tool_call)
+      tool = tools[tool_call.name.to_sym]
+      return tool_call_approval(tool, tool_call) if tool&.requires_approval?
+
+      @tool_call_decisions[tool_call.id] != false
+    end
+
     def deny_tool_calls(tool_calls)
       tool_calls.each_value do |tool_call|
         raise_if_cancelled!
@@ -1298,14 +1596,18 @@ module RubyLLM
     def handle_sequential_tool_calls(tool_calls)
       tool_calls.each_value do |tool_call|
         raise_if_cancelled!
-        run_callbacks(:before_message)
         result = execute_tool_with_callbacks(tool_call)
+        next if result.equal?(PAUSED)
+
+        run_callbacks(:before_message)
         add_tool_result_message(tool_call, result)
       end
     end
 
     def handle_concurrent_tool_calls(tool_calls)
       execute_tools_concurrently(tool_calls) do |tool_call, result|
+        next if result.equal?(PAUSED)
+
         raise_if_cancelled!
         run_callbacks(:before_message)
         add_tool_result_message(tool_call, result)
@@ -1322,6 +1624,8 @@ module RubyLLM
       raise_if_cancelled!
       run_callbacks(:before_tool_call, tool_call)
       result = execute_tool tool_call
+      return result if result.equal?(PAUSED)
+
       raise_if_cancelled!
       run_callbacks(:after_tool_result, result)
       result
@@ -1329,7 +1633,8 @@ module RubyLLM
 
     def add_tool_result_message(tool_call, result)
       content, attachments = Tool.split_result(result)
-      message = add_message role: :tool, content:, attachments:, tool_call_id: tool_call.id
+      mcp_result = result if result.is_a?(MCP::Result) && result.ui_uri
+      message = add_message(role: :tool, content:, attachments:, tool_call_id: tool_call.id, mcp_result:)
       run_callbacks(:after_message, message)
       message
     end
@@ -1358,7 +1663,9 @@ module RubyLLM
       }
 
       RubyLLM.instrument('tool_call.ruby_llm', payload, config: @config) do |event|
-        result = tool.call(**args, tool_call: tool_call)
+        result = Support::Cancellation.watch(-> { raise_if_cancelled! }) do
+          Support::ProgressReporter.listen(progress_listener(tool_call)) { invoke_tool(tool, tool_call, args) }
+        end
         event[:result] = result
         event[:result_content] = result
         event[:result_class] = result.class.name
@@ -1366,6 +1673,87 @@ module RubyLLM
       end
     end
 
+    def progress_listener(tool_call)
+      return if @callbacks.fetch(:after_tool_progress, []).empty?
+
+      ->(progress) { run_callbacks(:after_tool_progress, tool_call, progress) }
+    end
+
+    def invoke_tool(tool, tool_call, arguments)
+      input = tool_call_input(tool_call)
+      result = input ? tool.resume(input, arguments) : tool.call(**arguments, tool_call:)
+      return pause_tool_call(tool_call, result.to_h) if result.is_a?(MCP::Task)
+
+      record_tool_call_input(tool_call, nil) if input
+      result
+    rescue MCP::InputRequiredError => e
+      pause_tool_call(tool_call, e.to_h)
+    end
+
+    def pause_tool_call(tool_call, state)
+      record_tool_call_input(tool_call, state)
+      PAUSED
+    end
+
+    def paused?(tool_call)
+      state = tool_call_input(tool_call)
+      !state.nil? && (unanswered?(state) || state.key?('task'))
+    end
+
+    def input_pending?(tool_call)
+      unanswered?(tool_call_input(tool_call))
+    end
+
+    def unanswered?(state)
+      Array(state&.[]('requests')).any? { |request| request['response'].nil? }
+    end
+
+    def task_for(tool_call, state)
+      tool = tools[tool_call.name.to_sym]
+      tool.respond_to?(:task) ? tool.task(state, tool_call:) : MCP::Task.load(nil, state, tool_call:)
+    end
+
+    def cancel_tasks
+      response = pending_tool_response
+      return unless response
+
+      pending_tool_calls(response).each_value do |tool_call|
+        state = tool_call_input(tool_call)
+        next unless state&.key?('task')
+
+        cancel_task(task_for(tool_call, state))
+        record_tool_call_input(tool_call, nil)
+      end
+    end
+
+    def cancel_task(task)
+      task.cancel
+    rescue Error, ConfigurationError, Faraday::Error => e
+      RubyLLM.logger.debug { "RubyLLM could not cancel task #{task.id}: #{e.message}" }
+    end
+
+    def tool_call_input(tool_call)
+      @input_checker ? @input_checker.call(tool_call) : @tool_call_inputs[tool_call.id]
+    end
+
+    def record_tool_call_input(tool_call, input)
+      @tool_call_inputs[tool_call.id] = input
+      @input_recorder&.call(tool_call, input)
+    end
+
+    def settle_input(request)
+      input = tool_call_input(request.tool_call) or raise ArgumentError, 'Unknown input request'
+      requests = input['requests'].map do |data|
+        next data unless data['key'] == request.key
+
+        pending = MCP::InputRequest.from_h(data)
+        yield pending
+        pending.to_h
+      end
+      record_tool_call_input(request.tool_call, input.merge('requests' => requests))
+      self
+    end
+
     def apply_tool_choice(choice)
       if choice.nil?
         @tool_prefs[:choice] = nil
@@ -1427,11 +1815,29 @@ module RubyLLM
       messages.reverse.find { |message| message.role != :system }
     end
 
+    def hidden_from_model?(tool)
+      tool.is_a?(MCP::Tool) && !tool.visibility.include?(:model)
+    end
+
     def pending_tool_response
-      response = messages.reverse.find { |message| message.role != :system && !message.tool_result? }
+      response = latest_response(messages)
       response if response&.tool_call? && pending_tool_calls(response).any?
     end
 
+    # A blank response answers nothing, so it never hides the round before
+    # it, as the placeholder of a process that died after a tool finished.
+    def latest_response(list)
+      list.reverse.find do |message|
+        message.role != :system && !message.tool_result? && !blank_response?(message)
+      end
+    end
+
+    def blank_response?(message)
+      message.role == :assistant && !message.tool_call? && message.content.to_s.strip.empty? &&
+        message.attachments.empty? && message.thinking.nil? && message.server_tool_calls.empty? &&
+        message.raw_content.nil? && message.raw_reasoning.nil?
+    end
+
     def pending_tool_calls(response)
       answered = messages.filter_map { |message| message.tool_call_id if message.tool_result? }
       response.tool_calls.except(*answered)