activeagent 1.8.0 → 1.9.0

data/lib/active_agent/providers/mcp_tool_cache.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+require "monitor"
+require "active_support/core_ext/object/deep_dup"
+
+module ActiveAgent
+  module Providers
+    # Process-local cache for the tools an MCP server advertises.
+    #
+    # Asking a server what it offers is a round trip, and an expensive one: a
+    # hosted server measures ~450ms for `tools/list` on top of ~680ms for the
+    # handshake. The answer changes about as often as the server is redeployed,
+    # so a generation that pays that to relearn the same 27 tool names is paying
+    # it for nothing.
+    #
+    # With an entry cached, {MCPBridge} needs no connection at all to advertise
+    # the tools — it connects only if the model actually calls one. So the cost
+    # becomes zero for a generation that never reaches for an MCP tool, and one
+    # connection for a generation that does.
+    #
+    # Entries hold plain data: no sockets, no child processes, no class
+    # references. That is what makes it safe to hold across a fork — a child
+    # gets a copy-on-write snapshot with nothing in it bound to the parent's
+    # file descriptors or threads.
+    #
+    # @see ActiveAgent::Providers::MCPBridge
+    class MCPToolCache
+      # Seconds an entry stays usable. Long enough to cover a burst of
+      # generations, short enough that a redeployed server is picked up on its
+      # own without a restart.
+      DEFAULT_TTL = 300
+
+      # Upper bound on entries, oldest evicted first. Each entry is one server's
+      # tool schemas, so this is small; the cap exists to keep a process that
+      # talks to many distinct servers from growing without bound.
+      DEFAULT_MAX_ENTRIES = 100
+
+      @monitor = Monitor.new
+
+      class << self
+        # @return [Numeric] seconds an entry stays usable
+        def ttl = @ttl ||= DEFAULT_TTL
+
+        # @param seconds [Numeric] must be positive, or nothing would ever be
+        #   reused
+        # @return [Numeric]
+        def ttl=(seconds)
+          unless seconds.is_a?(Numeric) && seconds.positive?
+            fail ArgumentError, "MCP tool cache ttl must be a positive number of seconds, got #{seconds.inspect}."
+          end
+
+          @ttl = seconds
+        end
+
+        # @return [Integer] entries kept before the oldest is evicted
+        def max_entries = @max_entries ||= DEFAULT_MAX_ENTRIES
+
+        # @param count [Integer]
+        # @return [Integer]
+        def max_entries=(count)
+          unless count.is_a?(Integer) && count.positive?
+            fail ArgumentError, "MCP tool cache max_entries must be a positive Integer, got #{count.inspect}."
+          end
+
+          @max_entries = count
+        end
+
+        # @return [Boolean] whether lookups consult the cache at all
+        def enabled? = @enabled.nil? ? true : @enabled
+
+        # @param value [Boolean]
+        # @return [Boolean]
+        def enabled=(value)
+          @enabled = !!value
+        end
+
+        # @param ttl [Numeric, nil]
+        # @param max_entries [Integer, nil]
+        # @param enabled [Boolean, nil]
+        # @return [Class] self, for chaining
+        def configure(ttl: nil, max_entries: nil, enabled: nil)
+          self.ttl         = ttl if ttl
+          self.max_entries = max_entries if max_entries
+          self.enabled     = enabled unless enabled.nil?
+
+          self
+        end
+
+        # The cached tools for +key+, computing and storing them on a miss.
+        #
+        # The block runs outside the lock: it performs network I/O, and holding
+        # the lock across it would serialise every generation in the process.
+        # Two threads racing on the same cold key both fetch and the later write
+        # wins — a duplicated round trip costs less than a global lock on the
+        # latency path.
+        #
+        # @param key [String] identifies the declaration, e.g. a digest
+        # @param enabled [Boolean, nil] per-generation override; nil uses the
+        #   process-level setting
+        # @yieldreturn [Array<Hash>] the tools to cache when there is no entry
+        # @return [Array<Hash>] a copy the caller may mutate freely
+        def fetch(key, enabled: nil)
+          use_cache = enabled.nil? ? enabled? : enabled
+          return yield.deep_dup unless use_cache
+
+          cached = read(key)
+          return cached if cached
+
+          tools = yield
+          write(key, tools)
+          tools.deep_dup
+        end
+
+        # Drops one entry, so the next lookup asks the server again.
+        #
+        # @param key [String]
+        # @return [nil]
+        def invalidate(key)
+          monitor.synchronize { entries.delete(key) }
+
+          nil
+        end
+
+        # Drops every entry. For a redeploy-time hook or a test's setup.
+        #
+        # @return [nil]
+        def clear!
+          monitor.synchronize do
+            entries.clear
+            @hits   = 0
+            @misses = 0
+          end
+
+          nil
+        end
+
+        # Empties the cache and restores the default settings.
+        #
+        # An application that configured the cache should not have to hand back
+        # every value to get a clean slate; a test suite benefits most, since
+        # the cache is process-global and outlives a single test.
+        #
+        # @return [nil]
+        def reset!
+          monitor.synchronize do
+            entries.clear
+            @hits        = 0
+            @misses      = 0
+            @ttl         = nil
+            @max_entries = nil
+            @enabled     = nil
+          end
+
+          nil
+        end
+
+        # @return [Hash] entry count and hit/miss counters, for a health check
+        #   or to confirm the cache is doing what it should
+        def stats
+          monitor.synchronize { { size: entries.size, hits: @hits.to_i, misses: @misses.to_i } }
+        end
+
+        private
+
+        # @param key [String]
+        # @return [Array<Hash>, nil] a copy, or nil when absent or expired
+        def read(key)
+          monitor.synchronize do
+            entry = entries[key]
+
+            if entry.nil? || expired?(entry)
+              # A stale entry is dropped rather than left to expire twice.
+              entries.delete(key) if entry
+              @misses = @misses.to_i + 1
+
+              nil
+            else
+              @hits = @hits.to_i + 1
+
+              entry[:tools].deep_dup
+            end
+          end
+        end
+
+        # @param key [String]
+        # @param tools [Array<Hash>]
+        # @return [nil]
+        def write(key, tools)
+          monitor.synchronize do
+            # Re-inserting moves the key to the back, so eviction stays ordered
+            # by write time even when a key is refreshed.
+            entries.delete(key)
+            entries[key] = { tools: tools.deep_dup, stored_at: monotonic, expires_at: monotonic + ttl }
+
+            evict!
+          end
+
+          nil
+        end
+
+        # @param entry [Hash]
+        # @return [Boolean]
+        def expired?(entry) = entry[:expires_at] <= monotonic
+
+        # @return [void]
+        def evict!
+          entries.reject! { |_, entry| expired?(entry) }
+
+          # A Ruby Hash is insertion-ordered, so the front is the oldest write.
+          entries.shift while entries.size > max_entries
+        end
+
+        # @return [Hash] insertion-ordered
+        def entries = @entries ||= {}
+
+        # Reentrant, so a future caller can nest without deadlocking. Created with the class, so two first
+        # callers cannot each build their own.
+        #
+        # @return [Monitor]
+        def monitor = @monitor
+
+        # The monotonic clock, so an entry's lifetime is not affected by the
+        # wall clock moving.
+        #
+        # @return [Float]
+        def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/active_agent/providers/open_ai/_base.rb

@@ -50,7 +50,7 @@ module ActiveAgent
           kwargs = JSON.parse(api_function_call[:arguments], symbolize_names: true) if api_function_call[:arguments]
 
           instrument("tool_call.active_agent", tool_name: name) do
-            tools_function.call(name, **kwargs)
+            call_tool_function(name, **kwargs)
           end
         end
       end

data/lib/active_agent/providers/open_ai/chat_provider.rb

@@ -151,14 +151,15 @@ module ActiveAgent
         # Processes function/tool calls from the API response
         #
         # Executes each tool call and creates tool response messages
-        # for the next iteration of the conversation.
+        # for the next iteration of the conversation. Pushes nothing when a
+        # tool asked the user for input.
         #
         # @param api_function_calls [Array<Hash>] function calls with :type, :id, and :function keys
         # @return [void]
         # @see Base#process_function_calls
         def process_function_calls(api_function_calls)
-          api_function_calls.each do |api_function_call|
-            content = instrument("tool_call.active_agent", tool_name: api_function_call.dig(:function, :name)) do
+          results = dispatch_tool_calls(api_function_calls) do |api_function_call|
+            instrument("tool_call.active_agent", tool_name: api_function_call.dig(:function, :name)) do
               case api_function_call[:type].to_s
               when "function"
                 process_tool_call_function(api_function_call[:function])
@@ -166,7 +167,11 @@ module ActiveAgent
                 fail "Unexpected Tool Call Type: #{api_function_call[:type]}"
               end
             end
+          end
+
+          return unless results
 
+          api_function_calls.zip(results).each do |api_function_call, content|
             # Create tool message using gem's message param class
             message = ::OpenAI::Models::Chat::ChatCompletionToolMessageParam.new(
               role: "tool",
@@ -204,6 +209,20 @@ module ActiveAgent
           [ api_message ]
         end
 
+        # @see InputRequests#tool_call_reference
+        # @param api_function_call [Hash]
+        # @return [Array(String, String)]
+        def tool_call_reference(api_function_call)
+          [ api_function_call[:id].to_s, api_function_call.dig(:function, :name).to_s ]
+        end
+
+        # @see InputRequests#tool_call_arguments
+        # @param api_function_call [Hash]
+        # @return [Hash, String, nil]
+        def tool_call_arguments(api_function_call)
+          parse_tool_call_arguments(api_function_call.dig(:function, :arguments))
+        end
+
         # Extracts function calls from the last message in the stack.
         #
         # @return [Array<Hash>, nil] tool call objects or nil if no tool calls

data/lib/active_agent/providers/open_ai/options.rb

@@ -64,7 +64,7 @@ module ActiveAgent
 
         def resolve_project_id(kwargs)
           kwargs[:project] ||
-            kwargs[:project_id]
+            kwargs[:project_id] ||
             ENV["OPENAI_PROJECT_ID"] ||
             ENV["OPEN_AI_PROJECT_ID"]
         end

data/lib/active_agent/providers/open_ai/responses_provider.rb

@@ -25,6 +25,13 @@ module ActiveAgent
           Responses::RequestType.new
         end
 
+        # The Responses API accepts remote MCP servers, so those are served by
+        # the provider as they always were. A local process cannot be handed to
+        # it, so a `command:` declaration runs client-side instead.
+        #
+        # @return [Array<Symbol>]
+        def mcp_native_transports = [ :url ]
+
         protected
 
         # @see BaseProvider#prepare_prompt_request
@@ -87,8 +94,10 @@ module ActiveAgent
         # - `:"response.output_text.done"` - complete text
         # - `:"response.function_call_arguments.delta"` - function argument updates
         # - `:"response.function_call_arguments.done"` - complete function arguments
+        # - `:"response.reasoning_summary_*"`, `:"response.reasoning_text.*"` -
+        #   reasoning progress, kept from the reasoning item once it is done
         # - `:"response.content_part.done"` - content part completed
-        # - `:"response.output_item.done"` - message or function call completed
+        # - `:"response.output_item.done"` - message, reasoning or function call completed
         # - `:"response.completed"` - response finished
         #
         # @param api_response_event [Hash] streaming chunk with :type key
@@ -125,6 +134,12 @@ module ActiveAgent
           when :"response.function_call_arguments.delta", :"response.function_call_arguments.done"
           # No-Op: Wait for FC to Land
 
+          # -> -> -> Reasoning Progress
+          when :"response.reasoning_summary_part.added", :"response.reasoning_summary_part.done",
+               :"response.reasoning_summary_text.delta", :"response.reasoning_summary_text.done",
+               :"response.reasoning_text.delta", :"response.reasoning_text.done"
+          # No-Op: Wait for the reasoning item to land
+
           # -> -> Content Part Completed [Full Part]
           when :"response.content_part.done"
 
@@ -134,8 +149,9 @@ module ActiveAgent
 
           # Response Completed
           when :"response.completed"
-            # Once we are finished, close out and run tooling callbacks (Recursive)
-            process_prompt_finished
+            # Completion, tool loop included, runs from stream_finished! once
+            # the stream has drained, so each turn's tool calls run once.
+            self.stream_completion_pending = true
           else
             raise "Unexpected Response Chunk Type: #{api_response_event.type}"
           end
@@ -143,8 +159,9 @@ module ActiveAgent
 
         # Processes output item added events from streaming response
         #
-        # Handles message and function_call item types. For messages, adds to stack
-        # with empty content. For function calls, waits for completion event.
+        # Handles message, reasoning and function_call item types. For messages,
+        # adds to stack with empty content. Reasoning items and function calls
+        # wait for their completion event.
         #
         # Required because API returns empty array instead of empty string for
         # initial message content due to serialization bug.
@@ -157,8 +174,8 @@ module ActiveAgent
             # PATCH: API returns an empty array instead of empty string due to a bug in their serialization
             item_hash = Responses::Transforms.gem_to_hash(api_response_event.item).compact_blank
             message_stack << { content: "" }.merge(item_hash)
-          when :function_call
-            # No-Op: Wait for FC to Land (-> response.output_item.done)
+          when :function_call, :reasoning
+            # No-Op: Wait for the item to land (-> response.output_item.done)
           else
             raise "Unexpected Item Type: #{api_response_event.item.type}"
           end
@@ -166,8 +183,10 @@ module ActiveAgent
 
         # Processes output item completion events from streaming response
         #
-        # For function calls, adds completed item to message stack.
-        # For messages, no action needed as content already updated via delta events.
+        # For function calls and reasoning items, adds the completed item to the
+        # message stack, so the next turn sends each reasoning item back with
+        # the function calls it led to. For messages, no action needed as
+        # content already updated via delta events.
         #
         # @param api_response_event [Hash] response chunk with completed :item
         # @return [void]
@@ -175,7 +194,7 @@ module ActiveAgent
           case api_response_event.item.type
           when :message
             # No-Op: Message Up to Date
-          when :function_call
+          when :function_call, :reasoning
             item_hash = Responses::Transforms.gem_to_hash(api_response_event.item)
             message_stack << item_hash
           else
@@ -183,21 +202,25 @@ module ActiveAgent
           end
         end
 
-        # Executes function calls and creates output messages for conversation continuation
+        # Executes function calls and creates output messages for conversation
+        # continuation. Pushes nothing when a call paused for the user.
         #
         # @param api_function_calls [Array<Hash>] function calls with :call_id and :name keys
         # @return [void]
         # @see Base#process_function_calls
         def process_function_calls(api_function_calls)
-          api_function_calls.each do |api_function_call|
-            output = instrument("tool_call.active_agent", tool_name: api_function_call[:name]) do
-              process_tool_call_function(api_function_call).to_json
+          results = dispatch_tool_calls(api_function_calls) do |api_function_call|
+            instrument("tool_call.active_agent", tool_name: api_function_call[:name]) do
+              process_tool_call_function(api_function_call)
             end
+          end
+          return unless results
 
+          api_function_calls.zip(results).each do |api_function_call, result|
             # Create native gem input item for function call output
             message = ::OpenAI::Models::Responses::ResponseInputItem::FunctionCallOutput.new(
               call_id: api_function_call[:call_id],
-              output:
+              output:  result.to_json
             )
 
             # Convert to hash for message_stack
@@ -205,6 +228,36 @@ module ActiveAgent
           end
         end
 
+        # A function_call item's `id` names the item; `call_id` is what its
+        # function_call_output answers.
+        #
+        # @see InputRequests#tool_call_reference
+        # @param api_function_call [Hash]
+        # @return [Array(String, String)]
+        def tool_call_reference(api_function_call)
+          [ api_function_call[:call_id].to_s, api_function_call[:name].to_s ]
+        end
+
+        # @see InputRequests#tool_call_arguments
+        # @param api_function_call [Hash]
+        # @return [Hash, String, nil]
+        def tool_call_arguments(api_function_call)
+          parse_tool_call_arguments(api_function_call[:arguments])
+        end
+
+        # Returns `messages` as the request's `input` items. Serializing the
+        # whole request would shorten a lone user message to a bare string.
+        #
+        # @see InputRequests#serialized_messages
+        # @return [Array<Hash>]
+        def serialized_messages(messages, instructions: nil)
+          parameters = { messages:, instructions: }.compact
+          return [] if parameters.empty?
+
+          input = Responses::Transforms.gem_to_hash(prompt_request_type.cast(parameters).__getobj__)[:input]
+          input.is_a?(String) ? [ { role: "user", content: input } ] : Array(input)
+        end
+
         # Converts OpenAI gem response object to hash for storage.
         #
         # @param api_response [OpenAI::Models::Responses::Response]

data/lib/active_agent/providers/open_router/options.rb

@@ -46,7 +46,10 @@ module ActiveAgent
         # site_url from Rails routes/ActionMailer default_url_options.
         #
         # @param kwargs [Hash] configuration options
-        # @option kwargs [String] :api_key OpenRouter API key
+        # @option kwargs [String] :api_key OpenRouter API key. When neither it nor
+        #   :access_token is given, falls back to OPENROUTER_API_KEY,
+        #   OPEN_ROUTER_API_KEY, OPENROUTER_ACCESS_TOKEN, then OPEN_ROUTER_ACCESS_TOKEN.
+        # @option kwargs [String] :access_token alias for :api_key
         # @option kwargs [String] :app_name application name for rankings
         # @option kwargs [String] :site_url site URL for rankings
         # @return [Options]
@@ -85,7 +88,8 @@ module ActiveAgent
         private
 
         def resolve_api_key(kwargs)
-          kwargs["api_key"] ||
+          kwargs[:api_key] ||
+            kwargs[:access_token] ||
             ENV["OPENROUTER_API_KEY"] ||
             ENV["OPEN_ROUTER_API_KEY"] ||
             ENV["OPENROUTER_ACCESS_TOKEN"] ||

data/lib/active_agent/providers/ruby_llm/messages/_types.rb

@@ -34,8 +34,10 @@ module ActiveAgent
             when Array
               grouped = []
 
+              # Each tool result answers one call by its tool_call_id, so tool
+              # messages are never merged.
               value.each do |message|
-                if grouped.empty? || grouped.last.role != message.role
+                if grouped.empty? || grouped.last.role != message.role || message.role == "tool"
                   grouped << message.deep_dup
                 else
                   grouped.last.content += message.content.deep_dup

data/lib/active_agent/providers/ruby_llm/options.rb

@@ -15,6 +15,11 @@ module ActiveAgent
         # e.g. :vertexai, :gemini, :bedrock). A model ID served by several
         # backends otherwise resolves by RubyLLM's registry preference.
         attribute :platform, :string
+        # Pins which of the backend's wire protocols carries a request
+        # (RubyLLM's protocol:, e.g. :chat_completions or :responses for
+        # OpenAI). ruby_llm 2.x only; without it RubyLLM's own setting
+        # applies, and for OpenAI that defaults to :responses.
+        attribute :protocol, :string
         attribute :temperature, :float
         attribute :max_tokens, :integer