debug-agent 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7b9c945dc45966ff8c9d06b0679357d54ba9dc443d5ee68c532ae1058878c6e4
-  data.tar.gz: a986e568c59ca3f8d04f71d647ba0649bbbff7659f021eca349bc3cce3b3b044
+  metadata.gz: fe4d325302d304db5821ef8bc5283ce3978e26d7721604efcbf00a646229346c
+  data.tar.gz: '058ae474cc6e35f83f59ee86da1ca807af84a51762c66a9452827805e28664c9'
 SHA512:
-  metadata.gz: 90d75283c6f362c3be78a419923c26d622aa6d55ed3d29ebfca1c40341d7d264a9a6074fd30e93140fb13db44991a8a52261d0695a2df22bcf1e17e865f793bb
-  data.tar.gz: 319d197cd23d9c9fd15845dc4a8a896b2560d3da83b85ac69e9687ba4ce3495ed1b720089ce82cc6adef8497e570177078f9430191bbca260a32a230f68171aa
+  metadata.gz: f72cf134d401b2f055e5103eea6b6d35e06bbc75f7962a6f33d37f906f91e6899a5f562a5a032209448f469c5830b24d582b43b34730fbf949a1c47d4a8b25cb
+  data.tar.gz: dbb70e23e5bce9c717c8ecbdf708b2724811beeac9fa3672f496ac25dfedda108f0c051f71c7af5a1421cf181d120534aff1a94f6c511df3af04a56745a19098

data/README.md

@@ -1,12 +1,12 @@
 # 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-84-blue)
-![Inspectors](https://img.shields.io/badge/inspectors-31-green)
+![Tools](https://img.shields.io/badge/tools-98-blue)
+![Inspectors](https://img.shields.io/badge/inspectors-36-green)
 ![Ruby](https://img.shields.io/badge/Ruby-2.7%2B-CC342D)
 ![Gem](https://img.shields.io/badge/gem-debug--agent-red)
 
-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 — **84 diagnostic tools across 31 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 — **98 diagnostic tools across 36 inspectors**.
 
 ## Version Support
 
@@ -71,10 +71,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
-- **84 diagnostic tools** across **31 inspectors**
+- **98 diagnostic tools** across **36 inspectors**
 - Zero external dependencies (no Datadog, no Grafana, no APM)
 
-## Inspectors & Tools (84)
+## Inspectors & Tools (98)
 
 ### GC Inspector
 | Tool | Description |
@@ -250,6 +250,40 @@ http://localhost:4567/agent
 | `detect_pool_leaks` | Heuristic leak detection (growing pool, high wait ratio, saturation) |
 | `get_pool_wait_stats` | Connection acquire wait stats (avg, P95, max wait, timeout count) |
 
+### CPU Profiler Inspector (v0.7.0)
+| Tool | Description |
+|------|-------------|
+| `start_cpu_profile` | Start a CPU profiling session (stackprof/stackprof-native) |
+| `stop_cpu_profile` | Stop CPU profiling and return collected profile data |
+| `get_top_functions` | Get top CPU-consuming functions from the current profile |
+
+### Memory Leak Detector Inspector (v0.7.0)
+| Tool | Description |
+|------|-------------|
+| `take_heap_snapshot` | Capture an ObjectSpace heap snapshot for leak analysis |
+| `compare_heap_snapshots` | Compare two heap snapshots to identify object growth |
+| `get_leak_candidates` | Identify objects likely to be memory leaks |
+
+### Deployment/Build Info Inspector (v0.7.0)
+| Tool | Description |
+|------|-------------|
+| `get_build_info` | Build version, commit hash, and gem metadata |
+| `get_deployment_info` | Deployment environment, container, and orchestration metadata |
+| `get_runtime_version` | Ruby interpreter version, engine, and platform details |
+
+### Snapshot & Diff Inspector (v0.7.0)
+| Tool | Description |
+|------|-------------|
+| `take_snapshot` | Capture a runtime state snapshot |
+| `compare_snapshots` | Compare two snapshots to identify state changes |
+| `list_snapshots` | List all saved snapshots with timestamps |
+
+### Service Registry Inspector (v0.7.0)
+| Tool | Description |
+|------|-------------|
+| `get_registered_services` | List all registered application services |
+| `get_service_dependencies` | Map service-to-service dependency graph |
+
 ## Custom Tools
 
 ```ruby
@@ -302,6 +336,12 @@ cd demo && ruby -I../lib app.rb
 
 [![Gem](https://img.shields.io/badge/rubygems-debug--agent-red)](https://github.com/topcheer/ruby-debug-agent)
 
+## Built With
+
+[![ggcode](https://img.shields.io/badge/built%20with-ggcode-blue)](https://github.com/topcheer/ggcode)
+
+This project was built using [ggcode](https://github.com/topcheer/ggcode) — an AI coding assistant for terminal-based development.
+
 ## License
 
 MIT

data/lib/debug_agent/inspectors/build_info.rb

@@ -0,0 +1,87 @@
+require 'socket'
+require 'etc'
+
+module DebugAgent
+  register_tool('get_build_info',
+                'Get Ruby build info: version, engine (MRI/JRuby/TruffleRuby), ' \
+                'platform, build date, RUBY_DESCRIPTION') do
+    {
+      ruby_version: RUBY_VERSION,
+      ruby_engine: RUBY_ENGINE,
+      ruby_engine_version: defined?(RUBY_ENGINE_VERSION) ? RUBY_ENGINE_VERSION : RUBY_VERSION,
+      platform: RUBY_PLATFORM,
+      ruby_description: RUBY_DESCRIPTION,
+      ruby_patchlevel: defined?(RUBY_PATCHLEVEL) ? RUBY_PATCHLEVEL : nil,
+      ruby_revision: defined?(RUBY_REVISION) ? RUBY_REVISION.to_s : nil,
+      ruby_release_date: defined?(RUBY_RELEASE_DATE) ? RUBY_RELEASE_DATE : nil,
+      build_date: defined?(RUBY_RELEASE_DATE) ? RUBY_RELEASE_DATE : nil,
+      host_os: RbConfig::CONFIG['host_os'],
+      host_cpu: RbConfig::CONFIG['host_cpu'],
+      configure_args: RbConfig::CONFIG['configure_args']
+    }
+  rescue => e
+    { error: e.message }
+  end
+
+  register_tool('get_deployment_info',
+                'Get deployment info: hostname, PID, uptime, container detection, ' \
+                'APP_ENV, Rails env') do
+    rss = `ps -o rss= -p #{Process.pid}`.to_i
+    uptime_seconds = Time.now - DebugAgent::PROCESS_START_TIME
+
+    container_detected = File.exist?('/.dockerenv')
+    in_cgroup = false
+    begin
+      in_cgroup = File.read('/proc/1/cgroup').include?('docker') ||
+                  File.read('/proc/1/cgroup').include?('containerd')
+    rescue
+    end
+
+    {
+      hostname: Socket.gethostname,
+      pid: Process.pid,
+      ppid: Process.ppid,
+      process_name: $0,
+      uptime_seconds: uptime_seconds.round(0),
+      rss_mb: (rss / 1024.0).round(2),
+      container_detected: container_detected || in_cgroup,
+      docker_detected: File.exist?('/.dockerenv'),
+      app_env: ENV['APP_ENV'] || ENV['RAILS_ENV'] || ENV['RACK_ENV'] || 'unknown',
+      rails_env: defined?(::Rails) ? ::Rails.env.to_s : nil,
+      user: Etc.getpwuid(Process.uid)&.name,
+      uid: Process.uid,
+      gid: Process.gid,
+      cpu_count: Etc.nprocessors
+    }
+  rescue => e
+    { error: e.message }
+  end
+
+  register_tool('get_runtime_versions',
+                'Get versions of key gems: rails, sinatra, sidekiq, redis, puma ' \
+                'if loaded') do
+    key_gems = %w[rails sinatra sidekiq redis puma rack rack-attack \
+                  activerecord activesupport postgresql pg mysql2 bunny \
+                  faraday httplog oj msgpack json]
+
+    versions = {}
+    key_gems.each do |gem_name|
+      spec = Gem.loaded_specs[gem_name] || Gem.loaded_specs.values.find { |s| s.name == gem_name }
+      versions[gem_name] = spec&.version&.to_s if spec
+    end
+
+    # Remove nils
+    versions.compact!
+
+    {
+      ruby_version: RUBY_VERSION,
+      ruby_engine: RUBY_ENGINE,
+      rubygems_version: Gem::VERSION,
+      bundler_version: defined?(Bundler) ? Bundler::VERSION : nil,
+      loaded_gem_count: Gem.loaded_specs.size,
+      key_gem_versions: versions
+    }
+  rescue => e
+    { error: e.message }
+  end
+end

data/lib/debug_agent/inspectors/cpu_profile.rb

@@ -0,0 +1,192 @@
+require 'timeout'
+
+module DebugAgent
+  # CPU profiler inspector. Uses stackprof if available, otherwise falls back
+  # to a sampling profiler that periodically captures caller stacks.
+  @cpu_profile_data = nil
+  @cpu_profile_running = false
+  @cpu_profile_lock = Mutex.new
+
+  class << self
+    attr_reader :cpu_profile_data, :cpu_profile_running
+  end
+
+  register_tool('start_cpu_profile',
+                'Start CPU profiling for a given duration. Uses stackprof if available, ' \
+                'otherwise falls back to a sampling profiler. Auto-stops after duration.',
+                duration_seconds: { type: 'integer', description: 'Profile duration in seconds', required: false }) do |duration_seconds: 10|
+    duration = duration_seconds.to_i
+    duration = 10 if duration <= 0
+
+    @cpu_profile_lock.synchronize do
+      next { error: 'CPU profile already running' } if @cpu_profile_running
+      @cpu_profile_running = true
+      @cpu_profile_data = nil
+    end
+
+    if defined?(::StackProf)
+      # StackProf path: block-based profiling
+      StackProf.run(mode: :cpu, interval: 1000) do
+        sleep(duration)
+      end
+      @cpu_profile_lock.synchronize { @cpu_profile_running = false }
+      raw = StackProf.results
+      @cpu_profile_data = parse_stackprof(raw) if raw
+      {
+        status: 'completed',
+        backend: 'stackprof',
+        duration_seconds: duration,
+        samples: raw ? raw[:samples] : 0
+      }
+    else
+      # Fallback: sampling profiler using caller stacks
+      samples = Hash.new(0)
+      total_samples = 0
+      sample_lock = Mutex.new
+      end_time = Time.now + duration
+
+      sampler = Thread.new do
+        while Time.now < end_time && @cpu_profile_running
+          stack = caller(2)&.join("\n")
+          sample_lock.synchronize do
+            samples[stack] += 1
+            total_samples += 1
+          end if stack
+          sleep(0.001)
+        end
+      end
+
+      sampler.join
+      @cpu_profile_lock.synchronize { @cpu_profile_running = false }
+      @cpu_profile_data = parse_call_samples(samples, total_samples)
+      {
+        status: 'completed',
+        backend: 'sampling',
+        duration_seconds: duration,
+        total_samples: total_samples,
+        unique_stacks: samples.size
+      }
+    end
+  rescue => e
+    @cpu_profile_running = false
+    { error: e.message }
+  end
+
+  register_tool('stop_cpu_profile',
+                'Stop CPU profiling and return top 20 methods by self time. ' \
+                'Each entry includes method name, file, line, self_ms, total_ms, calls.') do
+    next { error: 'No profile data available. Run start_cpu_profile first.' } unless @cpu_profile_data
+
+    @cpu_profile_running = false
+    top = (@cpu_profile_data[:functions] || []).first(20)
+
+    {
+      status: 'stopped',
+      backend: @cpu_profile_data[:backend],
+      total_samples: @cpu_profile_data[:total_samples],
+      top_functions: top
+    }
+  rescue => e
+    { error: e.message }
+  end
+
+  register_tool('get_top_functions',
+                'Return top methods from last CPU profile. Sort by self_time, total_time, or calls.',
+                limit: { type: 'integer', description: 'Number of functions to return (default 20)', required: false },
+                sort_by: { type: 'string', description: 'Sort key: self_time, total_time, or calls (default self_time)', required: false }) do |limit: 20, sort_by: 'self_time'|
+    next { error: 'No profile data available. Run start_cpu_profile first.' } unless @cpu_profile_data
+
+    funcs = (@cpu_profile_data[:functions] || []).dup
+    sort_key = %w[self_time total_time calls].include?(sort_by.to_s) ? sort_by.to_sym : :self_time
+    funcs.sort_by! { |f| -f[sort_key].to_f }
+    top = funcs.first(limit.to_i > 0 ? limit.to_i : 20)
+
+    {
+      sort_by: sort_key,
+      total_functions: @cpu_profile_data[:functions]&.size || 0,
+      top_functions: top
+    }
+  rescue => e
+    { error: e.message }
+  end
+
+  # --- Helpers ---
+
+  class << self
+    private
+
+    def parse_stackprof(raw)
+      return nil unless raw && raw[:frames]
+
+      funcs = raw[:frames].map do |_frame_key, frame|
+        {
+          method: frame[:name] || 'unknown',
+          file: frame[:file],
+          line: frame[:line],
+          self_ms: ((frame[:samples].to_f / raw[:samples].to_f) * (raw[:gc_profile_time] || raw[:walltime] || 0) * 1000).round(2),
+          total_ms: ((frame[:total_samples].to_f / raw[:samples].to_f) * (raw[:gc_profile_time] || raw[:walltime] || 0) * 1000).round(2),
+          calls: frame[:samples].to_i
+        }
+      end.sort_by { |f| -f[:self_ms] }
+
+      {
+        backend: 'stackprof',
+        total_samples: raw[:samples],
+        functions: funcs
+      }
+    end
+
+    def parse_call_samples(samples, total_samples)
+      method_stats = Hash.new { |h, k| h[k] = { self_time: 0, total_time: 0, calls: 0 } }
+
+      samples.each do |stack_str, count|
+        lines = stack_str.split("\n")
+        next if lines.empty?
+
+        # First line of caller(2) is the most recently called method
+        top_line = lines.first
+        parsed = parse_backtrace_line(top_line)
+
+        key = "#{parsed[:file]}:#{parsed[:method]}"
+        method_stats[key][:self_time] += count
+        method_stats[key][:total_time] += count
+        method_stats[key][:calls] += 1
+
+        # All lines contribute to total_time of their respective methods
+        lines.each do |line|
+          p = parse_backtrace_line(line)
+          k = "#{p[:file]}:#{p[:method]}"
+          method_stats[k][:total_time] += count
+          method_stats[k][:calls] += count unless k == key
+        end
+      end
+
+      funcs = method_stats.map do |_k, s|
+        parsed = parse_backtrace_line(samples.keys.find { |stk| stk.include?(_k) || true }&.split("\n")&.first || '')
+        {
+          method: _k.split(':').last,
+          file: _k.split(':')[0...-1].join(':'),
+          line: parsed[:line],
+          self_ms: (s[:self_time].to_f / total_samples.to_f * 10000).round(2),
+          total_ms: (s[:total_time].to_f / total_samples.to_f * 10000).round(2),
+          calls: s[:calls]
+        }
+      end.sort_by { |f| -f[:self_ms] }
+
+      {
+        backend: 'sampling',
+        total_samples: total_samples,
+        functions: funcs
+      }
+    end
+
+    def parse_backtrace_line(line)
+      # Format: "/path/to/file.rb:42:in `method_name'"
+      if line =~ /^(.+):(\d+):in `(.+)'$/
+        { file: $1, line: $2.to_i, method: $3 }
+      else
+        { file: 'unknown', line: 0, method: 'unknown' }
+      end
+    end
+  end
+end

data/lib/debug_agent/inspectors/leak_detector.rb

@@ -0,0 +1,161 @@
+require 'objspace'
+
+module DebugAgent
+  # Memory leak detector inspector. Records heap snapshots and compares them
+  # to identify object types with consistent growth.
+  @heap_snapshots = {}
+  @heap_snapshot_counter = 0
+
+  class << self
+    attr_reader :heap_snapshots
+  end
+
+  register_tool('take_heap_snapshot',
+                'Take a heap snapshot recording object counts by type, heap slots, ' \
+                'and GC counts. Returns a snapshot ID for later comparison.') do
+    counts = Hash.new(0)
+    ObjectSpace.each_object do |obj|
+      begin
+        name = obj.class.name || obj.class.to_s
+        counts[name] += 1
+      rescue
+        counts['<unknown>'] += 1
+      end
+    end
+
+    gc_stats = GC.stat
+    total_objects = counts.values.sum
+
+    @heap_snapshot_counter += 1
+    snapshot_id = "heap-#{@heap_snapshot_counter}"
+
+    snapshot = {
+      id: snapshot_id,
+      taken_at: Time.now,
+      object_counts: counts,
+      total_objects: total_objects,
+      live_slots: gc_stats[:heap_live_slots],
+      free_slots: gc_stats[:heap_free_slots],
+      total_slots: gc_stats[:heap_live_slots].to_i + gc_stats[:heap_free_slots].to_i,
+      gc_count: gc_stats[:count],
+      major_gc_count: gc_stats[:major_gc_count],
+      minor_gc_count: gc_stats[:minor_gc_count],
+      total_allocated_objects: gc_stats[:total_allocated_objects],
+      total_freed_objects: gc_stats[:total_freed_objects],
+      heap_pages: gc_stats[:heap_length]
+    }
+
+    @heap_snapshots[snapshot_id] = snapshot
+
+    {
+      snapshot_id: snapshot_id,
+      taken_at: snapshot[:taken_at].iso8601,
+      summary: {
+        total_objects: total_objects,
+        total_classes: counts.size,
+        live_slots: snapshot[:live_slots],
+        free_slots: snapshot[:free_slots],
+        gc_count: snapshot[:gc_count],
+        top_types: counts.sort_by { |_, v| -v }.first(10).to_h
+      }
+    }
+  rescue => e
+    { error: e.message }
+  end
+
+  register_tool('compare_heap_snapshots',
+                'Compare two heap snapshots. Returns per-type count delta and growth ' \
+                'percentage, sorted by absolute growth.',
+                snapshot_a: { type: 'string', description: 'First snapshot ID', required: true },
+                snapshot_b: { type: 'string', description: 'Second snapshot ID', required: true }) do |snapshot_a:, snapshot_b:|
+    snap_a = @heap_snapshots[snapshot_a.to_s]
+    snap_b = @heap_snapshots[snapshot_b.to_s]
+
+    next { error: "Snapshot '#{snapshot_a}' not found. Available: #{@heap_snapshots.keys.join(', ')}" } unless snap_a
+    next { error: "Snapshot '#{snapshot_b}' not found. Available: #{@heap_snapshots.keys.join(', ')}" } unless snap_b
+
+    counts_a = snap_a[:object_counts]
+    counts_b = snap_b[:object_counts]
+
+    all_types = (counts_a.keys | counts_b.keys).uniq
+    deltas = all_types.map do |type|
+      ca = counts_a[type] || 0
+      cb = counts_b[type] || 0
+      delta = cb - ca
+      growth_pct = ca > 0 ? (delta.to_f / ca * 100).round(2) : (delta > 0 ? Float::INFINITY : 0.0)
+
+      {
+        type: type,
+        count_before: ca,
+        count_after: cb,
+        count_delta: delta,
+        growth_percentage: growth_pct
+      }
+    end
+
+    # Sort by absolute growth descending
+    deltas.sort_by! { |d| -d[:count_delta].abs }
+
+    {
+      snapshot_a: snapshot_a,
+      snapshot_b: snapshot_b,
+      time_between: (snap_b[:taken_at] - snap_a[:taken_at]).round(2),
+      summary: {
+        total_objects_before: snap_a[:total_objects],
+        total_objects_after: snap_b[:total_objects],
+        net_delta: snap_b[:total_objects] - snap_a[:total_objects],
+        gc_runs_between: snap_b[:gc_count] - snap_a[:gc_count],
+        live_slots_delta: snap_b[:live_slots] - snap_a[:live_slots]
+      },
+      type_changes: deltas.first(50)
+    }
+  rescue => e
+    { error: e.message }
+  end
+
+  register_tool('get_leak_candidates',
+                'Identify object types with consistent growth across stored snapshots. ' \
+                'Shows top growing object types.') do |snapshot_limit: 10|
+    next { error: 'Need at least 2 snapshots to detect trends' } if @heap_snapshots.size < 2
+
+    snapshots = @heap_snapshots.values.sort_by { |s| s[:taken_at] }
+    snapshots = snapshots.last([snapshot_limit.to_i, 2].max)
+
+    # For each type, compute growth across consecutive snapshot pairs
+    type_growth = Hash.new { |h, k| h[k] = { deltas: [], total_growth: 0 } }
+
+    snapshots.each_cons(2) do |s1, s2|
+      all_types = (s1[:object_counts].keys | s2[:object_counts].keys)
+      all_types.each do |type|
+        c1 = s1[:object_counts][type] || 0
+        c2 = s2[:object_counts][type] || 0
+        delta = c2 - c1
+        type_growth[type][:deltas] << delta
+        type_growth[type][:total_growth] += delta
+      end
+    end
+
+    candidates = type_growth
+                 .select { |_, g| g[:total_growth] > 0 && g[:deltas].all? { |d| d >= 0 } }
+                 .map do |type, g|
+                   {
+                     type: type,
+                     total_growth: g[:total_growth],
+                     snapshots_growing: g[:deltas].count(&:positive?),
+                     total_snapshots_compared: g[:deltas].size,
+                     consistency: g[:deltas].all?(&:positive?) ? 'consistent' : 'partial',
+                     per_period_deltas: g[:deltas]
+                   }
+                 end
+                 .sort_by { |c| -c[:total_growth] }
+
+    {
+      snapshots_analyzed: snapshots.size,
+      first_snapshot: snapshots.first[:id],
+      last_snapshot: snapshots.last[:id],
+      leak_candidates: candidates.first(20)
+    }
+  rescue => e
+    { error: e.message }
+  end
+end

data/lib/debug_agent/inspectors/service_registry.rb

@@ -0,0 +1,88 @@
+module DebugAgent
+  register_tool('get_registered_services',
+                'List all registered debug agent tools grouped by inspector category. ' \
+                'Shows tool count and names per group.') do
+    all_tools = registry.names
+
+    # Categorize tools by known inspector groups
+    categories = {
+      'runtime' => %w[get_gc_stats get_memory_summary trigger_gc get_thread_summary get_runtime_info get_object_allocations],
+      'gc' => %w[],
+      'object_space' => %w[],
+      'threads' => %w[],
+      'process' => %w[],
+      'system' => %w[],
+      'http_tracker' => %w[],
+      'routes' => %w[],
+      'redis' => %w[],
+      'rails' => %w[],
+      'sidekiq' => %w[],
+      'puma' => %w[],
+      'logging' => %w[],
+      'cache' => %w[],
+      'http_client' => %w[],
+      'metrics' => %w[],
+      'active_record_stats' => %w[],
+      'faraday' => %w[],
+      'concurrent' => %w[],
+      'security' => %w[],
+      'health' => %w[],
+      'scheduler' => %w[],
+      'error_tracking' => %w[],
+      'websocket' => %w[],
+      'locks' => %w[],
+      'migration' => %w[],
+      'config' => %w[],
+      'feature_flags' => %w[],
+      'endpoint_test' => %w[],
+      'pool_inspector' => %w[],
+      'cpu_profile' => %w[],
+      'leak_detector' => %w[],
+      'build_info' => %w[],
+      'snapshot' => %w[],
+      'service_registry' => %w[]
+    }
+
+    # Since we cannot reliably categorize at runtime without a lookup table,
+    # we list all tools alphabetically with their descriptions
+    tools_with_desc = all_tools.sort.map do |name|
+      tool = registry.get(name)
+      {
+        name: name,
+        description: tool&.respond_to?(:description) ? tool.description : nil
+      }
+    end
+
+    {
+      total_tools: all_tools.size,
+      tools: tools_with_desc
+    }
+  rescue => e
+    { error: e.message }
+  end
+
+  register_tool('get_service_dependencies',
+                'Show all loaded gems and their versions from Gem.loaded_specs') do
+    specs = Gem.loaded_specs.values.sort_by(&:name)
+
+    gems = specs.map do |spec|
+      {
+        name: spec.name,
+        version: spec.version.to_s,
+        loaded_from: spec.loaded_from,
+        dependencies: spec.dependencies.map { |d| "#{d.name} (#{d.requirement})" }
+      }
+    end
+
+    {
+      total_gems: gems.size,
+      ruby_version: RUBY_VERSION,
+      ruby_engine: RUBY_ENGINE,
+      rubygems_version: Gem::VERSION,
+      bundler_version: defined?(Bundler) ? Bundler::VERSION : nil,
+      gems: gems
+    }
+  rescue => e
+    { error: e.message }
+  end
+end

data/lib/debug_agent/inspectors/snapshot.rb

@@ -0,0 +1,206 @@
+require 'objspace'
+
+module DebugAgent
+  # Snapshot & Diff inspector. Collects metrics across all inspectors at a
+  # point in time and allows comparing snapshots to detect changes.
+  @metric_snapshots = {}
+  @metric_snapshot_counter = 0
+
+  class << self
+    attr_reader :metric_snapshots
+  end
+
+  register_tool('take_snapshot',
+                'Take a cross-inspector snapshot: thread count, fiber count, memory (RSS), ' \
+                'GC stats, object count, DB pool stats, cache stats, error count. Returns snapshot ID.') do
+    gc = GC.stat
+    obj_counts = ObjectSpace.count_objects
+    rss = `ps -o rss= -p #{Process.pid}`.to_i
+
+    metrics = {
+      taken_at: Time.now,
+      threads: Thread.list.size,
+      alive_threads: Thread.list.count(&:alive?),
+      fiber_count: Fiber.respond_to?(:list) ? Fiber.list.size : count_fibers,
+      rss_mb: (rss / 1024.0).round(2),
+      gc: {
+        count: gc[:count],
+        major_gc_count: gc[:major_gc_count],
+        minor_gc_count: gc[:minor_gc_count],
+        heap_live_slots: gc[:heap_live_slots],
+        heap_free_slots: gc[:heap_free_slots],
+        total_allocated_objects: gc[:total_allocated_objects],
+        total_freed_objects: gc[:total_freed_objects],
+        old_objects: gc[:old_objects]
+      },
+      objects: {
+        total: obj_counts[:TOTAL] || obj_counts.values.sum,
+        free_slots: obj_counts[:FREE] || 0,
+        t_string: obj_counts[:T_STRING] || 0,
+        t_array: obj_counts[:T_ARRAY] || 0,
+        t_hash: obj_counts[:T_HASH] || 0,
+        t_object: obj_counts[:T_OBJECT] || 0,
+        t_data: obj_counts[:T_DATA] || 0
+      },
+      db_pool: gather_db_pool_stats,
+      cache: gather_cache_stats,
+      error_count: gather_error_count
+    }
+
+    @metric_snapshot_counter += 1
+    snapshot_id = "snap-#{@metric_snapshot_counter}"
+    @metric_snapshots[snapshot_id] = metrics
+
+    {
+      snapshot_id: snapshot_id,
+      taken_at: metrics[:taken_at].iso8601,
+      summary: {
+        threads: metrics[:threads],
+        fibers: metrics[:fiber_count],
+        rss_mb: metrics[:rss_mb],
+        total_objects: metrics[:objects][:total],
+        gc_count: metrics[:gc][:count],
+        live_slots: metrics[:gc][:heap_live_slots]
+      }
+    }
+  rescue => e
+    { error: e.message }
+  end
+
+  register_tool('compare_snapshots',
+                'Compare two cross-inspector snapshots. Returns all changed values ' \
+                'with deltas.',
+                snapshot_a: { type: 'string', description: 'First snapshot ID', required: true },
+                snapshot_b: { type: 'string', description: 'Second snapshot ID', required: true }) do |snapshot_a:, snapshot_b:|
+    snap_a = @metric_snapshots[snapshot_a.to_s]
+    snap_b = @metric_snapshots[snapshot_b.to_s]
+
+    next { error: "Snapshot '#{snapshot_a}' not found. Available: #{@metric_snapshots.keys.join(', ')}" } unless snap_a
+    next { error: "Snapshot '#{snapshot_b}' not found. Available: #{@metric_snapshots.keys.join(', ')}" } unless snap_b
+
+    changes = compute_snapshot_diff(snap_a, snap_b, '')
+
+    {
+      snapshot_a: snapshot_a,
+      snapshot_b: snapshot_b,
+      time_between_seconds: (snap_b[:taken_at] - snap_a[:taken_at]).round(2),
+      changes: changes
+    }
+  rescue => e
+    { error: e.message }
+  end
+
+  register_tool('list_snapshots',
+                'List all stored cross-inspector snapshots') do
+    if @metric_snapshots.empty?
+      next { message: 'No snapshots taken yet. Call take_snapshot first.', count: 0, snapshots: [] }
+    end
+
+    {
+      count: @metric_snapshots.size,
+      snapshots: @metric_snapshots.map do |id, snap|
+        {
+          snapshot_id: id,
+          taken_at: snap[:taken_at].iso8601,
+          threads: snap[:threads],
+          rss_mb: snap[:rss_mb],
+          total_objects: snap[:objects][:total],
+          gc_count: snap[:gc][:count]
+        }
+      end
+    }
+  rescue => e
+    { error: e.message }
+  end
+
+  # --- Helpers ---
+
+  class << self
+    private
+
+    def count_fibers
+      # Best-effort fiber count via ObjectSpace
+      count = 0
+      ObjectSpace.each_object(Fiber) { count += 1 }
+      count
+    rescue
+      0
+    end
+
+    def gather_db_pool_stats
+      return nil unless defined?(::ActiveRecord::Base)
+
+      begin
+        pool = ::ActiveRecord::Base.connection_pool
+        stats = pool.respond_to?(:stats) ? pool.stats : {}
+        {
+          size: pool.respond_to?(:size) ? pool.size : nil,
+          stats: stats
+        }
+      rescue
+        nil
+      end
+    end
+
+    def gather_cache_stats
+      return nil unless defined?(::Rails)
+
+      begin
+        cache = ::Rails.cache
+        return nil unless cache
+        stats = if cache.respond_to?(:stats)
+                  cache.stats
+                elsif cache.respond_to?(:info)
+                  cache.info
+                else
+                  {}
+                end
+        { backend: cache.class.name, stats: stats }
+      rescue
+        nil
+      end
+    end
+
+    def gather_error_count
+      # ErrorTracking inspector stores error counts if available
+      if defined?(@error_log) && @error_log.is_a?(Array)
+        @error_log.size
+      else
+        0
+      end
+    end
+
+    def compute_snapshot_diff(a, b, prefix)
+      changes = []
+
+      if a.is_a?(Hash) && b.is_a?(Hash)
+        all_keys = (a.keys | b.keys)
+        all_keys.each do |key|
+          va = a[key]
+          vb = b[key]
+          path = prefix.empty? ? key.to_s : "#{prefix}.#{key}"
+
+          if va.is_a?(Hash) && vb.is_a?(Hash)
+            changes.concat(compute_snapshot_diff(va, vb, path))
+          elsif va != vb
+            changes << {
+              metric: path,
+              before: va,
+              after: vb,
+              delta: (va.is_a?(Numeric) && vb.is_a?(Numeric)) ? (vb - va) : nil
+            }
+          end
+        end
+      elsif a != b
+        changes << {
+          metric: prefix,
+          before: a,
+          after: b,
+          delta: (a.is_a?(Numeric) && b.is_a?(Numeric)) ? (b - a) : nil
+        }
+      end
+
+      changes
+    end
+  end
+end

data/lib/debug_agent/version.rb

@@ -1,3 +1,3 @@
 module DebugAgent
-  VERSION = '0.6.0'.freeze
+  VERSION = '0.7.0'.freeze
 end

data/lib/debug_agent.rb

@@ -41,10 +41,24 @@ require_relative 'debug_agent/inspectors/config_inspector'
 require_relative 'debug_agent/inspectors/feature_flags'
 require_relative 'debug_agent/inspectors/endpoint_test'
 require_relative 'debug_agent/inspectors/pool_inspector'
+require_relative 'debug_agent/inspectors/cpu_profile'
+require_relative 'debug_agent/inspectors/leak_detector'
+require_relative 'debug_agent/inspectors/build_info'
+require_relative 'debug_agent/inspectors/snapshot'
+require_relative 'debug_agent/inspectors/service_registry'
 
 module DebugAgent
   class Error < StandardError; end
 
+  # ggcode promotional message — shown once on first require
+  unless defined?(@_ggcode_banner_shown)
+    @_ggcode_banner_shown = true
+    puts ""
+    puts "  This package was built with ggcode — an AI coding assistant."
+    puts "  https://github.com/topcheer/ggcode"
+    puts ""
+  end
+
   # Process start time for uptime tracking
   PROCESS_START_TIME = Time.now
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: debug-agent
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - ggcode
@@ -165,10 +165,12 @@ files:
 - lib/debug_agent/context_compressor.rb
 - lib/debug_agent/engine.rb
 - lib/debug_agent/inspectors/active_record_stats.rb
+- lib/debug_agent/inspectors/build_info.rb
 - lib/debug_agent/inspectors/cache.rb
 - lib/debug_agent/inspectors/concurrent.rb
 - lib/debug_agent/inspectors/config_inspector.rb
 - lib/debug_agent/inspectors/core_ext.rb
+- lib/debug_agent/inspectors/cpu_profile.rb
 - lib/debug_agent/inspectors/endpoint_test.rb
 - lib/debug_agent/inspectors/error_tracking.rb
 - lib/debug_agent/inspectors/faraday.rb
@@ -177,6 +179,7 @@ files:
 - lib/debug_agent/inspectors/health.rb
 - lib/debug_agent/inspectors/http_client.rb
 - lib/debug_agent/inspectors/http_tracker.rb
+- lib/debug_agent/inspectors/leak_detector.rb
 - lib/debug_agent/inspectors/locks.rb
 - lib/debug_agent/inspectors/logging.rb
 - lib/debug_agent/inspectors/metrics.rb
@@ -191,7 +194,9 @@ files:
 - lib/debug_agent/inspectors/runtime.rb
 - lib/debug_agent/inspectors/scheduler.rb
 - lib/debug_agent/inspectors/security.rb
+- lib/debug_agent/inspectors/service_registry.rb
 - lib/debug_agent/inspectors/sidekiq.rb
+- lib/debug_agent/inspectors/snapshot.rb
 - lib/debug_agent/inspectors/system.rb
 - lib/debug_agent/inspectors/threads.rb
 - lib/debug_agent/inspectors/websocket.rb