debug-agent 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 94cb18c1904795fb713e2486d5f6d16e1bbce1a72d1820dd4122b2b7bc672a4d
-  data.tar.gz: 8cf474737f8b84aa5f2a20e5d07f13a02c7345df6805d6b075f72bbb5175fc4f
+  metadata.gz: f71863664d8e95b34f553c692cfc6de2328151f3496dc5bb92ba309232dc3b52
+  data.tar.gz: ab521965229d38b7e8a2ae4fd56a466170219865863573bad59fbe8676f14ce6
 SHA512:
-  metadata.gz: 48c72eaf044cb325c3d8cb9e5ddc5afabbf85f5830e675795e8afb34182db5eb381f90ce913af411b4cf4acb662f82bf23373f2c12785e3dcee0a2491624e2a6
-  data.tar.gz: 20e31311478fd6e5a54e0f693ce5a3cddc27952e5816a56082050bf17e77e4b19aba10d74bde0e95689765ec9e851228c0921724bb566f7609848ab76a844d79
+  metadata.gz: 01edd9b04e2c7054f6f247536eb85af48db98eb6c6367b4d863ea477b49388b347ad1a78d1758548caf965f483f10b432d979f397af8947e482ab3283104e0b6
+  data.tar.gz: cf20b7101a695433ddc35d6e4654d99555e50c7220fa8e4132e1495e6e9cadc88c1b217db487a5f9973c5a4a358ce2d6368bff3d65fbb9968ed420d2ee46d7a5

data/README.md

@@ -1,10 +1,10 @@
 # Ruby Debug Agent
 
 [![Gem Version](https://img.shields.io/badge/gem-debug--agent-red)](https://github.com/topcheer/ruby-debug-agent)
-![Tools](https://img.shields.io/badge/tools-40-blue)
-![Inspectors](https://img.shields.io/badge/inspectors-13-green)
+![Tools](https://img.shields.io/badge/tools-54-blue)
+![Inspectors](https://img.shields.io/badge/inspectors-20-green)
 
-An AI-powered runtime debugging agent that embeds directly into your Ruby application. Add one gem, configure an LLM key, and chat with your live app at `/agent` to inspect GC, ObjectSpace, threads, routes, Redis, Rails models/routes, Sidekiq queues, Puma stats, fibers/signals, process info, HTTP requests, and more — **40 diagnostic tools across 13 inspectors**.
+An AI-powered runtime debugging agent that embeds directly into your Ruby application. Add one gem, configure an LLM key, and chat with your live app at `/agent` to inspect GC, ObjectSpace, threads, routes, Redis, Rails models/routes, Sidekiq queues, Puma stats, fibers/signals, process info, HTTP requests, and more — **54 diagnostic tools across 20 inspectors**.
 
 ## Quick Start
 
@@ -55,10 +55,10 @@ http://localhost:4567/agent
 - **Context compression** — automatically summarizes old conversation when token limit is approached
 - **Dark-themed chat UI** with full markdown rendering (tables, code blocks, lists)
 - **Max tool rounds** (25) with forced final summary when limit is reached
-- **40 diagnostic tools** across **13 inspectors**
+- **54 diagnostic tools** across **20 inspectors**
 - Zero external dependencies (no Datadog, no Grafana, no APM)
 
-## Inspectors & Tools (40)
+## Inspectors & Tools (54)
 
 ### GC Inspector
 | Tool | Description |
@@ -152,6 +152,47 @@ http://localhost:4567/agent
 | `get_signal_handlers` | List registered signal handlers (Signal.trap) |
 | `get_trap_handlers` | Inspect trap handlers for SIGINT, SIGTERM, etc. |
 
+### Logging Inspector
+| Tool | Description |
+|------|-------------|
+| `get_log_buffer` | Recent log entries from the built-in ring buffer |
+| `get_logger_info` | Current log level and configuration for registered loggers |
+| `set_log_level` | Dynamically set the log level for a registered logger |
+
+### Cache Inspector
+| Tool | Description |
+|------|-------------|
+| `get_cache_stats` | Stats for registered caches (hit rate, miss count, key count) |
+| `get_cache_keys` | List keys from a registered cache with optional prefix filter |
+| `clear_cache` | Clear all entries from a registered cache |
+
+### Outbound HTTP Inspector
+| Tool | Description |
+|------|-------------|
+| `get_http_connections` | HTTP client connection stats (Net::HTTP, connection pool) |
+| `get_outbound_summary` | Aggregated outbound HTTP call stats (total, avg latency, error rate) |
+
+### Metrics Inspector
+| Tool | Description |
+|------|-------------|
+| `get_registered_metrics` | List all registered Prometheus metrics |
+| `get_metric_value` | Get current value of a specific metric by name |
+
+### ActiveRecord Stats Inspector
+| Tool | Description |
+|------|-------------|
+| `get_active_record_query_stats` | ActiveRecord query statistics (queries per model, N+1 detection) |
+
+### Faraday Inspector
+| Tool | Description |
+|------|-------------|
+| `get_faraday_connections` | List Faraday connection objects with host, port, and adapter info |
+
+### Concurrent Inspector
+| Tool | Description |
+|------|-------------|
+| `get_concurrent_state` | Ruby concurrency primitives state (Mutex, ConditionVariable, Queue) |
+
 ## Custom Tools
 
 ```ruby

data/lib/debug_agent/inspectors/active_record_stats.rb

@@ -0,0 +1,131 @@
+require 'thread'
+
+module DebugAgent
+  # Track ActiveRecord SQL events (sql.active_record) to report query stats
+  # and N+1 detection hints. Auto-installs a subscriber when the tool is run.
+  @ar_stats = {
+    total_queries: 0,
+    total_time_ms: 0.0,
+    slow_queries: [],
+    query_counts: Hash.new(0),
+    query_times: Hash.new(0.0),
+    slow_threshold_ms: 100
+  }
+  @ar_lock = Mutex.new
+  @ar_tracker_installed = false
+
+  class << self
+    attr_reader :ar_stats
+
+    # Subscribe to sql.active_record notifications (idempotent).
+    def install_ar_tracker
+      return true if @ar_tracker_installed
+      return false unless defined?(::ActiveSupport::Notifications)
+
+      ::ActiveSupport::Notifications.subscribe('sql.active_record') do |_name, started, finished, _id, payload|
+        DebugAgent.record_ar_query(started, finished, payload)
+      end
+      @ar_tracker_installed = true
+      true
+    end
+
+    def record_ar_query(started, finished, payload)
+      duration_ms = ((finished - started) * 1000.0)
+      sql = payload[:sql].to_s.strip
+      return if sql.empty?
+
+      fp = ar_fingerprint(sql)
+      name = payload[:name]
+
+      @ar_lock.synchronize do
+        s = @ar_stats
+        s[:total_queries] += 1
+        s[:total_time_ms] += duration_ms
+        next unless fp
+        s[:query_counts][fp] += 1
+        s[:query_times][fp] += duration_ms
+        if duration_ms >= s[:slow_threshold_ms] && s[:slow_queries].size < 200
+          s[:slow_queries] << {
+            sql: sql[0..500],
+            name: name,
+            duration_ms: duration_ms.round(2),
+            timestamp: finished.to_s
+          }
+        end
+      end
+    rescue
+      nil
+    end
+
+    # Normalize SQL into a fingerprint for grouping / N+1 detection.
+    def ar_fingerprint(sql)
+      sql
+        .gsub(/'[^']*'/, '?')
+        .gsub(/\b\d+\b/, '?')
+        .gsub(/\s+/, ' ')
+        .strip[0..200]
+    end
+  end
+
+  register_tool('get_active_record_query_stats',
+                'Query statistics from ActiveRecord: total queries, avg query time, ' \
+                'slow queries, and N+1 detection hints (subscribes to sql.active_record)') do
+    next { error: 'ActiveRecord is not loaded (activerecord gem not installed)' } unless defined?(::ActiveRecord)
+
+    install_ar_tracker
+
+    snapshot = @ar_lock.synchronize do
+      {
+        total_queries: @ar_stats[:total_queries],
+        total_time_ms: @ar_stats[:total_time_ms].round(2),
+        slow_queries: @ar_stats[:slow_queries].dup,
+        query_counts: @ar_stats[:query_counts].dup,
+        query_times: @ar_stats[:query_times].dup,
+        slow_threshold_ms: @ar_stats[:slow_threshold_ms]
+      }
+    end
+
+    total = snapshot[:total_queries]
+    avg = total.zero? ? 0.0 : (snapshot[:total_time_ms] / total)
+
+    # N+1 suspects: the same query fingerprint executed many times.
+    n_plus_suspects =
+      snapshot[:query_counts]
+        .select { |_, count| count >= 5 }
+        .sort_by { |_, count| -count }
+        .first(10)
+        .map do |fp, count|
+          time = snapshot[:query_times][fp]
+          {
+            fingerprint: fp,
+            count: count,
+            total_time_ms: time.round(2),
+            avg_time_ms: (time / count).round(2)
+          }
+        end
+
+    result = {
+      tracker_active: @ar_tracker_installed,
+      total_queries: total,
+      total_query_time_ms: snapshot[:total_time_ms],
+      avg_query_time_ms: avg.round(2),
+      slow_query_threshold_ms: snapshot[:slow_threshold_ms],
+      slow_query_count: snapshot[:slow_queries].size,
+      slow_queries: snapshot[:slow_queries].last(20).reverse,
+      n_plus_suspects: n_plus_suspects
+    }
+
+    # Best-effort: include query cache info if available.
+    if ::ActiveRecord::Base.connection.respond_to?(:query_cache)
+      begin
+        result[:query_cache_enabled] = ::ActiveRecord::Base.connection.query_cache_enabled
+      rescue
+        nil
+      end
+    end
+
+    result
+  rescue => e
+    { error: e.message }
+  end
+end

data/lib/debug_agent/inspectors/cache.rb

@@ -0,0 +1,194 @@
+module DebugAgent
+  # Registry of named cache objects. Applications register caches so the
+  # inspector can introspect stats, keys, and clear them.
+  #
+  #   DebugAgent.register_cache(:rails, Rails.cache)
+  @caches = {}
+
+  class << self
+    attr_reader :caches
+
+    def register_cache(name, cache)
+      @caches[name.to_s] = cache
+    end
+
+    # Introspect a cache object, supporting ActiveSupport::Cache::MemoryStore,
+    # generic ActiveSupport::Cache::Store, plain Hashes, and custom caches.
+    def cache_stats_for(cache)
+      if defined?(::ActiveSupport::Cache::MemoryStore) && cache.is_a?(::ActiveSupport::Cache::MemoryStore)
+        data = cache.instance_variable_get(:@data) || {}
+        key_access = cache.instance_variable_get(:@key_access) || {}
+        {
+          type: 'ActiveSupport::Cache::MemoryStore',
+          size: data.size,
+          max_size: cache.instance_variable_get(:@max_size),
+          tracked_keys: key_access.size,
+          sample_keys: data.keys.first(50)
+        }
+      elsif defined?(::ActiveSupport::Cache::Store) && defined?(::ActiveSupport::Cache) &&
+            cache.is_a?(::ActiveSupport::Cache::Store)
+        stats = best_effort_cache_stats(cache)
+        stats.merge(type: cache.class.name)
+      elsif cache.is_a?(Hash)
+        {
+          type: 'Hash',
+          size: cache.size,
+          sample_keys: cache.keys.first(50)
+        }
+      else
+        stats = best_effort_cache_stats(cache)
+        stats.merge(type: cache.class.name)
+      end
+    end
+
+    # Extract hit/miss and size where the cache exposes them (e.g. Dalli).
+    def best_effort_cache_stats(cache)
+      result = {}
+      result[:size] = cache_size_for(cache)
+
+      if cache.respond_to?(:stats)
+        raw =
+          begin
+            cache.stats
+          rescue
+            {}
+          end
+        if raw.is_a?(Hash)
+          result[:raw_stats] = raw
+          hits = raw['get_hits'] || raw[:get_hits]
+          misses = raw['get_misses'] || raw[:get_misses]
+          if hits && misses
+            total = hits.to_i + misses.to_i
+            result[:hits] = hits.to_i
+            result[:misses] = misses.to_i
+            result[:hit_rate] = total.zero? ? nil : format('%.1f%%', hits.to_f / total * 100)
+          end
+        end
+      end
+      result
+    end
+
+    def cache_keys_for(cache)
+      if defined?(::ActiveSupport::Cache::MemoryStore) && cache.is_a?(::ActiveSupport::Cache::MemoryStore)
+        (cache.instance_variable_get(:@data) || {}).keys
+      elsif cache.is_a?(Hash)
+        cache.keys
+      elsif cache.respond_to?(:keys)
+        begin
+          cache.keys
+        rescue
+          []
+        end
+      else
+        []
+      end
+    end
+
+    def cache_size_for(cache)
+      if defined?(::ActiveSupport::Cache::MemoryStore) && cache.is_a?(::ActiveSupport::Cache::MemoryStore)
+        (cache.instance_variable_get(:@data) || {}).size
+      elsif cache.respond_to?(:size)
+        begin
+          cache.size
+        rescue
+          nil
+        end
+      elsif cache.respond_to?(:length)
+        begin
+          cache.length
+        rescue
+          nil
+        end
+      end
+    end
+  end
+
+  register_tool('get_cache_stats',
+                'Get stats for registered caches: hit/miss ratio, size, entries. ' \
+                'Supports Rails.cache, ActiveSupport::Cache::MemoryStore, and Hash caches') do |name: nil|
+    if caches.empty?
+      next { error: 'No caches registered. Call DebugAgent.register_cache(:name, cache).' }
+    end
+
+    targets = name ? { name.to_s => caches[name.to_s] } : caches
+    targets = targets.reject { |_, c| c.nil? }
+    next { error: "No cache registered under '#{name}'" } if targets.empty?
+
+    results = targets.map do |cache_name, cache|
+      begin
+        cache_stats_for(cache).merge(name: cache_name)
+      rescue => e
+        { name: cache_name, error: e.message }
+      end
+    end
+
+    { caches: results }
+  rescue => e
+    { error: e.message }
+  end
+
+  register_tool('get_cache_keys',
+                'List keys in a registered cache with optional prefix filter',
+                name: { type: 'string', description: 'Registered cache name (optional, defaults to first)', required: false },
+                prefix: { type: 'string', description: 'Only return keys starting with this prefix', required: false }) do |name: nil, prefix: nil|
+    if caches.empty?
+      next { error: 'No caches registered. Call DebugAgent.register_cache(:name, cache).' }
+    end
+
+    cache_name, cache = name ? [name.to_s, caches[name.to_s]] : caches.first
+    next { error: "No cache registered under '#{name}'" } unless cache
+
+    keys = cache_keys_for(cache)
+    if prefix && !prefix.to_s.empty?
+      keys = keys.select { |k| k.to_s.start_with?(prefix.to_s) }
+    end
+
+    {
+      cache: cache_name,
+      total_keys: keys.size,
+      keys: keys.first(500)
+    }
+  rescue => e
+    { error: e.message }
+  end
+
+  register_tool('clear_cache',
+                'Clear a registered cache (destructive: removes all entries)',
+                name: { type: 'string', description: 'Registered cache name (optional, defaults to first)', required: false }) do |name: nil|
+    if caches.empty?
+      next { error: 'No caches registered. Call DebugAgent.register_cache(:name, cache).' }
+    end
+
+    cache_name, cache = name ? [name.to_s, caches[name.to_s]] : caches.first
+    next { error: "No cache registered under '#{name}'" } unless cache
+
+    before = cache_size_for(cache)
+
+    cleared =
+      if cache.respond_to?(:clear)
+        cache.clear
+        true
+      elsif cache.is_a?(Hash)
+        cache.clear
+        true
+      elsif cache.respond_to?(:clear_all)
+        cache.clear_all
+        true
+      elsif cache.respond_to?(:delete_all)
+        cache.delete_all
+        true
+      elsif cache.respond_to?(:flushdb)
+        cache.flushdb
+        true
+      else
+        false
+      end
+
+    next { error: "Cache '#{cache_name}' (#{cache.class}) does not support clearing" } unless cleared
+
+    after = cache_size_for(cache)
+    { cache: cache_name, cleared: true, size_before: before, size_after: after }
+  rescue => e
+    { error: e.message }
+  end
+end

data/lib/debug_agent/inspectors/concurrent.rb

@@ -0,0 +1,78 @@
+module DebugAgent
+  # Inspector for the concurrent-ruby gem: global executor pools and any
+  # registered promises/futures.
+  #
+  #   DebugAgent.register_concurrent(:my_task, Concurrent::Promises.future { ... })
+  @concurrent_promises = {}
+
+  class << self
+    attr_reader :concurrent_promises
+
+    def register_concurrent(name, promise)
+      @concurrent_promises[name.to_s] = promise
+    end
+
+    def executor_info(executor)
+      return nil unless executor
+      info = { class: executor.class.name }
+      %i[running?].each do |m|
+        info[m] = executor.public_send(m) if executor.respond_to?(m)
+      end
+      %i[length largest_length queue_length scheduled_task_count completed_task_count
+         max_threads min_threads idletime max_queue].each do |m|
+        info[m] = (executor.public_send(m) rescue nil) if executor.respond_to?(m)
+      end
+      info
+    rescue => e
+      { class: executor&.class&.name, error: e.message }
+    end
+
+    def promise_info(name, promise)
+      info = { name: name, class: promise.class.name }
+      info[:state] = promise.state if promise.respond_to?(:state)
+      if promise.respond_to?(:fulfilled?)
+        info[:fulfilled] = promise.fulfilled?
+        info[:rejected] = promise.rejected? if promise.respond_to?(:rejected?)
+        info[:pending] = promise.pending? if promise.respond_to?(:pending?)
+      end
+      if promise.respond_to?(:reason)
+        reason = promise.reason
+        info[:reason] = reason.is_a?(Exception) ? reason.message : reason.inspect unless reason.nil?
+      end
+      info
+    rescue => e
+      { name: name, error: e.message }
+    end
+  end
+
+  register_tool('get_concurrent_state',
+                'If concurrent-ruby is loaded, list global executor pools and registered ' \
+                'promises/futures with their state') do
+    next { error: 'concurrent-ruby is not loaded (concurrent-ruby gem not installed)' } unless defined?(::Concurrent)
+
+    executors = {}
+    if ::Concurrent.respond_to?(:global_io_executor)
+      executors[:global_io] = executor_info(::Concurrent.global_io_executor)
+    end
+    if ::Concurrent.respond_to?(:global_fast_executor)
+      executors[:global_fast] = executor_info(::Concurrent.global_fast_executor)
+    end
+    if ::Concurrent.respond_to?(:global_immediate_executor)
+      executors[:global_immediate] = executor_info(::Concurrent.global_immediate_executor)
+    end
+
+    promises =
+      if concurrent_promises.empty?
+        { message: 'No promises/futures registered. Call DebugAgent.register_concurrent(:name, future).' }
+      else
+        concurrent_promises.map { |n, p| promise_info(n, p) }
+      end
+
+    {
+      executors: executors,
+      registered_promises: promises
+    }
+  rescue => e
+    { error: e.message }
+  end
+end

data/lib/debug_agent/inspectors/error_tracking.rb

@@ -0,0 +1,120 @@
+require 'time'
+require 'thread'
+
+module DebugAgent
+  MAX_ERRORS = 50
+  @error_buffer = []
+  @error_buffer_lock = Mutex.new
+
+  class << self
+    attr_reader :error_buffer
+
+    def record_error(error, context = {})
+      @error_buffer_lock.synchronize do
+        @error_buffer << {
+          timestamp: Time.now.iso8601,
+          class: error.class.name,
+          message: error.message,
+          backtrace: (error.backtrace || []).first(10),
+          context: context
+        }
+        @error_buffer.shift if @error_buffer.size > MAX_ERRORS
+      end
+    end
+  end
+
+  # Capture unhandled exceptions at process exit
+  at_exit do
+    if $!
+      DebugAgent.record_error($!)
+    end
+  end
+
+  register_tool('get_recent_errors',
+                'Get recent unhandled exceptions captured by the agent (ring buffer, max 50). ' \
+                'Each entry: timestamp, class, message, backtrace',
+                limit: { type: 'integer', description: 'Maximum number of errors to return (default 20)', required: false }) do |limit: 20|
+    errors = @error_buffer_lock.synchronize { @error_buffer.dup }
+
+    if errors.empty?
+      next {
+        message: 'No errors captured yet. Errors are recorded via at_exit and when ' \
+                 'DebugAgent.record_error is called (e.g. from a Sinatra error handler).',
+        total: 0
+      }
+    end
+
+    limit = limit.to_i
+    limit = 20 if limit <= 0
+
+    { total: errors.size, errors: errors.reverse.first(limit) }
+  rescue => e
+    { error: e.message }
+  end
+
+  register_tool('get_error_stats',
+                'Get error statistics: total errors, rate per minute, and top error types') do
+    errors = @error_buffer_lock.synchronize { @error_buffer.dup }
+
+    if errors.empty?
+      next { total: 0, message: 'No errors captured yet.' }
+    end
+
+    # Group by error class
+    by_class = errors.group_by { |e| e[:class] }
+    top_types = by_class.map do |klass, entries|
+      { class: klass, count: entries.size, last_seen: entries.last[:timestamp] }
+    end.sort_by { |t| -t[:count] }
+
+    # Calculate rate per minute (errors in the last 60 seconds)
+    now = Time.now
+    recent = errors.select do |e|
+      begin
+        (now - Time.iso8601(e[:timestamp])) <= 60
+      rescue
+        false
+      end
+    end
+
+    {
+      total: errors.size,
+      buffer_capacity: MAX_ERRORS,
+      rate_per_minute: recent.size,
+      unique_error_types: by_class.size,
+      top_error_types: top_types.first(10),
+      first_error: errors.first[:timestamp],
+      last_error: errors.last[:timestamp]
+    }
+  rescue => e
+    { error: e.message }
+  end
+
+  register_tool('get_error_patterns',
+                'Group captured errors by exception class to identify recurring patterns') do
+    errors = @error_buffer_lock.synchronize { @error_buffer.dup }
+
+    if errors.empty?
+      next { total: 0, message: 'No errors captured yet.' }
+    end
+
+    patterns = errors.group_by { |e| e[:class] }.map do |klass, entries|
+      sample_messages = entries.map { |e| e[:message] }.uniq.first(5)
+      {
+        class: klass,
+        count: entries.size,
+        sample_messages: sample_messages,
+        first_seen: entries.first[:timestamp],
+        last_seen: entries.last[:timestamp],
+        sample_backtrace: entries.last[:backtrace]
+      }
+    end.sort_by { |p| -p[:count] }
+
+    {
+      total_errors: errors.size,
+      unique_patterns: patterns.size,
+      patterns: patterns
+    }
+  rescue => e
+    { error: e.message }
+  end
+end

data/lib/debug_agent/inspectors/faraday.rb

@@ -0,0 +1,79 @@
+module DebugAgent
+  # Registry of named Faraday connections so the inspector can introspect them.
+  #
+  #   DebugAgent.register_faraday(:api, Faraday.new('https://api.example.com'))
+  @faraday_connections = {}
+
+  class << self
+    attr_reader :faraday_connections
+
+    def register_faraday(name, conn)
+      @faraday_connections[name.to_s] = conn
+    end
+
+    def faraday_conn_info(name, conn)
+      info = { name: name, class: conn.class.name }
+
+      if conn.respond_to?(:url_prefix)
+        info[:url] = conn.url_prefix.to_s
+        info[:host] = conn.url_prefix.host
+        info[:port] = conn.url_prefix.port
+        info[:scheme] = conn.url_prefix.scheme
+      end
+
+      builder = conn.respond_to?(:builder) ? conn.builder : nil
+      if builder
+        handlers =
+          if builder.respond_to?(:handlers)
+            builder.handlers.map { |h| faraday_handler_name(h) }
+          else
+            []
+          end
+        info[:middleware] = handlers
+
+        adapter =
+          if builder.respond_to?(:adapter)
+            faraday_handler_name(builder.adapter)
+          end
+        info[:adapter] = adapter if adapter
+      end
+
+      info[:headers] = conn.headers.to_h if conn.respond_to?(:headers) && conn.headers.respond_to?(:to_h)
+
+      info
+    rescue => e
+      { name: name, error: e.message }
+    end
+
+    def faraday_handler_name(handler)
+      return handler.name if handler.respond_to?(:name)
+      return handler.class.name if handler.respond_to?(:class)
+      handler.to_s
+    end
+  end
+
+  register_tool('get_faraday_connections',
+                'List registered Faraday connections with URL, adapter, and middleware stack ' \
+                '(requires faraday gem)') do |name: nil|
+    next { error: 'Faraday is not loaded (faraday gem not installed)' } unless defined?(::Faraday)
+
+    conns = faraday_connections
+    if conns.empty?
+      next {
+        message: 'No Faraday connections registered. Call DebugAgent.register_faraday(:name, conn).'
+      }
+    end
+
+    targets = name ? { name.to_s => conns[name.to_s] } : conns
+    targets = targets.reject { |_, c| c.nil? }
+    next { error: "No Faraday connection registered under '#{name}'" } if targets.empty?
+
+    list = targets.map do |conn_name, conn|
+      faraday_conn_info(conn_name, conn)
+    end
+
+    { connections: list }
+  rescue => e
+    { error: e.message }
+  end
+end