rails_pulse 0.4.2 → 0.5.0.pre.1

data/lib/rails_pulse/mcp/tools/exceptions.rb

@@ -0,0 +1,114 @@
+module RailsPulse
+  module Mcp
+    module Tools
+      class Exceptions < ::MCP::Tool
+        extend Helpers
+
+        tool_name "rails_pulse_exceptions"
+        description "Exception groups captured from web requests and background jobs: one entry per exception " \
+                    "class and app-code location, with its status (open, resolved, ignored), occurrence count, " \
+                    "latest message, and when it first and last fired. Use this to see what is actually raising " \
+                    "right now; rails_pulse_errors only knows which endpoints answered 5xx."
+
+        annotations(
+          read_only_hint: true,
+          destructive_hint: false,
+          open_world_hint: false
+        )
+
+        input_schema(
+          properties: {
+            **Helpers.window_properties("last_7_days"),
+            period: {
+              type: "string",
+              description: "Only groups last seen in this window: 'last_hour', 'last_24_hours', 'last_7_days', " \
+                           "or 'all' for no time filter. Ignored when 'since' or 'until' is given.",
+              default: "last_7_days"
+            },
+            status: {
+              type: "string",
+              description: "Lifecycle filter: 'open' (default), 'resolved', 'ignored', or 'all'",
+              default: "open"
+            },
+            search: {
+              type: "string",
+              description: "Substring match on the exception class or location, e.g. 'RecordNotFound' or 'app/models'"
+            },
+            limit: {
+              type: "integer",
+              description: "Maximum number of groups (1-100)",
+              default: 25
+            }
+          }
+        )
+
+        # `period: "all"` drops the time filter; groups are otherwise limited to
+        # those last seen inside the window.
+        def self.call(period: "last_7_days", status: "open", search: nil, limit: 25, server_context:, **options)
+          respond(server_context) do |client|
+            limit = limit.to_i.clamp(1, 100)
+            all_time = period.to_s == "all" && options[:since].nil? && options[:until].nil?
+            window = all_time ? nil : resolve_window(period: period, since: options[:since], until_time: options[:until])
+
+            params = { limit: limit, offset: 0 }
+            params.merge!(window_params(window)) if window
+            params[:status] = status unless status.to_s == "all"
+            params[:search] = search if search.to_s != ""
+
+            result = client.get("/exceptions", params)
+            groups = (result["data"] || []).map { |g| format_group(g) }
+            total  = result.dig("meta", "total") || groups.size
+
+            {
+              window: window || { period: "all" },
+              status_filter: status,
+              total_groups: total,
+              groups_returned: groups.size,
+              groups: groups,
+              summary: build_summary(groups, total, status),
+              next_steps: build_next_steps(groups)
+            }
+          end
+        end
+
+        private_class_method def self.format_group(group)
+          {
+            id: group["id"],
+            exception_class: group["exception_class"],
+            location: group["location"],
+            message: truncate(group["message"], 300),
+            status: group["status"],
+            occurrence_count: group["occurrence_count"],
+            first_seen_at: group["first_seen_at"],
+            last_seen_at: group["last_seen_at"],
+            resolved_at: group["resolved_at"]
+          }
+        end
+
+        private_class_method def self.build_summary(groups, total, status)
+          label = status.to_s == "all" ? "" : "#{status} "
+          return "No #{label}exception groups found for this period." if groups.empty?
+
+          occurrences = groups.sum { |g| g[:occurrence_count].to_i }
+          loudest = groups.max_by { |g| g[:occurrence_count].to_i }
+          parts = [ "#{total} #{label}exception group(s), #{occurrences} occurrences across the #{groups.size} returned" ]
+          parts << "Most frequent: #{loudest[:exception_class]} at #{loudest[:location] || 'unknown location'} " \
+                   "(#{loudest[:occurrence_count]} occurrences)"
+          parts.join(". ") + "."
+        end
+
+        private_class_method def self.build_next_steps(groups)
+          return [ "Nothing is raising in this window. Widen period or set status: \"all\" to see resolved and ignored groups." ] if groups.empty?
+
+          steps = []
+          latest = groups.max_by { |g| g[:last_seen_at].to_s }
+          steps << "Start with #{latest[:exception_class]} at #{latest[:location] || 'unknown location'}: it fired most recently " \
+                   "(#{latest[:last_seen_at]}). Read the location and message, then open the file at that frame."
+          steps << "Call rails_pulse_deployments for the same period to see whether the first_seen_at of a group lines up with a release."
+          steps << "Call rails_pulse_errors to see which endpoints answered 5xx as a result, and rails_pulse_jobs for failing job classes."
+          steps
+        end
+      end
+    end
+  end
+end

data/lib/rails_pulse/mcp/tools/helpers.rb

@@ -0,0 +1,162 @@
+require "json"
+require "time"
+
+module RailsPulse
+  module Mcp
+    module Tools
+      module Helpers
+        PERIODS = {
+          "last_hour" => 3600,
+          "last_24_hours" => 86_400,
+          "last_7_days" => 604_800
+        }.freeze
+
+        # Raised for a time argument a tool cannot turn into a window. Carries
+        # the correction in its message, so the agent can fix the call rather
+        # than retry it unchanged.
+        class WindowError < ArgumentError; end
+
+        # A trailing Z or ±HH:MM offset.
+        ZONED = /(?:Z|[+-]\d{2}:?\d{2})\z/i
+
+        # ISO 8601: a date, optionally a time, optionally a zone. Anything else
+        # is refused rather than handed to Time.parse, which reads
+        # "last_30_days" as the 30th of this month and "24h" as midnight.
+        ISO8601 = /\A\d{4}-\d{2}-\d{2}(?:[T ]\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?)?(?:Z|[+-]\d{2}:?\d{2})?\z/i
+
+        # The default window when a tool is given neither a period nor bounds.
+        DEFAULT_PERIOD = "last_24_hours".freeze
+
+        # The time arguments every windowed tool accepts. Spliced into each
+        # tool's input_schema so the three stay described identically.
+        def self.window_properties(default_period)
+          {
+            period: {
+              type: "string",
+              description: "Relative window: 'last_hour', 'last_24_hours' or 'last_7_days'. For any other " \
+                           "window pass 'since' and 'until'. Ignored when either is given.",
+              default: default_period
+            },
+            since: {
+              type: "string",
+              description: "Start of the window, ISO 8601 (e.g. '2026-09-24T12:00:00Z'). Read as UTC when no " \
+                           "zone is given. Use with 'until' to pin an exact window that can be compared with another."
+            },
+            until: {
+              type: "string",
+              description: "End of the window, ISO 8601. Read as UTC when no zone is given. Omit to measure up to now."
+            }
+          }
+        end
+
+        # Turns a tool's time arguments into explicit UTC bounds.
+        #
+        # `period` names a relative window and is enough for "how are things
+        # right now". `since`/`until` pin an exact one, which is what makes a
+        # question repeatable: the 24 hours before a deploy stay the same 24
+        # hours however long afterwards they are asked about. Explicit bounds
+        # win when both are given.
+        #
+        # @return [Hash] `:since` and `:until` as ISO 8601 UTC strings (`:until`
+        #   is nil when the window runs to now), plus `:period` describing which
+        #   form was used.
+        def resolve_window(period: nil, since: nil, until_time: nil)
+          from = resolve_start(period, since)
+          to = until_time ? parse_time(until_time, "until") : nil
+
+          if to && from >= to
+            raise WindowError, "'since' (#{from.iso8601}) must be earlier than 'until' (#{to.iso8601})."
+          end
+          if from > Time.now.utc
+            raise WindowError, "'since' (#{from.iso8601}) is in the future, so nothing can have been recorded yet."
+          end
+
+          {
+            since: from.iso8601,
+            until: to&.iso8601,
+            period: since || until_time ? "custom" : (period || DEFAULT_PERIOD)
+          }
+        end
+
+        # A timestamp with no zone is read as UTC, so a window means the same
+        # thing on the agent's machine as on the server.
+        def parse_time(value, name)
+          string = value.to_s.strip
+          raise ArgumentError unless string.match?(ISO8601)
+
+          parsed = Time.parse(string)
+          return parsed.utc if string.match?(ZONED)
+
+          Time.utc(parsed.year, parsed.month, parsed.day, parsed.hour, parsed.min, parsed.sec)
+        rescue ArgumentError, TypeError
+          raise WindowError,
+            "Invalid #{name}: #{value.inspect}. Use an ISO 8601 timestamp such as 2026-09-24T12:00:00Z."
+        end
+
+        # The API's time arguments for a resolved window. `until` is omitted
+        # when the window runs to now, which the API reads as no upper bound.
+        def window_params(window)
+          params = { since: window[:since] }
+          params[:until] = window[:until] if window[:until]
+          params
+        end
+
+        def resolve_start(period, since)
+          return parse_time(since, "since") if since
+
+          seconds = PERIODS[period || DEFAULT_PERIOD]
+          return (Time.now.utc - seconds) if seconds
+
+          # An ISO 8601 period was the documented way to pin a start before
+          # `since` existed, so it is still read as one.
+          return parse_time(period, "period") if period.to_s.strip.match?(ISO8601)
+
+          raise WindowError,
+            "Unknown period #{period.inspect}. Use #{PERIODS.keys.join(', ')}, or pass 'since' and 'until' " \
+            "as ISO 8601 timestamps for any other window."
+        end
+
+        # Every row of a paginated endpoint, for a tool that ranks the rows
+        # itself. Bounded so an unexpectedly large table cannot keep the tool
+        # paging forever.
+        #
+        # @return [Array(Array<Hash>, Hash)] the rows and the first page's response
+        def fetch_all(client, path, params, page_size: 500, max_pages: 20)
+          rows = []
+          first = nil
+          max_pages.times do |page|
+            result = client.get(path, params.merge(limit: page_size, offset: page * page_size))
+            first ||= result
+            batch = result["data"] || []
+            rows.concat(batch)
+            total = result.dig("meta", "total")
+            break if batch.size < page_size || (total && rows.size >= total)
+          end
+          [ rows, first ]
+        end
+
+        def percentile(sorted, pct)
+          return 0 if sorted.empty?
+          k = ((pct / 100.0) * (sorted.size - 1)).ceil
+          sorted[k]
+        end
+
+        def truncate(str, length)
+          str = str.to_s
+          str.length > length ? "#{str[0, length]}..." : str
+        end
+
+        def respond(server_context)
+          payload = yield server_context[:client]
+          ::MCP::Tool::Response.new([ { type: "text", text: JSON.pretty_generate(payload) } ])
+        rescue WindowError => e
+          # The call is malformed rather than the server unreachable, so the
+          # message says how to correct it.
+          ::MCP::Tool::Response.new([ { type: "text", text: e.message } ], error: true)
+        rescue CLI::Client::ApiError => e
+          ::MCP::Tool::Response.new([ { type: "text", text: "Error querying Rails Pulse: #{e.message}" } ], error: true)
+        end
+      end
+    end
+  end
+end

data/lib/rails_pulse/mcp/tools/jobs.rb

@@ -0,0 +1,155 @@
+module RailsPulse
+  module Mcp
+    module Tools
+      class Jobs < ::MCP::Tool
+        extend Helpers
+
+        ERROR_MESSAGE_LENGTH = 200
+
+        # Failed runs fetched for recent_failures. The count reported beside
+        # them is the API's total, not the size of this sample.
+        FAILED_RUN_SAMPLE = 100
+
+        tool_name "rails_pulse_jobs"
+        description "Background job health: failure rates, slow jobs, and recent failures with error classes. " \
+                    "Use this to find failing or slow background jobs."
+
+        annotations(
+          read_only_hint: true,
+          destructive_hint: false,
+          open_world_hint: false
+        )
+
+        input_schema(
+          properties: {
+            **Helpers.window_properties("last_24_hours"),
+            limit: {
+              type: "integer",
+              description: "Maximum number of jobs to return (1-50)",
+              default: 10
+            },
+            job: {
+              type: "string",
+              description: "Restrict to one job class (e.g. 'GenerateReportJob')"
+            }
+          }
+        )
+
+        def self.call(period: "last_24_hours", limit: 10, job: nil, server_context:, **options)
+          respond(server_context) do |client|
+            window = resolve_window(period: period, since: options[:since], until_time: options[:until])
+            limit = limit.to_i.clamp(1, 50)
+
+            # Windowed: the API answers these from summaries so the counts and
+            # durations cover the same period as recent_failures. Every job is
+            # fetched because the API orders by name and the ranking here is
+            # by failure rate; a first page would drop the worst after the
+            # alphabet ran past it.
+            job_params = window_params(window)
+            job_params[:job] = job if job
+            jobs, result = fetch_all(client, "/jobs", job_params)
+            granularity = result.dig("meta", "window", "period_type")
+
+            run_params = window_params(window).merge(status: "failed", limit: FAILED_RUN_SAMPLE)
+            run_params[:job] = job if job
+            runs_result = client.get("/job_runs", run_params)
+            failed_runs = runs_result["data"] || []
+            failed_total = runs_result.dig("meta", "total") || failed_runs.size
+
+            formatted = jobs.map { |j| format_job(j) }
+              .sort_by { |j| [ -j[:failure_rate].to_f, -slowness(j) ] }
+              .first(limit)
+
+            payload = {
+              window: window.merge(granularity ? { summary_period: granularity } : {}),
+              jobs: formatted,
+              failed_runs: failed_total,
+              recent_failures: format_failures(failed_runs),
+              summary: build_summary(formatted, jobs.size, failed_total, failed_runs.size),
+              next_steps: build_next_steps(formatted, failed_runs)
+            }
+            note = formatted.filter_map { |j| j[:percentiles_note] }.first
+            payload[:note] = note if note
+            payload
+          end
+        end
+
+        # The tool always asks for a window, so every figure comes from the
+        # window's `stats`. The job's lifetime counters are never substituted:
+        # a withheld percentile stays nil rather than becoming an all-time one.
+        private_class_method def self.format_job(job)
+          stats = job["stats"] || {}
+          formatted = {
+            name: job["name"],
+            queue: job["queue_name"],
+            runs: stats["runs_count"].to_i,
+            failures: stats["failures_count"].to_i,
+            failure_rate: stats["failure_rate"].to_f.round(1),
+            avg_ms: stats["avg_duration"]&.to_f&.round(1),
+            max_ms: stats["max_duration"]&.to_f&.round(1),
+            p95_ms: stats["p95_duration"]&.to_f&.round(1),
+            p99_ms: stats["p99_duration"]&.to_f&.round(1)
+          }
+          formatted[:percentiles_note] = stats["percentiles_note"] if stats["percentiles_note"]
+          formatted
+        end
+
+        # p95 when the window has one, otherwise the mean.
+        private_class_method def self.slowness(job)
+          (job[:p95_ms] || job[:avg_ms]).to_f
+        end
+
+        private_class_method def self.format_failures(runs)
+          runs.group_by { |r| r["job_name"] || "unknown" }.map do |name, group|
+            latest = group.max_by { |r| r["occurred_at"].to_s }
+            {
+              job: name,
+              count: group.size,
+              error_classes: group.map { |r| r["error_class"] || "unknown" }.tally,
+              latest: {
+                occurred_at: latest["occurred_at"],
+                error_class: latest["error_class"],
+                error_message: truncate(latest["error_message"], ERROR_MESSAGE_LENGTH),
+                attempts: latest["attempts"]
+              }
+            }
+          end.sort_by { |f| -f[:count] }
+        end
+
+        private_class_method def self.build_summary(jobs, job_total, failed_total, failed_sampled)
+          return "No background jobs recorded." if jobs.empty?
+
+          failed = "#{failed_total} failed run(s) in period"
+          failed += " (latest #{failed_sampled} grouped in recent_failures)" if failed_total > failed_sampled
+          parts = [ "#{job_total} job(s) ran, #{failed}" ]
+          worst = jobs.max_by { |j| j[:failure_rate] }
+          parts << "Highest failure rate: #{worst[:name]} (#{worst[:failure_rate]}%)" if worst[:failure_rate] > 0
+          slowest = jobs.max_by { |j| slowness(j) }
+          if slowest
+            label = slowest[:p95_ms] ? "p95 #{slowest[:p95_ms]}ms" : "avg #{slowest[:avg_ms]}ms"
+            parts << "Slowest: #{slowest[:name]} (#{label})"
+          end
+          parts.join(". ") + "."
+        end
+
+        private_class_method def self.build_next_steps(jobs, failed_runs)
+          steps = []
+          if jobs.empty?
+            steps << "No jobs tracked — confirm `config.track_jobs` is enabled in the Rails Pulse initializer."
+          end
+          if failed_runs.any?
+            steps << "Group failures by error_class in recent_failures; a single class dominating usually points at one root cause."
+          end
+          if jobs.any? { |j| j[:failure_rate] > 5 }
+            steps << "Jobs with failure rate above 5% need retry/discard handling reviewed."
+          end
+          if jobs.any? { |j| slowness(j) > 60_000 }
+            steps << "Jobs taking over 60s (p95, or the mean where no p95 is given) may be blocking queues — consider splitting or batching."
+          end
+          steps << "Use rails_pulse_queries to check whether slow jobs are dominated by SQL."
+          steps
+        end
+      end
+    end
+  end
+end

data/lib/rails_pulse/mcp/tools/queries.rb

@@ -0,0 +1,136 @@
+module RailsPulse
+  module Mcp
+    module Tools
+      class Queries < ::MCP::Tool
+        extend Helpers
+
+        SQL_LENGTH = 300
+        MAX_PAGE = 500
+
+        tool_name "rails_pulse_queries"
+        description "Find the most expensive SQL queries for a time period: execution count, average/max/total time, " \
+                    "and N+1 detection. Use this to see which queries are worth optimising."
+
+        annotations(
+          read_only_hint: true,
+          destructive_hint: false,
+          open_world_hint: false
+        )
+
+        input_schema(
+          properties: {
+            **Helpers.window_properties("last_24_hours"),
+            limit: {
+              type: "integer",
+              description: "Maximum number of queries (1-50)",
+              default: 10
+            },
+            sort: {
+              type: "string",
+              description: "Order by 'total_duration' (default), 'avg_duration', 'max_duration', or 'executions'",
+              default: "total_duration"
+            },
+            n_plus_one_only: {
+              type: "boolean",
+              description: "Only return queries flagged as likely N+1",
+              default: false
+            },
+            # rails_pulse_endpoint and rails_pulse_slow_requests hand back an
+            # integer route_id, so the next call passes a number.
+            route: {
+              type: %w[integer string],
+              description: "Restrict to SQL issued while serving one endpoint. A route_id from rails_pulse_routes " \
+                           "or rails_pulse_slow_requests, or a controller action or path to match on."
+            }
+          }
+        )
+
+        def self.call(period: "last_24_hours", limit: 10, sort: "total_duration", n_plus_one_only: false, route: nil, server_context:, **options)
+          respond(server_context) do |client|
+            window = resolve_window(period: period, since: options[:since], until_time: options[:until])
+            limit = limit.to_i.clamp(1, 50)
+            # The N+1 flag is filtered here, not by the API, so fetch the
+            # largest page it allows and keep the first `limit` matches.
+            page = n_plus_one_only ? MAX_PAGE : limit
+            params = window_params(window).merge(sort: sort, limit: page)
+            params[:route] = route if route
+            result = client.get("/queries", params)
+
+            queries = (result["data"] || []).map { |q| format_query(q) }
+            queries = queries.select { |q| q[:n_plus_one][:likely] }.first(limit) if n_plus_one_only
+
+            payload = {
+              window: window,
+              sort: sort,
+              total_queries: result.dig("meta", "total") || queries.size,
+              queries: queries,
+              summary: build_summary(queries),
+              next_steps: build_next_steps(queries)
+            }
+            payload[:route] = route if route
+            payload
+          end
+        end
+
+        # Transaction control repeats within a request by design; it is never
+        # an N+1 however often it appears.
+        TRANSACTION_STATEMENT = /\A(BEGIN|COMMIT|ROLLBACK|SAVEPOINT|RELEASE)\b/i
+
+        private_class_method def self.format_query(query)
+          stats = query["stats"] || {}
+          analysis = query["n_plus_one"] || {}
+          repetition = stats["max_repetition_count"].to_i
+          sql = query["normalized_sql"].to_s.gsub(/\s+/, " ").strip
+          repeated = repetition > 1 && !sql.match?(TRANSACTION_STATEMENT)
+
+          {
+            id: query["id"],
+            sql: truncate(sql, SQL_LENGTH),
+            executions: stats["executions"],
+            avg_duration_ms: stats["avg_duration_ms"],
+            max_duration_ms: stats["max_duration_ms"],
+            total_duration_ms: stats["total_duration_ms"],
+            n_plus_one: {
+              likely: analysis["likely"] == true || repeated,
+              confidence: analysis["confidence"],
+              max_repetition_count: repetition > 0 ? repetition : nil
+            },
+            issue_count: Array(query["issues"]).size,
+            suggestions: Array(query["suggestions"]),
+            # Where the query was issued from, most frequent first, so the
+            # investigation reaches the code rather than stopping at the SQL.
+            source_locations: Array(stats["source_locations"])
+          }
+        end
+
+        private_class_method def self.build_summary(queries)
+          return "No query activity found for this period." if queries.empty?
+
+          top = queries.first
+          n_plus_one = queries.count { |q| q[:n_plus_one][:likely] }
+          parts = [ "Top query by #{top[:executions]} executions / #{top[:total_duration_ms]}ms total: #{truncate(top[:sql], 80)}" ]
+          parts << "#{n_plus_one} likely N+1 quer#{n_plus_one == 1 ? 'y' : 'ies'}" if n_plus_one > 0
+          parts.join(". ") + "."
+        end
+
+        private_class_method def self.build_next_steps(queries)
+          steps = []
+          if queries.any? { |q| q[:n_plus_one][:likely] }
+            steps << "N+1 candidates: find the call site and preload the association (`includes`/`preload`) or batch the lookup."
+          end
+          if queries.any? { |q| q[:avg_duration_ms].to_f > 100 }
+            steps << "Queries averaging over 100ms: check `suggestions` for missing indexes and run EXPLAIN on the normalized SQL."
+          end
+          if queries.any? { |q| q[:executions].to_i > 1000 && q[:avg_duration_ms].to_f < 5 }
+            steps << "Very frequent fast queries add up — consider caching or reducing calls per request."
+          end
+          if queries.any? { |q| q[:source_locations].any? }
+            steps << "source_locations names the file and line each query was issued from — start there rather than searching for the SQL."
+          end
+          steps << "Use rails_pulse_endpoint to see which endpoints are slow and correlate with these queries."
+          steps
+        end
+      end
+    end
+  end
+end

data/lib/rails_pulse/mcp/tools/routes.rb

@@ -0,0 +1,97 @@
+module RailsPulse
+  module Mcp
+    module Tools
+      class Routes < ::MCP::Tool
+        extend Helpers
+
+        tool_name "rails_pulse_routes"
+        description "List the application's tracked routes/endpoints with request volume, average latency, and error " \
+                    "counts for a period. Use this to discover endpoint names before calling rails_pulse_endpoint."
+
+        annotations(
+          read_only_hint: true,
+          destructive_hint: false,
+          open_world_hint: false
+        )
+
+        input_schema(
+          properties: {
+            **Helpers.window_properties("last_7_days"),
+            search: {
+              type: "string",
+              description: "Case-insensitive substring match on path or controller action (e.g. 'checkout')"
+            },
+            limit: {
+              type: "integer",
+              description: "Maximum number of routes (1-100)",
+              default: 50
+            },
+            sort: {
+              type: "string",
+              description: "Order by 'request_count' (default), 'avg_duration', or 'error_count'",
+              default: "request_count"
+            }
+          }
+        )
+
+        def self.call(period: "last_7_days", search: nil, limit: 50, sort: "request_count", server_context:, **options)
+          respond(server_context) do |client|
+            window = resolve_window(period: period, since: options[:since], until_time: options[:until])
+            limit = limit.to_i.clamp(1, 100)
+
+            params = window_params(window).merge(sort: sort, limit: limit)
+            params[:search] = search if search
+            result = client.get("/routes", params)
+
+            routes = (result["data"] || []).map { |r| format_route(r) }
+            routes.select! { |r| matches?(r, search) } if search
+
+            {
+              window: window,
+              sort: sort,
+              total_routes: result.dig("meta", "total") || routes.size,
+              routes: routes,
+              summary: build_summary(routes, search),
+              next_steps: [
+                "Pass a route's controller_action (e.g. 'CheckoutController#create') to rails_pulse_endpoint for a full profile.",
+                "Routes with traffic but no controller_action are usually engine or Rack endpoints."
+              ]
+            }
+          end
+        end
+
+        private_class_method def self.format_route(route)
+          stats = route["stats"] || {}
+          {
+            id: route["id"],
+            http_methods: route["http_methods"],
+            path: route["path"],
+            controller_action: route["controller_action"],
+            request_count: stats["request_count"],
+            avg_duration_ms: stats["avg_duration_ms"],
+            error_count: stats["error_count"],
+            tags: route["tags"]
+          }
+        end
+
+        private_class_method def self.matches?(route, search)
+          term = search.downcase
+          route[:path].to_s.downcase.include?(term) || route[:controller_action].to_s.downcase.include?(term)
+        end
+
+        private_class_method def self.build_summary(routes, search)
+          if routes.empty?
+            return search ? "No routes matching '#{search}' had traffic in this period." : "No routes had traffic in this period."
+          end
+
+          busiest = routes.max_by { |r| r[:request_count].to_i }
+          parts = [ "#{routes.size} route(s) with traffic" ]
+          parts << "Busiest: #{busiest[:controller_action] || busiest[:path]} (#{busiest[:request_count]} requests)"
+          slowest = routes.max_by { |r| r[:avg_duration_ms].to_f }
+          parts << "Slowest: #{slowest[:controller_action] || slowest[:path]} (avg #{slowest[:avg_duration_ms]}ms)" if slowest
+          parts.join(". ") + "."
+        end
+      end
+    end
+  end
+end