talk_to_your_app 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 467ae958ec880ab1d8b68a96af59513b371d3ff77beca2e2a50b198d262f49e8
-  data.tar.gz: 92bf430e1aeb96cb9bb0cb1d7719fa8c181b9f946984bd014811da2e03e574d4
+  metadata.gz: 75f1f5c1937a94473396574f7ce8d0162ee3169bfe7d4c44484ba7e7f7244be4
+  data.tar.gz: 85f09fd8619735cdb26c84d7ad7f07eeb4ff194d7084024eccdc40c9f8ec4b2b
 SHA512:
-  metadata.gz: 3e86ab287da1da3cc7669a7bc3c71e3ba435e3a49148df21549895d1092e8165fa1ddd959f33ef2bbc2ecb24513910b4d9b6bf6019db398db529842603548de5
-  data.tar.gz: 38994e1cc2a9ef4e935313ea520357771f23a3d281b84a1160efa7da1ef23c9080adb8c18b4c4e4045a8fbfcd34c3cf170068968429f3573b89d9bfcdb5dac4b
+  metadata.gz: 7efa844413ccc3376ce151e6e8a6f8376bdad560411c34cd8cd89ca93f9f5612d9438cc2ae28194a3e412fc172f1445dfdda59bcbf4b33c43d192c16366f7810
+  data.tar.gz: cc2ba452e469decbc311c708cef55edc482d1216a523367ebdbf1a227e6355c9342b31b02e436d7dba1fc63d77bb3767c83e1e6fc63d4aeddb48a2e3a45459d9

data/CHANGELOG.md

@@ -6,6 +6,18 @@ breaking changes.
 
 ## [Unreleased]
 
+### Added
+- **New `health` plugin.** Exposes operator-registered health checks as MCP tools:
+  `health.list` (names of registered checks) and `health.run` (execute one, get
+  `{ name, passed, value }`). Register checks in the initializer with
+  `config.health_check(:name) { ... }` — the block returns a bare boolean or a
+  `[passed, value]` pair. A raising check is reported as a failed check
+  (`passed: false`, `error: "..."`) rather than a 500, matching the DB and
+  Flipper plugins' posture toward backend failures. No scheduling, aggregation,
+  or alerting in v1 — see `docs/brainstorms/talk-to-your-app-gem-v1-requirements.md`
+  (R20-R22), which specified this plugin as part of the original v1 scope but
+  was not yet implemented.
+
 ## [0.2.0] - 2026-09-02
 
 ### Changed

data/README.md

@@ -178,6 +178,7 @@ All plugins are **off by default** — enable them explicitly, and an agent can
 | [Flipper](#flipper) | Read and toggle feature flags (global, actor, group, %) | `config.plugin :flipper, connection: :writer` |
 | [Rake](#rake-allow-listed-task-runner) | Run allow-listed rake tasks and read their output | `config.plugin :rake, connection: false, allowed: [...]` |
 | [Cache](#cache) | Clear the Rails cache | `config.plugin :cache, connection: false` |
+| [Health](#health) | List and run operator-registered health checks | `config.plugin :health, connection: false` |
 | [Custom Tools](#custom-tools) | Call tools you write yourself (writes allowed) | `config.plugin :custom_tools, connection: false` |
 
 ### DB
@@ -314,6 +315,36 @@ config.plugin :cache, connection: false
 
 - **`cache.clear`** — calls `Rails.cache.clear` and returns `{ cleared, store }`. Every cached entry is dropped and the app re-warms from cold, so scope it to trusted principals: `config.authorize { |principal, tool, _args| tool != "cache.clear" || principal == "admin" }`.
 
+### Health
+
+Exposes health checks you register in Ruby as MCP tools — the "is X actually working" questions that don't map onto a SQL query, a job queue, or a feature flag: is the third-party transcription API responding, are the last N video-generation jobs succeeding, is the payment webhook queue caught up.
+
+```ruby
+config.plugin :health, connection: false
+
+config.health_check(:video_pipeline) do
+  recent = VideoJob.where("created_at > ?", 15.minutes.ago)
+  [recent.any? && recent.all?(&:succeeded?), recent.count]
+end
+
+config.health_check(:transcription_api, timeout: 3) do
+  Transcription::Client.ping? # a bare boolean is fine too
+end
+```
+
+A check is a block that takes no arguments and returns either a bare boolean (pass/fail, no extra value) or a `[passed, value]` pair, where `value` is any JSON-serializable payload worth surfacing alongside the result (a count, a status string, a timestamp). Any other return shape (a bare number, `nil`, a 3-element array, ...) is rejected as a tool error rather than guessed at — silently coercing e.g. `0` or `nil` via Ruby truthiness would misreport the exact thing this tool exists to report accurately. Re-registering a name overwrites it, so re-running the initializer in a test or console session doesn't accumulate duplicates.
+
+`timeout:` (seconds, default `10`) bounds how long `health.run` waits on the block. A check is arbitrary code that may call a third-party API — without a bound, a wedged dependency hangs the calling thread indefinitely, which on a multi-threaded Puma worker can starve the whole MCP endpoint. A timed-out check reports `passed: false` the same as any other failure.
+
+> ⚠️ **`timeout:` is a best-effort backstop, not a hard kill — unlike Rake's subprocess `timeout:` above.** It's implemented with Ruby's `Timeout.timeout`, which can't interrupt a thread blocked inside a C extension (a stuck socket read in an HTTP client, a blocking DB driver call, a stalled DNS lookup) — exactly the shape of a real third-party API outage. Prefer the dependency's own timeout/deadline option inside the check when it has one.
+
+> ⚠️ **The registered block is a single `Proc` invoked concurrently** by every simultaneous `health.run` call for that name. Don't lazily assign to a closed-over local (`@client ||= build_client`) inside the block — that's a data race across concurrent requests. Build any long-lived resource once, outside the block, and reference it; fetch anything request-scoped fresh inside the block.
+
+- **`health.list`** — the names of every registered check, sorted.
+- **`health.run`** — `name` (required, must be a registered check). Returns `{ name, passed, value }`. A check that raises or times out is reported as `{ passed: false, value: nil, error: "<class>" }` rather than surfacing a 500 — the same posture the DB and Flipper plugins take toward backend failures. The full exception (class **and** message) is logged server-side at `warn`; only the exception class reaches the MCP client, since the rescued code is arbitrary operator Ruby and a message can easily embed a URL, token, or internal hostname.
+
+v1 is deliberately minimal: no scheduling, no aggregation across runs, no alerting, no historical storage. A check runs exactly when `health.run` is called and reports that one result. Wire it into your own scheduler/alerting if you want more.
+
 ### Custom Tools
 
 Write your own tools by subclassing `TalkToYourApp::Tool` — the same base class the bundled tools use, with typed arguments and **writes allowed** (unlike the read-only DB plugin). Drop one per file in `app/talk_to_your_app/custom_tools/` and it's exposed automatically; no explicit registration.

data/lib/generators/talk_to_your_app/install/templates/initializer.rb.tt

@@ -101,6 +101,7 @@ TalkToYourApp.configure do |config|
   # config.plugin :flipper, connection: :write      # Flipper writes flag state — requires a :writing connection
   # config.plugin :rake, connection: false, allowed: ["stats", "report:generate"]   # optional: timeout: 60 (per-task seconds, default 20)
   # config.plugin :cache, connection: false         # cache.clear (Rails.cache.clear) — destructive, scope with config.authorize
+  # config.plugin :health, connection: false        # health.list / health.run over config.health_check blocks
   # config.plugin :custom_tools, connection: false  # or connection: :read to give tools a default
   #
   # DANGER — running :db against a writable connection. Wiring a :writing

data/lib/talk_to_your_app/configuration.rb

@@ -10,6 +10,8 @@ module TalkToYourApp
   # the TalkToYourApp module, so calling `TalkToYourApp.configure` more than
   # once merges into the same instance rather than replacing it.
   class Configuration
+    DEFAULT_HEALTH_CHECK_TIMEOUT = 10
+
     # Path the MCP endpoint is mounted at in the host app's router. Default "/mcp".
     attr_accessor :mount_at
 
@@ -83,6 +85,8 @@ module TalkToYourApp
       @instructions = nil
       @connections = {}
       @enabled_plugins = {}
+      @health_checks = {}
+      @health_checks_mutex = Mutex.new
       @logger = nil
       @api_keys = {}
       @allowed_origins = []
@@ -132,6 +136,19 @@ module TalkToYourApp
       false
     end
 
+    def health_check(name, timeout: DEFAULT_HEALTH_CHECK_TIMEOUT, &block)
+      raise ArgumentError, "health_check #{name.inspect}: a block is required" unless block
+      unless timeout.is_a?(Numeric) && timeout.positive?
+        raise ArgumentError, "health_check #{name.inspect}: timeout must be a positive number, got #{timeout.inspect}"
+      end
+
+      @health_checks_mutex.synchronize { @health_checks[name.to_sym] = { block: block, timeout: timeout } }
+    end
+
+    def health_checks
+      @health_checks_mutex.synchronize { @health_checks.dup }
+    end
+
     # Declared named connections, keyed by gem-internal symbol name.
     attr_reader :connections
 

data/lib/talk_to_your_app/plugins/health/plugin.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "../../plugin"
+require_relative "tools/list_checks"
+require_relative "tools/run_check"
+
+module TalkToYourApp
+  module Plugins
+    module Health
+      class Plugin < TalkToYourApp::Plugin
+        tools Tools::ListChecks, Tools::RunCheck
+      end
+    end
+  end
+end
+
+TalkToYourApp.register_plugin(:health, TalkToYourApp::Plugins::Health::Plugin)

data/lib/talk_to_your_app/plugins/health/tools/list_checks.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative "../../../tool"
+
+module TalkToYourApp
+  module Plugins
+    module Health
+      module Tools
+        class ListChecks < TalkToYourApp::Tool
+          name        "health.list"
+          description "List the names of registered health checks."
+
+          def call(_args, _ctx)
+            json(checks: TalkToYourApp.configuration.health_checks.keys.map(&:to_s).sort)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/talk_to_your_app/plugins/health/tools/run_check.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "timeout"
+require_relative "../../../tool"
+
+module TalkToYourApp
+  module Plugins
+    module Health
+      module Tools
+        class RunCheck < TalkToYourApp::Tool
+          # Deliberately < Exception, not StandardError: Timeout.timeout raises
+          # wherever the block is currently executing, including inside a
+          # check's own `rescue StandardError`. A StandardError subclass here
+          # would let a broad rescue in the check's body swallow the timeout
+          # before we ever see it. Exception is what Ruby's own Timeout.timeout
+          # uses internally for the same reason, so this can't be caught by an
+          # ordinary application-level rescue. `ensure` blocks still run.
+          class HealthCheckTimeout < Exception; end
+          private_constant :HealthCheckTimeout
+
+          name        "health.run"
+          description "Run a named health check and return pass/fail plus its value."
+          argument    :name, :string, required: true, description: "Health check name, from health.list."
+
+          def call(args, _ctx)
+            check = TalkToYourApp.configuration.health_checks[args[:name].to_sym]
+            return error("Unknown health check: #{args[:name].inspect}. Call health.list for the registered names.") unless check
+
+            result = Timeout.timeout(check[:timeout], HealthCheckTimeout) { check[:block].call }
+            normalized = normalize(args[:name], result)
+            if normalized.is_a?(String)
+              log_failure(args[:name], normalized)
+              return error(normalized)
+            end
+
+            passed, value = normalized
+            json(name: args[:name], passed: passed, value: value)
+          rescue HealthCheckTimeout
+            log_failure(args[:name], "timed out after #{check[:timeout]}s")
+            json(name: args[:name], passed: false, value: nil, error: "timed out after #{check[:timeout]}s")
+          rescue StandardError => e
+            log_failure(args[:name], "#{e.class}: #{e.message}")
+            json(name: args[:name], passed: false, value: nil, error: e.class.name)
+          end
+
+          private
+
+          def log_failure(name, message)
+            TalkToYourApp.configuration.logger&.warn("talk_to_your_app: health check #{name.inspect} failed: #{message}")
+          rescue StandardError
+            nil
+          end
+
+          def normalize(check_name, result)
+            case result
+            when Array
+              unless result.size == 2 && [true, false].include?(result[0])
+                return "health check #{check_name.inspect} returned an array of shape #{result.inspect} — " \
+                       "expected exactly [passed, value] with passed a true/false."
+              end
+              result
+            when true, false
+              [result, nil]
+            else
+              "health check #{check_name.inspect} returned #{result.class}, expected a boolean or [passed, value]."
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/talk_to_your_app/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TalkToYourApp
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/talk_to_your_app.rb

@@ -146,4 +146,5 @@ require_relative "talk_to_your_app/plugins/jobs/plugin"
 require_relative "talk_to_your_app/plugins/flipper/plugin"
 require_relative "talk_to_your_app/plugins/rake/plugin"
 require_relative "talk_to_your_app/plugins/cache/plugin"
+require_relative "talk_to_your_app/plugins/health/plugin"
 require_relative "talk_to_your_app/plugins/custom_tools/plugin"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: talk_to_your_app
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Igor Kasyanchuk
@@ -96,6 +96,9 @@ files:
 - lib/talk_to_your_app/plugins/flipper/tools/enabled_flags.rb
 - lib/talk_to_your_app/plugins/flipper/tools/list_flags.rb
 - lib/talk_to_your_app/plugins/flipper/tools/read_flag.rb
+- lib/talk_to_your_app/plugins/health/plugin.rb
+- lib/talk_to_your_app/plugins/health/tools/list_checks.rb
+- lib/talk_to_your_app/plugins/health/tools/run_check.rb
 - lib/talk_to_your_app/plugins/jobs/adapters/sidekiq.rb
 - lib/talk_to_your_app/plugins/jobs/adapters/solid_queue.rb
 - lib/talk_to_your_app/plugins/jobs/interface.rb