talk_to_your_app 0.1.0.pre.1

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

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module TalkToYourApp
+  # The operator-facing health-check registry. Host developers register named
+  # checks in Ruby; the Health plugin exposes them over MCP. Checks are plain
+  # callables owned by the host app — the gem does no scheduling, aggregation,
+  # alerting, or historical storage.
+  #
+  # Put one check per file under app/talk_to_your_app/health/ (loaded
+  # automatically by the :health plugin); each file calls register:
+  #
+  #   TalkToYourApp::Health.register(:video_pipeline, description: "Encoder lag") do
+  #     { status: :pass, value: encoder_lag_ratio }
+  #   end
+  module Health
+    Check = Struct.new(:name, :description, :callable)
+
+    module_function
+
+    # Registers a check by block or callable. Re-registering a name replaces it
+    # and warns, so a typo'd duplicate is visible rather than silent.
+    def register(name, callable = nil, description: nil, &block)
+      runnable = block || callable
+      raise ArgumentError, "health check #{name.inspect} needs a block or callable" unless runnable
+
+      key = name.to_sym
+      warn("talk_to_your_app: health check #{key.inspect} was already registered; replacing it.") if checks.key?(key)
+      checks[key] = Check.new(key, description, runnable)
+    end
+
+    def checks
+      @checks ||= {}
+    end
+
+    def registered?(name)
+      checks.key?(name.to_sym)
+    end
+
+    def clear!
+      @checks = {}
+    end
+
+    # Runs a check and returns a normalized result hash. A raised exception is
+    # caught and reported as status "error" rather than crashing the request.
+    def run(name)
+      check = checks[name.to_sym]
+      return nil unless check
+
+      normalize(check.callable.call)
+    rescue StandardError => e
+      { status: "error", error_class: e.class.name, message: e.message }
+    end
+
+    # Accepts a bare boolean or a { status:, value:, message: } hash.
+    def normalize(result)
+      case result
+      when true  then { status: "pass" }
+      when false then { status: "fail" }
+      when Hash
+        normalized = result.transform_keys(&:to_sym)
+        normalized[:status] = normalized[:status].to_s if normalized[:status]
+        normalized
+      else
+        { status: "pass", value: result }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative "../../../tool"
+
+module TalkToYourApp
+  module Plugins
+    module Health
+      module Tools
+        # Lists the registered health checks with their descriptions.
+        class ListChecks < TalkToYourApp::Tool
+          name        "health.list"
+          description "List the registered health checks."
+
+          def call(_args, _ctx)
+            checks = TalkToYourApp::Health.checks.values.map do |check|
+              { name: check.name, description: check.description }
+            end
+            json(checks: checks)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "../../../tool"
+
+module TalkToYourApp
+  module Plugins
+    module Health
+      module Tools
+        # Runs a named health check and returns its normalized result. An unknown
+        # name is a usage error (MCP tool error); a check that runs but fails or
+        # raises returns a normal result whose `status` carries the outcome.
+        class RunCheck < TalkToYourApp::Tool
+          name        "health.run"
+          description "Run a named health check and return pass/fail plus its value."
+          argument    :name, :string, required: true, description: "The registered check name."
+
+          def call(args, _ctx)
+            result = TalkToYourApp::Health.run(args[:name])
+            return error("Unknown health check: #{args[:name]}") if result.nil?
+
+            json(result)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/talk_to_your_app/plugins/jobs/adapters/sidekiq.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require "time"
+
+module TalkToYourApp
+  module Plugins
+    module Jobs
+      module Adapters
+        # Sidekiq adapter. Reads queue, retry, and dead-set data through
+        # Sidekiq's public API. Read-only: it never enqueues, retries, or kills.
+        # All four methods return the common shape defined by Jobs::Interface.
+        module Sidekiq
+          REQUIRED_GEM = { const: "Sidekiq", gem_name: "sidekiq" }.freeze
+
+          module_function
+
+          def required_gem
+            REQUIRED_GEM
+          end
+
+          def queue_sizes
+            ::Sidekiq::Stats.new.queues
+          end
+
+          # Sidekiq has no first-class "recent jobs" API; we scan the queues and
+          # the retry set, sort newest-first by enqueued time, and cap at limit.
+          # Per-queue fetch is bounded so a many-queue install does not materialize
+          # limit*queue_count records to return `limit`; this can miss the very
+          # newest jobs when they cluster in one queue, which is acceptable for an
+          # inspection tool.
+          def recent_jobs(limit:)
+            queues = ::Sidekiq::Queue.all
+            per_queue = [(limit / [queues.size, 1].max) + 1, limit].min
+            queued = queues.flat_map { |queue| queue.first(per_queue) }
+            retries = ::Sidekiq::RetrySet.new.first(limit)
+            (queued + retries)
+              .sort_by { |entry| -raw_enqueued_at(entry) }
+              .first(limit)
+              .map { |entry| job_hash(entry) }
+          end
+
+          def failed_jobs(limit:)
+            ::Sidekiq::DeadSet.new.first(limit).map { |entry| job_hash(entry) }
+          end
+
+          # Worker/queue health. Lists the running Sidekiq processes with their
+          # concurrency and busy-thread counts, plus set sizes.
+          def health
+            require "sidekiq/api"
+            stats = ::Sidekiq::Stats.new
+            processes = ::Sidekiq::ProcessSet.new.map do |process|
+              {
+                hostname: process["hostname"],
+                pid: process["pid"],
+                concurrency: process["concurrency"],
+                busy: process["busy"],
+                queues: process["queues"],
+                started_at: process["started_at"] ? Time.at(process["started_at"].to_f).utc.iso8601 : nil,
+                quiet: process["quiet"] == "true",
+              }
+            end
+            {
+              adapter: "sidekiq",
+              processes: processes,
+              process_count: processes.size,
+              total_concurrency: processes.sum { |p| p[:concurrency].to_i },
+              busy_threads: stats.workers_size,
+              enqueued: stats.enqueued,
+              scheduled: stats.scheduled_size,
+              retries: stats.retry_size,
+              dead: stats.dead_size,
+              default_queue_latency: ::Sidekiq::Queue.new.latency,
+            }
+          end
+
+          # Sidekiq exposes cumulative and day-resolution counts, not arbitrary
+          # trailing windows; the response says so via `note`.
+          def rate_metrics(window:)
+            stats = ::Sidekiq::Stats.new
+            {
+              window_seconds: window,
+              processed: stats.processed,
+              failed: stats.failed,
+              enqueued: stats.enqueued,
+              note: "Sidekiq reports cumulative processed/failed counts; the window is not applied at sub-day resolution.",
+            }
+          end
+
+          # Both Sidekiq::JobRecord and Sidekiq::SortedEntry expose the raw job
+          # hash via #item. Keys are always present (nil where absent) so the
+          # shape is stable across adapters and across recent/failed.
+          def job_hash(entry)
+            item = entry.respond_to?(:item) ? entry.item : entry
+            {
+              jid: item["jid"],
+              class: item["class"] || item["wrapped"],
+              queue: item["queue"],
+              args: item["args"],
+              enqueued_at: iso8601(item["enqueued_at"] || item["created_at"]),
+              error_message: item["error_message"],
+            }
+          end
+
+          # Sidekiq stores timestamps as Unix floats; surface ISO-8601 so the
+          # field type matches the Solid Queue adapter.
+          def iso8601(unix_timestamp)
+            return nil unless unix_timestamp
+
+            Time.at(unix_timestamp.to_f).utc.iso8601
+          end
+
+          def raw_enqueued_at(entry)
+            item = entry.respond_to?(:item) ? entry.item : entry
+            (item["enqueued_at"] || item["created_at"] || 0).to_f
+          end
+        end
+      end
+    end
+  end
+end
+
+TalkToYourApp::Plugins::Jobs.register_adapter(:sidekiq, TalkToYourApp::Plugins::Jobs::Adapters::Sidekiq)

data/lib/talk_to_your_app/plugins/jobs/adapters/solid_queue.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module TalkToYourApp
+  module Plugins
+    module Jobs
+      module Adapters
+        # Solid Queue adapter. Reads Solid Queue's ActiveRecord models, which
+        # live in the host application's database. By default the queries run on
+        # the primary connection (whatever Solid Queue itself is configured to
+        # use); operators wanting isolation point Solid Queue at a separate
+        # database in their own config. Read-only and returns the common shape.
+        module SolidQueue
+          REQUIRED_GEM = { const: "SolidQueue", gem_name: "solid_queue" }.freeze
+
+          module_function
+
+          def required_gem
+            REQUIRED_GEM
+          end
+
+          def queue_sizes
+            ::SolidQueue::ReadyExecution.group(:queue_name).count
+          end
+
+          def recent_jobs(limit:)
+            ::SolidQueue::Job.order(created_at: :desc).limit(limit).map { |job| job_hash(job) }
+          end
+
+          def failed_jobs(limit:)
+            ::SolidQueue::FailedExecution.includes(:job).order(created_at: :desc).limit(limit).map do |failure|
+              job_hash(failure.job).merge(error_message: failure.message)
+            end
+          end
+
+          # Worker/queue health. Lists the registered Solid Queue processes
+          # (supervisor/workers/dispatcher/scheduler) with their last heartbeat,
+          # plus pending/claimed/scheduled/failed counts.
+          def health
+            processes = ::SolidQueue::Process.all.map do |process|
+              {
+                kind: process.kind,
+                hostname: process.hostname,
+                pid: process.pid,
+                name: process.name,
+                last_heartbeat_at: process.last_heartbeat_at&.utc&.iso8601,
+              }
+            end
+            {
+              adapter: "solid_queue",
+              processes: processes,
+              process_count: processes.size,
+              workers: processes.count { |p| p[:kind].to_s.include?("Worker") },
+              pending: ::SolidQueue::ReadyExecution.count,
+              claimed: ::SolidQueue::ClaimedExecution.count,
+              scheduled: ::SolidQueue::ScheduledExecution.count,
+              failed: ::SolidQueue::FailedExecution.count,
+            }
+          end
+
+          def rate_metrics(window:)
+            since = Time.now - window.to_i # plain Ruby; no ActiveSupport core-ext dependency
+            {
+              window_seconds: window,
+              enqueued: ::SolidQueue::Job.where(created_at: since..).count,
+              processed: ::SolidQueue::Job.where.not(finished_at: nil).where(finished_at: since..).count,
+              failed: ::SolidQueue::FailedExecution.where(created_at: since..).count,
+            }
+          end
+
+          def job_hash(job)
+            # Keep every key present even for an orphaned failure (nil job), so
+            # the shape matches the Sidekiq adapter.
+            return { jid: nil, class: nil, queue: nil, args: nil, enqueued_at: nil, error_message: nil } unless job
+
+            {
+              jid: job.active_job_id || job.id,
+              class: job.class_name,
+              queue: job.queue_name,
+              args: job.arguments,
+              enqueued_at: job.created_at&.utc&.iso8601,
+              error_message: nil, # failed_jobs overrides this; present for shape stability
+            }
+          end
+        end
+      end
+    end
+  end
+end
+
+TalkToYourApp::Plugins::Jobs.register_adapter(:solid_queue, TalkToYourApp::Plugins::Jobs::Adapters::SolidQueue)

data/lib/talk_to_your_app/plugins/jobs/interface.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module TalkToYourApp
+  module Plugins
+    module Jobs
+      # The contract every jobs adapter must satisfy. Adapters duck-type it —
+      # there is no abstract base class and no `include`. Each method returns a
+      # plain Ruby structure with a stable shape across adapters, so a client
+      # sees the same response whether the backend is Sidekiq or Solid Queue.
+      #
+      #   queue_sizes            -> { "queue_name" => Integer, ... }
+      #   recent_jobs(limit:)    -> [ { jid:, class:, queue:, args:, enqueued_at:, error_message: }, ... ]
+      #   failed_jobs(limit:)    -> [ { jid:, class:, queue:, args:, enqueued_at:, error_message: }, ... ]
+      #   rate_metrics(window:)  -> { window_seconds:, processed:, failed:, enqueued:, note? }
+      #   health                 -> { adapter:, processes:[...], ... } (adapter-specific)
+      #
+      # `health` is intentionally adapter-specific: it reports worker/process
+      # health (running processes, threads/concurrency, pending/claimed counts),
+      # whose meaningful fields differ between backends. Every adapter includes
+      # an `adapter:` key so clients can branch on it.
+      #
+      # Job hashes carry the same keys across adapters and across recent/failed;
+      # `enqueued_at` is an ISO-8601 string and `error_message` is nil for jobs
+      # that have not failed. `window:` is a number of seconds; adapters that
+      # cannot honor sub-day granularity include a `note` explaining the
+      # resolution they returned.
+      module Interface
+        METHODS = %i[queue_sizes recent_jobs failed_jobs rate_metrics health].freeze
+
+        # True when the adapter responds to every interface method. Checked at
+        # boot so an incomplete adapter fails fast rather than at first call.
+        def self.satisfied_by?(adapter)
+          METHODS.all? { |method| adapter.respond_to?(method) }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require_relative "../../plugin"
+require_relative "interface"
+require_relative "tools/queue_sizes"
+require_relative "tools/recent_jobs"
+require_relative "tools/failed_jobs"
+require_relative "tools/rate_metrics"
+require_relative "tools/health"
+
+module TalkToYourApp
+  module Plugins
+    # The Jobs plugin exposes read-only background-job metrics through a common
+    # interface, backed by an operator-selected adapter. Adapters register
+    # themselves (U8 Sidekiq, U9 Solid Queue); the operator declares which one
+    # with `config.plugin :jobs, adapter: :sidekiq`. Selection is explicit, never
+    # auto-detected — boot fails if no adapter is declared or the named one is
+    # unknown or its backing gem is absent.
+    module Jobs
+      @adapters = {}
+
+      class << self
+        # Registers an adapter class under a name. The class duck-types
+        # Jobs::Interface and exposes `required_gem` ({ const:, gem_name: }).
+        def register_adapter(name, adapter_class)
+          @adapters[name.to_sym] = adapter_class
+        end
+
+        def adapter_for(name)
+          @adapters[name&.to_sym]
+        end
+
+        def known_adapter_names
+          @adapters.keys
+        end
+
+        # Resolves the adapter selected in the current configuration.
+        def configured_adapter
+          options = TalkToYourApp.configuration.enabled_plugins[:jobs] || {}
+          adapter_for(options[:adapter]) ||
+            raise(ConfigurationError, "talk_to_your_app: the jobs plugin has no adapter configured.")
+        end
+      end
+
+      class Plugin < TalkToYourApp::Plugin
+        tools Tools::QueueSizes, Tools::RecentJobs, Tools::FailedJobs, Tools::RateMetrics, Tools::Health
+
+        def self.validate_enablement!(options)
+          adapter_name = options[:adapter]
+          if adapter_name.nil?
+            raise ConfigurationError,
+              "talk_to_your_app: the jobs plugin requires an `adapter:` option, e.g. " \
+              "`config.plugin :jobs, adapter: :sidekiq`."
+          end
+
+          adapter = Jobs.adapter_for(adapter_name)
+          unless adapter
+            raise ConfigurationError,
+              "talk_to_your_app: jobs adapter #{adapter_name.inspect} is not supported. " \
+              "Available adapters: #{Jobs.known_adapter_names.inspect}."
+          end
+
+          req = adapter.required_gem
+          if req && !Object.const_defined?(req[:const])
+            raise ConfigurationError,
+              "talk_to_your_app: jobs adapter #{adapter_name.inspect} requires the `#{req[:gem_name]}` gem " \
+              "(constant #{req[:const]} is not defined)."
+          end
+
+          unless Interface.satisfied_by?(adapter)
+            raise ConfigurationError,
+              "talk_to_your_app: jobs adapter #{adapter_name.inspect} does not implement the full interface " \
+              "(#{Interface::METHODS.join(", ")})."
+          end
+        end
+      end
+    end
+  end
+end
+
+TalkToYourApp.register_plugin(:jobs, TalkToYourApp::Plugins::Jobs::Plugin)
+
+# Bundled adapters self-register on load (after Jobs.register_adapter exists).
+# They reference their backing gem's constants only inside method bodies, so
+# loading them never requires the gem.
+require_relative "adapters/sidekiq"
+require_relative "adapters/solid_queue"

data/lib/talk_to_your_app/plugins/jobs/tools/failed_jobs.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "../../../tool"
+
+module TalkToYourApp
+  module Plugins
+    module Jobs
+      module Tools
+        # Returns recently failed jobs with their error messages, capped at 500.
+        class FailedJobs < TalkToYourApp::Tool
+          MAX_LIMIT = 500
+
+          name        "jobs.failed_jobs"
+          description "Recently failed jobs and their error messages."
+          argument    :limit, :integer, default: 50, minimum: 1, maximum: MAX_LIMIT,
+            description: "How many failed jobs to return (1-500)."
+
+          def call(args, _ctx)
+            limit = args[:limit].to_i.clamp(1, MAX_LIMIT)
+            json(TalkToYourApp::Plugins::Jobs.configured_adapter.failed_jobs(limit: limit))
+          rescue StandardError => e
+            error("Jobs backend unavailable: #{e.class}: #{e.message}")
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "../../../tool"
+
+module TalkToYourApp
+  module Plugins
+    module Jobs
+      module Tools
+        # Reports worker/queue health: running processes, threads/concurrency,
+        # and pending/claimed/scheduled counts. The shape is adapter-specific
+        # (each response carries an `adapter` key to branch on).
+        class Health < TalkToYourApp::Tool
+          name        "jobs.health"
+          description "Background-job worker/queue health (processes, threads, pending). Adapter-specific."
+
+          def call(_args, _ctx)
+            json(TalkToYourApp::Plugins::Jobs.configured_adapter.health)
+          rescue StandardError => e
+            error("Jobs backend unavailable: #{e.class}: #{e.message}")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/talk_to_your_app/plugins/jobs/tools/queue_sizes.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative "../../../tool"
+
+module TalkToYourApp
+  module Plugins
+    module Jobs
+      module Tools
+        # Returns the current size of each queue as { queue_name => count }.
+        class QueueSizes < TalkToYourApp::Tool
+          name        "jobs.queue_sizes"
+          description "Current size of each background-job queue."
+
+          def call(_args, _ctx)
+            json(TalkToYourApp::Plugins::Jobs.configured_adapter.queue_sizes)
+          rescue StandardError => e
+            error("Jobs backend unavailable: #{e.class}: #{e.message}")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/talk_to_your_app/plugins/jobs/tools/rate_metrics.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative "../../../tool"
+
+module TalkToYourApp
+  module Plugins
+    module Jobs
+      module Tools
+        # Processed/failed/enqueued counts over a trailing window. The window is
+        # expressed in seconds (default 30 minutes); adapters that cannot honor
+        # sub-day granularity say so in the response `note`.
+        class RateMetrics < TalkToYourApp::Tool
+          DEFAULT_WINDOW_SECONDS = 1800
+
+          name        "jobs.rate_metrics"
+          description "Processed/failed/enqueued counts over a trailing window (seconds)."
+          argument    :window, :integer, default: DEFAULT_WINDOW_SECONDS, minimum: 1,
+            description: "Trailing window in seconds (default 1800 = 30 minutes)."
+
+          def call(args, _ctx)
+            window = args[:window] || DEFAULT_WINDOW_SECONDS
+            json(TalkToYourApp::Plugins::Jobs.configured_adapter.rate_metrics(window: window))
+          rescue StandardError => e
+            error("Jobs backend unavailable: #{e.class}: #{e.message}")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/talk_to_your_app/plugins/jobs/tools/recent_jobs.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "../../../tool"
+
+module TalkToYourApp
+  module Plugins
+    module Jobs
+      module Tools
+        # Returns the most recently enqueued jobs, newest first, capped at 500.
+        class RecentJobs < TalkToYourApp::Tool
+          MAX_LIMIT = 500
+
+          name        "jobs.recent_jobs"
+          description "Most recently enqueued jobs (newest first)."
+          argument    :limit, :integer, default: 50, minimum: 1, maximum: MAX_LIMIT,
+            description: "How many jobs to return (1-500)."
+
+          def call(args, _ctx)
+            limit = args[:limit].to_i.clamp(1, MAX_LIMIT)
+            json(TalkToYourApp::Plugins::Jobs.configured_adapter.recent_jobs(limit: limit))
+          rescue StandardError => e
+            error("Jobs backend unavailable: #{e.class}: #{e.message}")
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative "../../plugin"
+require_relative "tools/run"
+
+module TalkToYourApp
+  module Plugins
+    # The Rake plugin runs operator-approved rake tasks over MCP. It is
+    # fail-closed and allow-list-only: it refuses to boot without an explicit
+    # `allowed:` list, and refuses any task not on that list. Because rake tasks
+    # can do anything, the allow-list is the security boundary — keep it tight,
+    # and prefer read-only/reporting tasks.
+    #
+    #   config.plugin :rake, allowed: ["stats", "report:generate"]
+    module Rake
+      module_function
+
+      def allowed_tasks
+        options = TalkToYourApp.configuration.enabled_plugins[:rake] || {}
+        Array(options[:allowed]).map(&:to_s)
+      end
+
+      def allowed?(task)
+        allowed_tasks.include?(task.to_s)
+      end
+
+      class Plugin < TalkToYourApp::Plugin
+        tools Tools::Run
+
+        def self.validate_enablement!(options)
+          return unless Array(options[:allowed]).empty?
+
+          raise ConfigurationError,
+            "talk_to_your_app: the rake plugin requires a non-empty `allowed:` list of rake task names, " \
+            "e.g. `config.plugin :rake, allowed: [\"stats\", \"report:generate\"]`. Tasks not on the list are refused."
+        end
+      end
+    end
+  end
+end
+
+TalkToYourApp.register_plugin(:rake, TalkToYourApp::Plugins::Rake::Plugin)