mcpspan 0.3.0 → 0.4.0

package/README.md

@@ -209,8 +209,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.
 

package/dist/index.cjs

@@ -146,7 +146,7 @@ var EventQueue = class {
 * Single source of truth: `package.json` follows this constant, not the other
 * way round, and a unit test fails if the two ever drift apart.
 */
-const SDK_VERSION = "0.3.0";
+const SDK_VERSION = "0.4.0";
 //#endregion
 //#region src/transport.ts
 /** Path the ingest API accepts batches on, appended to the configured endpoint. */
@@ -546,7 +546,7 @@ function definitionHash(tool) {
 		return;
 	}
 }
-/** Sorted keys, no whitespace, minimal escaping: the same text in every SDK. */
+/** Sorted keys, no whitespace, minimal escaping: the same text in every SDK. Throws on what JSON cannot hold. */
 function canonical(value) {
 	if (value === null) return "null";
 	if (typeof value === "boolean") return String(value);
@@ -856,6 +856,7 @@ function track(toolName, handler) {
 					sdkVersion: SDK_VERSION,
 					...session !== void 0 && { sessionId: session },
 					...definition(toolName),
+					...call?.repeated === true && { repeated: true },
 					...outcome
 				});
 			} catch {}
@@ -964,7 +965,8 @@ function recordRefusedCall(refused) {
 			timestamp: refused.timestamp,
 			sdkVersion: SDK_VERSION,
 			...refused.sessionId !== void 0 && { sessionId: refused.sessionId },
-			...refused.errorSource === "unknown_tool" ? {} : definition(refused.toolName)
+			...refused.errorSource === "unknown_tool" ? {} : definition(refused.toolName),
+			...refused.repeated === true && { repeated: true }
 		});
 	} catch {}
 }
@@ -1369,6 +1371,40 @@ function watchPrimitive(handler, server) {
 	};
 }
 //#endregion
+//#region src/repeats.ts
+/**
+* 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.
+*/
+/** Session and tool pairs kept, the oldest forgotten first. */
+const MAX_KEPT = 1e4;
+const latest = /* @__PURE__ */ new Map();
+/**
+* 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. Never throws: an
+* argument object that cannot be written down is never a repeat.
+*/
+function noteArguments(sessionId, toolName, args) {
+	try {
+		const digest = (0, node_crypto.createHash)("sha256").update(canonical(args ?? {}), "utf8").digest("hex");
+		const key = `${sessionId}\u0000${toolName}`;
+		const previous = latest.get(key);
+		latest.delete(key);
+		latest.set(key, digest);
+		if (latest.size > MAX_KEPT) {
+			const oldest = latest.keys().next().value;
+			if (oldest !== void 0) latest.delete(oldest);
+		}
+		return previous === digest;
+	} catch {
+		return false;
+	}
+}
+//#endregion
 //#region src/instrument.ts
 /**
 * Methods an MCP server registers tools through.
@@ -1397,6 +1433,28 @@ const registries = /* @__PURE__ */ new WeakMap();
 * it on its own. A weak set, so contexts leave with their requests.
 */
 const reachedHandler = /* @__PURE__ */ new WeakSet();
+/** Requests whose arguments repeat the previous call's to the same tool in the session (contract, 3.9). */
+const repeatedCalls = /* @__PURE__ */ new WeakSet();
+/**
+* Compares a call's arguments, as the client sent them, with the previous call's to the same tool in the same
+* session, as it arrives, before any validation; and marks the request so the handler side knows too. A call
+* without a session is never compared.
+*/
+function noteRepeat(server, request, context) {
+	try {
+		const name = request.params?.name;
+		if (typeof name !== "string" || typeof context !== "object" || context === null) return false;
+		const params = request.params;
+		if (params["inputResponses"] !== void 0 || params["requestState"] !== void 0) return false;
+		const sessionId = sessionFor(server, context);
+		if (sessionId === void 0) return false;
+		const repeated = noteArguments(sessionId, name, request.params?.arguments);
+		if (repeated) repeatedCalls.add(context);
+		return repeated;
+	} catch {
+		return false;
+	}
+}
 /**
 * Request contexts whose handler last answered with an interim
 * `input_required` result (the 2026-07-28 protocol's way to ask the client for
@@ -1546,10 +1604,12 @@ function noteReached(handler, server) {
 		const sessionId = hasContext ? sessionFor(server, context) : void 0;
 		const client = clientFor(server, hasContext ? context : void 0);
 		const serverVersion = serverVersionOf(server);
+		const repeated = hasContext && repeatedCalls.has(context);
 		const result = withCall({
 			...sessionId !== void 0 && { sessionId },
 			...client !== void 0 && { client },
-			...serverVersion !== void 0 && { serverVersion }
+			...serverVersion !== void 0 && { serverVersion },
+			...repeated && { repeated }
 		}, run);
 		if (hasContext) noteInterim(context, result);
 		return result;
@@ -1622,6 +1682,7 @@ function watchToolCalls(handler, server, registry) {
 		if (!isRecording() || request?.method !== "tools/call") return call();
 		const timestamp = (/* @__PURE__ */ new Date()).toISOString();
 		const startedAt = performance.now();
+		const repeated = noteRepeat(server, request, context);
 		const noteRefusal = (message) => {
 			try {
 				const reached = typeof context === "object" && context !== null && reachedHandler.has(context);
@@ -1637,7 +1698,8 @@ function watchToolCalls(handler, server, registry) {
 						durationMs: performance.now() - startedAt,
 						sessionId: sessionFor(server, context),
 						client: clientFor(server, context),
-						serverVersion: serverVersionOf(server)
+						serverVersion: serverVersionOf(server),
+						repeated
 					});
 					return;
 				}
@@ -1651,7 +1713,8 @@ function watchToolCalls(handler, server, registry) {
 					durationMs: performance.now() - startedAt,
 					sessionId: sessionFor(server, context),
 					client: clientFor(server, context),
-					serverVersion: serverVersionOf(server)
+					serverVersion: serverVersionOf(server),
+					repeated
 				});
 			} catch {}
 		};

package/dist/index.d.cts

@@ -201,6 +201,8 @@ interface ToolCallEvent {
   responseBytes?: number;
   /** The tool's definition as last listed, fingerprinted (contract, 3.8). */
   definitionHash?: string;
+  /** The arguments are the previous call's to the same tool in this session (contract, 3.9). */
+  repeated?: boolean;
   /** When the call started, as an ISO 8601 timestamp. */
   timestamp: string;
   /** Version of the mcpspan package that produced the event. */

package/dist/index.d.mts

@@ -201,6 +201,8 @@ interface ToolCallEvent {
   responseBytes?: number;
   /** The tool's definition as last listed, fingerprinted (contract, 3.8). */
   definitionHash?: string;
+  /** The arguments are the previous call's to the same tool in this session (contract, 3.9). */
+  repeated?: boolean;
   /** When the call started, as an ISO 8601 timestamp. */
   timestamp: string;
   /** Version of the mcpspan package that produced the event. */

package/dist/index.mjs

@@ -145,7 +145,7 @@ var EventQueue = class {
 * Single source of truth: `package.json` follows this constant, not the other
 * way round, and a unit test fails if the two ever drift apart.
 */
-const SDK_VERSION = "0.3.0";
+const SDK_VERSION = "0.4.0";
 //#endregion
 //#region src/transport.ts
 /** Path the ingest API accepts batches on, appended to the configured endpoint. */
@@ -545,7 +545,7 @@ function definitionHash(tool) {
 		return;
 	}
 }
-/** Sorted keys, no whitespace, minimal escaping: the same text in every SDK. */
+/** Sorted keys, no whitespace, minimal escaping: the same text in every SDK. Throws on what JSON cannot hold. */
 function canonical(value) {
 	if (value === null) return "null";
 	if (typeof value === "boolean") return String(value);
@@ -855,6 +855,7 @@ function track(toolName, handler) {
 					sdkVersion: SDK_VERSION,
 					...session !== void 0 && { sessionId: session },
 					...definition(toolName),
+					...call?.repeated === true && { repeated: true },
 					...outcome
 				});
 			} catch {}
@@ -963,7 +964,8 @@ function recordRefusedCall(refused) {
 			timestamp: refused.timestamp,
 			sdkVersion: SDK_VERSION,
 			...refused.sessionId !== void 0 && { sessionId: refused.sessionId },
-			...refused.errorSource === "unknown_tool" ? {} : definition(refused.toolName)
+			...refused.errorSource === "unknown_tool" ? {} : definition(refused.toolName),
+			...refused.repeated === true && { repeated: true }
 		});
 	} catch {}
 }
@@ -1368,6 +1370,40 @@ function watchPrimitive(handler, server) {
 	};
 }
 //#endregion
+//#region src/repeats.ts
+/**
+* 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.
+*/
+/** Session and tool pairs kept, the oldest forgotten first. */
+const MAX_KEPT = 1e4;
+const latest = /* @__PURE__ */ new Map();
+/**
+* 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. Never throws: an
+* argument object that cannot be written down is never a repeat.
+*/
+function noteArguments(sessionId, toolName, args) {
+	try {
+		const digest = createHash("sha256").update(canonical(args ?? {}), "utf8").digest("hex");
+		const key = `${sessionId}\u0000${toolName}`;
+		const previous = latest.get(key);
+		latest.delete(key);
+		latest.set(key, digest);
+		if (latest.size > MAX_KEPT) {
+			const oldest = latest.keys().next().value;
+			if (oldest !== void 0) latest.delete(oldest);
+		}
+		return previous === digest;
+	} catch {
+		return false;
+	}
+}
+//#endregion
 //#region src/instrument.ts
 /**
 * Methods an MCP server registers tools through.
@@ -1396,6 +1432,28 @@ const registries = /* @__PURE__ */ new WeakMap();
 * it on its own. A weak set, so contexts leave with their requests.
 */
 const reachedHandler = /* @__PURE__ */ new WeakSet();
+/** Requests whose arguments repeat the previous call's to the same tool in the session (contract, 3.9). */
+const repeatedCalls = /* @__PURE__ */ new WeakSet();
+/**
+* Compares a call's arguments, as the client sent them, with the previous call's to the same tool in the same
+* session, as it arrives, before any validation; and marks the request so the handler side knows too. A call
+* without a session is never compared.
+*/
+function noteRepeat(server, request, context) {
+	try {
+		const name = request.params?.name;
+		if (typeof name !== "string" || typeof context !== "object" || context === null) return false;
+		const params = request.params;
+		if (params["inputResponses"] !== void 0 || params["requestState"] !== void 0) return false;
+		const sessionId = sessionFor(server, context);
+		if (sessionId === void 0) return false;
+		const repeated = noteArguments(sessionId, name, request.params?.arguments);
+		if (repeated) repeatedCalls.add(context);
+		return repeated;
+	} catch {
+		return false;
+	}
+}
 /**
 * Request contexts whose handler last answered with an interim
 * `input_required` result (the 2026-07-28 protocol's way to ask the client for
@@ -1545,10 +1603,12 @@ function noteReached(handler, server) {
 		const sessionId = hasContext ? sessionFor(server, context) : void 0;
 		const client = clientFor(server, hasContext ? context : void 0);
 		const serverVersion = serverVersionOf(server);
+		const repeated = hasContext && repeatedCalls.has(context);
 		const result = withCall({
 			...sessionId !== void 0 && { sessionId },
 			...client !== void 0 && { client },
-			...serverVersion !== void 0 && { serverVersion }
+			...serverVersion !== void 0 && { serverVersion },
+			...repeated && { repeated }
 		}, run);
 		if (hasContext) noteInterim(context, result);
 		return result;
@@ -1621,6 +1681,7 @@ function watchToolCalls(handler, server, registry) {
 		if (!isRecording() || request?.method !== "tools/call") return call();
 		const timestamp = (/* @__PURE__ */ new Date()).toISOString();
 		const startedAt = performance.now();
+		const repeated = noteRepeat(server, request, context);
 		const noteRefusal = (message) => {
 			try {
 				const reached = typeof context === "object" && context !== null && reachedHandler.has(context);
@@ -1636,7 +1697,8 @@ function watchToolCalls(handler, server, registry) {
 						durationMs: performance.now() - startedAt,
 						sessionId: sessionFor(server, context),
 						client: clientFor(server, context),
-						serverVersion: serverVersionOf(server)
+						serverVersion: serverVersionOf(server),
+						repeated
 					});
 					return;
 				}
@@ -1650,7 +1712,8 @@ function watchToolCalls(handler, server, registry) {
 					durationMs: performance.now() - startedAt,
 					sessionId: sessionFor(server, context),
 					client: clientFor(server, context),
-					serverVersion: serverVersionOf(server)
+					serverVersion: serverVersionOf(server),
+					repeated
 				});
 			} catch {}
 		};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcpspan",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Self-hosted analytics for MCP servers: which tools, resources and prompts get used, by which client, how fast, and why they fail.",
   "keywords": [
     "mcp",