debug-mcp 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6257424af8b8ba371cecbb8f76fa8b0b68b1bb7d087528b7d5a99b4f53cccf92
-  data.tar.gz: abaaef014089cfc1dfa20e653a5c86f0614b3de3c685fc0d19602fcc8a411edc
+  metadata.gz: d3d8443d036bf6e58f7733e1a34f7cfb12d8d21f8efe922af9f50e98c55ebcc8
+  data.tar.gz: e22ddb40fe698ace1b8251f8da4c42dd76c91b1023011e4d8864f1adadd3703a
 SHA512:
-  metadata.gz: 8a747e5eb9a03f257af96d135128b4ade00c64700ae8c7fe9c7dd7f93c8b025fa41dfc7d345bce78aa2544ab8af0e701329257205294b4e74c1682d23b323a93
-  data.tar.gz: db31877e159f7777f2fa4f242bc07440deb512d99e7eb929de36538ce5f5f879e5efe1b511e5838cdf7d4122f1ebd214176afa2411f3e105621c40038003eaf2
+  metadata.gz: 57ca99711e4d91e66b1d534ecb1bd55609b39c80e3172e01bd1c3b37be0cdbe3795481db0fb48636dd57a72ae99f7ce87ff7a8f54d77d5622e4f2cbf4e7a9f1e
+  data.tar.gz: b95dd34474b6f8b2e330a514a9e06d724139df98d1ed78b23d8f92124dc56ae4a8c5e5e0f86f903d7bda3b9e2d08d479c9a7101cb9d16dff2792065852e94453

data/CHANGELOG.md

@@ -1,5 +1,61 @@
 # Changelog
 
+## 0.3.0 — 2026-06-18
+
+### Features
+
+- **`rails_recent_events` tool** — Read recent Rails internal events (SQL, renders,
+  cache, job enqueues, request lifecycle) from the running process without
+  `trigger_request`. Forward-only (the first call installs the subscriber) and
+  paused-only; every response carries an observability header (`installed_at`,
+  `forward_only`, `events_before_install_are_unavailable`, buffer size + dropped
+  count, `seq` range) so an empty result is never mistaken for "nothing happened".
+  Clock-independent `after_seq` cursor paging.
+
+- **`rails_mail_deliveries` tool** — Structure `ActionMailer::Base.deliveries`
+  (from/to/cc/bcc/subject/body preview/attachment names). `observable` is true only
+  when `delivery_method` is `:test`; otherwise the response states that an empty list
+  is not proof no mail was sent. Bodies are truncated to a preview inside the target
+  process (transport-safe, PII-safe by default); attachment content is never returned.
+
+- **`rails_info` Observability section** — `rails_info` now reports `delivery_method`,
+  ActiveJob `queue_adapter`, cache store, and PID, so an agent can tell up front
+  whether mail/jobs are observable in this process.
+
+### Bug Fixes
+
+- **NotificationsSubscriber lifecycle (machine-verified)** — The injected buffer
+  module now separates definition from activation: `.install` is always called and is
+  idempotent, so a module left with zero subscriptions (e.g. an install attempt that
+  raised in signal trap context, where `ActiveSupport::Notifications.subscribe` takes
+  an internal mutex) recovers on the next injection instead of being permanently
+  poisoned. `install` refuses early in trap context. The injected module is versioned
+  so an older one in a long-running process is replaced. Reads use `Mutex#try_lock`
+  with a lockless fallback so a fetch can't deadlock against a debugger-stopped thread.
+  Per-event monotonic `seq` with clock-independent `fetch_last` / `fetch_after_seq`.
+  SQL bodies and request paths are truncated at save time.
+
+- **Notifications event capture over the debug socket** — Results are now
+  returned as the evaluated expression's value (base64-encoded JSON) instead of
+  via `puts`. End-to-end testing against a live rdbg-attached process showed the
+  debug socket does not forward the debuggee's stdout, so the previous
+  `puts(x.to_json)` path returned nothing — this also fixes `trigger_request`'s
+  `Rails Events` section, which used the same mechanism.
+
+### Documentation
+
+- Corrected docs that claimed Rails tools are registered only when a Rails process is
+  detected — they are always registered and guard themselves via `require_rails!`.
+
+## 0.2.1 — 2026-06-17
+
+### Bug Fixes
+
+- **Fix `list_files` with explicit `session_id`** — `list_files` used an outdated
+  `SessionManager#get` call path when a session ID was provided, causing
+  `NoMethodError` instead of listing files. It now uses the same
+  `SessionManager#client(session_id)` API as other tools.
+
 ## 0.2.0 — 2026-05-14
 
 ### Features

data/README.ja.md

@@ -204,15 +204,27 @@ debug-mcp --session-timeout 3600  # 1時間
 | `run_script` | rdbg経由でRubyスクリプトを起動して接続 |
 | `trigger_request` | デバッグ中のRailsアプリにHTTPリクエストを送信 |
 
-### Railsツール（自動検出）
+### Railsツール
 
-Railsプロセスを検出すると自動的に登録されます。
+常時登録されますが、Railsプロセスへの接続が必要で、プレーンなRubyスクリプトに対してはエラーを返します。
 
 | ツール | 説明 |
 |------|------|
-| `rails_info` | アプリ名・Rails/Rubyバージョン・環境・ルートパスを表示 |
+| `rails_info` | アプリ名・Rails/Rubyバージョン・環境・ルートパス・DB設定に加え、**Observability** セクション（delivery method・queue adapter・cache store・PID）を表示 |
 | `rails_routes` | ルーティング一覧（verb, path, controller#action）、コントローラ・パスでフィルタ可能 |
 | `rails_model` | モデル構造：カラム・アソシエーション・バリデーション・enum・スコープを表示 |
+| `rails_recent_events` | `trigger_request` を介さず、実行中プロセスの直近Railsイベント（SQL/render/cache/job/request）を表示 |
+| `rails_mail_deliveries` | `ActionMailer::Base.deliveries` のメール（from/to/件名/本文プレビュー/添付名）を表示 |
+
+### リクエストの外側での実行時観測
+
+次の3ツールで、AIはログを読まずに副作用を確認できます。
+
+- **`rails_info`** は観測の前提条件を報告します。たとえば `delivery_method` が `:test` か（メールを観測できるか）、どの `queue_adapter` を使っているか。AIは「何が見えて何が見えないか」を最初に把握できます。
+- **`rails_recent_events`** は `trigger_request` と同じ `ActiveSupport::Notifications` バッファを、リクエストとは独立に読み出します。**forward-only**（最初の呼び出しでsubscriberをinstallし、それ以降のイベントのみ可視）かつ **paused-only**（対象プロセスがdebuggerプロンプトで停止している必要あり）です。応答には毎回ヘッダ（`installed_at`・`forward_only`・`events_before_install_are_unavailable`・buffer件数/drop件数・`seq` 範囲）が付き、空の結果を「何も起きなかった」と誤解しないようにしています。`after_seq` カーソルで前方ページング可能（時計に非依存）。subscriber注入はプロセス内instrumentationの副作用なので、厳密にはread-onlyではありません。
+- **`rails_mail_deliveries`** は `ActionMailer::Base.deliveries` を構造化します。`delivery_method` が `:test` のときだけ中身が入るため、それ以外では「観測不能」と明示し、空＝未送信ではないことを示します。本文はデフォルトでプレビューに切り詰め（PII対策）、添付の中身は返しません。
+
+> 未提供: 専用の `rails_jobs`（queueスナップショット）ツール。ActiveJobのenqueueは既に `enqueue.active_job` として `rails_recent_events` / `trigger_request` に現れます。TestAdapterの `enqueued_jobs`/`performed_jobs` スナップショットは今後の課題です。
 
 ## Rails イベントキャプチャ
 
@@ -411,7 +423,11 @@ Agent: get_context()
 
 debug-mcpはデバッグツールであり、実行中のRubyプロセスへの深いランタイムアクセスを提供します。
 
-**専用ツールにより任意コード実行を最小化。** 変数の確認・ソースコードの閲覧・モデル構造の調査など、ほとんどのデバッグ操作は任意コードを実行しない専用ツールで行われます。ランタイム検査用に`evaluate_code`も利用可能で、危険な操作に対しては組み込みの安全性チェッカーが警告します。
+**開発環境専用です。** debug-mcpは自分のローカル/開発プロセスへのattachを想定しており、本番環境は対象外です。深いランタイムアクセス（`evaluate_code`によるコード実行を含む）を提供するもので、敵対的な対象に対して安全に作られているわけではありません。
+
+**専用ツールにより任意コード実行を最小化。** 変数の確認・ソースコードの閲覧・モデル構造の調査など、ほとんどのデバッグ操作は任意コードを実行しない専用ツールで行われます。ランタイム検査用に`evaluate_code`も利用可能で、危険な操作に対しては組み込みの安全性チェッカーが警告します。なお、このチェッカーやツール選択の誘導はあくまでadvisory（助言）であり、エージェントを促すだけで実行をブロックするものではありません。
+
+**信頼できないデータには向けないでください。** エージェントは対象プロセスのランタイムデータ（変数値・DBの行・HTTPレスポンスなど）を読み取り、`evaluate_code`を通じてそれに基づいて動作し得ます。上記の安全策はadvisoryなので、そのデータにprompt injectionのペイロードが含まれているとエージェントが誘導される可能性があります。injectionが差し込まれ得る入力を扱うプロセスに対してdebug-mcpを実行しないでください。
 
 **debug gemには認証機能がありません。** デバッグソケットにアクセスできれば、対象プロセスで任意のコードを実行できます。必ずlocalhost（`127.0.0.1`）にバインドするか、Unixソケットを使用してください。具体的な設定例は[Docker節](#docker内のrailsアプリをデバッグ)を参照してください。
 

data/README.md

@@ -205,15 +205,27 @@ The session manager also detects and cleans up sessions whose target process has
 | `run_script` | Start a Ruby script under rdbg and connect to it |
 | `trigger_request` | Send an HTTP request to a Rails app under debug |
 
-### Rails Tools (auto-detected)
+### Rails Tools
 
-These tools are automatically registered when a Rails process is detected.
+These tools are always registered, but they require a connected Rails process and return an error when used against a plain Ruby script.
 
 | Tool | Description |
 |------|-------------|
-| `rails_info` | Show app name, Rails/Ruby versions, environment, root path |
+| `rails_info` | Show app name, Rails/Ruby versions, environment, root path, DB config, and an **Observability** section (delivery method, queue adapter, cache store, PID) |
 | `rails_routes` | Show routes (verb, path, controller#action), filterable by controller or path |
 | `rails_model` | Show model structure: columns, associations, validations, enums, scopes |
+| `rails_recent_events` | Show recent Rails internal events (SQL/render/cache/job/request) from the running process, without `trigger_request` |
+| `rails_mail_deliveries` | Show emails in `ActionMailer::Base.deliveries` (from/to/subject/body preview/attachment names) |
+
+### Runtime observability beyond a single request
+
+Three of the Rails tools let an agent confirm side effects without reading logs:
+
+- **`rails_info`** reports the observability *preconditions* — e.g. whether `delivery_method` is `:test` (so mail is observable) and which `queue_adapter` is in use — so the agent knows up front what it can and cannot see.
+- **`rails_recent_events`** reads the same `ActiveSupport::Notifications` buffer used by `trigger_request`, but independent of a request. It is **forward-only** (the first call installs the subscriber; only events fired afterwards are visible) and **paused-only** (the process must be stopped at a debugger prompt). Every response includes a header — `installed_at`, `forward_only`, `events_before_install_are_unavailable`, buffer size/dropped count, and the `seq` range — so an empty result is never mistaken for "nothing happened". Page forward with the `after_seq` cursor (clock-independent). Installing the subscriber is an in-process instrumentation side effect, so this tool is not strictly read-only.
+- **`rails_mail_deliveries`** structures `ActionMailer::Base.deliveries`. It is only populated when `delivery_method` is `:test`; otherwise the response says so, so an empty list does not imply no mail was sent. Bodies are truncated to a preview (PII-safe by default) and attachment content is never returned.
+
+> Not yet included: a dedicated `rails_jobs` queue-snapshot tool. ActiveJob enqueues already appear in `rails_recent_events` / `trigger_request` via `enqueue.active_job`; a TestAdapter `enqueued_jobs`/`performed_jobs` snapshot is planned as a follow-up.
 
 ## Rails event capture
 
@@ -412,7 +424,11 @@ Agent: get_context()
 
 debug-mcp is a debugging tool that intentionally provides deep runtime access. Here's what you should know:
 
-**Structured tools minimize arbitrary code execution.** Most debugging tasks — viewing variables, reading source code, inspecting model structure — are handled by dedicated tools that don't run arbitrary code. `evaluate_code` is available for runtime inspection, and a built-in safety checker warns about dangerous operations.
+**For development environments only.** debug-mcp is meant for attaching to your own local or development processes — not production. It grants deep runtime access (including code execution via `evaluate_code`) and is not designed to be safe against a hostile target.
+
+**Structured tools minimize arbitrary code execution.** Most debugging tasks — viewing variables, reading source code, inspecting model structure — are handled by dedicated tools that don't run arbitrary code. `evaluate_code` is available for runtime inspection, and a built-in safety checker warns about dangerous operations. Note that this checker and the tool-selection guidance are advisory — they nudge the agent but do not block execution.
+
+**Don't point it at untrusted data.** The agent reads runtime data from the target process (variable values, DB rows, HTTP responses) and can act on it via `evaluate_code`. Because the safeguards above are advisory, a prompt-injection payload in that data could steer the agent. Don't run debug-mcp against a process handling input where injection could be introduced.
 
 **The debug gem has no authentication.** Anyone who can reach the debug socket can execute arbitrary code in the target process. Always bind to localhost (`127.0.0.1`) or use Unix sockets. See the [Docker section](#debug-a-dockerized-rails-app) for configuration examples.
 

data/lib/debug_mcp/notifications_subscriber.rb

@@ -8,6 +8,18 @@ module DebugMcp
   module NotificationsSubscriber
     BUFFER_MAX = 1000
 
+    # Bumped whenever INJECTION_CODE's structure changes so that an older buffer
+    # module already injected into a long-running target process is replaced
+    # instead of silently kept. The injected module exposes `.version` and the
+    # injection guard re-defines the module when the versions differ.
+    VERSION = "2"
+
+    # Save-time caps applied inside the target process, before JSON encoding.
+    # These bound transport size (the debug socket is line-oriented — see
+    # parse_json_array) and limit how much raw SQL / path text we retain.
+    STORE_SQL_MAX = 2000
+    STORE_PATH_MAX = 1000
+
     SUBSCRIBED_EVENTS = %w[
       sql.active_record
       render_template.action_view
@@ -23,38 +35,108 @@ module DebugMcp
       process_action.action_controller
     ].freeze
 
+    # Code injected (via Base64 eval) into the target process. It defines a
+    # process-global ::DebugMcpNotificationsBuffer module that subscribes to
+    # ActiveSupport::Notifications and buffers recent events.
+    #
+    # Lifecycle notes (these fix bugs found by machine verification):
+    # - Module DEFINITION and subscriber ACTIVATION are separated. The
+    #   `.install` call lives OUTSIDE the `unless defined?` guard and is always
+    #   invoked, so a module that was defined but left with zero subscriptions
+    #   (e.g. a previous install attempt raised in trap context) recovers on the
+    #   next injection. `.install` itself is idempotent via `@subscriptions.any?`.
+    # - Reads never block: `safe_read` uses Mutex#try_lock and falls back to a
+    #   lockless read. A blocking `synchronize` would deadlock if a debugger-
+    #   stopped thread is holding the mutex; the process is paused during reads,
+    #   so no writer is actually running and a lockless read is safe.
+    # - A version mismatch re-defines the module (after uninstalling the old one).
     INJECTION_CODE = <<~RUBY
-      unless defined?(::DebugMcpNotificationsBuffer)
-        module ::DebugMcpNotificationsBuffer
-          BUFFER_MAX = #{BUFFER_MAX}
-          SUBSCRIBED_EVENTS = #{SUBSCRIBED_EVENTS.inspect}.freeze
-
-          @buffer = []
-          @subscriptions = []
-          @mutex = Mutex.new
+      unless defined?(::DebugMcpNotificationsBuffer) &&
+             ::DebugMcpNotificationsBuffer.respond_to?(:version) &&
+             ::DebugMcpNotificationsBuffer.version == #{VERSION.inspect}
+        if defined?(::DebugMcpNotificationsBuffer) && ::DebugMcpNotificationsBuffer.respond_to?(:uninstall)
+          ::DebugMcpNotificationsBuffer.uninstall rescue nil
+        end
 
+        module ::DebugMcpNotificationsBuffer
           class << self
             attr_reader :buffer, :subscriptions
 
+            def version; #{VERSION.inspect}; end
+            def buffer_max; #{BUFFER_MAX}; end
+            def subscribed_events; #{SUBSCRIBED_EVENTS.inspect}.freeze; end
+
+            def init!
+              @buffer = []
+              @subscriptions = []
+              @mutex = Mutex.new
+              @seq = 0
+              @dropped = 0
+              @installed_at = nil
+              @buffer_started_at = Time.now.to_f
+            end
+
             def push(event)
               @mutex.synchronize do
+                @seq += 1
+                event[:seq] = @seq
                 @buffer << event
-                @buffer.shift while @buffer.size > BUFFER_MAX
+                while @buffer.size > buffer_max
+                  @buffer.shift
+                  @dropped += 1
+                end
+              end
+            end
+
+            # Read without ever blocking. If try_lock fails the mutex is held by
+            # a debugger-stopped thread; we read locklessly (safe while paused).
+            def safe_read
+              locked = @mutex.try_lock
+              begin
+                yield
+              ensure
+                @mutex.unlock if locked
               end
             end
 
             def fetch_by_request_id(request_id)
-              @mutex.synchronize { @buffer.select { |e| e[:request_id] == request_id } }
+              safe_read { @buffer.select { |e| e[:request_id] == request_id } }
             end
 
             def fetch_since(timestamp)
-              @mutex.synchronize { @buffer.select { |e| e[:timestamp] >= timestamp } }
+              safe_read { @buffer.select { |e| e[:timestamp] >= timestamp } }
+            end
+
+            def fetch_last(n)
+              safe_read { @buffer.last(n) }
+            end
+
+            def fetch_after_seq(cursor)
+              safe_read { @buffer.select { |e| e[:seq] > cursor } }
             end
 
             def clear
               @mutex.synchronize { @buffer.clear }
             end
 
+            def metadata
+              safe_read do
+                {
+                  version: version,
+                  installed: @subscriptions.any?,
+                  installed_at: @installed_at,
+                  buffer_started_at: @buffer_started_at,
+                  buffer_size: @buffer.size,
+                  buffer_max: buffer_max,
+                  dropped_count: @dropped,
+                  oldest_seq: (@buffer.first && @buffer.first[:seq]),
+                  newest_seq: (@buffer.last && @buffer.last[:seq]),
+                  last_seq: @seq,
+                  subscriptions_count: @subscriptions.size,
+                }
+              end
+            end
+
             def install
               return if @subscriptions.any?
 
@@ -74,9 +156,10 @@ module DebugMcp
                 # never raise from subscriber callback
               end
 
-              SUBSCRIBED_EVENTS.each do |event_name|
+              subscribed_events.each do |event_name|
                 @subscriptions << ::ActiveSupport::Notifications.subscribe(event_name, &callback)
               end
+              @installed_at = Time.now.to_f
             end
 
             def uninstall
@@ -107,7 +190,7 @@ module DebugMcp
               case name
               when "sql.active_record"
                 {
-                  sql: payload[:sql].to_s,
+                  sql: truncate_text(payload[:sql].to_s, #{STORE_SQL_MAX}),
                   query_name: payload[:name].to_s,
                   cached: payload[:cached] ? true : false,
                   binds: safe_binds(payload[:type_casted_binds] || payload[:binds]),
@@ -137,7 +220,7 @@ module DebugMcp
                   controller: payload[:controller],
                   action: payload[:action],
                   method: payload[:method],
-                  path: payload[:path],
+                  path: truncate_text(payload[:path].to_s, #{STORE_PATH_MAX}),
                   format: payload[:format].to_s,
                   status: payload[:status],
                   view_runtime: payload[:view_runtime],
@@ -150,6 +233,13 @@ module DebugMcp
               { error: "payload_sanitize_failed: \#{e.class}" }
             end
 
+            def truncate_text(str, limit)
+              return str if str.length <= limit
+              str[0, limit] + "...[truncated \#{str.length - limit} chars]"
+            rescue StandardError
+              "<untruncatable>"
+            end
+
             def safe_binds(binds)
               return [] unless binds.respond_to?(:each)
               binds.map { |b| safe_inspect(b, 100) }
@@ -164,16 +254,25 @@ module DebugMcp
               "<uninspectable>"
             end
           end
+
+          init!
         end
-        ::DebugMcpNotificationsBuffer.install
       end
+      ::DebugMcpNotificationsBuffer.install
     RUBY
 
     class << self
-      # Inject the subscriber into the Rails process. Idempotent.
+      # Inject the subscriber into the Rails process and activate it. Idempotent.
       # Returns true on success, false otherwise.
+      #
+      # Returns false in signal trap context WITHOUT sending the injection: in
+      # trap context ActiveSupport::Notifications.subscribe raises ThreadError
+      # (Fanout#subscribe takes an internal mutex), and merely defining the
+      # module there would leave it with zero subscriptions. We refuse early so
+      # the caller can surface RailsHelper::TRAP_CONTEXT_HINT instead.
       def install(client)
         return false unless RailsHelper.rails?(client)
+        return false if RailsHelper.trap_context?(client)
 
         encoded = Base64.strict_encode64(INJECTION_CODE)
         cmd = "p begin; require 'base64'; eval(::Base64.decode64('#{encoded}').force_encoding('UTF-8')); " \
@@ -197,40 +296,65 @@ module DebugMcp
       def fetch_by_request_id(client, request_id)
         return [] unless request_id
 
-        code = "puts(defined?(::DebugMcpNotificationsBuffer) ? " \
-               "::DebugMcpNotificationsBuffer.fetch_by_request_id(#{request_id.inspect}).to_json : '[]')"
-        result = client.send_command(code)
-        parse_json_array(result)
+        code = RailsHelper.json_command(
+          "defined?(::DebugMcpNotificationsBuffer) ? " \
+          "::DebugMcpNotificationsBuffer.fetch_by_request_id(#{request_id.inspect}).to_json : '[]'",
+        )
+        RailsHelper.decode_json_result(client.send_command(code), [])
       rescue DebugMcp::Error
         []
       end
 
       # Fetch events fired at-or-after the given timestamp.
+      # Prefer fetch_last / fetch_after_seq: those are clock-independent, whereas
+      # this compares against a client-supplied timestamp and is sensitive to
+      # clock skew between the MCP host and the target process.
       def fetch_since(client, timestamp)
-        code = "puts(defined?(::DebugMcpNotificationsBuffer) ? " \
-               "::DebugMcpNotificationsBuffer.fetch_since(#{timestamp.to_f}).to_json : '[]')"
-        result = client.send_command(code)
-        parse_json_array(result)
+        code = RailsHelper.json_command(
+          "defined?(::DebugMcpNotificationsBuffer) ? " \
+          "::DebugMcpNotificationsBuffer.fetch_since(#{timestamp.to_f}).to_json : '[]'",
+        )
+        RailsHelper.decode_json_result(client.send_command(code), [])
       rescue DebugMcp::Error
         []
       end
 
-      private
-
-      def parse_json_array(text)
-        return [] unless text
-        text.each_line do |line|
-          stripped = line.strip
-          next unless stripped.start_with?("[")
-          begin
-            parsed = JSON.parse(stripped, symbolize_names: true)
-            return parsed if parsed.is_a?(Array)
-          rescue JSON::ParserError
-            next
-          end
-        end
+      # Fetch the last n buffered events. Clock-independent.
+      def fetch_last(client, n)
+        code = RailsHelper.json_command(
+          "defined?(::DebugMcpNotificationsBuffer) ? " \
+          "::DebugMcpNotificationsBuffer.fetch_last(#{n.to_i}).to_json : '[]'",
+        )
+        RailsHelper.decode_json_result(client.send_command(code), [])
+      rescue DebugMcp::Error
+        []
+      end
+
+      # Fetch events with seq strictly greater than cursor. Clock-independent
+      # cursor pagination — pass the previous response's newest_seq. An optional
+      # limit caps the result in the TARGET process (oldest-after-cursor first),
+      # so a busy buffer never serializes all 1000 events just to be sliced later.
+      def fetch_after_seq(client, cursor, limit = nil)
+        selector = "::DebugMcpNotificationsBuffer.fetch_after_seq(#{cursor.to_i})"
+        selector += ".first(#{limit.to_i})" if limit
+        code = RailsHelper.json_command(
+          "defined?(::DebugMcpNotificationsBuffer) ? #{selector}.to_json : '[]'",
+        )
+        RailsHelper.decode_json_result(client.send_command(code), [])
+      rescue DebugMcp::Error
         []
       end
+
+      # Fetch subscriber metadata (version, installed_at, buffer_size,
+      # dropped_count, seq cursors, ...). Returns {} if not installed.
+      def metadata(client)
+        code = RailsHelper.json_command(
+          "defined?(::DebugMcpNotificationsBuffer) ? ::DebugMcpNotificationsBuffer.metadata.to_json : '{}'",
+        )
+        RailsHelper.decode_json_result(client.send_command(code), {})
+      rescue DebugMcp::Error
+        {}
+      end
     end
   end
 end

data/lib/debug_mcp/rails_helper.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "base64"
+require "json"
 require_relative "source_tagging"
 
 module DebugMcp
@@ -143,6 +144,32 @@ module DebugMcp
       nil
     end
 
+    # Probe Rails runtime observability settings (trap-safe; uses eval_expr).
+    # Returns a hash of human-readable string values, falling back to
+    # "(unavailable)" when a probe can't be evaluated (e.g. trap context).
+    #
+    # These are plain attribute/class reads (delivery_method, queue adapter
+    # name, cache store class) that do NOT fire ActiveSupport::Notifications
+    # events, so no debug_eval source tagging is needed — consistent with
+    # eval_expr's contract. Shared by rails_info and the mail/recent-events
+    # tools so they report the same observability preconditions.
+    def observability_probe(client)
+      {
+        delivery_method: probe_value(client,
+          "(defined?(ActionMailer::Base) ? ActionMailer::Base.delivery_method : :no_action_mailer)"),
+        queue_adapter: probe_value(client,
+          "(defined?(ActiveJob::Base) ? " \
+          "(ActiveJob::Base.queue_adapter_name rescue ActiveJob::Base.queue_adapter.class.name) : " \
+          ":no_active_job)"),
+        cache_store: probe_value(client,
+          "((defined?(Rails) && Rails.respond_to?(:cache) && Rails.cache) ? Rails.cache.class.name : '(none)')"),
+      }
+    end
+
+    def probe_value(client, expr)
+      eval_expr(client, expr) || "(unavailable)"
+    end
+
     # Get the path to the Rails log file (trap-safe).
     # Returns the absolute path string or nil if not determinable.
     def log_file_path(client)
@@ -155,6 +182,47 @@ module DebugMcp
       nil
     end
 
+    # Wrap a target-side expression that evaluates to a JSON STRING so its value
+    # comes back as a base64 blob on the debug gem's `=> <result>` line.
+    #
+    # Why base64: send_command only returns the evaluated expression's inspected
+    # value; the debuggee's own stdout (anything printed with puts/p) is NOT
+    # forwarded over the debug socket. So we cannot rely on `puts(x.to_json)`
+    # emitting a parseable line — its output goes to the target's stdout and
+    # send_command just sees `=> nil`. Returning the JSON directly would work but
+    # then it is wrapped in Ruby string-inspect escaping (\" , \\ , \n) that is
+    # fragile to undo. Base64's alphabet contains none of those, so it round-trips
+    # through inspect/quoting untouched.
+    def json_command(json_string_expr)
+      "[(#{json_string_expr})].pack(\"m0\")"
+    end
+
+    # Decode the result of a json_command from send_command output. The debug gem
+    # echoes the evaluated value as a quoted string, e.g. `"<base64>"` (sometimes
+    # with a `=> ` prefix, and — for long values — WRAPPED across several lines at
+    # the debugger's width, which read_until_input joins with newlines).
+    #
+    # The value is a base64 blob, whose alphabet contains no `"`, so we take
+    # everything between the first and last double-quote and strip whitespace
+    # (Base64.decode64 also ignores embedded newlines). Returns `default` on any
+    # failure (not installed, parse error, timeout-truncated output, ...).
+    def decode_json_result(output, default)
+      return default unless output
+
+      first = output.index('"')
+      last = output.rindex('"')
+      return default unless first && last && last > first
+
+      b64 = output[(first + 1)...last].gsub(/\s/, "")
+      return default if b64.empty?
+
+      # strict_decode64 (vs decode64) rejects a truncated/corrupt blob instead of
+      # silently returning partial bytes, so we fall back to `default` cleanly.
+      JSON.parse(Base64.strict_decode64(b64), symbolize_names: true)
+    rescue StandardError
+      default
+    end
+
     TRAP_CONTEXT_HINT = "Note: The process may be in signal trap context (common with Puma). " \
                         "Set a breakpoint and use trigger_request to escape trap context first."
   end

data/lib/debug_mcp/server.rb

@@ -23,6 +23,8 @@ require_relative "tools/disconnect"
 require_relative "tools/rails_info"
 require_relative "tools/rails_routes"
 require_relative "tools/rails_model"
+require_relative "tools/rails_recent_events"
+require_relative "tools/rails_mail_deliveries"
 
 module DebugMcp
   class Server
@@ -53,11 +55,17 @@ module DebugMcp
       Tools::TriggerRequest,
     ].freeze
 
-    # Rails tools: dynamically added when a Rails process is detected
+    # Rails tools: always registered (see TOOLS below). They require a connected
+    # Rails process and guard themselves via RailsHelper.require_rails!, returning
+    # an error on plain Ruby targets. register_rails_tools exists for hosts that
+    # want to add them to a pre-built server, but the default server registers
+    # them up front.
     RAILS_TOOLS = [
       Tools::RailsInfo,
       Tools::RailsRoutes,
       Tools::RailsModel,
+      Tools::RailsRecentEvents,
+      Tools::RailsMailDeliveries,
     ].freeze
 
     # All tools (used in tests and for reference)
@@ -116,9 +124,11 @@ module DebugMcp
       trigger_request handles resuming the process automatically.
 
       Rails debugging:
-      When you connect to a Rails process, additional Rails-specific tools become available \
-      automatically (rails_info, rails_routes, rails_model). These tools are NOT shown \
-      when debugging plain Ruby scripts.
+      Rails-specific tools (rails_info, rails_routes, rails_model, rails_recent_events) are \
+      always available, but they require a connected Rails process and will return an error \
+      when used against a plain Ruby script. rails_recent_events shows recent internal events \
+      (SQL, renders, cache, job enqueues) captured from the running process; it is forward-only \
+      (only events after its first call are visible).
 
       Rails debugging workflow:
       1. Start the Rails server with debugging: RUBY_DEBUG_OPEN=true bin/rails server
@@ -134,7 +144,7 @@ module DebugMcp
       7. To debug another request, set new breakpoints and call trigger_request again
       8. When done debugging, use 'disconnect' to detach and resume the server
 
-      Note: rails_info, rails_routes, and rails_model may not work in trap context. \
+      Note: rails_info, rails_routes, rails_model, and rails_recent_events may not work in trap context. \
       Use them after hitting a breakpoint via trigger_request.
 
       Docker / containerized processes:

data/lib/debug_mcp/tools/list_files.rb

@@ -55,11 +55,7 @@ module DebugMcp
         private
 
         def get_client(server_context, session_id)
-          if session_id
-            server_context[:session_manager].get(session_id).client
-          else
-            server_context[:session_manager].client
-          end
+          server_context[:session_manager].client(session_id)
         rescue DebugMcp::Error
           nil
         end
@@ -76,11 +72,7 @@ module DebugMcp
         end
 
         def remote_cwd(server_context, session_id)
-          client = if session_id
-            server_context[:session_manager].get(session_id).client
-          else
-            server_context[:session_manager].client
-          end
+          client = server_context[:session_manager].client(session_id)
           client.auto_repause!
           result = client.send_command("p Dir.pwd")
           cleaned = result.strip.sub(/\A=> /, "")