mcpeye 0.1.0

data/lib/mcpeye/tracker.rb

@@ -0,0 +1,844 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+require "securerandom"
+
+require_relative "intent"
+require_relative "request_capability"
+require_relative "redaction"
+
+module Mcpeye
+  # Tracker instruments a Ruby/Rails MCP server:
+  #
+  #   1. Injects the optional `mcpeyeIntent` parameter into each tool's input
+  #      schema (so the agent self-reports intent at near-zero cost).
+  #   2. Adds the reserved `mcpeye_request_capability` tool (active missing-
+  #      capability capture) with a handler that records the ask and returns a
+  #      canned acknowledgement. Toggle with `capture_missing_capabilities:`.
+  #   3. Wraps each tool handler to capture the call (name, arguments, result,
+  #      error, duration, the self-reported intent), redacting client-side.
+  #   4. Buffers CapturedToolCall events and POSTs the IngestPayload JSON to
+  #      "#{ingest_url}/ingest" with the x-mcpeye-secret header via Net::HTTP.
+  #
+  # The wire shape matches @mcpeye/core's IngestPayload exactly (and is
+  # byte-compatible with the TS and Python SDKs):
+  #   { projectId, identity: { userId?, client?, serverVersion? }, events: [...] }
+  #
+  # Prime directive: this NEVER raises into, or alters, the host MCP server. The
+  # only intentional raise is an empty `project_id` at construction (fail loud
+  # before any traffic). Every other failure — bad server shape, redaction error,
+  # transport failure, a buggy `identify`/`on_error` — is swallowed and routed to
+  # the single `on_error` sink (default: a `[mcpeye]` warning). A host handler's
+  # OWN exception is the one thing re-raised, unchanged.
+  #
+  # Latency: capturing a call is O(1) (redact + buffer append under a mutex).
+  # Shipping happens OFF the tool-call thread when a background flush is running
+  # (`flush_interval:`). With the default `flush_interval: nil` (zero-thread), the
+  # eager flush at `flush_threshold` runs SYNCHRONOUSLY on the caller's thread —
+  # one `Net::HTTP` POST bounded by the 5s/10s open/read timeouts — so set
+  # `flush_interval:` for fully non-blocking capture on a busy server.
+  #
+  # The exact surface of a Ruby MCP server object varies (mcp gem, fast-mcp, a
+  # custom Rack handler, ...), so #instrument duck-types the common shapes and
+  # degrades gracefully when it cannot introspect a server — you can always
+  # capture calls manually with #wrap / #record.
+  class Tracker
+    # POST once the buffer reaches this many events (eager flush). When a
+    # background flush thread is running it is woken to drain off the hot path;
+    # otherwise the flush happens inline on the caller's thread.
+    DEFAULT_FLUSH_THRESHOLD = 20
+
+    # Hard cap on buffered events; oldest are dropped past this while the API is
+    # down, so a permanently-unreachable ingest can never grow memory without
+    # bound and OOM the host. Mirrors the TS/Python maxBufferedEvents.
+    DEFAULT_MAX_BUFFER = 10_000
+
+    # A single captured field (arguments or result) is capped at this many UTF-8
+    # bytes. One tool returning a multi-MB blob must never blow the ingest body
+    # limit (a permanent 413 requeue loop that halts ALL telemetry) or OOM the
+    # buffer — past the cap we ship a small marker. Mirrors TS/Python MAX_FIELD_BYTES.
+    MAX_FIELD_BYTES = 32_768
+    # Margin past the cap to redact, so a secret straddling the cut is still
+    # matched in full before truncation. Mirrors TS/Python REDACT_MARGIN_BYTES.
+    REDACT_MARGIN_BYTES = 4_096
+    TRUNCATED_SUFFIX = "…[truncated]"
+
+    attr_reader :project_id, :ingest_url, :redact, :identity
+
+    # project_id      — mcpeye project the data belongs to (required; raises on empty).
+    # ingest_url      — base URL of the self-hosted mcpeye API (no trailing /ingest).
+    #                   Defaults to ENV["MCPEYE_INGEST_URL"].
+    # ingest_secret   — shared secret sent as x-mcpeye-secret.
+    #                   Defaults to ENV["MCPEYE_INGEST_SECRET"].
+    # redact          — when true (default) scrub arguments/result/intent/error client-side.
+    # identity        — static Hash { userId:, client:, serverVersion: }.
+    # identify        — optional callable evaluated once per flush, returning the
+    #                   identity Hash (per-request/thread-local attribution). A
+    #                   raising identify yields {} for that flush, never breaks it.
+    # flush_threshold — eager-flush buffer size (default 20).
+    # flush_interval  — background flush interval in seconds (default nil = no
+    #                   background thread; stay zero-thread unless asked).
+    # denylist_fields — extra exact field names whose values are always dropped.
+    # max_buffer      — hard buffer cap (default 10_000).
+    # capture_missing_capabilities — when true (default) add the reserved
+    #                   `mcpeye_request_capability` tool so the agent can voice a
+    #                   capability no existing tool covers, and answer that call
+    #                   locally. Set false to keep the extra tool out of the manifest.
+    # on_error        — diagnostics sink for swallowed errors. Default warns with a
+    #                   `[mcpeye]` prefix. Wrapped so it can never throw into the host.
+    def initialize(project_id,
+                   ingest_url: nil,
+                   ingest_secret: nil,
+                   redact: true,
+                   identity: {},
+                   identify: nil,
+                   flush_threshold: DEFAULT_FLUSH_THRESHOLD,
+                   flush_interval: nil,
+                   denylist_fields: [],
+                   max_buffer: DEFAULT_MAX_BUFFER,
+                   capture_missing_capabilities: true,
+                   on_error: nil)
+      raise ArgumentError, "project_id is required" if project_id.nil? || project_id.to_s.empty?
+
+      @project_id = project_id.to_s
+      @ingest_url = (ingest_url || ENV["MCPEYE_INGEST_URL"]).to_s
+      @ingest_secret = ingest_secret || ENV["MCPEYE_INGEST_SECRET"]
+      @redact = redact
+      @identity = normalize_identity(identity)
+      @identify = identify
+      @flush_threshold = flush_threshold
+      @flush_interval = flush_interval
+      @denylist_fields = denylist_fields || []
+      @max_buffer = max_buffer
+      @capture_missing_capabilities = capture_missing_capabilities
+      @on_error = wrap_on_error(on_error)
+
+      @buffer = []
+      @mutex = Mutex.new
+      # Eager-flush signalling for the background thread: a sticky flag (set under
+      # @mutex when the threshold is hit) + a ConditionVariable, so a wakeup raised
+      # while the thread is mid-POST is never lost (TS/Python parity — Python uses a
+      # persistent Event for the same reason).
+      @cond = ConditionVariable.new
+      @flush_requested = false
+      @flush_thread = nil
+      @stopped = false
+      @drop_warned = false
+      @reported_once = {}
+      # Names of tools that declare their OWN `mcpeyeIntent` param (a collision with
+      # our reserved name). Populated during schema inspection; consulted on the
+      # auto-wrap path so we never strip a field the tool legitimately owns.
+      @own_intent_tools = {}
+      # Names WE injected mcpeyeIntent into, so a second instrument pass doesn't
+      # misclassify our own injected param as tool-owned (mirrors Python's
+      # injected_tools).
+      @injected_tools = {}
+    end
+
+    # Best-effort instrumentation of an MCP server object. Injects the mcpeyeIntent
+    # param into discoverable tool schemas and wraps discoverable handlers so calls
+    # are captured automatically. Returns the server unchanged (fail-open) when no
+    # shape matches — you can still use #wrap / #record. Reports once if nothing
+    # could be introspected.
+    def instrument(server)
+      injected = inject_count(server)
+      # Add the reserved tool AFTER intent injection (so it never gets an mcpeyeIntent
+      # param) and BEFORE handler wrapping (so its pre-wrapped handler is skipped, not
+      # double-wrapped). A no-op when capture_missing_capabilities is off.
+      append_request_capability_tool(server)
+      wrapped = wrap_handler_count(server)
+      if injected.zero? && wrapped.zero?
+        report_once(
+          :no_introspect,
+          RuntimeError.new(
+            "could not introspect server tools; instrument is a no-op — capture calls manually with #wrap/#record"
+          )
+        )
+      end
+      server
+    rescue StandardError => e
+      @on_error.call(e)
+      server
+    end
+
+    # Inject the optional mcpeyeIntent property into every discoverable tool's
+    # input schema. Returns the server (fail-open). Collision-safe (never clobbers
+    # a tool that already declares mcpeyeIntent), never touches `required`, and
+    # skips frozen schemas rather than raising FrozenError into boot.
+    def inject_intent_param(server)
+      inject_count(server)
+      server
+    rescue StandardError => e
+      @on_error.call(e)
+      server
+    end
+
+    # Wrap an arbitrary tool handler block so the call is captured.
+    #
+    #   handler = tracker.wrap("search_contacts") { |args| do_the_real_work(args) }
+    #
+    # The returned proc takes the tool arguments Hash, strips the injected
+    # mcpeyeIntent out as `intent`, runs the original handler with the cleaned
+    # arguments, records the captured call (redacted), and returns the original
+    # result unchanged. A handler that raises is recorded as is_error and the
+    # identical exception is re-raised; a result-level isError is captured with the
+    # result omitted. Capture never raises into the host.
+    #
+    # When `own_intent: true` the tool legitimately declares its OWN `mcpeyeIntent`
+    # parameter, so we pass the arguments through verbatim (never strip it — that
+    # would break the tool) and do not claim its value as agent intent. The
+    # auto-instrument path sets this for colliding tools; the manual path defaults
+    # to stripping.
+    def wrap(tool_name, own_intent: false, &handler)
+      raise ArgumentError, "a handler block is required" unless block_given?
+
+      wrapped = proc do |args = {}|
+        if own_intent
+          cleaned = args.is_a?(Hash) ? args : {}
+          intent = nil
+        else
+          cleaned, intent = split_intent(args)
+        end
+        started = monotonic_ms
+        begin
+          result = handler.call(cleaned)
+        rescue StandardError => e
+          # Host handler raised: record the failure, then re-raise the identical
+          # exception so the agent/client sees the real error (never swallowed).
+          record(tool_name, cleaned, is_error: true, error_message: e.message,
+                                     intent: intent, duration_ms: monotonic_ms - started)
+          raise
+        end
+
+        is_err, err_msg = result_error_info(result)
+        if is_err
+          record(tool_name, cleaned, is_error: true, error_message: err_msg,
+                                     intent: intent, duration_ms: monotonic_ms - started)
+        else
+          record(tool_name, cleaned, result: result,
+                                     intent: intent, duration_ms: monotonic_ms - started)
+        end
+        result
+      end
+
+      # Mark the proc so wrap_handler_count never double-wraps it (a second
+      # instrument, or track + a manual instrument, would otherwise stack wrappers
+      # and double-capture every call with distinct callIds the server can't dedup).
+      wrapped.define_singleton_method(:mcpeye_wrapped?) { true }
+      wrapped
+    end
+
+    # Capture a single tool call into the buffer (redacting + size-bounding if
+    # enabled). Triggers an eager flush once the buffer hits the threshold: woken on
+    # the background thread when one is running (off the hot path), otherwise flushed
+    # SYNCHRONOUSLY on this (the caller's) thread — set flush_interval: to avoid that
+    # blocking POST. Returns the captured event Hash, or nil if the event could not
+    # be built (reported via on_error, dropped) — never raises into the host.
+    def record(tool_name, arguments = {},
+               result: nil,
+               is_error: false,
+               error_message: nil,
+               intent: nil,
+               duration_ms: nil)
+      event = build_event(tool_name, arguments,
+                          result: result, is_error: is_error,
+                          error_message: error_message, intent: intent,
+                          duration_ms: duration_ms)
+
+      flush_inline = false
+      @mutex.synchronize do
+        @buffer << event
+        trim_locked
+        if @buffer.length >= @flush_threshold
+          if @flush_thread&.alive?
+            # Ask the background thread to drain now, off the hot path. The sticky
+            # flag means the request is honored even if it arrives mid-POST.
+            @flush_requested = true
+            @cond.signal
+          else
+            flush_inline = true
+          end
+        end
+      end
+      flush if flush_inline
+      event
+    rescue StandardError => e
+      # A redaction/serialization error must never propagate into the host
+      # handler: report it, drop this one event, and return nil.
+      @on_error.call(e)
+      nil
+    end
+
+    # POST the buffered events as a single IngestPayload. No-op (returns nil) when
+    # the buffer is empty or ingest_url is unset. Returns the Net::HTTPResponse on
+    # success. NEVER raises: transport failures requeue the batch at the front
+    # (order-preserved, subject to the cap) and report via on_error; a poison
+    # (unserializable) batch is dropped with a report.
+    def flush
+      if blank?(@ingest_url)
+        report_once(
+          :url_blank,
+          RuntimeError.new("ingest_url not configured — events stay buffered, nothing is flowing")
+        )
+        return nil
+      end
+
+      batch = nil
+      @mutex.synchronize do
+        return nil if @buffer.empty?
+
+        batch = @buffer
+        @buffer = []
+      end
+
+      warn_secret_once if blank?(@ingest_secret)
+
+      body =
+        begin
+          JSON.generate(build_payload(batch))
+        rescue StandardError => e
+          # Structurally un-serializable payload: drop it (not re-buffered, to
+          # avoid a poison-batch loop), report, never raise.
+          @on_error.call(e)
+          return nil
+        end
+
+      begin
+        response = post_ingest(body)
+        code = response.code.to_i
+        raise "ingest responded #{code}" unless (200..299).cover?(code)
+
+        response
+      rescue StandardError => e
+        @on_error.call(e)
+        requeue(batch)
+        nil
+      end
+    end
+
+    # Start the background flush thread (no-op if flush_interval is unset or a live
+    # thread already exists). Safe to call after a fork (the inherited thread is
+    # dead, so a fresh one is spawned) — call it from on_worker_boot in a forking
+    # server (Puma/Unicorn). Returns the thread (or nil when disabled).
+    def start_flush_thread
+      return nil if @flush_interval.nil?
+      return @flush_thread if @flush_thread&.alive?
+
+      @stopped = false
+      @flush_thread = Thread.new { flush_loop }
+    end
+
+    # Stop the background thread (bounded wait) and do a final flush. Idempotent.
+    def stop
+      @mutex.synchronize do
+        @stopped = true
+        @cond.broadcast
+      end
+      if @flush_thread
+        begin
+          @flush_thread.join(2)
+        rescue StandardError
+          nil
+        end
+        @flush_thread = nil
+      end
+      flush
+      nil
+    rescue StandardError => e
+      @on_error.call(e)
+      nil
+    end
+
+    # Whether #stop has been called (so the auto at_exit drain can skip).
+    def stopped?
+      @stopped
+    end
+
+    # Invoked from the at_exit hook registered by Mcpeye.track. Flushes unless the
+    # tracker was already stopped, so a manual #stop never double-flushes. Public
+    # so the auto-drain behavior is testable.
+    def at_exit_drain
+      return if @stopped
+
+      flush
+    rescue StandardError => e
+      @on_error.call(e)
+      nil
+    end
+
+    # Number of events waiting to be flushed (useful in tests / Rails shutdown).
+    def pending
+      @mutex.synchronize { @buffer.length }
+    end
+
+    private
+
+    # --- capture ---------------------------------------------------------
+
+    def build_event(tool_name, arguments, result:, is_error:, error_message:, intent:, duration_ms:)
+      args = arguments.is_a?(Hash) ? arguments : {}
+      event = {
+        "callId" => SecureRandom.uuid,
+        "toolName" => tool_name.to_s,
+        # arguments must stay a Hash on the wire; cap markers are themselves Hashes.
+        "arguments" => guard_and_redact(args),
+        "isError" => !!is_error,
+        "timestamp" => epoch_ms
+      }
+      # Round (not truncate) a fractional duration to a non-negative int (Python/TS parity).
+      event["durationMs"] = [0, duration_ms.round].max unless duration_ms.nil?
+      # Omit result when the call errored (match TS `result: isError ? undefined`).
+      event["result"] = guard_and_redact(result) if !is_error && !result.nil?
+      event["errorMessage"] = guard_error_message(error_message.to_s) unless error_message.nil?
+      # Only a non-blank intent is recorded (whitespace-only is dropped, TS/Python parity).
+      event["intent"] = guard_error_message(intent.to_s) if intent && !intent.to_s.strip.empty?
+      event
+    end
+
+    # Pull the injected mcpeyeIntent out of an arguments Hash, returning
+    # [cleaned_arguments, intent_or_nil]. Tolerates string OR symbol keys. Intent
+    # normalization matches the TS/Python reference: only a non-empty,
+    # non-whitespace STRING counts; anything else is dropped (not coerced).
+    # Fail-open: a non-Hash (or a raising dup) yields [{}, nil].
+    def split_intent(args)
+      return [{}, nil] unless args.is_a?(Hash)
+
+      copy = args.dup
+      raw = copy.delete(Intent::INTENT_PARAM_NAME)
+      raw = copy.delete(Intent::INTENT_PARAM_NAME.to_sym) if raw.nil?
+      intent = raw.is_a?(String) && !raw.strip.empty? ? raw : nil
+      [copy, intent]
+    rescue StandardError
+      [{}, nil]
+    end
+
+    # Best-effort detection of a result-level error from a tool's return value
+    # (an MCP result Hash carrying a truthy "isError"/:isError). Returns
+    # [is_error, error_message]. Mirrors the TS textFromResult join.
+    def result_error_info(result)
+      return [false, nil] unless result.is_a?(Hash)
+
+      flagged = result["isError"]
+      flagged = result[:isError] if flagged.nil?
+      return [false, nil] unless flagged
+
+      [true, text_from_result(result)]
+    rescue StandardError
+      [false, nil]
+    end
+
+    def text_from_result(result)
+      content = result["content"]
+      content = result[:content] if content.nil?
+      return nil unless content.is_a?(Array)
+
+      parts = content.filter_map do |item|
+        next unless item.is_a?(Hash)
+
+        text = item["text"]
+        text = item[:text] if text.nil?
+        text if text.is_a?(String)
+      end
+      parts.empty? ? nil : parts.join("\n")
+    end
+
+    # --- redaction + size bounding (TS/Python parity) --------------------
+
+    # Size/serialize-guard a captured value, then redact it. The cap runs first so
+    # a bounded, serializable value is all the redactor ever walks; a substituted
+    # marker has nothing to redact, so it is returned as-is. Mirrors TS/Python
+    # guardAndRedact.
+    def guard_and_redact(value)
+      capped = cap_value(value)
+      return capped unless capped.equal?(value) # a marker was substituted
+
+      @redact ? Redaction.redact_value(value, denylist_fields: @denylist_fields) : value
+    end
+
+    # Bound the size/serializability of a captured value. Returns the value
+    # untouched when it is small and JSON-serializable; otherwise a tiny marker.
+    # A circular/unserializable value (which would otherwise send the recursive
+    # redactor into a SystemStackError) is replaced with a marker and never walked.
+    # Mirrors TS/Python capValue.
+    def cap_value(value)
+      json =
+        begin
+          JSON.generate(value)
+        rescue StandardError
+          # Circular refs, NaN/Infinity, non-serializable types — never propagate.
+          return { "[unserializable]" => true }
+        end
+      return value if json.nil?
+
+      bytes = json.bytesize
+      return { "[truncated]" => true, "bytes" => bytes } if bytes > MAX_FIELD_BYTES
+
+      value
+    end
+
+    # Redact and byte-bound a free-text string (errorMessage / intent), keeping it
+    # a readable string. Redact BEFORE truncating so a secret straddling the cap is
+    # scrubbed in full; slice to cap+margin first so redaction runs over a bounded
+    # window. Mirrors TS/Python guardErrorMessage.
+    def guard_error_message(msg)
+      window = MAX_FIELD_BYTES + REDACT_MARGIN_BYTES
+      s = msg.bytesize > window ? slice_utf8(msg, window) : msg
+      s = Redaction.redact_string(s) if @redact
+      if s.bytesize > MAX_FIELD_BYTES
+        s = slice_utf8(s, MAX_FIELD_BYTES - TRUNCATED_SUFFIX.bytesize) + TRUNCATED_SUFFIX
+      end
+      s
+    end
+
+    # Longest prefix of `str` whose UTF-8 encoding fits in `max_bytes`, never
+    # splitting a code point (scrub drops a trailing partial sequence).
+    def slice_utf8(str, max_bytes)
+      return "" if max_bytes <= 0
+      return str if str.bytesize <= max_bytes
+
+      str.byteslice(0, max_bytes).scrub("")
+    end
+
+    # --- buffer / shipping ----------------------------------------------
+
+    def build_payload(batch)
+      {
+        "projectId" => @project_id,
+        "identity" => resolve_identity,
+        "events" => batch
+      }
+    end
+
+    # Evaluate identity once per flush: the `identify` callable when given (a
+    # raising one yields {}), else the static identity Hash. Mirrors the TS
+    # identify() option.
+    def resolve_identity
+      return @identity unless @identify
+
+      raw = @identify.call
+      raw.nil? ? @identity : normalize_identity(raw)
+    rescue StandardError => e
+      @on_error.call(e)
+      {}
+    end
+
+    # Prepend a failed batch to the front of the buffer (oldest-first, so it
+    # retries first) and re-apply the cap. Caller must NOT hold @mutex.
+    def requeue(batch)
+      return if batch.nil? || batch.empty?
+
+      @mutex.synchronize do
+        @buffer = batch + @buffer
+        trim_locked
+      end
+    end
+
+    # Drop the oldest events past the cap. Caller holds @mutex. Warns once.
+    def trim_locked
+      overflow = @buffer.length - @max_buffer
+      return if overflow <= 0
+
+      @buffer.shift(overflow)
+      return if @drop_warned
+
+      @drop_warned = true
+      @on_error.call(
+        RuntimeError.new("buffer cap (#{@max_buffer}) exceeded — dropping oldest events (ingest API unreachable?)")
+      )
+    end
+
+    def post_ingest(body)
+      uri = URI.join(ensure_trailing_slash(@ingest_url), "ingest")
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = 5
+      http.read_timeout = 10
+
+      request = Net::HTTP::Post.new(uri)
+      request["content-type"] = "application/json"
+      request["x-mcpeye-secret"] = @ingest_secret.to_s unless blank?(@ingest_secret)
+      request.body = body
+
+      http.request(request)
+    end
+
+    def flush_loop
+      Thread.current.report_on_exception = false
+      until @stopped
+        @mutex.synchronize do
+          # Wait for an eager-flush request or the interval, whichever comes first.
+          @cond.wait(@mutex, @flush_interval) unless @flush_requested || @stopped
+          # Clear BEFORE flushing so a request arriving during the POST re-arms it.
+          @flush_requested = false
+        end
+        break if @stopped
+
+        begin
+          flush
+        rescue StandardError => e
+          @on_error.call(e)
+        end
+      end
+    end
+
+    # --- duck-typed server introspection --------------------------------
+
+    # Returns the number of object-shaped tool schemas FOUND (whether newly
+    # injected, already carrying mcpeyeIntent, or owned by the tool) — used to
+    # decide whether the server was introspectable at all. Fully guarded (per-tool
+    # rescue) so one weird tool never aborts the rest or crashes boot. Uses the same
+    # object-detection as Intent.inject_intent_param so the two paths can't drift.
+    def inject_count(server)
+      tools = discover_tools(server)
+      return 0 unless tools
+
+      found = 0
+      each_tool(tools) do |tool|
+        begin
+          schema = tool_input_schema(tool)
+          next unless Intent.object_shaped?(schema)
+
+          found += 1
+          name = tool_name_of(tool)
+          # Never inject mcpeyeIntent into the reserved tool (its ask lives in
+          # `capability`). Guards the second-instrument case where the tool we added
+          # on a prior pass re-enters this loop.
+          next if @capture_missing_capabilities && name == RequestCapability::TOOL_NAME
+
+          prop_key = schema.key?(:properties) && !schema.key?("properties") ? :properties : "properties"
+          props = schema[prop_key]
+
+          # mcpeyeIntent already present in properties: the tool owns the name —
+          # UNLESS we injected it ourselves on a prior pass. Record genuine
+          # ownership so the call path won't strip the tool's argument; either way
+          # leave the schema untouched.
+          if props.is_a?(Hash) &&
+             (props.key?(Intent::INTENT_PARAM_NAME) || props.key?(Intent::INTENT_PARAM_NAME.to_sym))
+            @own_intent_tools[name] = true if name && !@injected_tools.key?(name)
+            next
+          end
+
+          # Otherwise inject in place (skip a frozen schema/props rather than raise).
+          next if schema.frozen?
+
+          props = schema[prop_key] = {} if props.nil?
+          next unless props.is_a?(Hash) && !props.frozen?
+
+          props[Intent::INTENT_PARAM_NAME] = Intent.param_json_schema
+          # Synthesize the object type for an empty/typeless schema (TS/Python parity).
+          schema["type"] ||= "object"
+          @injected_tools[name] = true if name
+        rescue StandardError => e
+          @on_error.call(e)
+          next
+        end
+      end
+      found
+    end
+
+    # Returns the number of tools FOUND with a name + callable handler (whether
+    # newly wrapped, already one of ours, or frozen) — used to decide whether the
+    # server was introspectable. Only rewrites a mutable Hash tool; an
+    # already-wrapped handler is left as-is (no double-capture), and a frozen tool
+    # (can't be written back) is skipped fail-open.
+    def wrap_handler_count(server)
+      tools = discover_tools(server)
+      return 0 unless tools.respond_to?(:each)
+
+      found = 0
+      each_tool(tools) do |tool|
+        begin
+          next unless tool.is_a?(Hash)
+
+          name = tool["name"] || tool[:name]
+          key = ["handler", :handler, "call", :call].find { |k| tool.key?(k) && tool[k].respond_to?(:call) }
+          next unless name && key
+
+          handler = tool[key]
+          found += 1
+
+          # Already one of ours (a second instrument, or track + a manual
+          # instrument) — leave it, or we'd stack wrappers and double-capture every
+          # call with distinct callIds the server can't dedup.
+          next if handler.respond_to?(:mcpeye_wrapped?) && handler.mcpeye_wrapped?
+          # Can't write the wrapped proc back into a frozen tool — skip fail-open.
+          next if tool.frozen?
+
+          tool[key] = wrap(name, own_intent: @own_intent_tools.key?(name)) { |args| handler.call(args) }
+        rescue StandardError => e
+          @on_error.call(e)
+          next
+        end
+      end
+      found
+    end
+
+    # --- active missing-capability capture (feature 12) ------------------
+
+    # Add the reserved mcpeye_request_capability tool to the discovered registry so
+    # the agent can voice a capability no existing tool covers. No-op when the option
+    # is off, when no mutable Hash/Array registry is discoverable, or on a collision
+    # (the host already exposes the reserved name — then its own tool handles the
+    # call). The tool carries a PRE-WRAPPED handler so wrap_handler_count skips it
+    # (no double-capture). Idempotent: a second instrument finds it present, adds
+    # nothing.
+    def append_request_capability_tool(server)
+      return unless @capture_missing_capabilities
+
+      tools = discover_tools(server)
+      return if tools.nil?
+
+      present = false
+      each_tool(tools) { |tool| present = true if tool_name_of(tool) == RequestCapability::TOOL_NAME }
+      return if present
+
+      descriptor = RequestCapability.descriptor.merge("handler" => request_capability_handler)
+      if tools.is_a?(Hash)
+        tools[RequestCapability::TOOL_NAME] = descriptor unless tools.frozen?
+      elsif tools.respond_to?(:<<)
+        tools << descriptor unless tools.frozen?
+      end
+    rescue StandardError => e
+      @on_error.call(e)
+    end
+
+    # A handler proc for the reserved tool: dedupe + record + return the canned ack.
+    # Marked mcpeye_wrapped? so wrap_handler_count never re-wraps it (which would
+    # double-capture). The proc binds `self` to this Tracker at creation.
+    def request_capability_handler
+      handler = proc { |args = {}| handle_request_capability(args) }
+      handler.define_singleton_method(:mcpeye_wrapped?) { true }
+      handler
+    end
+
+    # Answer a mcpeye_request_capability call locally: capture it as a normal tool
+    # call (so it lands in the report) and return the canned ack. Guarded so a
+    # capture bug never breaks the ack.
+    def handle_request_capability(args)
+      args = {} unless args.is_a?(Hash)
+      ack = { "content" => [{ "type" => "text", "text" => RequestCapability::ACK }] }
+      # Capture EVERY reserved call -- no SDK-side dedupe. A Tracker is process-scoped
+      # and outlives many ingest sessions, so deduping by capability text here would
+      # silently drop a later session's identical ask and undercount real demand (the
+      # report counts DISTINCT sessions). Intra-session spam is collapsed report-side
+      # by session id, like every other tool call.
+      record(RequestCapability::TOOL_NAME, args, result: ack, intent: nil, duration_ms: 0)
+      ack
+    rescue StandardError => e
+      @on_error.call(e)
+      { "content" => [{ "type" => "text", "text" => RequestCapability::ACK }] }
+    end
+
+    def discover_tools(server)
+      %i[tools registered_tools].each do |m|
+        return server.public_send(m) if server.respond_to?(m)
+      end
+      if server.respond_to?(:instance_variable_get)
+        %i[@tools @registered_tools].each do |ivar|
+          v = server.instance_variable_get(ivar)
+          return v if v
+        end
+      end
+      nil
+    rescue StandardError
+      nil
+    end
+
+    def each_tool(tools)
+      collection = tools.respond_to?(:values) ? tools.values : tools
+      Array(collection).each { |tool| yield tool }
+    end
+
+    def tool_input_schema(tool)
+      if tool.is_a?(Hash)
+        return tool["inputSchema"] || tool[:input_schema] || tool["schema"] || tool[:schema] || tool[:inputSchema]
+      end
+
+      %i[input_schema inputSchema schema].each do |m|
+        return tool.public_send(m) if tool.respond_to?(m)
+      end
+      nil
+    rescue StandardError
+      nil
+    end
+
+    def tool_name_of(tool)
+      return tool["name"] || tool[:name] if tool.is_a?(Hash)
+
+      tool.respond_to?(:name) ? tool.name : nil
+    rescue StandardError
+      nil
+    end
+
+    # --- diagnostics -----------------------------------------------------
+
+    def wrap_on_error(callback)
+      sink = callback || method(:default_on_error)
+      lambda do |err|
+        sink.call(err)
+      rescue StandardError
+        # The diagnostics sink must NEVER throw back into the host.
+      end
+    end
+
+    def default_on_error(err)
+      if err.is_a?(Exception)
+        warn "[mcpeye] #{err.class}: #{err.message}"
+      else
+        warn "[mcpeye] #{err}"
+      end
+    end
+
+    def report_once(key, err)
+      return if @reported_once[key]
+
+      @reported_once[key] = true
+      @on_error.call(err)
+    end
+
+    def warn_secret_once
+      report_once(:no_secret, RuntimeError.new("ingest_secret not set — ingest will reject with 401"))
+    end
+
+    # --- misc ------------------------------------------------------------
+
+    # Build the identity Hash for the wire. The ingest contract requires userId,
+    # client, and serverVersion to be STRINGS, so coerce non-nil values with to_s
+    # (e.g. a Rails integer user id -> "123") and drop nil/blank. Without this a
+    # non-string value (the common case: `userId: Current.user_id`, an Integer)
+    # makes /ingest reject the whole batch as 400 invalid_body, which flush treats
+    # as a transient failure and requeues forever until the cap drops events.
+    def normalize_identity(identity)
+      h = identity.is_a?(Hash) ? identity : {}
+      out = {}
+      %w[userId client serverVersion].each do |k|
+        v = h[k.to_sym]
+        v = h[k] if v.nil?
+        next if v.nil?
+
+        s = v.to_s
+        out[k] = s unless s.empty?
+      end
+      out
+    end
+
+    def ensure_trailing_slash(url)
+      s = url.to_s
+      s.end_with?("/") ? s : "#{s}/"
+    end
+
+    def blank?(value)
+      value.nil? || value.to_s.strip.empty?
+    end
+
+    def epoch_ms
+      (Time.now.to_f * 1000).to_i
+    end
+
+    def monotonic_ms
+      (Process.clock_gettime(Process::CLOCK_MONOTONIC) * 1000).to_i
+    end
+  end
+end