actionagent 1.2.2 → 1.5.0

data/app/services/action_agent/evaluation_tool_resolver.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  # Names the MCP server behind a tool an evaluation run needs, for the
+  # report's fix items (ActiveAgent::Evals::Report#fix_items): a scenario
+  # that expected +search_slots+ and never got it is fixed by enabling the
+  # server that serves it, and the item can only say so — and deep-link to
+  # MCP Services — when something here can name that server.
+  #
+  # Resolution follows the order ToolDiscovery attributes traffic in: an
+  # explicit +mcp__server__tool+ namespace wins because the name said so,
+  # then MCPCatalog's hints for the bare names of well-known servers, then
+  # the servers the agent itself declares in +mcp_servers+ when one of them
+  # lists the tool. Nothing here reads telemetry: the resolver runs inside
+  # the request that serializes a run, and every lookup is a constant or a
+  # single agent attribute.
+  #
+  # The status is what the fix item's action turns on:
+  #
+  #   "enabled"   — the agent's mcp_servers configuration names the server
+  #   "available" — the catalog (built-in or ActionAgent.mcp_catalog) knows
+  #                 the server and the agent has not enabled it
+  #   nil         — the namespace named a server nothing here knows; the
+  #                 report renders that as "unknown"
+  #
+  # @example
+  #   resolver = EvaluationToolResolver.new(agent)
+  #   resolver.call("browser_navigate")
+  #   # => { "key" => "playwright", "name" => "Playwright", "status" => "available" }
+  class EvaluationToolResolver
+    ENABLED = "enabled"
+    AVAILABLE = "available"
+
+    attr_reader :agent
+
+    # @param agent [ActionAgent::Agent, nil] the agent the run evaluated; nil
+    #   resolves against the catalog alone
+    def initialize(agent)
+      @agent = agent
+    end
+
+    # The Report's +tool_resolver+ contract.
+    #
+    # @param tool_name [String, Symbol] a tool name as a scenario expected it
+    #   or the model called it
+    # @return [Hash, nil] +{ "key", "name", "status" }+, or nil when no
+    #   server can be named for the tool
+    def call(tool_name)
+      key = server_key_for(tool_name)
+      return nil if key.nil?
+
+      { "key" => key, "name" => display_name_for(key), "status" => status_for(key) }
+    end
+
+    # @param tool_name [String, Symbol]
+    # @return [String, nil] the server key the tool belongs to
+    def server_key_for(tool_name)
+      name = tool_name.to_s.strip
+      return nil if name.blank?
+
+      ActiveAgent::Telemetry::ToolOrigin.server_for(name).presence ||
+        MCPCatalog.server_for_tool(name).presence ||
+        configured_tools[name]
+    end
+
+    # @param key [String] a server key
+    # @return [String, nil] ENABLED, AVAILABLE, or nil when unknown
+    def status_for(key)
+      return ENABLED if configured_keys.include?(normalize(key))
+      return AVAILABLE if MCPCatalog.find(key)
+
+      nil
+    end
+
+    # The server keys the agent declares, normalized. Callers that need to know
+    # what an agent is wired to — rather than where one tool lives — read this.
+    #
+    # @return [Array<String>]
+    def declared_server_keys
+      configured_keys.to_a
+    end
+
+    private
+
+    # The catalog's name when it has one; otherwise the name the agent's
+    # own configuration gives the server, and the key as a last resort
+    # (which is what MCPCatalog.display_name falls back to as well).
+    def display_name_for(key)
+      return MCPCatalog.display_name(key) if MCPCatalog.find(key)
+
+      configured_names[normalize(key)] || MCPCatalog.display_name(key)
+    end
+
+    # Server keys the agent declares, normalized for comparison.
+    def configured_keys
+      @configured_keys ||= configured_entries.filter_map { |entry| normalize(entry_key(entry)) }.to_set
+    end
+
+    # normalized key => the display name a configured hash entry carries
+    # alongside its key ({"key" => "booking", "name" => "Booking Service"}).
+    def configured_names
+      @configured_names ||= configured_entries.each_with_object({}) do |entry, map|
+        next unless entry.respond_to?(:key?)
+
+        key = normalize(entry_key(entry))
+        name = (entry["name"] || entry[:name]).to_s.strip
+        next if key.nil? || name.blank? || name.downcase == key
+
+        map[key] ||= name
+      end
+    end
+
+    # bare tool name => server key, from configured entries that list the
+    # tools they serve ({"name" => "booking", "tools" => ["search_slots"]}),
+    # in the catalog's own +tool_hints+ spelling or as tool hashes.
+    def configured_tools
+      @configured_tools ||= configured_entries.each_with_object({}) do |entry, map|
+        next unless entry.respond_to?(:key?)
+
+        key = entry_key(entry)
+        next if key.nil?
+
+        Array(entry["tools"] || entry[:tools] || entry["tool_hints"] || entry[:tool_hints]).each do |tool|
+          name = (tool.respond_to?(:key?) ? tool["name"] || tool[:name] : tool).to_s.strip
+          map[name] ||= key unless name.blank?
+        end
+      end
+    end
+
+    # The agent's mcp_servers as a list of entries. Agents store an Array of
+    # bare names or builder hashes, but an agent seeded from an older
+    # template carries a top-level Hash keyed by server name
+    # ({"playwright" => {"command" => ...}}) — the same shape ToolDiscovery
+    # tolerates — whose values become entries carrying that key.
+    def configured_entries
+      @configured_entries ||= begin
+        servers = agent&.mcp_servers
+
+        if servers.is_a?(Hash)
+          servers.map do |key, value|
+            value.respond_to?(:key?) ? value.to_h.stringify_keys.merge("key" => key.to_s) : key.to_s
+          end
+        else
+          Array(servers)
+        end
+      end
+    end
+
+    # An entry names its server as a bare string, or under +key+ or +name+
+    # in a builder hash. Anything else (a stray Array, a number) is skipped.
+    def entry_key(entry)
+      return entry.to_s.strip.presence if entry.is_a?(String) || entry.is_a?(Symbol)
+      return nil unless entry.respond_to?(:key?)
+
+      (entry["key"] || entry[:key] || entry["name"] || entry[:name]).to_s.strip.presence
+    end
+
+    def normalize(key)
+      key.to_s.strip.downcase.presence
+    end
+  end
+end

data/app/services/action_agent/mcp_catalog.rb

@@ -19,7 +19,7 @@ module ActionAgent
   # shows up in the MCP Services view (as +known: false+) the moment a
   # namespaced tool call from it is ingested. The catalog only adds names,
   # descriptions, and the ability to launch.
-  class McpCatalog
+  class MCPCatalog
     # Whether a server can be started inside a sandbox session. Servers that
     # need workspace-specific credentials (github, slack, postgres) are
     # listable and attributable but not launchable from the dashboard — there
@@ -156,7 +156,12 @@ module ActionAgent
         sandbox: false,
         first_party: true,
         requires_credentials: [ "Platform API key" ],
-        tool_hints: %w[call_agent list_agents]
+        # No tool_hints: the facade's tools are run_<slug> (one per agent, see
+        # Api::MCPController#tools_list), which no static list can name. The
+        # old hints advertised call_agent and list_agents, which the facade
+        # never exposed, and would have misattributed an agent-defined tool
+        # of either name to this server.
+        tool_hints: []
       }
     ].freeze
 
@@ -172,11 +177,12 @@ module ActionAgent
     end.freeze
 
     class << self
-      # Every catalog entry, as API-shaped hashes.
+      # Every catalog entry — built-ins plus the host's
+      # +ActionAgent.mcp_catalog+ registrations — as API-shaped hashes.
       #
       # @return [Array<Hash>]
       def all
-        SERVERS.map { |server| present(server) }
+        entries.map { |server| present(server) }
       end
 
       # Entries that can be started inside a sandbox session.
@@ -189,14 +195,21 @@ module ActionAgent
       # @param key [String, Symbol]
       # @return [Hash, nil] the catalog entry, or nil when unknown
       def find(key)
-        entry = BY_KEY[key.to_s]
+        entry = index[key.to_s]
         present(entry) if entry
       end
 
+      # Every catalog key, built-ins first.
+      #
+      # @return [Array<String>]
+      def keys
+        entries.map { |server| server[:key] }
+      end
+
       # @param key [String, Symbol]
       # @return [Boolean] whether the server can be started in a sandbox
       def launchable?(key)
-        BY_KEY[key.to_s]&.fetch(:sandbox, false) || false
+        index[key.to_s]&.fetch(:sandbox, false) || false
       end
 
       # The catalog server a bare (non-namespaced) tool name belongs to.
@@ -208,7 +221,7 @@ module ActionAgent
       # @param tool_name [String, Symbol]
       # @return [String, nil] the server key
       def server_for_tool(tool_name)
-        TOOL_HINTS[tool_name.to_s]
+        tool_hints[tool_name.to_s]
       end
 
       # The display name for a server key, falling back to the key itself for
@@ -217,11 +230,36 @@ module ActionAgent
       # @param key [String, Symbol]
       # @return [String]
       def display_name(key)
-        BY_KEY[key.to_s]&.fetch(:name) || key.to_s
+        index[key.to_s]&.[](:name) || key.to_s
       end
 
       private
 
+      # Built-ins plus host registrations, deduplicated by key (first
+      # declaration wins, so a built-in keeps its key). Derived per call
+      # rather than memoized: the host list is tiny and tests reconfigure it.
+      def entries
+        (SERVERS + host_entries).uniq { |server| server[:key] }
+      end
+
+      def host_entries
+        Array(ActionAgent.mcp_catalog).filter_map do |entry|
+          normalized = entry.to_h.symbolize_keys
+          normalized[:key] = normalized[:key].to_s
+          normalized unless normalized[:key].blank?
+        end
+      end
+
+      def index
+        entries.index_by { |server| server[:key] }
+      end
+
+      def tool_hints
+        entries.each_with_object({}) do |server, map|
+          Array(server[:tool_hints]).each { |tool| map[tool.to_s] ||= server[:key] }
+        end
+      end
+
       # Drops the internal-only tool_hints and normalizes optional keys so
       # every entry serializes with the same shape.
       def present(server)

data/app/services/action_agent/mcp_client.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "resolv"
+require "uri"
+require "json"
+
+module ActionAgent
+  # Speaks Streamable HTTP MCP: initialize once per client, then call tools
+  # under the session id the server hands back. One instance per server url.
+  #
+  # A server answers as plain JSON or as an SSE stream whose data: lines carry
+  # the JSON-RPC response; both are accepted.
+  class MCPClient
+    OPEN_TIMEOUT_SECONDS = 5
+    READ_TIMEOUT_SECONDS = 60
+
+    class Error < StandardError; end
+
+    def initialize(url:, label: nil)
+      @uri = URI(url)
+      @label = label.presence || @uri.host
+      @mutex = Mutex.new
+    end
+
+    # The server's own tool definitions, as the provider expects them:
+    # { name:, description:, parameters: }. An MCP server describes its tools
+    # in tools/list, so the model is told about them in the server's words
+    # rather than a copy kept in the dashboard.
+    def list_tools
+      ensure_session!
+      response = post({ jsonrpc: "2.0", id: next_id, method: "tools/list", params: {} }, session: @session_id)
+      Array(response.dig("result", "tools")).map do |tool|
+        {
+          name: tool["name"],
+          description: tool["description"].to_s,
+          parameters: tool["inputSchema"] || { type: "object", properties: {} }
+        }
+      end
+    end
+
+    # Returns { text:, is_error: } — the tool result's text content.
+    def call_tool(name, arguments = {})
+      Rails.logger.debug("[MCPClient] call #{name} args=#{arguments.inspect[0, 200]}")
+      ensure_session!
+      response = post(
+        { jsonrpc: "2.0", id: next_id, method: "tools/call",
+          params: { name: name, arguments: arguments } },
+        session: @session_id
+      )
+      result = response["result"]
+      unless result
+        Rails.logger.warn("[MCPClient] #{name} unexpected response: #{response.inspect[0, 500]}")
+        raise Error, (response.dig("error", "message") || "empty MCP response")
+      end
+
+      text = Array(result["content"]).filter_map { |block| block["text"] }.join("\n")
+      { text: text, is_error: result["isError"] ? true : false }
+    rescue Errno::ECONNREFUSED, Errno::EHOSTUNREACH, Net::OpenTimeout, SocketError => e
+      raise Error, "MCP server #{@label} unreachable at #{@uri} (#{e.class})"
+    end
+
+    private
+
+    # Opens the session once. A server that keeps per-session state answers
+    # initialize with an Mcp-Session-Id and expects it on every later request;
+    # a stateless server (the shape a multi-worker Rails host serves) returns
+    # none, and later requests carry no session header. Both are the protocol's
+    # own contract, so an absent id is not an error — @initialized records that
+    # the handshake happened either way.
+    def ensure_session!
+      @mutex.synchronize do
+        next if @initialized
+
+        _body, response = post_raw(
+          { jsonrpc: "2.0", id: next_id, method: "initialize",
+            params: { protocolVersion: "2025-03-26", capabilities: {},
+                      clientInfo: { name: "activeagents", version: "1.0" } } }
+        )
+        @session_id = response["mcp-session-id"].presence
+        @initialized = true
+
+        post({ jsonrpc: "2.0", method: "notifications/initialized" }, session: @session_id)
+      end
+    end
+
+    def post(payload, session: nil)
+      body, _response = post_raw(payload, session: session)
+      body
+    end
+
+    def post_raw(payload, session: nil)
+      # Tool calls run inside the provider SDK's streaming enumerator — a
+      # fiber, where Net::HTTP reads of SSE bodies misbehave (headers arrive,
+      # body comes back empty). A dedicated thread always does real blocking
+      # IO outside any fiber/scheduler context.
+      Thread.new { blocking_post_raw(payload, session: session) }.value
+    end
+
+    def blocking_post_raw(payload, session: nil)
+      http = Net::HTTP.new(@uri.host, @uri.port)
+      # Without this an https:// endpoint is sent as plaintext to port 443.
+      http.use_ssl = @uri.scheme == "https"
+      # Container->host bridge hostnames (host.orb.internal) publish an IPv6
+      # address whose path doesn't reach the server; dual-stack connects then
+      # fail intermittently. Pin to IPv4 while keeping the Host header.
+      if (ipv4 = ipv4_address)
+        http.ipaddr = ipv4
+      end
+      http.open_timeout = OPEN_TIMEOUT_SECONDS
+      http.read_timeout = READ_TIMEOUT_SECONDS
+      request = Net::HTTP::Post.new(@uri.request_uri)
+      request["Content-Type"] = "application/json"
+      request["Accept"] = "application/json, text/event-stream"
+      request["Mcp-Session-Id"] = session if session
+      request.body = payload.to_json
+
+      response = http.request(request)
+      Rails.logger.debug(
+        "[MCPClient] #{payload[:method]} -> #{response.code} " \
+        "ct=#{response['Content-Type']} bytes=#{response.body.to_s.bytesize} session=#{session ? 'yes' : 'no'}"
+      )
+      unless response.code.to_i.between?(200, 299)
+        Rails.logger.warn("[MCPClient] HTTP #{response.code}: #{response.body.to_s[0, 300]}")
+        raise Error, "MCP server returned HTTP #{response.code}"
+      end
+
+      parsed = parse_body(response)
+      if parsed.empty? && payload[:id]
+        Rails.logger.warn("[MCPClient] unparsed body (#{response['Content-Type']}): #{response.body.to_s[0, 500]}")
+      end
+      [ parsed, response ]
+    end
+
+    # Streamable HTTP answers as plain JSON or as an SSE stream whose data:
+    # lines carry the JSON-RPC response — accept both.
+    def parse_body(response)
+      body = response.body.to_s
+      return {} if body.empty?
+
+      if response["Content-Type"].to_s.include?("text/event-stream")
+        body.lines
+            .select { |line| line.start_with?("data:") }
+            .filter_map { |line| JSON.parse(line.delete_prefix("data:").strip) rescue nil }
+            .find { |json| json["result"] || json["error"] } || {}
+      else
+        # A notification carries no id, and a server may answer it with a bare
+        # `null` body — JSON, but not an object.
+        JSON.parse(body) || {}
+      end
+    rescue JSON::ParserError
+      {}
+    end
+
+    def ipv4_address
+      return @ipv4_address if defined?(@ipv4_address)
+
+      @ipv4_address = Resolv.getaddresses(@uri.host).find { |address| address =~ Resolv::IPv4::Regex }
+    rescue Resolv::ResolvError
+      @ipv4_address = nil
+    end
+
+    def next_id
+      @id = (@id || 0) + 1
+    end
+  end
+end

data/app/services/action_agent/mcp_recording_middleware.rb

@@ -7,7 +7,7 @@ module ActionAgent
   # to a SessionRecording for playback and debugging.
   #
   # Usage:
-  #   middleware = McpRecordingMiddleware.new(session_recording: recording)
+  #   middleware = MCPRecordingMiddleware.new(session_recording: recording)
   #
   #   # Process a tool call
   #   result = middleware.intercept(tool_call) do
@@ -15,7 +15,7 @@ module ActionAgent
   #     mcp_client.call_tool(tool_call)
   #   end
   #
-  class McpRecordingMiddleware
+  class MCPRecordingMiddleware
     # Map of Playwright MCP tool names to our action types
     PLAYWRIGHT_TOOLS = {
       "browser_navigate" => "navigate",

data/app/services/action_agent/mcp_tool_dispatcher.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  # Routes a tool call to the MCP server that serves it.
+  #
+  # An agent names the servers it uses in +mcp_servers+, and a catalog entry
+  # carries the url to reach one over HTTP. A tool the agent's servers claim is
+  # called there; anything else returns nil, and the caller falls back to the
+  # engine's own AgentToolbox.
+  #
+  # Only HTTP transports are dispatchable. A stdio server runs as a child
+  # process of whatever launched it, so the dashboard has no address to call —
+  # those stay listable and attributable without being callable.
+  class MCPToolDispatcher
+    HTTP_TRANSPORTS = %w[http streamable_http sse].freeze
+
+    def initialize(agent)
+      @agent = agent
+      @resolver = EvaluationToolResolver.new(agent)
+      @clients = {}
+    end
+
+    # Whether this tool belongs to one of the agent's own reachable servers.
+    def dispatchable?(tool_name)
+      endpoint_for(tool_name).present?
+    end
+
+    # Whether the agent names any server the dashboard can call. An agent with
+    # none has nothing to execute beyond the engine's own toolbox.
+    def any_reachable_server?
+      resolver.declared_server_keys.any? do |key|
+        entry = MCPCatalog.find(key)
+        entry && entry[:transport].to_s.in?(HTTP_TRANSPORTS) && entry[:url].present?
+      end
+    end
+
+    # Calls the tool on its server. Returns the same shape AgentToolbox
+    # produces for a text result, or an { error: } hash when the server
+    # refuses — a failing tool is a result to score, not an exception to
+    # abort the run.
+    #
+    # @return [Hash, nil] nil when no configured server claims the tool
+    def call(tool_name, arguments = {})
+      endpoint = endpoint_for(tool_name)
+      return nil unless endpoint
+
+      result = client_for(endpoint).call_tool(tool_name.to_s, arguments)
+      return { error: "#{tool_name} failed: #{result[:text]}" } if result[:is_error]
+
+      { text: result[:text] }
+    rescue MCPClient::Error => e
+      { error: "#{tool_name} failed: #{e.message}" }
+    end
+
+    # Tool definitions from every reachable server the agent declares, in the
+    # shape tool_schemas hands the provider. A server that cannot be reached
+    # contributes nothing rather than failing the run — the tools it serves
+    # then simply are not offered, and a scenario expecting them fails with a
+    # fault naming them.
+    def tool_definitions
+      resolver.declared_server_keys.flat_map do |key|
+        entry = MCPCatalog.find(key)
+        next [] unless entry && entry[:transport].to_s.in?(HTTP_TRANSPORTS) && entry[:url].present?
+
+        begin
+          client_for(entry).list_tools
+        rescue MCPClient::Error => e
+          Rails.logger.warn("[MCPToolDispatcher] #{key} tools/list failed: #{e.message}")
+          []
+        end
+      end
+    end
+
+    private
+
+    attr_reader :agent, :resolver
+
+    # The catalog entry for the server that serves this tool, but only when the
+    # agent configured that server and the entry carries an http url. Scoping to
+    # the agent's own servers is what keeps one agent's tools from reaching
+    # another's.
+    def endpoint_for(tool_name)
+      key = resolver.server_key_for(tool_name)
+      return nil if key.blank?
+      return nil unless resolver.status_for(key) == EvaluationToolResolver::ENABLED
+
+      entry = MCPCatalog.find(key)
+      return nil unless entry && entry[:transport].to_s.in?(HTTP_TRANSPORTS)
+      return nil if entry[:url].blank?
+
+      entry
+    end
+
+    # One client per server for the life of this dispatcher, so a run's tool
+    # calls share the MCP session the first call opens.
+    def client_for(entry)
+      @clients[entry[:key]] ||= MCPClient.new(url: absolute_url(entry[:url]), label: entry[:name] || entry[:key])
+    end
+
+    # A host registers its own servers with a path ("/mcp/diagnostic"), since it
+    # does not know the origin it will be served under. ACTIONAGENT_MCP_ORIGIN
+    # names that origin; without it a relative path is not reachable.
+    def absolute_url(url)
+      return url if url.to_s.start_with?("http://", "https://")
+
+      origin = ENV["ACTIONAGENT_MCP_ORIGIN"].presence
+      raise MCPClient::Error, "set ACTIONAGENT_MCP_ORIGIN to reach #{url}" if origin.blank?
+
+      # URI.join, not File.join: a path is a URL reference, and only URI
+      # resolves one against an origin that carries its own path.
+      URI.join(origin, url).to_s
+    rescue URI::Error => e
+      raise MCPClient::Error, "ACTIONAGENT_MCP_ORIGIN #{origin.inspect} cannot reach #{url}: #{e.message}"
+    end
+  end
+end