activeagent 1.8.1 → 1.9.0

data/lib/active_agent/providers/concerns/input_requests.rb

@@ -0,0 +1,332 @@
+# frozen_string_literal: true
+
+require "active_agent/input_request"
+
+module ActiveAgent
+  module Providers
+    # Pauses a generation when a tool returns an {ActiveAgent::InputRequest},
+    # and resumes it from the checkpoint with the user's answers.
+    #
+    # A provider takes part by running a turn's tool calls through
+    # {#dispatch_tool_calls} and building its result messages from what that
+    # returns. Under a provider whose tool loop calls `call_tool_function`
+    # directly, a tool that returns an InputRequest, or a tool that needs
+    # approval, raises {ActiveAgent::InputRequest::UnsupportedProviderError}.
+    #
+    # A tool needs approval when the `requires_approval:` prompt option names
+    # it, or when it is served by a client-side MCP server whose declaration's
+    # `require_approval` covers it (see {MCPBridge#requires_approval?}). Its
+    # call then pauses with a `:confirm` request before the tool runs, and runs
+    # only once the user approves it.
+    module InputRequests
+      extend ActiveSupport::Concern
+
+      # The metadata of a request the approval gate makes, as opposed to one
+      # a tool returned.
+      APPROVAL_METADATA = { "approval" => true }.freeze
+
+      included do
+        # The agent action the generation runs, recorded in a checkpoint.
+        attr_internal :generation_action_name
+
+        # The tool names the `requires_approval:` prompt option lists.
+        attr_internal :tool_approvals
+
+        # The checkpoint and answers being resumed from, until the paused
+        # turn's results have been dispatched.
+        attr_internal :input_request_resume
+
+        # The completed results and input requests of a turn that paused.
+        attr_internal :paused_tool_turn
+
+        # Whether a pause publishes `input_requested.active_agent`.
+        attr_internal :announce_input_requests
+      end
+
+      # @return [Boolean] whether the last tool turn left calls waiting on the user
+      def awaiting_input? = paused_tool_turn.present?
+
+      protected
+
+      # Continues a paused generation from where it stopped: the assistant turn
+      # that made the tool calls goes back on the message stack, the calls are
+      # dispatched with their answers, and the tool loop carries on.
+      #
+      # @return [Common::PromptResponse]
+      # @raise [ActiveAgent::InputRequest::ResumeError] before any tool runs,
+      #   when the checkpoint was taken on another provider or model, or its
+      #   tool calls do not match its results and requests
+      def resume_prompt
+        resume = input_request_resume
+        resume.assert_provider!(service: service_name, provider: tag_name, model: request.model)
+
+        clear_tool_choice if resume.tool_choice_cleared?
+        message_stack.push(*resume.tool_call_turn)
+        tool_calls = Array(process_prompt_finished_extract_function_calls)
+        resume.assert_tool_calls!(tool_calls.map { tool_call_reference(_1).first })
+
+        self.tool_turns = resume.tool_turns
+        process_function_calls(tool_calls)
+        return paused_prompt_response if awaiting_input?
+
+        resolve_prompt
+      end
+
+      # Runs a turn's tool calls, each through the block, and returns their
+      # results in call order.
+      #
+      # Returns nil when a call paused: its tool returned an InputRequest, or
+      # it needs approval and has none yet, in which case the tool does not
+      # run. The other calls still run, and their results are kept for the
+      # checkpoint rather than sent: the turn's results go to the model
+      # together, once every call has one.
+      #
+      # On resume:
+      #   - a call completed before the pause reuses its result in JSON form
+      #   - a declined call gets {ActiveAgent::InputRequest::DECLINED_RESULT}
+      #     without running
+      #   - a call to a client-side MCP tool its server no longer offers gets
+      #     an `{ error: }` result without running
+      #   - a call that waited for approval runs once approved, with no answer
+      #     in execution state: the approval answers the gate, not the tool
+      #   - any other paused call runs again with its answer readable through
+      #     {ActiveAgent::InputRequest.answer_for}
+      #
+      # @param calls [Array<Hash>] provider-native tool calls
+      # @yieldparam call [Hash] one call to run
+      # @yieldreturn [Object] the tool's result
+      # @return [Array<Object>, nil]
+      def dispatch_tool_calls(calls, &block)
+        resume = input_request_resume
+        paused = []
+        gated  = []
+
+        results = calls.map do |call|
+          id, name = tool_call_reference(call)
+          result   = dispatch_tool_call(call, id, name, resume, gated, &block)
+          next result unless result.is_a?(ActiveAgent::InputRequest)
+
+          result = result.for_tool_call(id:, name:, arguments: tool_call_arguments(call))
+          paused << [ id, name, result ]
+          result
+        end
+
+        self.input_request_resume = nil
+        return results if paused.empty?
+
+        requests = paused.map(&:last)
+        self.paused_tool_turn = {
+          results:             completed_results(calls, results, requests),
+          input_requests:      requests,
+          approval_tool_calls: gated,
+          approved_tool_calls: paused.filter_map { |id, _, _| id if resume && (resume.approval_given?(id) || resume.approved?(id)) },
+          mcp_tool_calls:      paused.filter_map { |id, name, _| id if mcp_owns_tool?(name) }
+        }
+        nil
+      end
+
+      # Returns the id and tool name of a provider-native tool call. Providers
+      # whose calls carry them elsewhere override this.
+      #
+      # @param call [Hash]
+      # @return [Array(String, String)]
+      def tool_call_reference(call)
+        [ call[:id].to_s, call[:name].to_s ]
+      end
+
+      # Returns the arguments of a provider-native tool call, as the model
+      # sent them. Providers whose calls carry them elsewhere override this.
+      #
+      # @param call [Hash]
+      # @return [Hash, nil]
+      def tool_call_arguments(call)
+        call[:input]
+      end
+
+      # @param json [String, nil] arguments a model sent as a JSON string
+      # @return [Hash, String, nil] the parsed arguments, or `json` itself
+      #   when it is not valid JSON
+      def parse_tool_call_arguments(json)
+        return json unless json.is_a?(String)
+        return {} if json.blank?
+
+        JSON.parse(json)
+      rescue JSON::ParserError
+        json
+      end
+
+      # Returns the `requires_approval:` prompt option as tool names.
+      #
+      # @param value [String, Symbol, Array<String, Symbol>, nil]
+      # @return [Array<String>]
+      # @raise [ArgumentError] for anything else, such as `true`, which names
+      #   no tool and would gate nothing
+      def normalize_tool_approvals(value)
+        names = Array(value)
+        return names.map(&:to_s) if names.all? { _1.is_a?(String) || _1.is_a?(Symbol) }
+
+        raise ArgumentError, "requires_approval: takes a tool name or an array of tool names, not #{value.inspect}"
+      end
+
+      # Whether a call to the tool must be approved before the tool runs.
+      #
+      # @param name [String, Symbol]
+      # @return [Boolean]
+      def approval_required?(name)
+        Array(tool_approvals).include?(name.to_s) || (mcp_owns_tool?(name) && mcp_bridge.requires_approval?(name))
+      end
+
+      # @param name [String, Symbol] the tool about to run
+      # @raise [ActiveAgent::InputRequest::UnsupportedProviderError] when the
+      #   tool needs approval and the call was not dispatched through
+      #   {#dispatch_tool_calls}, which is where the approval is asked for
+      def assert_approval_gate_reached!(name)
+        return if @_dispatching_tool_call || !approval_required?(name)
+
+        raise ActiveAgent::InputRequest::UnsupportedProviderError,
+              "#{tag_name} ran #{name}, which needs approval, outside dispatch_tool_calls, so nobody was asked to approve it."
+      end
+
+      # Runs a tool call made outside {#dispatch_tool_calls} with no tool call
+      # in execution state. Such a call can neither pause nor be answered, and
+      # it must not read the answer of an enclosing call that started this
+      # generation.
+      #
+      # @return [Object] the block's result
+      def isolate_undispatched_tool_call(&block)
+        return yield if @_dispatching_tool_call
+
+        ActiveAgent::InputRequest.dispatching(nil, &block)
+      end
+
+      # @param result [Object] what a tool returned
+      # @raise [ActiveAgent::InputRequest::UnsupportedProviderError] when the
+      #   result is an InputRequest and the call was not dispatched through
+      #   {#dispatch_tool_calls}
+      def assert_input_request_supported!(result)
+        return unless result.is_a?(ActiveAgent::InputRequest) && !@_dispatching_tool_call
+
+        raise ActiveAgent::InputRequest::UnsupportedProviderError,
+              "#{tag_name} cannot pause a generation for user input: its tool loop does not run calls through " \
+              "dispatch_tool_calls, and a tool returned an ActiveAgent::InputRequest."
+      end
+
+      # Builds the response for a generation that is waiting on the user, and
+      # announces it with `input_requested.active_agent` unless
+      # `announce_input_requests` is false.
+      #
+      # @param api_response [Hash, nil] the response that made the tool calls
+      # @return [Common::PromptResponse]
+      def paused_prompt_response(api_response = nil)
+        broadcast_stream_close
+
+        input_requests = paused_tool_turn[:input_requests]
+        instrument("input_requested.active_agent", input_requests:) if announce_input_requests
+
+        build_prompt_response(api_response, input_requests:, checkpoint:)
+      end
+
+      # Returns a JSON-safe hash {ActiveAgent::Generation#resume_now} continues
+      # from; see {ActiveAgent::InputRequest::Resume} for its keys.
+      #
+      # @return [Hash{String => Object}]
+      def checkpoint
+        {
+          version:             ActiveAgent::InputRequest::Resume::VERSION,
+          service:             service_name,
+          provider:            tag_name,
+          model:               request.model&.to_s,
+          action_name:         generation_action_name,
+          tool_turns:,
+          tool_choice_cleared: tool_choice_cleared == true,
+          messages:            checkpoint_messages,
+          tool_call_turn_size: serialized_messages(message_stack).size,
+          completed_results:   paused_tool_turn[:results],
+          input_requests:      paused_tool_turn[:input_requests].map(&:to_h),
+          approval_tool_calls: paused_tool_turn[:approval_tool_calls],
+          approved_tool_calls: paused_tool_turn[:approved_tool_calls],
+          mcp_tool_calls:      paused_tool_turn[:mcp_tool_calls]
+        }.as_json
+      end
+
+      # Returns `messages` in the provider's serialized form.
+      #
+      # @param messages [Array, nil]
+      # @param instructions [String, Array, nil]
+      # @return [Array<Hash>]
+      def serialized_messages(messages, instructions: nil)
+        parameters = { messages:, instructions: }.compact
+        return [] if parameters.empty?
+
+        prompt_request_type.serialize(prompt_request_type.cast(parameters))[:messages] || []
+      end
+
+      private
+
+      # Runs one call of a turn, or answers it without running the tool.
+      #
+      # Whether a paused call waited for approval is read from the checkpoint,
+      # so a resume whose `requires_approval:` differs still treats the answer
+      # as an approval and never hands it to the tool.
+      #
+      # @param gated [Array<String>] collects the ids of calls the approval
+      #   gate pauses
+      # @return [Object] the tool's result, or an InputRequest when the call
+      #   pauses
+      def dispatch_tool_call(call, id, name, resume, gated)
+        if resume&.completed?(id)
+          resume.completed_result(id)
+        elsif resume&.declined?(id)
+          ActiveAgent::InputRequest::DECLINED_RESULT
+        elsif resume&.mcp_tool_call?(id) && !mcp_owns_tool?(name)
+          { error: "#{name} is no longer offered by its MCP server" }
+        elsif resume&.approval_given?(id)
+          dispatching_tool_call(id, answer: nil) { yield call }
+        elsif resume&.approved?(id) || !approval_required?(name)
+          dispatching_tool_call(id, answer: resume&.answer(id)) { yield call }
+        else
+          gated << id
+          ActiveAgent::InputRequest.confirm("Allow #{name} to run?", metadata: APPROVAL_METADATA)
+        end
+      end
+
+      # Returns the conversation through the assistant tool-call turn, in the
+      # provider's serialized form, without the messages the provider derives
+      # from instructions (OpenAI Chat's developer message): a resumed
+      # generation renders its instructions again. The caller's messages are
+      # cast without instructions, and every later message follows them.
+      #
+      # @return [Array<Hash>]
+      def checkpoint_messages
+        conversation         = serialized_messages([ *request.messages, *message_stack ])
+        with_instructions    = serialized_messages(context[:messages], instructions: context[:instructions])
+        without_instructions = serialized_messages(context[:messages])
+
+        without_instructions + conversation.drop(with_instructions.size)
+      end
+
+      # @return [Hash{String => Object}] each finished call's result in JSON
+      #   form, by call id
+      # @raise [ArgumentError] when the calls lack unique ids, which a
+      #   checkpoint needs to match results and answers to calls
+      def completed_results(calls, results, requests)
+        ids = calls.map { tool_call_reference(_1).first }
+        if ids.any?(&:blank?) || ids.uniq.size != ids.size
+          raise ArgumentError, "#{tag_name} returned tool calls without unique ids, so the generation cannot pause for input"
+        end
+
+        paused = requests.map(&:tool_call_id)
+        ids.zip(results).reject { |id, _| paused.include?(id) }.to_h { |id, result| [ id, result.as_json ] }
+      end
+
+      # @return [Object] the block's result
+      def dispatching_tool_call(id, answer:)
+        previous, @_dispatching_tool_call = @_dispatching_tool_call, true
+
+        ActiveAgent::InputRequest.dispatching(id, answer:) { yield }
+      ensure
+        @_dispatching_tool_call = previous
+      end
+    end
+  end
+end

data/lib/active_agent/providers/concerns/mcp_serving.rb

@@ -0,0 +1,267 @@
+# frozen_string_literal: true
+
+require_relative "../mcp_bridge"
+
+module ActiveAgent
+  module Providers
+    # Serves `mcps:` declarations, natively where a provider's API can and
+    # client-side everywhere else.
+    #
+    # A declaration is passthrough by default: it becomes the provider's own
+    # `mcp_servers` parameter, and the provider connects, lists the tools and
+    # calls them. That works only where the provider implements MCP, and where it
+    # does not the failure is quiet — DeepSeek ignores `mcp_servers`, returns 200,
+    # and answers without the server's data, so it reads as a poor answer rather
+    # than as a configuration error.
+    #
+    # The default is therefore inverted here: a provider declares the transports
+    # its own API can serve ({#mcp_native_transports}, empty by default) and
+    # {MCPBridge} serves the rest, which is what makes `mcps:` work on every
+    # provider rather than only the ones that implement it.
+    #
+    # Each provider may override:
+    # - `mcp_native_transports`: the transport kinds its own API can serve
+    module MCPServing
+      extend ActiveSupport::Concern
+
+      # The accepted `mcp_strategy:` values.
+      STRATEGIES = %i[auto client server].freeze
+
+      included do
+        # @return [MCPBridge, nil] bridge over the client-side declarations
+        attr_internal :mcp_bridge
+      end
+
+      # The MCP server transports this provider can serve through its own API.
+      #
+      # `:url` is a remote server, which a provider that speaks MCP can simply be
+      # handed. `:command` is a local process, and no provider can serve one:
+      # nothing but this process is going to spawn it, so those always run
+      # client-side whatever the provider supports.
+      #
+      # Empty by default, which is what makes the bridge the universal path —
+      # every provider supports `mcps:` whether or not its API does.
+      #
+      # @return [Array<Symbol>]
+      def mcp_native_transports = []
+
+      protected
+
+      # Request parameters for a real prompt, with `mcps:` resolved.
+      #
+      # Declarations the provider can serve itself are left in `mcps:` for it to
+      # translate; the rest are served by {MCPBridge}, which exposes their tools
+      # as ordinary tools the provider can already call.
+      #
+      # @return [Hash]
+      def mcp_resolved_context
+        native, bridged = mcp_partition_servers(context[:mcps])
+        parameters      = mcp_except_options(context)
+
+        parameters = parameters.merge(mcps: native) if native.any?
+
+        # Release a bridge left by an earlier call on this instance before this
+        # one replaces the field, or its connections outlive the generation that
+        # opened them.
+        mcp_release_bridge!
+        self.mcp_bridge = bridged.any? ? MCPBridge.new(bridged, cache: context[:mcp_cache]) : nil
+
+        return parameters if mcp_bridge.nil?
+
+        parameters.merge(tools: mcp_bridge.merge_tools(parameters[:tools]))
+      end
+
+      # Closes the bridge's server connections, if one was built.
+      #
+      # A bridged server holds a live connection, and for a `command:` server
+      # that connection is a process. It has to be released when the generation
+      # that opened it finishes — the garbage collector would never reap it, so
+      # a long-lived worker would accumulate orphans until it ran out of PIDs.
+      #
+      # Safe to call when no bridge was built, and safe to call twice.
+      #
+      # @return [void]
+      def mcp_release_bridge!
+        mcp_bridge&.close
+        self.mcp_bridge = nil
+      end
+
+      # Request parameters for a preview, keeping only what the provider serves.
+      #
+      # Discovering a server's tools means connecting to it, and a preview must
+      # not perform I/O, so a client-side server does not appear in a preview at
+      # all — its tools are unknown until it is connected to.
+      #
+      # @return [Hash]
+      def mcp_preview_context
+        native, = mcp_partition_servers(context[:mcps])
+        parameters = mcp_except_options(context)
+
+        native.any? ? parameters.merge(mcps: native) : parameters
+      end
+
+      # @param name [String, Symbol] tool name
+      # @return [Boolean] whether a bridged server provides this tool
+      def mcp_owns_tool?(name)
+        mcp_bridge&.owns?(name) || false
+      end
+
+      # Invokes a tool on a bridged server.
+      #
+      # @param name [String] tool name
+      # @param kwargs [Hash] tool arguments
+      # @return [Object] the tool's result
+      def mcp_call_tool(name, **kwargs) = mcp_bridge.call(name, **kwargs)
+
+      # Splits `mcps:` into what the provider serves and what the bridge serves.
+      #
+      # A declaration whose calls may need approval is always the bridge's,
+      # because a provider that serves a server itself runs its tool calls where
+      # the approval gate never sees them (see {#mcp_gated?}).
+      #
+      # @param declarations [Array<Hash>, Hash, nil]
+      # @return [Array<Array<Hash>>] the provider's declarations, then the
+      #   bridge's
+      # @raise [ArgumentError] when `mcp_strategy: :server` was asked for and the
+      #   provider cannot serve one of the declarations, or one may need approval
+      def mcp_partition_servers(declarations)
+        declarations = mcp_normalize_declarations(declarations)
+
+        case mcp_strategy
+        when :client
+          [ [], declarations ]
+        when :server
+          declarations.each { |declaration| mcp_assert_servable!(declaration) }
+
+          [ declarations, [] ]
+        else
+          declarations.partition do |declaration|
+            mcp_native_transports.include?(mcp_transport(declaration)) && !mcp_gated?(declaration)
+          end
+        end
+      end
+
+      # Whether some of a declaration's tool calls may need approval: its
+      # `require_approval` covers a tool, or its server may offer a tool the
+      # `requires_approval:` prompt option names (see
+      # {#mcp_approvals_served_by}).
+      #
+      # @param declaration [Hash]
+      # @return [Boolean]
+      def mcp_gated?(declaration)
+        return false unless declaration.is_a?(Hash)
+
+        MCPBridge.approval_policy?(declaration[:require_approval]) || mcp_approvals_served_by(declaration).any?
+      end
+
+      # Returns the names in the `requires_approval:` prompt option that a
+      # declaration's server may offer: those among its `allowed_tools`, or,
+      # when it lists none, every name that no tool in `tools:` has. The tools
+      # of a server without `allowed_tools` are unknown until it is connected
+      # to, so it is taken to offer any name.
+      #
+      # @param declaration [Hash]
+      # @return [Array<String>]
+      def mcp_approvals_served_by(declaration)
+        approvals = Array(tool_approvals)
+        return [] if approvals.empty?
+
+        allowed = Array(declaration[:allowed_tools]).map { |tool| mcp_tool_name(tool) }
+        return approvals & allowed if allowed.any?
+
+        approvals - Array(context[:tools]).map { |tool| mcp_tool_name(tool) }
+      end
+
+      # @param tool [Hash, String, Symbol] a tool definition, in the common
+      #   format or OpenAI Chat's `{ function: { name: } }`, or a tool name
+      # @return [String]
+      def mcp_tool_name(tool)
+        return tool.to_s unless tool.is_a?(Hash)
+
+        function = tool[:function] || tool["function"]
+        name     = tool[:name] || tool["name"]
+        name   ||= function[:name] || function["name"] if function.is_a?(Hash)
+
+        name.to_s
+      end
+
+      # @return [Symbol] how to serve `mcps:`: `:auto` (default, native where the
+      #   provider can and client-side otherwise), `:client` to always run the
+      #   servers here, or `:server` to require the provider to run them
+      # @raise [ArgumentError] for a value outside `STRATEGIES`
+      def mcp_strategy
+        strategy = (context[:mcp_strategy] || :auto).to_sym
+        return strategy if STRATEGIES.include?(strategy)
+
+        fail ArgumentError, "`mcp_strategy:` must be one of #{STRATEGIES.map(&:inspect).join(', ')}, got #{strategy.inspect}."
+      end
+
+      # Removes the MCP options, which are instructions to this concern rather
+      # than parameters any provider accepts.
+      #
+      # @param parameters [Hash]
+      # @return [Hash]
+      def mcp_except_options(parameters)
+        parameters.except(:mcps, :mcp_strategy, :mcp_cache)
+      end
+
+      # @param declarations [Array<Hash>, Hash, nil]
+      # @return [Array<Hash>]
+      def mcp_normalize_declarations(declarations)
+        return [] if declarations.blank?
+        # `Array(hash)` would split a lone declaration into pairs.
+        declarations = [ declarations ] if declarations.is_a?(Hash)
+
+        # A declaration loaded from YAML or JSON arrives with String keys, and `mcp_transport` reads Symbols.
+        Array(declarations).map { |declaration| declaration.is_a?(Hash) ? declaration.deep_symbolize_keys : declaration }
+      end
+
+      # @param declaration [Hash]
+      # @return [Symbol, nil] `:url`, `:command`, or nil when neither is declared
+      def mcp_transport(declaration)
+        return nil unless declaration.is_a?(Hash)
+        return :url if declaration[:url].present?
+        return :command if declaration[:command].present?
+
+        nil
+      end
+
+      # @param declaration [Hash]
+      # @return [void]
+      # @raise [ArgumentError] when the provider cannot serve the declaration
+      def mcp_assert_servable!(declaration)
+        transport = mcp_transport(declaration)
+
+        unless transport && mcp_native_transports.include?(transport)
+          fail ArgumentError,
+               "#{service_name} cannot serve #{transport ? "a #{transport.inspect}" : "this"} MCP server itself, " \
+               "but `mcp_strategy: :server` requires it to. Servers it can serve: " \
+               "#{mcp_native_transports.any? ? mcp_native_transports.inspect : "none"}. " \
+               "Use `mcp_strategy: :auto` to run the rest client-side."
+        end
+
+        if MCPBridge.approval_policy?(declaration[:require_approval])
+          fail ArgumentError,
+               "The #{declaration[:name].to_s.inspect} MCP server's tool calls need approval, which is asked for " \
+               "only when ActiveAgent runs the server client-side, but `mcp_strategy: :server` hands it to " \
+               "#{service_name}. Use `mcp_strategy: :auto` or `:client`, or set `require_approval: \"never\"`."
+        end
+
+        approvals = mcp_approvals_served_by(declaration)
+        return if approvals.empty?
+
+        remedy = if declaration[:allowed_tools].present?
+          "Remove #{approvals.to_sentence} from its `allowed_tools:`"
+        else
+          "List the tools it may offer in `allowed_tools:`"
+        end
+
+        fail ArgumentError,
+             "`requires_approval:` names #{approvals.to_sentence}, which the #{declaration[:name].to_s.inspect} " \
+             "MCP server may offer, and approval is asked for only when ActiveAgent runs the server client-side, " \
+             "but `mcp_strategy: :server` hands it to #{service_name}. #{remedy}, or use `mcp_strategy: :auto` " \
+             "or `:client`."
+      end
+    end
+  end
+end

data/lib/active_agent/providers/concerns/tool_choice_clearing.rb

@@ -16,27 +16,42 @@ module ActiveAgent
     module ToolChoiceClearing
       extend ActiveSupport::Concern
 
+      included do
+        # Whether this generation has cleared a forced tool_choice. A paused
+        # generation's checkpoint records it, since a resumed generation
+        # casts its request, tool_choice included, from the action again.
+        attr_internal :tool_choice_cleared
+      end
+
       # @api private
       def prepare_prompt_request_tools
-        return unless request.tool_choice
+        # Once cleared, tool_choice is not read again: the Anthropic SDK's
+        # request model raises when its tool_choice is read back as nil.
+        return if tool_choice_cleared || !request.tool_choice
 
         functions_used = extract_used_function_names
 
         # Clear if forcing required and any tool was used
         if tool_choice_forces_required? && functions_used.any?
-          request.tool_choice = nil
+          clear_tool_choice
           return
         end
 
         # Clear if forcing specific tool and that tool was used
         forces_specific, tool_name = tool_choice_forces_specific?
         if forces_specific && tool_name && functions_used.include?(tool_name)
-          request.tool_choice = nil
+          clear_tool_choice
         end
       end
 
       private
 
+      # @return [void]
+      def clear_tool_choice
+        request.tool_choice      = nil
+        self.tool_choice_cleared = true
+      end
+
       # Extracts the list of function names that have been called.
       #
       # @return [Array<String>] function names

data/lib/active_agent/providers/deep_seek_provider.rb

@@ -0,0 +1,6 @@
+# DeepSeek, alias for the brand-cased service name resolution
+#
+# `service: "DeepSeek"` underscores to "deep_seek", so provider_load looks for
+# this file. The provider itself lives in deepseek_provider.rb, which is also
+# what `:deepseek` / "Deepseek" resolves to before the service-name remap.
+require_relative "deepseek_provider"

data/lib/active_agent/providers/deepseek/_types.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative "options"
+require_relative "chat/_types"