mcpspan 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8d0a4e3f16e81ed07733683b6bd1984d05955ba6cd3baff32dfeae0855dd3a52
-  data.tar.gz: 5b3a34b8f738da547c0d6cebbfdcb4debf6622eaf92f5c6bfb3ba6c68438dd5a
+  metadata.gz: a62e8c7de0a3fe8feed4683fa2a3aaa3b307c317f69d3f42091e62dbf32f05a7
+  data.tar.gz: 719d417a432bb75fdb3437d1e043c63d95754ed056d047fff42f23a28e3ac5c2
 SHA512:
-  metadata.gz: 4b93798f1e34fec652bb47d9a184d22df8a1cf6ee64b3ef774203572b6ffe9d314e511f164bb175e6f50cee52602415aa7740c46cb74525646acfbb9b34dfa1d
-  data.tar.gz: 8847e3f04f30ba0e3c2f2aafb693851084f963c308e3cac81c665f816f3399e591d893a0d0716e0412cfb2d77b3210902ba24dc2cc658eff8062967dbbde4863
+  metadata.gz: c595aa5e4e7416e2e0ea941ab5d032d9acf349c582731fa49a5c93859863a3210e4984aeef330c57a644ad9b8ba95c786ab21c2e7f3cfe67bb9e5938adc0f2fc
+  data.tar.gz: '078ec63e4be0c64dbe694a2f6fca21a9a7bda88f48ace0e9ee4a371ee1c7c9e77150d4dd52637012d62fb0cbedc7a93ba0613ee4dde7429c139f7b51039ef752'

data/README.md

@@ -149,8 +149,10 @@ mode, not in debug.
 
 What is collected: the tool name, how long it took, whether it succeeded, the
 error type and a truncated message when it did not, how large the answer was
-in bytes (its size only, never its content), which client called, and the SDK
-version. For a resource or a prompt, the same, under the name it was
+in bytes (its size only, never its content), whether it repeated the previous
+call's arguments to the same tool in its session (compared in your process;
+the arguments, or any digest of them, never leave it), which client called,
+and the SDK version. For a resource or a prompt, the same, under the name it was
 registered with: never the address a client read, only its template or, for
 an address the server does not have, its scheme.
 

data/lib/mcpspan/collector.rb

@@ -20,7 +20,7 @@ module McpSpan
 
     # What an integration knows about one call as it starts. A kind of nil is a tool call.
     Call = Struct.new(:tool_name, :parameters, :client_name, :client_version, :server_version, :session_id, :started,
-                      :timestamp, :kind, keyword_init: true,)
+                      :timestamp, :kind, :repeated, keyword_init: true,)
 
     @lock = Mutex.new
     @reporter = nil
@@ -141,6 +141,7 @@ module McpSpan
           response_bytes: response_bytes(response),
           # A tool the server has, refused arguments included: often the schema is why.
           definition_hash: call.kind.nil? && source != Source::UNKNOWN_TOOL ? Definitions.of(call.tool_name) : nil,
+          repeated: call.kind.nil? && call.repeated ? true : nil,
           timestamp: call.timestamp.strftime("%Y-%m-%dT%H:%M:%S.%LZ"),
           session_id: call.session_id,
           parameters: call.parameters,

data/lib/mcpspan/definitions.rb

@@ -48,6 +48,12 @@ module McpSpan
         nil
       end
 
+      # A value as canonical JSON (contract, 3.8), read the way it was sent: through JSON, so symbols and strings
+      # alike. Raises on what cannot be written so.
+      def canonical_text(value)
+        canonical(JSON.parse(JSON.generate(value)))
+      end
+
       private
 
       # Sorted keys, no whitespace, minimal escaping: the same text in every SDK.

data/lib/mcpspan/event.rb

@@ -6,8 +6,8 @@ module McpSpan
   # One call of a tool, a resource or a prompt, in the shape the ingest API takes. Parameter values are never in it.
   Event = Struct.new(
     :id, :kind, :tool_name, :duration_ms, :success, :error_source, :error_type, :error_message,
-    :client_type, :client_name, :client_version, :server_version, :response_bytes, :definition_hash, :timestamp,
-    :session_id, :parameters,
+    :client_type, :client_name, :client_version, :server_version, :response_bytes, :definition_hash, :repeated,
+    :timestamp, :session_id, :parameters,
     keyword_init: true,
   ) do
     # The event as the API takes it, leaving absent fields out rather than sending them as null.
@@ -27,6 +27,7 @@ module McpSpan
         serverVersion: server_version,
         responseBytes: response_bytes,
         definitionHash: definition_hash,
+        repeated: repeated,
         timestamp: timestamp,
         sdkVersion: VERSION,
         sessionId: session_id,

data/lib/mcpspan/instrumentation.rb

@@ -177,6 +177,10 @@ module McpSpan
           server_version: Instrumentation.server_version(self),
           **Instrumentation.client(envelope, session, self),
         )
+        # Compared once, as the request arrives, before any validation (contract, 3.9).
+        if call&.session_id && !Repeats.continues_earlier_call?(request)
+          call.repeated = Repeats.note(call.session_id, name, request[:arguments])
+        end
         [call, tool]
       rescue *INTERNAL
         nil

data/lib/mcpspan/repeats.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module McpSpan
+  # Whether a call repeats the previous call to the same tool in the same session (contract, 3.9): an agent stuck in a
+  # loop. Only the answer leaves the process. Kept here is a SHA-256 of the canonical arguments of the latest call per
+  # session and tool, never sent: a digest of a short identifier or an enumerated value is found by trying every one.
+  module Repeats
+    # Session and tool pairs kept, the oldest forgotten first.
+    MAX_KEPT = 10_000
+
+    # Insertion-ordered: a pair noted again is moved to the end, so the first is always the longest unused.
+    @latest = {}
+    @lock = Mutex.new
+
+    class << self
+      # Notes a call's arguments, as the client sent them, and says whether they are the previous call's to the same
+      # tool in the same session. Arguments that cannot be written down are never a repeat.
+      def note(session_id, tool_name, arguments)
+        digest = Digest::SHA256.digest(Definitions.canonical_text(arguments || {}))
+        key = [session_id, tool_name.to_s]
+        @lock.synchronize do
+          previous = @latest.delete(key)
+          @latest[key] = digest
+          @latest.shift if @latest.size > MAX_KEPT
+          previous == digest
+        end
+      rescue StandardError
+        false
+      end
+
+      # Whether a call answers an interim result's question (2026-07-28): it then continues that call, and is neither
+      # compared nor kept.
+      def continues_earlier_call?(request)
+        return false unless request.is_a?(Hash)
+
+        %i[inputResponses requestState].any? do |name|
+          value = request[name] || request[name.to_s]
+          !value.nil? && value != ""
+        end
+      end
+
+      # For tests: forgets every call.
+      def forget
+        @lock.synchronize { @latest.clear }
+      end
+    end
+  end
+end

data/lib/mcpspan/version.rb

@@ -2,5 +2,5 @@
 
 module McpSpan
   # The SDK's own version, reported with every event.
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/mcpspan.rb

@@ -7,6 +7,7 @@ require_relative "mcpspan/transport"
 require_relative "mcpspan/reporter"
 require_relative "mcpspan/collector"
 require_relative "mcpspan/definitions"
+require_relative "mcpspan/repeats"
 require_relative "mcpspan/instrumentation"
 require_relative "mcpspan/primitives"
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mcpspan
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Kacper Zatoń
@@ -24,6 +24,7 @@ files:
 - lib/mcpspan/event.rb
 - lib/mcpspan/instrumentation.rb
 - lib/mcpspan/primitives.rb
+- lib/mcpspan/repeats.rb
 - lib/mcpspan/reporter.rb
 - lib/mcpspan/text.rb
 - lib/mcpspan/transport.rb