mcpeye 0.1.4 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3d50e6d30ef0e2cf6796b7b7b67397c40c11290f289152d124c3ff5417ff6150
-  data.tar.gz: 23729136fae41b35dcf3152354d59fd5e2753d7429831b1f474bc01de56c6d5a
+  metadata.gz: 42505a75e113368b219cf57a34a12d8e503a67ba53819bf3ba134855ebdd8593
+  data.tar.gz: e9450434dfe0ed2686821ca35cf2aae489d7e9348f9a904987f4f68c9fd5837d
 SHA512:
-  metadata.gz: 84b70bcbed2a41a80a198b44e32b4f84eaa7f753aa3701e708eebc7210e78833dd6a1d67f471ac7e62aa7f1326dd96a75eaa9b3e8946465e78432e2554ee67e7
-  data.tar.gz: a75cc956872617ae3da0400b44b8a54a1f3e2bb7b265ca6e4dad5fb5ae50f453d24ec3256cfda971563091ff77f1a4b33059d6bfc73b378745530ffdefd015a4
+  metadata.gz: 19a625c460d5b56092efe9c7599ef3eb112eabbc31f7dbd3638c000c63d87db343178f82aa0f78705f2c7b0ed9d9859afca8f2aa4d117577524e18fd0417def9
+  data.tar.gz: 76c16dee3a85ccb231d2f7aa52e1283a4a88634938d487b0d934eb9da4320c3137612e49a4f1b7c829b8f3bc00919e5829ccab47b47bfe3fd8f4f2886062c850

data/CHANGELOG.md

@@ -3,6 +3,27 @@
 All notable changes to the `mcpeye` gem are documented here.
 This project adheres to [Semantic Versioning](https://semver.org).
 
+## 0.1.5
+
+- **Behavior change — native-intent fallback (default on).** mcpeye now coexists
+  with MCP servers that expose their own analytics-style `intent` field. We still
+  inject and prefer `mcpeyeIntent`; when the agent leaves it empty we **fall back**
+  to harvesting the server's own `intent` field. This is **on by default** via the
+  new `host_intent_param:` keyword (default `true`):
+  - `true` — gated auto-detect: harvest a string field named `intent` whose
+    description reads like an intent prompt. Functional fields (e.g. a Stripe
+    `PaymentIntent` id) are rejected. **Auto-detect runs only on the `track` path**,
+    which needs the tool schema; on `#wrap` / `#record` pass the field name
+    explicitly.
+  - `false` — disable entirely; capture only `mcpeyeIntent`.
+  - `"name"` — harvest that exact field, bypassing the semantic gate (works even
+    where there's no schema to inspect, e.g. `#wrap`). Denylisted field names stay
+    blocked.
+  - **To opt out:** set `host_intent_param: false`.
+- **New provenance: `intentSource`.** Every captured event now records where its
+  intent came from — `"mcpeye"` (our injected param won) or `"native"` (harvested
+  from the host's field as a fallback). Present only when an intent is present.
+
 ## 0.1.1
 
 - Docs: add this changelog. No functional or API changes.

data/README.md

@@ -126,12 +126,13 @@ All optional except `project_id`:
 | `ingest_secret:` | `ENV["MCPEYE_INGEST_SECRET"]` | Sent as `x-mcpeye-secret`. Missing → ingest 401 (warned once).             |
 | `redact:`        | `true`                        | Scrub secrets/PII from arguments/result/intent/error. `false` = verbatim.  |
 | `identity:`      | `{}`                          | Static `{ userId:, client:, serverVersion: }`.                             |
-| `identify:`      | `nil`                         | Callable evaluated **once per flush** for per-request identity. A raising one yields `{}`. |
+| `identify:`      | `nil`                         | Callable resolving end-user identity. `userId`/`userEmail` are read **per call** (on the request thread → correct attribution on multi-user servers); batch-level `client`/`serverVersion` are read per flush. A raising one yields `{}`. See [Use in a Rails MCP server](#use-in-a-rails-mcp-server). |
 | `flush_interval:`| `nil` (no thread)             | Seconds between background flushes. Set it to drain low-traffic servers.    |
 | `flush_threshold:` | `20`                        | Eager-flush once this many events buffer.                                   |
 | `denylist_fields:` | `[]`                        | Extra field names whose values are always dropped (case-insensitive).      |
 | `max_buffer:`    | `10_000`                      | Hard cap; oldest events drop past it while the API is down (warned once).  |
 | `capture_missing_capabilities:` | `true`         | Add + locally answer the reserved `mcpeye_request_capability` tool. `false` keeps it out of your manifest. |
+| `host_intent_param:` | `true`                    | Coexist with a server's own analytics-style `intent` field. `true` = gated auto-detect + harvest as a fallback; `false` = off; `"name"` = harvest that exact field, bypassing the gate. See [Works with servers that already capture intent](#works-with-servers-that-already-capture-intent). |
 | `on_error:`      | `warn "[mcpeye] ..."`         | Diagnostics sink for every swallowed error. Wrapped so it can never throw.  |
 
 > **Manifest cost.** With `capture_missing_capabilities: true`, your server's tool
@@ -238,6 +239,12 @@ end
 unchanged. A handler that raises is recorded as `isError` and the **identical
 exception is re-raised**. Or record fully by hand:
 
+> **Host intent on this path:** `#wrap` has no schema to auto-detect from, so gated
+> auto-detect can't run here. To harvest your server's own intent field, set
+> `host_intent_param: "reason"` on the tracker (`Mcpeye.track` / `Mcpeye::Tracker.new`);
+> `#wrap` then harvests that field from the call args. The explicit form bypasses the
+> gate, so point it only at a prose intent field (denylisted names still blocked).
+
 ```ruby
 MCPEYE.record(
   "place_order",
@@ -258,6 +265,48 @@ the event is recorded with `isError: true`, an `errorMessage` derived from the
 content text, and the `result` omitted. The handler's return value is passed back
 to the caller unchanged.
 
+## Works with servers that already capture intent
+
+Some MCP servers already expose their own analytics-style `intent` field. mcpeye
+coexists with them: it keeps injecting `mcpeyeIntent`, and when the agent leaves
+that empty it **falls back** to harvesting the server's own field. Provenance is
+recorded on every captured event as `intentSource`:
+
+- `intentSource: "mcpeye"` — our injected `mcpeyeIntent` was filled. **It always
+  wins** when present.
+- `intentSource: "native"` — `mcpeyeIntent` was empty, so the value came from your
+  server's own intent field (used only as a fallback).
+
+`host_intent_param:` (default `true`) controls the fallback:
+
+- `true` — gated auto-detect: harvest a string field named `intent` whose
+  *description* reads like an intent prompt. Functional fields named `intent` —
+  e.g. a Stripe `PaymentIntent` id — are rejected by the gate.
+- `false` — off; capture only `mcpeyeIntent`.
+- `"reason"` (a string) — harvest that exact field, **bypassing** the semantic gate.
+
+The host still receives a harvested field (it may be required); mcpeye only omits
+it from its own captured copy so the value isn't double-counted.
+
+```ruby
+Mcpeye.track(server, "my-project-id", host_intent_param: true)      # default: gated auto-detect
+Mcpeye.track(server, "my-project-id", host_intent_param: false)     # off
+Mcpeye.track(server, "my-project-id", host_intent_param: "reason")  # explicit field name (bypasses the gate)
+```
+
+> **An explicit field name bypasses the safety gate.** `host_intent_param: "reason"`
+> harvests that exact field with no description check, so point it **only** at a
+> prose intent field — not at an id/status/enum. (Denylisted field names like
+> `token`/`secret` are still blocked.)
+
+> **`#wrap` and the no-schema path:** auto-detect needs the tool's schema (it reads
+> the field's description), so it only works on the schema-aware `track` /
+> `#instrument` path. For the manual `#wrap` path — which has no published schema to
+> inspect — set `host_intent_param: "reason"` on the tracker
+> (`Mcpeye.track` / `Mcpeye::Tracker.new`) and `#wrap` harvests that field from the
+> call args. `#record` does **not** harvest — it captures whatever `intent:` /
+> `intent_source:` you pass it, so resolve the intent yourself before calling it.
+
 ## Redaction
 
 Client-side, regex-based, deliberately conservative — it over-redacts rather than
@@ -275,11 +324,11 @@ of obvious secrets that slip into free-text arguments and intent strings.
 
 ## API
 
-- `Mcpeye.track(server, project_id, ingest_url:, ingest_secret:, redact:, identity:, identify:, flush_interval:, on_error:, **opts) -> Tracker`
+- `Mcpeye.track(server, project_id, ingest_url:, ingest_secret:, redact:, identity:, identify:, flush_interval:, host_intent_param:, on_error:, **opts) -> Tracker`
 - `Mcpeye::Tracker#instrument(server)` — inject param + wrap discoverable handlers
 - `Mcpeye::Tracker#inject_intent_param(server)`
 - `Mcpeye::Tracker#wrap(tool_name) { |args| ... } -> Proc`
-- `Mcpeye::Tracker#record(tool_name, args, result:, is_error:, error_message:, intent:, duration_ms:) -> Hash`
+- `Mcpeye::Tracker#record(tool_name, args, result:, is_error:, error_message:, intent:, intent_source:, duration_ms:) -> Hash`
 - `Mcpeye::Tracker#flush -> Net::HTTPResponse | nil` (never raises)
 - `Mcpeye::Tracker#start_flush_thread` — start the background flush timer (call in `on_worker_boot`)
 - `Mcpeye::Tracker#stop -> nil` — stop the timer + final flush

data/lib/mcpeye/intent.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "set"
+
 module Mcpeye
   # The injected-intent contract.
   #
@@ -21,6 +23,11 @@ module Mcpeye
   module Intent
     INTENT_PARAM_NAME = "mcpeyeIntent"
 
+    # Provenance of a captured intent: our injected param vs the server's native
+    # field. Recorded on the wire as `intentSource` (only when intent is present).
+    INTENT_SOURCE_MCPEYE = "mcpeye"
+    INTENT_SOURCE_NATIVE = "native"
+
     # Byte-for-byte identical to packages/core/src/intent.ts INTENT_PARAM_DESCRIPTION.
     # If you change one, change all SDKs (TS, Python, Ruby) together.
     INTENT_PARAM_DESCRIPTION =
@@ -86,6 +93,120 @@ module Mcpeye
       schema["type"] ||= "object"
       schema
     end
+
+    # --- host-intent coexistence ----------------------------------------
+    #
+    # Some MCP servers already ship an analytics-style intent field (e.g. a param
+    # literally named `intent` whose description says "explain why you are calling
+    # this tool, for analytics"). When they do, the agent fills THEIR field and
+    # leaves our injected `mcpeyeIntent` empty — so we capture nothing. The SDKs
+    # handle this by HARVESTING the host field as a FALLBACK: our `mcpeyeIntent`
+    # still wins when filled; the host value is used only when ours is empty.
+    #
+    # The danger is `intent` is also a common FUNCTIONAL field name (a Stripe
+    # PaymentIntent id, an NLU classified-intent label, a routing key) — all
+    # strings. Auto-detection is gated on the field's DESCRIPTION semantically
+    # matching the analytics-intent contract (conjunctive cues + hard-negative
+    # tokens), never on name+type alone. An explicit param config bypasses the gate.
+    #
+    # Ported byte-for-byte from packages/core/src/intent.ts. The gate lists below
+    # MUST stay identical across all SDKs; spec/host_intent_spec.rb asserts them
+    # against the shared fixture packages/core/fixtures/host-intent-matrix.json.
+    DEFAULT_HOST_INTENT_PARAM_NAMES = ["intent"].freeze
+
+    # A description must contain BOTH a purpose cue AND an analytics cue (substring,
+    # case-insensitive — catches inflections like "blocker"/"blockers").
+    PURPOSE_CUES = ["why", "reason", "intent", "purpose", "trying to", "accomplish", "in their own words"].freeze
+    ANALYTICS_CUES = ["analytics", "tracking", "workflow", "product", "user intent", "blocker", "unmet", "capability"].freeze
+
+    # Hard-negative tokens disqualify a field even with cues. Short/ambiguous ones
+    # are matched as whole TOKENS (so "id" does not trip on "provide"); unambiguous
+    # compounds are matched as substrings.
+    NEGATIVE_EXACT = [
+      "id", "identifier", "uuid", "secret", "token", "status", "enum", "classification", "routing", "route", "key"
+    ].to_set.freeze
+    NEGATIVE_SUBSTR = ["paymentintent", "payment intent", "client_secret", "client secret"].freeze
+
+    # Why a description did or didn't qualify as an analytics-intent field. Returns
+    # one of: "ok", "no_description", "negative_token", "missing_purpose_cue",
+    # "missing_analytics_cue". Surfaced as a per-tool reason code under
+    # MCPEYE_DEBUG=intent. Mirrors TS analyticsIntentReason exactly.
+    def self.analytics_intent_reason(description)
+      return "no_description" unless description.is_a?(String) && !description.strip.empty?
+
+      d = description.downcase
+      return "negative_token" if NEGATIVE_SUBSTR.any? { |t| d.include?(t) }
+
+      tokens = d.scan(/[a-z0-9_]+/)
+      return "negative_token" if tokens.any? { |t| NEGATIVE_EXACT.include?(t) }
+      return "missing_purpose_cue" unless PURPOSE_CUES.any? { |c| d.include?(c) }
+      return "missing_analytics_cue" unless ANALYTICS_CUES.any? { |c| d.include?(c) }
+
+      "ok"
+    end
+
+    # True iff a param description reads like an analytics-intent field.
+    def self.describes_analytics_intent?(description)
+      analytics_intent_reason(description) == "ok"
+    end
+
+    # Read a property's metadata from a schema `properties` Hash, tolerating BOTH
+    # string and symbol keys (Ruby schemas use either). Returns
+    # [is_string, description_or_nil] or nil when the property is absent/non-Hash.
+    def self.string_prop_description(props, name)
+      p = props[name]
+      p = props[name.to_sym] if p.nil? && name.is_a?(String)
+      p = props[name.to_s] if p.nil? && name.is_a?(Symbol)
+      return nil unless p.is_a?(Hash)
+
+      type = p["type"] || p[:type]
+      desc = p["description"] || p[:description]
+      [type == "string", desc.is_a?(String) ? desc : nil]
+    end
+
+    # Resolve which host field (if any) to harvest as a FALLBACK intent for a tool,
+    # from its inputSchema `properties`. Precedence:
+    #   explicit_param (no gate, must be a string) ->
+    #   gated auto-detect over `names` (string + description passes the gate) ->
+    #   nil.
+    # Pure; mirrors TS resolveHostIntentParam. Tolerates string/symbol keys.
+    #
+    # opts: { names: [..], explicit_param: "..", detect: true/false }
+    def self.resolve_host_intent_param(properties, opts = {})
+      return nil unless properties.is_a?(Hash)
+
+      explicit_param = opts[:explicit_param] || opts["explicit_param"]
+      detect = opts.key?(:detect) ? opts[:detect] : (opts.key?("detect") ? opts["detect"] : true)
+      names = opts[:names] || opts["names"] || DEFAULT_HOST_INTENT_PARAM_NAMES
+
+      unless explicit_param.nil? || (explicit_param.is_a?(String) && explicit_param.empty?)
+        meta = string_prop_description(properties, explicit_param)
+        return meta && meta[0] ? explicit_param : nil
+      end
+
+      return nil unless detect
+
+      names.each do |name|
+        meta = string_prop_description(properties, name)
+        return name if meta && meta[0] && describes_analytics_intent?(meta[1])
+      end
+      nil
+    end
+
+    # Is a FIELD NAME denylisted (Redaction::DEFAULT_DENYLIST ∪ caller's
+    # `denylist_fields`), compared case-insensitively — the same normalization the
+    # redactor uses when walking object keys. The harvest path calls this BEFORE
+    # promoting a host field's value into the standalone `intent` string (which
+    # bypasses object-key field-denylisting), so a host field literally named
+    # `token`/`secret` yields an empty intent instead of a leak. Mirrors TS
+    # isDeniedField (which lives in redaction.ts); kept here because redaction.rb is
+    # frozen and the harvest gate is part of the intent contract.
+    def self.denied_field?(name, denylist_fields = [])
+      n = name.to_s.downcase
+      return true if Redaction::DEFAULT_DENYLIST.any? { |f| f.to_s.downcase == n }
+
+      Array(denylist_fields).any? { |f| f.to_s.downcase == n }
+    end
   end
 
   # Re-export at the top level so callers can use Mcpeye::INTENT_PARAM_NAME.

data/lib/mcpeye/request_capability.rb

@@ -28,11 +28,13 @@ module Mcpeye
     # pulls calls; a timid framing leaves the signal near zero. Change all SDKs together.
     TOOL_DESCRIPTION =
       "Use this tool whenever the user wants something the available tools do not cover, " \
-      "or whenever the task might benefit from a more specialized capability even if an " \
-      "existing tool could be used as a fallback. Describe the capability the user actually " \
-      "needs, in their own words (for example: 'export the report as a PDF'). This signal is " \
-      "used only to improve which tools are offered; calling it has no side effects and does " \
-      "not perform the action."
+      "or whenever the task might benefit from a more specialized capability, even if an " \
+      "existing tool (or the server's own 'more tools' feature) could be used as a fallback. " \
+      "Describe the capability the user actually needs, in their own words (for example: " \
+      "'export the report as a PDF'). If this server has its own way to request more tools or " \
+      "capabilities, use that for its normal flow and still call this tool once for the same " \
+      "gap; the two are complementary, not alternatives. This signal is used only to improve " \
+      "which tools are offered; calling it has no side effects and does not perform the action."
 
     CAPABILITY_DESCRIPTION =
       "The capability the user needs that the available tools do not provide, in the user's " \
@@ -43,6 +45,7 @@ module Mcpeye
 
     ACK =
       "Thanks. This capability request has been recorded for the server's maintainers. " \
+      "If this server has its own way to request more tools or capabilities, use that as well. " \
       "Continue helping the user with the available tools as best you can."
 
     # The reserved tool's input schema: `capability` required, `context` optional.

data/lib/mcpeye/tracker.rb

@@ -72,20 +72,56 @@ module Mcpeye
       raw_args = request[:arguments] || request["arguments"]
       args = raw_args.is_a?(Hash) ? raw_args : {}
 
-      # Strip the injected intent in place (request[:arguments] is the same object),
-      # so the gem validates/dispatches WITHOUT mcpeyeIntent.
+      # Reserved capability tool: answer locally ONLY when capture is on AND the host
+      # has NOT claimed the name for a real tool of its own (collision -> forward to
+      # the host, mirroring the duck path). reserved_host_owned? is learned from
+      # tools/list, which a client always calls before it can call a tool. (LATENT BUG
+      # fixed: previously this intercepted unconditionally, hijacking a host tool that
+      # legitimately owns the reserved name.)
+      if name == Mcpeye::RequestCapability::TOOL_NAME &&
+         tracker.capture_missing_capabilities? && !tracker.reserved_host_owned?
+        return tracker.answer_request_capability_official(args)
+      end
+
+      # Resolve intent + provenance, consulting the per-tool maps (no longer a blind
+      # delete). `captured_args` is what we RECORD; for a native harvest it omits the
+      # promoted field, while the host STILL receives it via `args` (request[:arguments]
+      # is the same object) — it may be a required field.
       intent = nil
+      intent_source = nil
+      captured_args = args
       begin
-        v = args.delete(Mcpeye::Intent::INTENT_PARAM_NAME)
-        v = args.delete(Mcpeye::Intent::INTENT_PARAM_NAME.to_sym) if v.nil?
-        intent = v if v.is_a?(String) && !v.strip.empty?
+        if tracker.own_intent_tool?(name)
+          # Collision: the tool owns mcpeyeIntent. Do NOT strip it (that would break a
+          # tool that marks it required), do not claim it as agent intent, never harvest.
+          intent = nil
+        else
+          # Strip OUR injected param in place so the gem validates/dispatches WITHOUT it.
+          v = args.delete(Mcpeye::Intent::INTENT_PARAM_NAME)
+          v = args.delete(Mcpeye::Intent::INTENT_PARAM_NAME.to_sym) if v.nil?
+          if v.is_a?(String) && !v.strip.empty?
+            # mcpeye's own param wins whenever the agent filled it.
+            intent = v
+            intent_source = Mcpeye::Intent::INTENT_SOURCE_MCPEYE
+          else
+            # FALLBACK: harvest the host's own analytics-intent field (after the strip),
+            # if this tool has an eligible one. Resolved at CALL time against the map.
+            harvested = tracker.harvest_host_intent(name, args)
+            if harvested
+              intent = harvested[1]
+              intent_source = Mcpeye::Intent::INTENT_SOURCE_NATIVE
+              # Omit the promoted field from the CAPTURED copy ONLY; the host (super)
+              # still sees it via `args`.
+              captured_args = args.dup
+              captured_args.delete(harvested[0])
+              captured_args.delete(harvested[0].to_sym) if harvested[0].is_a?(String)
+            end
+          end
+        end
       rescue StandardError
         intent = nil
-      end
-
-      # Reserved capability tool: never dispatch to the host; answer locally.
-      if name == Mcpeye::RequestCapability::TOOL_NAME && tracker.capture_missing_capabilities?
-        return tracker.answer_request_capability_official(args)
+        intent_source = nil
+        captured_args = args
       end
 
       started = Process.clock_gettime(Process::CLOCK_MONOTONIC, :float_millisecond)
@@ -94,7 +130,8 @@ module Mcpeye
       rescue StandardError => e
         dur = Process.clock_gettime(Process::CLOCK_MONOTONIC, :float_millisecond) - started
         begin
-          tracker.record(name, args, is_error: true, error_message: e.message, intent: intent, duration_ms: dur)
+          tracker.record(name, captured_args, is_error: true, error_message: e.message,
+                                              intent: intent, intent_source: intent_source, duration_ms: dur)
         rescue StandardError
           nil
         end
@@ -105,9 +142,11 @@ module Mcpeye
         dur = Process.clock_gettime(Process::CLOCK_MONOTONIC, :float_millisecond) - started
         is_error, error_text, result_payload = Mcpeye::OfficialServerCapture.classify(response)
         if is_error
-          tracker.record(name, args, is_error: true, error_message: error_text, intent: intent, duration_ms: dur)
+          tracker.record(name, captured_args, is_error: true, error_message: error_text,
+                                              intent: intent, intent_source: intent_source, duration_ms: dur)
         else
-          tracker.record(name, args, result: result_payload, intent: intent, duration_ms: dur)
+          tracker.record(name, captured_args, result: result_payload,
+                                              intent: intent, intent_source: intent_source, duration_ms: dur)
         end
       rescue StandardError
         nil
@@ -218,6 +257,7 @@ module Mcpeye
                    denylist_fields: [],
                    max_buffer: DEFAULT_MAX_BUFFER,
                    capture_missing_capabilities: true,
+                   host_intent_param: true,
                    on_error: nil)
       raise ArgumentError, "project_id is required" if project_id.nil? || project_id.to_s.empty?
 
@@ -232,6 +272,11 @@ module Mcpeye
       @denylist_fields = denylist_fields || []
       @max_buffer = max_buffer
       @capture_missing_capabilities = capture_missing_capabilities
+      # Host-intent coexistence config (explicit field name and/or gated auto-detect):
+      #   true  => gated auto-detect of "intent"
+      #   false => OFF (never harvest)
+      #   "str" => explicit field name, BYPASS gate (works even on no-schema paths)
+      @host_intent_explicit, @host_intent_detect = parse_host_intent_config(host_intent_param)
       @on_error = wrap_on_error(on_error)
 
       @buffer = []
@@ -254,6 +299,27 @@ module Mcpeye
       # misclassify our own injected param as tool-owned (mirrors Python's
       # injected_tools).
       @injected_tools = {}
+      # Per-tool map { tool_name => host_intent_param_name } of fields to harvest as
+      # a FALLBACK intent. REBUILT on every tools/list (not grow-only like
+      # @own_intent_tools) so a schema change can't leave a stale-eligible field.
+      # Consulted at tools/call only when mcpeyeIntent came back empty.
+      @host_intent_tools = {}
+      # True when the HOST already exposes a tool named mcpeye_request_capability (a
+      # collision). Recorded from the official tools/list (mirrors the duck path's
+      # reserved-owned handling); when true the official call path forwards the
+      # reserved name to the host instead of answering locally.
+      @reserved_host_owned = false
+      # Latch: emit the one-time loud "harvesting host intent" activation log once.
+      @host_intent_activated = false
+      # Latch: warn once if an explicit host_intent_param matched no listed tool.
+      @host_intent_explicit_warned = false
+      # Latch: true once a tools/list ever populated the detection map. On the
+      # schema paths (official/duck) this makes harvest strictly map-driven like
+      # the TS reference; the explicit-config fallback applies ONLY on a no-schema
+      # path (#wrap), where no tools/list ever ran.
+      @host_intent_listed = false
+      # MCPEYE_DEBUG=intent: log per-tool detection reason codes.
+      @debug_intent = intent_debug_enabled?
     end
 
     # Best-effort instrumentation of an MCP server object. Injects the mcpeyeIntent
@@ -330,11 +396,42 @@ module Mcpeye
       raise ArgumentError, "a handler block is required" unless block_given?
 
       wrapped = proc do |args = {}|
+        # `intent_source` is the provenance of `intent`: "mcpeye" (our injected
+        # param) | "native" (a harvested host field) | nil (no intent).
+        # `captured_args` is what we RECORD — it may omit a harvested host field so
+        # the worker summary doesn't double-count it; the HANDLER still receives that
+        # field via `cleaned` (it may be a required arg). Never mutate `cleaned`.
+        intent_source = nil
         if own_intent
+          # Collision: the tool owns mcpeyeIntent. Pass args through verbatim, do not
+          # claim its value as agent intent, and (per precedence) never host-harvest.
           cleaned = args.is_a?(Hash) ? args : {}
           intent = nil
+          captured_args = cleaned
         else
           cleaned, intent = split_intent(args)
+          if intent
+            # mcpeye's own param wins whenever the agent filled it.
+            intent_source = Intent::INTENT_SOURCE_MCPEYE
+            captured_args = cleaned
+          else
+            # FALLBACK: the agent left mcpeyeIntent empty — harvest the host server's
+            # own analytics-intent field, if this tool has an eligible one. Resolved
+            # at CALL time against the (mutable) tracker, since host eligibility is
+            # learned at LIST time, after this wrapper was created.
+            harvested = harvest_host_intent(tool_name, cleaned)
+            if harvested
+              intent = harvested[1]
+              intent_source = Intent::INTENT_SOURCE_NATIVE
+              # Omit the promoted field from the CAPTURED copy ONLY. The handler still
+              # gets it via `cleaned`.
+              captured_args = cleaned.dup
+              captured_args.delete(harvested[0])
+              captured_args.delete(harvested[0].to_sym) if harvested[0].is_a?(String)
+            else
+              captured_args = cleaned
+            end
+          end
         end
         started = monotonic_ms
         begin
@@ -342,18 +439,21 @@ module Mcpeye
         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)
+          record(tool_name, captured_args, is_error: true, error_message: e.message,
+                                           intent: intent, intent_source: intent_source,
+                                           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)
+          record(tool_name, captured_args, is_error: true, error_message: err_msg,
+                                           intent: intent, intent_source: intent_source,
+                                           duration_ms: monotonic_ms - started)
         else
-          record(tool_name, cleaned, result: result,
-                                     intent: intent, duration_ms: monotonic_ms - started)
+          record(tool_name, captured_args, result: result,
+                                           intent: intent, intent_source: intent_source,
+                                           duration_ms: monotonic_ms - started)
         end
         result
       end
@@ -376,11 +476,12 @@ module Mcpeye
                is_error: false,
                error_message: nil,
                intent: nil,
+               intent_source: 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)
+                          intent_source: intent_source, duration_ms: duration_ms)
 
       flush_inline = false
       @mutex.synchronize do
@@ -512,7 +613,8 @@ module Mcpeye
 
     # --- capture ---------------------------------------------------------
 
-    def build_event(tool_name, arguments, result:, is_error:, error_message:, intent:, duration_ms:)
+    def build_event(tool_name, arguments, result:, is_error:, error_message:, intent:, intent_source: nil,
+                    duration_ms:)
       args = arguments.is_a?(Hash) ? arguments : {}
       event = {
         "callId" => SecureRandom.uuid,
@@ -528,7 +630,12 @@ module Mcpeye
       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?
+      if intent && !intent.to_s.strip.empty?
+        event["intent"] = guard_error_message(intent.to_s)
+        # Provenance ("mcpeye"|"native") is only meaningful alongside an intent (wire
+        # invariant: intentSource present only when intent present).
+        event["intentSource"] = intent_source.to_s if intent_source
+      end
       # Per-CALL end-user identity. build_event runs on the caller's (request) thread
       # — via the official call_tool hook or the wrap proc — so `identify` is evaluated
       # where the host's per-request user context is live (unlike the per-flush batch
@@ -762,6 +869,11 @@ module Mcpeye
       return 0 unless tools
 
       found = 0
+      # Pairs of [tool_name, original_properties] gathered from THIS pass, used to
+      # REBUILD the per-tool host-intent map (the duck path's analog of the official
+      # tools/list augmentation). Detection reads the `intent` field, not the
+      # `mcpeyeIntent` we inject, so capturing the live props hash is sufficient.
+      host_intent_pairs = []
       each_tool(tools) do |tool|
         begin
           schema = tool_input_schema(tool)
@@ -776,6 +888,7 @@ module Mcpeye
 
           prop_key = schema.key?(:properties) && !schema.key?("properties") ? :properties : "properties"
           props = schema[prop_key]
+          host_intent_pairs << [name, props] if name && props.is_a?(Hash)
 
           # mcpeyeIntent already present in properties: the tool owns the name —
           # UNLESS we injected it ourselves on a prior pass. Record genuine
@@ -802,6 +915,8 @@ module Mcpeye
           next
         end
       end
+      # REBUILD the host-intent map from this pass's schemas (clears stale entries).
+      detect_host_intent_tools(host_intent_pairs)
       found
     end
 
@@ -964,6 +1079,10 @@ module Mcpeye
       tools = result[:tools] || result["tools"]
       return unless tools.is_a?(Array)
 
+      # Gather [name, original_properties] pairs from the PRE-augmentation schemas,
+      # to REBUILD the per-tool host-intent map (the official-path analog of the duck
+      # path's per-tool recording — which previously recorded NOTHING here).
+      host_intent_pairs = []
       tools.each do |tool|
         next unless tool.is_a?(Hash)
 
@@ -973,10 +1092,32 @@ module Mcpeye
         next if key.nil?
 
         schema = tool[key]
-        tool[key] = inject_intent_into_schema(schema) if schema.is_a?(Hash)
+        if schema.is_a?(Hash)
+          name = tool[:name] || tool["name"]
+          props = schema[:properties] || schema["properties"]
+          if name && props.is_a?(Hash)
+            host_intent_pairs << [name, props]
+            # Collision: the host tool declares its OWN mcpeyeIntent. Record it so the
+            # official call path won't strip a field the tool legitimately owns.
+            if props.key?(Intent::INTENT_PARAM_NAME) || props.key?(Intent::INTENT_PARAM_NAME.to_sym)
+              @own_intent_tools[name.to_s] = true
+            end
+          end
+          tool[key] = inject_intent_into_schema(schema)
+        end
       end
 
-      if add_reserved && tools.none? { |t| t.is_a?(Hash) && (t[:name] || t["name"]) == RequestCapability::TOOL_NAME }
+      # REBUILD the host-intent map each list (clears stale entries). Done BEFORE the
+      # reserved-tool append so detection never sees our own injected reserved tool.
+      detect_host_intent_tools(host_intent_pairs)
+
+      # Record whether the HOST already owns the reserved name (a collision), so the
+      # official call path forwards it to the host instead of answering locally —
+      # mirroring the duck path's reserved-owned handling.
+      @reserved_host_owned =
+        tools.any? { |t| t.is_a?(Hash) && (t[:name] || t["name"]).to_s == RequestCapability::TOOL_NAME }
+
+      if add_reserved && !@reserved_host_owned
         tools << RequestCapability.descriptor
       end
     end
@@ -1088,6 +1229,170 @@ module Mcpeye
       report_once(:no_secret, RuntimeError.new("ingest_secret not set — ingest will reject with 401"))
     end
 
+    # --- host-intent coexistence -----------------------------------------
+
+    # Parse the host_intent_param keyword into [explicit_param_or_nil, detect_bool]:
+    #   false       => [nil, false]            (OFF — never harvest)
+    #   ""/" "      => [nil, true]             (blank string => default gated detect)
+    #   "reason"    => ["reason", false]       (explicit field, BYPASS gate)
+    #   true/other  => [nil, true]             (gated auto-detect of "intent")
+    # Mirrors the TS parseHostIntentConfig.
+    def parse_host_intent_config(value)
+      return [nil, false] if value == false
+
+      if value.is_a?(String)
+        s = value.strip
+        return s.empty? ? [nil, true] : [s, false]
+      end
+
+      [nil, true] # nil | true | anything else
+    end
+
+    # True when MCPEYE_DEBUG opts into host-intent detection diagnostics
+    # ("1", "all", or a comma/space list including "intent"). Mirrors TS.
+    def intent_debug_enabled?
+      d = (ENV["MCPEYE_DEBUG"] || "").downcase
+      d == "1" || d == "all" || d.split(/[\s,]+/).include?("intent")
+    rescue StandardError
+      false
+    end
+
+    # Rebuild @host_intent_tools from a list of [tool_name, properties_hash] pairs
+    # (the ORIGINAL, pre-augmentation schemas of THIS tools/list). Clears stale
+    # entries first (NOT grow-only). Skips the reserved tool. Emits the one-time
+    # activation log and, under MCPEYE_DEBUG=intent, per-tool rejection reasons.
+    # Fail-open: never raises into the host list handler.
+    def detect_host_intent_tools(tool_props_pairs)
+      @host_intent_tools = {}
+      return if @host_intent_explicit.nil? && !@host_intent_detect # host_intent_param: false
+
+      listed = 0
+      tool_props_pairs.each do |name, props|
+        next if name.nil? || name.to_s.empty?
+
+        listed += 1
+        next if @capture_missing_capabilities && name.to_s == RequestCapability::TOOL_NAME
+
+        param = Intent.resolve_host_intent_param(
+          props,
+          explicit_param: @host_intent_explicit, detect: @host_intent_detect
+        )
+        if param
+          @host_intent_tools[name.to_s] = param
+        elsif @debug_intent
+          log_host_intent_rejection(name, props)
+        end
+      rescue StandardError => e
+        @on_error.call(e)
+      end
+
+      # A real tools/list ran: from now on harvest is map-only on schema paths.
+      @host_intent_listed = true if listed.positive?
+      announce_host_intent_activation
+      warn_host_intent_explicit_mismatch(listed)
+    rescue StandardError => e
+      @on_error.call(e)
+    end
+
+    # One-time loud activation log: a silent change to WHAT we capture would erode
+    # trust in the dashboard, so announce it the first time it actually fires.
+    def announce_host_intent_activation
+      return if @host_intent_tools.empty? || @host_intent_activated
+
+      @host_intent_activated = true
+      tool_list = @host_intent_tools.map { |t, p| "#{t}.#{p}" }.join(", ")
+      warn(
+        "[mcpeye] using your server's own intent field as a fallback on " \
+        "#{@host_intent_tools.size} tool(s): #{tool_list}. mcpeye's own mcpeyeIntent " \
+        "still wins when the agent fills it; disable with host_intent_param: false."
+      )
+    end
+
+    # One-time warn if an EXPLICIT param matched nothing (likely a typo/misconfig).
+    def warn_host_intent_explicit_mismatch(listed_count)
+      return unless @host_intent_explicit
+      return unless @host_intent_tools.empty? && listed_count.positive? && !@host_intent_explicit_warned
+
+      @host_intent_explicit_warned = true
+      warn(
+        "[mcpeye] host_intent_param \"#{@host_intent_explicit}\" did not match a string " \
+        "field on any listed tool — no host intent will be harvested. Check the field name."
+      )
+    end
+
+    # MCPEYE_DEBUG=intent: explain why a present-but-rejected candidate wasn't harvested.
+    def log_host_intent_rejection(name, props)
+      return unless props.is_a?(Hash)
+
+      candidate = @host_intent_explicit || "intent"
+      meta = props[candidate] || props[candidate.to_sym]
+      return if meta.nil? # no candidate field -> nothing to explain
+
+      reason =
+        if !meta.is_a?(Hash)
+          "not_an_object"
+        elsif (meta["type"] || meta[:type]) != "string"
+          "not_string"
+        else
+          desc = meta["description"] || meta[:description]
+          Intent.analytics_intent_reason(desc.is_a?(String) ? desc : nil)
+        end
+      warn(
+        "[mcpeye:intent] tool \"#{name}\" field \"#{candidate}\" not harvested (#{reason}). " \
+        "Set host_intent_param: \"#{candidate}\" to harvest it explicitly."
+      )
+    rescue StandardError => e
+      @on_error.call(e)
+    end
+
+    # The eligible host-intent param for a tool (call-time lookup), or nil. Public
+    # so the duck-wrap proc and the official call hook — which resolve eligibility at
+    # CALL time against this mutable tracker — share one source of truth.
+    public def host_intent_param_for(tool_name)
+      @host_intent_tools[tool_name.to_s]
+    end
+
+    # Resolve the eligible host-intent value to promote for a call, or nil. Returns
+    # [param_name, value] when the tool has an eligible, non-denylisted host field
+    # whose arg is a non-empty string; else nil. Reads string OR symbol arg keys.
+    # Mirrors TS harvestHostIntent (strictly map-driven once a tools/list has run),
+    # plus an explicit-config fallback for the no-schema path (#wrap): there no
+    # tools/list ever populated the map, so an EXPLICIT host_intent_param is honored
+    # directly against the call args (the integrator opted in). On the schema paths
+    # (official/duck) @host_intent_listed is true, so we stay map-only — a non-string
+    # or absent explicit field is NOT harvested from a stray runtime arg, exactly
+    # like TS. Gated auto-detect always requires a map entry.
+    public def harvest_host_intent(tool_name, args)
+      param = host_intent_param_for(tool_name)
+      param = @host_intent_explicit if param.nil? && !@host_intent_listed
+      return nil if param.nil?
+      # PII guard: never promote a denylisted field name into the standalone intent.
+      return nil if Intent.denied_field?(param, @denylist_fields)
+      return nil unless args.is_a?(Hash)
+
+      v = args[param]
+      v = args[param.to_sym] if v.nil? && param.is_a?(String)
+      return [param, v] if v.is_a?(String) && !v.strip.empty?
+
+      nil
+    rescue StandardError
+      nil
+    end
+
+    # Read by the official call hook (which lives outside the Tracker instance) to
+    # decide whether to forward a reserved-name call to the host (collision) vs
+    # answer it locally.
+    public def reserved_host_owned?
+      @reserved_host_owned
+    end
+
+    # True when a tool declares its OWN mcpeyeIntent param (a collision). Read by the
+    # official call hook so it never strips a field the tool legitimately owns and
+    # never host-harvests for a collision tool (precedence: collision wins).
+    public def own_intent_tool?(tool_name)
+      @own_intent_tools.key?(tool_name.to_s)
+    end
+
     # --- misc ------------------------------------------------------------
 
     # Build the identity Hash for the wire. The ingest contract requires userId,

data/lib/mcpeye/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Mcpeye
-  VERSION = "0.1.4"
+  VERSION = "0.1.6"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mcpeye
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.6
 platform: ruby
 authors:
 - mcpeye
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-23 00:00:00.000000000 Z
+date: 2026-06-25 00:00:00.000000000 Z
 dependencies: []
 description: mcpeye captures what your agents try to do through your MCP tools — including
   the asks your tools could NOT fulfill — and ships them to a self-hosted mcpeye instance