actionagent 1.3.0 → 1.5.0

data/app/services/action_agent/evaluation_evidence.rb

@@ -0,0 +1,234 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  # Read-only, owner-scoped facts for the dashboard assistant. Cards and links
+  # come from records, not from model output. Existing runs lack repository and
+  # immutable rubric provenance, so none can establish current-branch behavior.
+  class EvaluationEvidence
+    MAX_EVALUATIONS = 20
+    MAX_CANDIDATES = 10
+    MAX_SCAN_RESULTS = 200
+    MAX_REPORT_RESULTS = 20
+    TEXT_LIMIT = 1200
+    SCORE_LIMIT = 20
+
+    PROVENANCE_CAVEAT = "Historical evidence only: repository, tested commit, tool contract, and fixture snapshots were not recorded. This does not verify current main."
+    RUBRIC_CAVEAT = "Scenario expectations and evaluation criteria are mutable; their current definitions are not a snapshot of the checks used for this result."
+    REPORT_CAVEAT = "The linked report may display current scenario text and configuration. This card uses the recorded replay prompt when available."
+    WEAK_CHECK_CAVEAT = "Recorded scores show only response shape or runtime checks; they do not establish answer correctness."
+    CONTEXT_CAVEAT = "No matching recorded replay from this evaluation's agent supplies prompt context."
+    REDACTED_ERROR = "Recorded error details withheld because they may contain credentials. Open the report for details."
+
+    SHAPE_SCORE_KEYS = %w[response_present response_length min_length latency max_latency_ms token_budget tools_succeeded].freeze
+    EXPECTATION_SCORE_KEYS = %w[expected_tools expected_content forbidden_content].freeze
+
+    def initialize(owner:)
+      @agents = ActionAgent.agents_for(owner)
+    end
+
+    def list_evaluations(agent_id: nil, query: nil, limit: MAX_EVALUATIONS)
+      limit = bounded_limit(limit, MAX_EVALUATIONS)
+      scope = evaluations_scope(agent_id: agent_id)
+      if query.present?
+        pattern = "%#{Evaluation.sanitize_sql_like(query.to_s.first(200).downcase, '!')}%"
+        scope = scope.where("LOWER(#{Evaluation.quoted_table_name}.name) LIKE ? ESCAPE '!'", pattern)
+      end
+      rows = scope.includes(:agent).order(updated_at: :desc, id: :desc).limit(limit + 1).to_a
+      evaluations = rows.first(limit)
+      latest = latest_runs(evaluations.map(&:id))
+      report_runs = EvaluationScenarioResult.where(evaluation_run_id: latest.values.map(&:id)).distinct.pluck(:evaluation_run_id)
+
+      {
+        cards: evaluations.map do |evaluation|
+          run = latest[evaluation.id]
+          {
+            id: "evaluation-#{evaluation.id}", type: "evaluation", title: text(evaluation.name),
+            evaluation_id: evaluation.id, agent_id: evaluation.agent_id, agent_name: text(evaluation.agent.name),
+            path: "/evaluations", latest_run: run && run_summary(run, report: report_runs.include?(run.id)),
+            caveats: [ PROVENANCE_CAVEAT, RUBRIC_CAVEAT ]
+          }
+        end,
+        coverage: { returned: evaluations.size, limit: limit, truncated: rows.size > limit },
+        caveats: [ PROVENANCE_CAVEAT ]
+      }
+    end
+
+    def find_demo_candidates(agent_id: nil, evaluation_id: nil, limit: MAX_CANDIDATES)
+      limit = bounded_limit(limit, MAX_CANDIDATES)
+      evaluations = evaluations_scope(agent_id: agent_id, evaluation_id: evaluation_id)
+      scope = terminal_results(evaluations)
+      # Read newest attempts first, including failures. Filtering to passed
+      # before deduplication would resurrect a pass superseded by a regression.
+      rows = scope.preload(:agent_run, evaluation_run: { evaluation: :agent })
+        .limit(MAX_SCAN_RESULTS + 1).to_a
+      scanned = rows.first(MAX_SCAN_RESULTS)
+      latest = scanned.uniq { |result| [ result.evaluation_scenario_id, result.provider, result.model ] }
+      candidates = latest.select { |result| candidate?(result) }
+
+      {
+        cards: candidates.first(limit).map { |result| result_card(result, type: "demo_candidate") },
+        coverage: {
+          scanned: scanned.size, scan_limit: MAX_SCAN_RESULTS, cohorts: latest.size,
+          eligible: candidates.size, returned: [ candidates.size, limit ].min, limit: limit,
+          truncated: rows.size > MAX_SCAN_RESULTS || candidates.size > limit
+        },
+        caveats: [ PROVENANCE_CAVEAT, RUBRIC_CAVEAT,
+          "Search covers the newest recorded terminal results within the scan limit; untested scenarios and runs without results provide no passing evidence." ]
+      }
+    end
+
+    def read_evaluation_run(evaluation_id:, run_id:)
+      evaluation = evaluations_scope(evaluation_id: evaluation_id).includes(:agent).first!
+      run = evaluation.evaluation_runs.find(run_id)
+      # A long suite's first questions may all pass. Keep failures visible in
+      # the bounded excerpt, then pending and successful cases, rather than
+      # making an error late in the suite impossible for the assistant to read.
+      rows = run.scenario_results.preload(:agent_run).order(result_priority, :id).limit(MAX_REPORT_RESULTS + 1).to_a
+      results = rows.first(MAX_REPORT_RESULTS)
+      # Avoid fetching the same parent and agent for every result card.
+      results.each { |result| result.association(:evaluation_run).target = run }
+      run.association(:evaluation).target = evaluation
+
+      {
+        cards: [ run_summary(run, report: results.any?).merge(
+          id: "evaluation-run-#{run.id}", type: "evaluation_run", title: "#{text(evaluation.name)} · run #{run.id}",
+          agent_id: evaluation.agent_id, agent_name: text(evaluation.agent.name),
+          caveats: [ PROVENANCE_CAVEAT, RUBRIC_CAVEAT, REPORT_CAVEAT ]
+        ) ] + results.map { |result| result_card(result, type: "evaluation_result") },
+        coverage: {
+          scanned: results.size, limit: MAX_REPORT_RESULTS, truncated: rows.size > MAX_REPORT_RESULTS,
+          selection: "failures_first", recorded_status_counts: run.scenario_results.group(:status).count
+        },
+        caveats: [ PROVENANCE_CAVEAT, RUBRIC_CAVEAT, REPORT_CAVEAT ]
+      }
+    end
+
+    private
+
+    def evaluations_scope(agent_id: nil, evaluation_id: nil)
+      agents = agent_id.present? ? @agents.where(id: @agents.find(agent_id).id) : @agents
+      scope = Evaluation.where(agent_id: agents.select(:id))
+      return scope if evaluation_id.blank?
+
+      scope.where(id: scope.find(evaluation_id).id)
+    end
+
+    def latest_runs(evaluation_ids)
+      return {} if evaluation_ids.empty?
+
+      table = EvaluationRun.quoted_table_name
+      EvaluationRun.where(evaluation_id: evaluation_ids).where(
+        "#{table}.id = (SELECT latest.id FROM #{table} latest WHERE latest.evaluation_id = #{table}.evaluation_id ORDER BY latest.created_at DESC, latest.id DESC LIMIT 1)"
+      ).index_by(&:evaluation_id)
+    end
+
+    def terminal_results(evaluations)
+      runs = EvaluationRun.where(evaluation_id: evaluations.select(:id), status: [ :complete, :failed ])
+      run_table = EvaluationRun.arel_table
+      EvaluationScenarioResult.joins(:evaluation_run)
+        .where(evaluation_run_id: runs.select(:id), status: [ :passed, :failed, :errored ])
+        .order(run_table[:created_at].desc, run_table[:id].desc, EvaluationScenarioResult.arel_table[:id].desc)
+    end
+
+    def result_priority
+      statuses = EvaluationScenarioResult.statuses
+      Arel::Nodes::Case.new(EvaluationScenarioResult.arel_table[:status])
+        .when(statuses.fetch("errored")).then(0)
+        .when(statuses.fetch("failed")).then(1)
+        .when(statuses.fetch("pending")).then(2)
+        .else(3)
+    end
+
+    def linked_replay(result)
+      replay = result.agent_run
+      return unless replay && replay.agent_id == result.evaluation_run.evaluation.agent_id
+      return if replay.input_prompt.blank?
+
+      replay
+    end
+
+    def candidate?(result)
+      replay = linked_replay(result)
+      result.passed? && result.output.present? && result.error_message.blank? && replay&.complete? &&
+        result.provider != "mock" && replay.output_metadata&.dig("provider") != "mock"
+    end
+
+    def result_card(result, type:)
+      run = result.evaluation_run
+      replay = linked_replay(result)
+      strength = check_strength(result)
+      caveats = [ PROVENANCE_CAVEAT, RUBRIC_CAVEAT, REPORT_CAVEAT ]
+      caveats << CONTEXT_CAVEAT unless replay
+      caveats << "The replay did not record its instructions; the current agent instructions are not historical evidence." if replay && instructions_digest(replay).nil?
+      caveats << "This evaluation run did not complete successfully; this result covers only its own recorded replay." unless run.complete?
+      caveats << "The mock provider produces simulated test output, not real model evidence." if result.provider == "mock" || replay&.output_metadata&.dig("provider") == "mock"
+      caveats << WEAK_CHECK_CAVEAT if strength == "shape_or_runtime_checks_only"
+      caveats << "Recorded score names do not establish the rubric's meaning or strength." if strength == "unknown_rubric"
+
+      {
+        id: "evaluation-result-#{result.id}", type: type,
+        title: replay ? text(replay.input_prompt) : "Recorded result #{result.id}",
+        evaluation_id: run.evaluation_id, run_id: run.id, result_id: result.id,
+        agent_id: run.evaluation.agent_id, agent_name: text(run.evaluation.agent.name),
+        agent_run_id: replay&.id, replay_status: replay&.status, scenario_id: result.evaluation_scenario_id,
+        path: "/evaluations/#{run.evaluation_id}/runs/#{run.id}/report",
+        report_path: "/api/evaluations/#{run.evaluation_id}/runs/#{run.id}/report",
+        status: result.status, evidence_status: candidate?(result) ? "historical_pass" : "recorded_result",
+        recorded_prompt: replay && text(replay.input_prompt), output_excerpt: text(result.output),
+        prompt_truncated: replay ? replay.input_prompt.length > TEXT_LIMIT : false,
+        output_truncated: result.output.to_s.length > TEXT_LIMIT,
+        provider: text(result.provider), model: text(result.model), recorded_at: result.created_at&.iso8601,
+        completed_at: run.completed_at&.iso8601, score: result.score,
+        recorded_scores: bounded_scores(result.scores), check_strength: strength,
+        instructions_digest: instructions_digest(replay),
+        tool_names: result.tool_names.first(20).map { |name| text(name, limit: 100) },
+        fault: text(result.fault), error: safe_error(result.error_message), recommendation: text(result.recommendation),
+        caveats: caveats
+      }
+    end
+
+    def run_summary(run, report: false)
+      {
+        evaluation_id: run.evaluation_id, run_id: run.id, status: run.status,
+        samples_evaluated: run.samples_evaluated, samples_passed: run.samples_passed,
+        created_at: run.created_at&.iso8601, completed_at: run.completed_at&.iso8601,
+        error: safe_error(run.error_message),
+        path: report ? "/evaluations/#{run.evaluation_id}/runs/#{run.id}/report" : "/evaluations"
+      }
+    end
+
+    def check_strength(result)
+      keys = result.scores.to_h.keys.map(&:to_s)
+      return "expectation_scores_recorded" if (keys & EXPECTATION_SCORE_KEYS).any?
+      return "shape_or_runtime_checks_only" if keys.any? && (keys - SHAPE_SCORE_KEYS).empty?
+
+      "unknown_rubric"
+    end
+
+    # Stored exceptions are arbitrary provider text, sometimes including keys,
+    # authenticated URLs or entire request bodies. Keep status/fault categories
+    # and the report link, but never export the exception to another provider.
+    def safe_error(value)
+      REDACTED_ERROR if value.present?
+    end
+
+    def bounded_scores(scores)
+      scores.to_h.first(SCORE_LIMIT).to_h.transform_keys { |key| text(key, limit: 100) }.transform_values do |value|
+        value.is_a?(Numeric) ? value : text(value, limit: 100)
+      end
+    end
+
+    def instructions_digest(replay)
+      instructions = replay&.output_metadata&.dig("instructions")
+      Digest::SHA256.hexdigest(instructions) if instructions.is_a?(String) && instructions.present?
+    end
+
+    def bounded_limit(value, maximum)
+      value.to_i.clamp(1, maximum)
+    end
+
+    def text(value, limit: TEXT_LIMIT)
+      value&.to_s&.first(limit)
+    end
+  end
+end

data/app/services/action_agent/evaluation_runner_service.rb

@@ -417,11 +417,21 @@ module ActionAgent
       PROMPT
     end
 
+    # The judge answers with a JSON number, so "9e-2" is 0.09; a digit-only
+    # regex read that as 9 and clamped a near-zero score to a perfect 1.0.
+    # Mirrors ActiveAgent::Evals::Judge#parse_score, which is private there
+    # and may be the older, unfixed one when the host pins activeagent 1.4.0.
     def parse_judge_score(content)
-      match = content.to_s.match(/"score"\s*:\s*(\d+(?:\.\d+)?)/)
-      return nil unless match
+      json = content.to_s[/\{.*\}/m]
+      return nil unless json
+
+      parsed = JSON.parse(json)
+      value = parsed.is_a?(Hash) ? parsed["score"] : nil
+      return nil unless value.is_a?(Numeric) && value.finite?
 
-      match[1].to_f.clamp(0.0, 1.0)
+      value.to_f.clamp(0.0, 1.0)
+    rescue JSON::ParserError
+      nil
     end
 
     # The judge needs real provider credentials; scoring with the mock

data/app/services/action_agent/evaluation_tool_resolver.rb

@@ -72,6 +72,14 @@ module ActionAgent
       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
@@ -89,7 +97,7 @@ module ActionAgent
     end
 
     # normalized key => the display name a configured hash entry carries
-    # alongside its key ({"key" => "sparkle", "name" => "Sparkle Match"}).
+    # 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?)
@@ -103,7 +111,7 @@ module ActionAgent
     end
 
     # bare tool name => server key, from configured entries that list the
-    # tools they serve ({"name" => "sparkle", "tools" => ["search_slots"]}),
+    # 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|

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_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