toad-eye 2.9.2 → 2.11.0

package/README.md

@@ -169,4 +169,4 @@ Full metrics and span attribute reference: [COMPATIBILITY.md](https://github.com
 
 ## Tech Stack
 
-TypeScript · OpenTelemetry SDK 2.x · Hono · Docker Compose (Prometheus, Jaeger, Grafana, OTel Collector) · Vitest (278+ tests)
+TypeScript · OpenTelemetry SDK 2.x · Hono · Docker Compose (Prometheus, Jaeger, Grafana, OTel Collector) · Vitest (285+ tests)

package/dist/alerts/channels.js

@@ -7,7 +7,7 @@ function smtpCacheKey(config) {
 }
 function formatMessage(alert) {
     const topModelsText = alert.topModels.length > 0
-        ? `\nTop models by spend:\n${alert.topModels.map((m) => `  • ${m.model}: $${m.value.toFixed(4)}`).join("\n")}`
+        ? `\nTop contributors:\n${alert.topModels.map((m) => `  • ${m.model}: ${m.value.toFixed(4)}`).join("\n")}`
         : "";
     return [
         `🚨 Alert: ${alert.rule.name}`,
@@ -27,6 +27,7 @@ async function sendTelegram(config, alert) {
             chat_id: config.chatId,
             text: formatMessage(alert),
         }),
+        signal: AbortSignal.timeout(10_000),
     });
     if (!res.ok)
         throw new Error(`Telegram send failed: ${res.status}`);
@@ -36,6 +37,7 @@ async function sendSlackWebhook(config, alert) {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({ text: formatMessage(alert) }),
+        signal: AbortSignal.timeout(10_000),
     });
     if (!res.ok)
         throw new Error(`Slack webhook failed: ${res.status}`);
@@ -44,6 +46,7 @@ async function sendWebhook(config, alert) {
     const res = await fetch(config.url, {
         method: "POST",
         headers: { "Content-Type": "application/json", ...config.headers },
+        signal: AbortSignal.timeout(10_000),
         body: JSON.stringify({
             alertName: alert.rule.name,
             metric: alert.rule.metric,

package/dist/alerts/conditions.js

@@ -11,6 +11,7 @@ const METRIC_MAP = {
     "gen_ai.mcp.tool.duration": "gen_ai_mcp_tool_duration",
     "gen_ai.mcp.resource.reads": "gen_ai_mcp_resource_reads_total",
     "gen_ai.mcp.tool.callers": "gen_ai_mcp_tool_callers_total",
+    "gen_ai.mcp.tool.hallucinations": "gen_ai_mcp_tool_hallucinations_total",
     // Legacy names (backward compat)
     "llm.request.cost": "gen_ai_client_request_cost_USD_sum",
     "llm.request.duration": "gen_ai_client_operation_duration_milliseconds",
@@ -93,7 +94,7 @@ function matches(value, comparator, threshold) {
 }
 async function queryScalar(prometheusUrl, promql) {
     const url = `${prometheusUrl}/api/v1/query?query=${encodeURIComponent(promql)}`;
-    const res = await fetch(url);
+    const res = await fetch(url, { signal: AbortSignal.timeout(10_000) });
     if (!res.ok)
         throw new Error(`Prometheus query failed: ${res.status} ${res.statusText}`);
     const data = (await res.json());
@@ -103,7 +104,7 @@ async function queryScalar(prometheusUrl, promql) {
 async function queryTopModels(prometheusUrl, metric, window) {
     const promql = buildTopModelsQuery(metric, window);
     const url = `${prometheusUrl}/api/v1/query?query=${encodeURIComponent(promql)}`;
-    const res = await fetch(url);
+    const res = await fetch(url, { signal: AbortSignal.timeout(10_000) });
     if (!res.ok)
         return [];
     const labelKey = isMcpMetric(metric)

package/dist/alerts/grafana.js

@@ -12,6 +12,7 @@ export async function postGrafanaAnnotation(grafanaUrl, alert, apiKey) {
     const res = await fetch(`${grafanaUrl}/api/annotations`, {
         method: "POST",
         headers,
+        signal: AbortSignal.timeout(10_000),
         body: JSON.stringify({
             time: Date.now(),
             tags: ["toad-eye", "alert", alert.name],

package/dist/alerts/manager.js

@@ -14,6 +14,8 @@ export class AlertManager {
         this.config = config;
     }
     start() {
+        if (this.intervalId !== undefined)
+            return;
         const configured = this.config.evalIntervalSeconds ?? DEFAULT_EVAL_INTERVAL_SECONDS;
         const clampedSeconds = Math.max(configured, MIN_EVAL_INTERVAL_SECONDS);
         if (configured < MIN_EVAL_INTERVAL_SECONDS) {

package/dist/cli.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { execFileSync, spawn } from "node:child_process";
+import { createConnection } from "node:net";
 import { cpSync, existsSync, mkdirSync, realpathSync, writeFileSync, } from "node:fs";
 import { join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -73,17 +74,66 @@ function requireDocker() {
         process.exit(1);
     }
 }
+const PORT_CONFIG = [
+    { env: "COLLECTOR_PORT", default: 4318, service: "OTel Collector" },
+    { env: "PROMETHEUS_PORT", default: 9090, service: "Prometheus" },
+    { env: "JAEGER_PORT", default: 16686, service: "Jaeger" },
+    { env: "GRAFANA_PORT", default: 3100, service: "Grafana" },
+];
+function getPort(env, defaultPort) {
+    const val = process.env[env];
+    return val ? parseInt(val, 10) : defaultPort;
+}
+function checkPort(port) {
+    return new Promise((resolve) => {
+        const socket = createConnection({ port, host: "127.0.0.1" });
+        socket.setTimeout(500);
+        socket.on("connect", () => {
+            socket.destroy();
+            resolve(true); // port is in use
+        });
+        socket.on("error", () => resolve(false)); // port is free
+        socket.on("timeout", () => {
+            socket.destroy();
+            resolve(false);
+        });
+    });
+}
+async function checkPorts() {
+    const conflicts = [];
+    for (const { env, default: defaultPort, service } of PORT_CONFIG) {
+        const port = getPort(env, defaultPort);
+        const inUse = await checkPort(port);
+        if (inUse) {
+            conflicts.push(`  ❌ Port ${port} is already in use (${service})\n     Fix: stop the other service, or set ${env}=${port + 1}`);
+        }
+    }
+    if (conflicts.length > 0) {
+        console.error("Port conflicts detected:\n");
+        console.error(conflicts.join("\n\n"));
+        console.error();
+        process.exit(1);
+    }
+}
 function up() {
     requireDocker();
     const composeFile = requireInfra();
     console.log("🐸 Starting observability stack...");
     console.log("   (first run downloads ~500MB of Docker images — this may take a few minutes)\n");
-    execFileSync("docker", ["compose", "-f", composeFile, "up", "-d"], {
-        stdio: "inherit",
-    });
-    console.log();
-    status();
-    console.log("   Run 'npx toad-eye demo' to send test data and verify the stack works.");
+    // Check ports synchronously via async wrapper — CLI is short-lived
+    const checkAndStart = async () => {
+        await checkPorts();
+        execFileSync("docker", ["compose", "-f", composeFile, "up", "-d"], {
+            stdio: "inherit",
+        });
+        console.log();
+        status();
+        console.log("   Dashboards will be empty until data arrives.\n");
+        console.log("   Next steps:");
+        console.log("     npx toad-eye demo          ← send mock traffic, see data in Grafana");
+        console.log("     or add toad-eye to your app  (see README)");
+    };
+    void checkAndStart();
 }
 function down() {
     const composeFile = requireInfra("Nothing to stop.");
@@ -175,19 +225,37 @@ async function demo() {
     });
     console.log("🐸👁️ toad-eye demo — sending mock LLM traffic");
     console.log("    Press Ctrl+C to stop\n");
-    console.log("✅ Stack verified! Add this to your app:\n");
-    console.log("   import { initObservability } from 'toad-eye';\n   initObservability({ serviceName: 'my-app', instrument: ['openai'] });\n");
     process.on("SIGINT", async () => {
         console.log("\n\u{1f44b} Shutting down...");
         await shutdown();
         process.exit(0);
     });
+    let opened = false;
+    function openGrafana() {
+        if (opened)
+            return;
+        opened = true;
+        const url = "http://localhost:3100";
+        const cmd = process.platform === "darwin"
+            ? "open"
+            : process.platform === "win32"
+                ? "start"
+                : "xdg-open";
+        try {
+            spawn(cmd, [url], { detached: true, stdio: "ignore" }).unref();
+            console.log(`\n  📊 Opened Grafana: ${url}\n`);
+        }
+        catch {
+            console.log(`\n  📊 Open Grafana: ${url} (admin/admin)\n`);
+        }
+    }
     const tick = async () => {
         const { provider, model } = pickRandom(DEMO_MODELS);
         const prompt = pickRandom(DEMO_PROMPTS);
         try {
             await traceLLMCall({ provider, model, prompt, temperature: 0.7 }, () => simulateLLMCall(provider, model, prompt));
             console.log(`  \u2705 [${provider}/${model}] ${prompt}`);
+            openGrafana();
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);

package/dist/core/console-exporter.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Console span exporter — pretty-prints completed spans to stderr.
+ *
+ * Used in "light mode" (output: "console") — no Docker, no OTel Collector,
+ * just immediate feedback in the terminal.
+ *
+ * Format:
+ *   🐸 tools/call calculate  [42ms] ✅
+ *   🐸 chat gpt-4o  [1.2s] $0.003 ✅
+ *   🐸 tools/call broken  [12ms] ❌ TypeError
+ */
+import type { SpanExporter, ReadableSpan } from "@opentelemetry/sdk-trace-base";
+import { type ExportResult } from "@opentelemetry/core";
+export declare class ToadEyeConsoleExporter implements SpanExporter {
+    export(spans: ReadableSpan[], resultCallback: (result: ExportResult) => void): void;
+    shutdown(): Promise<void>;
+}

package/dist/core/console-exporter.js

@@ -0,0 +1,55 @@
+/**
+ * Console span exporter — pretty-prints completed spans to stderr.
+ *
+ * Used in "light mode" (output: "console") — no Docker, no OTel Collector,
+ * just immediate feedback in the terminal.
+ *
+ * Format:
+ *   🐸 tools/call calculate  [42ms] ✅
+ *   🐸 chat gpt-4o  [1.2s] $0.003 ✅
+ *   🐸 tools/call broken  [12ms] ❌ TypeError
+ */
+import { SpanStatusCode } from "@opentelemetry/api";
+import { ExportResultCode } from "@opentelemetry/core";
+function formatDuration(ms) {
+    if (ms < 1)
+        return "<1ms";
+    if (ms < 1000)
+        return `${Math.round(ms)}ms`;
+    return `${(ms / 1000).toFixed(1)}s`;
+}
+function getAttr(span, key) {
+    const val = span.attributes[key];
+    if (typeof val === "string" || typeof val === "number")
+        return val;
+    return undefined;
+}
+function formatSpan(span) {
+    const durationMs = (span.endTime[0] - span.startTime[0]) * 1000 +
+        (span.endTime[1] - span.startTime[1]) / 1_000_000;
+    const isError = span.status.code === SpanStatusCode.ERROR;
+    const icon = isError ? "❌" : "✅";
+    const cost = getAttr(span, "gen_ai.toad_eye.cost");
+    const costStr = typeof cost === "number" && cost > 0 ? ` $${cost.toFixed(4)}` : "";
+    const errorType = isError ? getAttr(span, "error.type") : undefined;
+    const errorStr = errorType ? ` ${errorType}` : "";
+    return `  🐸 ${span.name}  [${formatDuration(durationMs)}]${costStr} ${icon}${errorStr}`;
+}
+// Filter out internal spans that add noise in console mode
+const SKIP_PREFIXES = ["gen_ai.agent.step."];
+function shouldShow(span) {
+    return !SKIP_PREFIXES.some((p) => span.name.startsWith(p));
+}
+export class ToadEyeConsoleExporter {
+    export(spans, resultCallback) {
+        for (const span of spans) {
+            if (shouldShow(span)) {
+                process.stderr.write(formatSpan(span) + "\n");
+            }
+        }
+        resultCallback({ code: ExportResultCode.SUCCESS });
+    }
+    shutdown() {
+        return Promise.resolve();
+    }
+}

package/dist/core/metrics.d.ts

@@ -20,3 +20,4 @@ export declare function recordResponseEmpty(provider: string, model: string, att
 export declare function recordResponseLatencyPerToken(msPerToken: number, provider: string, model: string, attrs?: Record<string, string>): void;
 export declare function recordContextUtilization(utilization: number, provider: string, model: string): void;
 export declare function recordContextBlocked(model: string): void;
+export declare function recordThinkingRatio(ratio: number, provider: string, model: string): void;

package/dist/core/metrics.js

@@ -19,6 +19,7 @@ let responseEmpty;
 let responseLatencyPerToken;
 let contextUtilization;
 let contextBlocked;
+let thinkingRatio;
 let initialized = false;
 export function initMetrics() {
     if (initialized)
@@ -86,6 +87,9 @@ export function initMetrics() {
     contextBlocked = meter.createCounter(GEN_AI_METRICS.CONTEXT_BLOCKED, {
         description: "Number of LLM calls blocked by context guard",
     });
+    thinkingRatio = meter.createHistogram(GEN_AI_METRICS.THINKING_RATIO, {
+        description: "Ratio of thinking/reasoning tokens to total output (0.0–1.0). High values indicate deep reasoning.",
+    });
     initialized = true;
 }
 /** Reset metrics state so the next initMetrics() creates fresh instruments. Called from shutdown(). */
@@ -219,3 +223,11 @@ export function recordContextBlocked(model) {
         [GEN_AI_ATTRS.REQUEST_MODEL]: model,
     });
 }
+export function recordThinkingRatio(ratio, provider, model) {
+    if (!isReady())
+        return;
+    thinkingRatio.record(ratio, {
+        [GEN_AI_ATTRS.PROVIDER]: provider,
+        [GEN_AI_ATTRS.REQUEST_MODEL]: model,
+    });
+}

package/dist/core/span-end-processor.js

@@ -34,7 +34,7 @@ function toSpanEndData(span) {
     return {
         traceId: ctx.traceId,
         spanId: ctx.spanId,
-        parentSpanId: span.parentSpanId || undefined,
+        parentSpanId: span.parentSpanContext?.spanId,
         name: span.name,
         kind: SPAN_KIND_MAP[span.kind] ?? "internal",
         status: span.status.code === SpanStatusCode.ERROR

package/dist/core/spans.d.ts

@@ -17,6 +17,10 @@ export interface LLMCallOutput {
     readonly outputTokens: number;
     /** Cost in USD. If omitted, auto-calculated from model pricing table. */
     readonly cost?: number | undefined;
+    /** Thinking/reasoning content from thinking models (o1, Claude extended thinking, Gemini). */
+    readonly thinkingContent?: string | undefined;
+    /** Thinking/reasoning tokens used (separate from outputTokens). */
+    readonly thinkingTokens?: number | undefined;
 }
 export declare function processContent(text: string): string | undefined;
 export declare function traceLLMCall(input: LLMCallInput, fn: () => Promise<LLMCallOutput>): Promise<LLMCallOutput>;

package/dist/core/spans.js

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 import { trace, SpanStatusCode } from "@opentelemetry/api";
 import { GEN_AI_ATTRS, INSTRUMENTATION_NAME } from "../types/index.js";
-import { recordRequestDuration, recordRequestCost, recordTokens, recordRequest, recordError, recordBudgetExceeded, recordBudgetBlocked, recordBudgetDowngraded, recordResponseEmpty, recordResponseLatencyPerToken, recordContextUtilization, recordContextBlocked, } from "./metrics.js";
+import { recordRequestDuration, recordRequestCost, recordTokens, recordRequest, recordError, recordBudgetExceeded, recordBudgetBlocked, recordBudgetDowngraded, recordResponseEmpty, recordResponseLatencyPerToken, recordContextUtilization, recordContextBlocked, recordThinkingRatio, } from "./metrics.js";
 import { getConfig, getBudgetTracker } from "./tracer.js";
 import { calculateCost, getModelPricing } from "./pricing.js";
 import { ToadBudgetExceededError } from "../budget/index.js";
@@ -124,6 +124,26 @@ function setSuccessAttributes(span, input, output, resolvedCost) {
         [GEN_AI_ATTRS.STATUS]: "success",
         [GEN_AI_ATTRS.FINISH_REASONS]: ["stop"],
     });
+    // Thinking model support (o1, Claude extended thinking, Gemini)
+    if (output.thinkingTokens !== undefined && output.thinkingTokens > 0) {
+        span.setAttribute("gen_ai.usage.reasoning_tokens", output.thinkingTokens);
+        const ratio = output.thinkingTokens / (output.outputTokens + output.thinkingTokens);
+        span.setAttribute("gen_ai.toad_eye.thinking.ratio", ratio);
+        recordThinkingRatio(ratio, input.provider, input.model);
+    }
+    if (output.thinkingContent !== undefined) {
+        const config = getConfig();
+        const recordThinking = config?.recordContent !== false;
+        if (recordThinking) {
+            const processed = processContent(output.thinkingContent);
+            if (processed !== undefined) {
+                span.addEvent("gen_ai.thinking", {
+                    "gen_ai.toad_eye.thinking.content": processed,
+                });
+            }
+        }
+        span.setAttribute("gen_ai.toad_eye.thinking.content_length", output.thinkingContent.length);
+    }
     span.setStatus({ code: SpanStatusCode.OK });
 }
 function setErrorAttributes(span, message) {

package/dist/core/tracer.js

@@ -14,6 +14,7 @@ import { resetMcpMetrics } from "../mcp/metrics.js";
 import { BudgetTracker } from "../budget/index.js";
 import { ToadEyeAISpanProcessor } from "../vercel.js";
 import { ToadEyeSpanEndProcessor } from "./span-end-processor.js";
+import { ToadEyeConsoleExporter } from "./console-exporter.js";
 const DEFAULT_ENDPOINT = "http://localhost:4318";
 const DEFAULT_CLOUD_ENDPOINT = "https://cloud.toad-eye.dev";
 let sdk = null;
@@ -66,22 +67,29 @@ export function initObservability(config) {
         return;
     }
     validateConfig(config);
-    const { endpoint, headers, isCloudMode } = resolveTransport(config);
+    const isConsoleMode = config.output === "console";
+    const { endpoint, headers, isCloudMode } = isConsoleMode
+        ? { endpoint: "", headers: {}, isCloudMode: false }
+        : resolveTransport(config);
     const resource = resourceFromAttributes({
         [ATTR_SERVICE_NAME]: config.serviceName,
     });
-    const traceExporter = new OTLPTraceExporter({
-        url: `${endpoint}/v1/traces`,
-        headers,
-    });
-    const metricExporter = new OTLPMetricExporter({
-        url: `${endpoint}/v1/metrics`,
-        headers,
-    });
-    const metricReader = new PeriodicExportingMetricReader({
-        exporter: metricExporter,
-        exportIntervalMillis: isCloudMode ? 10_000 : 5_000,
-    });
+    const traceExporter = isConsoleMode
+        ? new ToadEyeConsoleExporter()
+        : new OTLPTraceExporter({
+            url: `${endpoint}/v1/traces`,
+            headers,
+        });
+    // In console mode, skip metric export — no Prometheus to send to
+    const metricReader = isConsoleMode
+        ? undefined
+        : new PeriodicExportingMetricReader({
+            exporter: new OTLPMetricExporter({
+                url: `${endpoint}/v1/metrics`,
+                headers,
+            }),
+            exportIntervalMillis: isCloudMode ? 10_000 : 5_000,
+        });
     // When custom SpanProcessors are needed (e.g., Vercel AI SDK, onSpanEnd),
     // we must also include a BatchSpanProcessor for trace export —
     // NodeSDK won't create one automatically when spanProcessors is provided.
@@ -107,16 +115,19 @@ export function initObservability(config) {
     sdk = new NodeSDK({
         resource,
         traceExporter,
-        metricReader,
+        ...(metricReader !== undefined && { metricReader }),
         ...(spanProcessors.length > 0 && { spanProcessors }),
         ...(sampler !== undefined && { sampler }),
     });
     sdk.start();
     currentConfig = config;
     initMetrics();
+    if (isConsoleMode) {
+        console.log(`toad-eye: console mode — spans will be printed to stderr. No Docker needed.`);
+    }
     // Non-blocking connectivity check — warns the user if the OTel Collector is unreachable.
-    // Fire-and-forget: does not block initObservability(). Cloud mode skips this check.
-    if (!isCloudMode) {
+    // Fire-and-forget: does not block initObservability(). Cloud/console mode skips this check.
+    if (!isCloudMode && !isConsoleMode) {
         void fetch(`${endpoint}/v1/traces`, {
             method: "POST",
             body: "[]",

package/dist/instrumentations/create.js

@@ -4,7 +4,6 @@ import { traceLLMCall, processContent } from "../core/spans.js";
 import { calculateCost, getModelPricing } from "../core/pricing.js";
 import { recordRequestDuration, recordRequestCost, recordTokens, recordRequest, recordError, recordTimeToFirstToken, recordResponseEmpty, recordResponseLatencyPerToken, recordContextUtilization, recordContextBlocked, recordBudgetExceeded, recordBudgetDowngraded, } from "../core/metrics.js";
 import { getConfig, getBudgetTracker } from "../core/tracer.js";
-import { ToadBudgetExceededError } from "../budget/index.js";
 import { GEN_AI_ATTRS, INSTRUMENTATION_NAME } from "../types/index.js";
 const require = createRequire(import.meta.url);
 function isModuleInstalled(moduleName) {

package/dist/instrumentations/mcp.d.ts

@@ -8,5 +8,9 @@
  * Uses __toad_eye_mcp_patched flag to prevent double-instrumentation
  * when both auto and manual approaches are used.
  */
-export declare function enableMcpInstrumentation(): boolean;
+/**
+ * Enable MCP server auto-instrumentation.
+ * For ESM projects, pass McpServer class directly to avoid CJS/ESM module mismatch.
+ */
+export declare function enableMcpInstrumentation(McpServerClass?: any): boolean;
 export declare function disableMcpInstrumentation(): void;

package/dist/instrumentations/mcp.js

@@ -17,16 +17,25 @@ const MODULE_NAME = "@modelcontextprotocol/sdk/server/mcp.js";
 let mcpServerProto = null;
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 let originals = null;
-export function enableMcpInstrumentation() {
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function resolveServerClass() {
     try {
-        require.resolve(MODULE_NAME);
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const sdk = require(MODULE_NAME);
+        return sdk.McpServer ?? sdk.default?.McpServer;
     }
     catch {
-        return false;
+        return null;
     }
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
-    const sdk = require(MODULE_NAME);
-    const McpServer = sdk.McpServer ?? sdk.default?.McpServer;
+}
+/**
+ * Enable MCP server auto-instrumentation.
+ * For ESM projects, pass McpServer class directly to avoid CJS/ESM module mismatch.
+ */
+export function enableMcpInstrumentation(
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+McpServerClass) {
+    const McpServer = McpServerClass ?? resolveServerClass();
     if (!McpServer?.prototype)
         return false;
     if (McpServer.prototype[PATCHED_FLAG])

package/dist/mcp/client.d.ts

@@ -5,5 +5,9 @@
  * Injects W3C traceparent into _meta field so server-side middleware
  * can link client and server spans into one distributed trace.
  */
-export declare function enableMcpClientInstrumentation(): boolean;
+/**
+ * Enable MCP client instrumentation by auto-resolving the Client class.
+ * Works in CJS projects. For ESM projects, prefer passing the Client class directly.
+ */
+export declare function enableMcpClientInstrumentation(ClientClass?: any): boolean;
 export declare function disableMcpClientInstrumentation(): void;

package/dist/mcp/client.js

@@ -8,6 +8,7 @@
 import { createRequire } from "node:module";
 import { trace, context, propagation, SpanKind } from "@opentelemetry/api";
 import { MCP_METHODS, endSpanSuccess, endSpanError } from "./spans.js";
+import { recordMcpToolHallucination } from "./metrics.js";
 const require = createRequire(import.meta.url);
 const TRACER_NAME = "toad-eye-mcp-client";
 const PATCHED_FLAG = "__toad_eye_mcp_client_patched";
@@ -34,18 +35,35 @@ function injectTraceContext(params) {
     }
     return params;
 }
-export function enableMcpClientInstrumentation() {
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function resolveClientClass() {
+    // Try CJS first (works when consumer uses require)
     try {
-        require.resolve("@modelcontextprotocol/sdk/client/index.js");
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const sdk = require("@modelcontextprotocol/sdk/client/index.js");
+        return sdk.Client ?? sdk.default?.Client;
     }
     catch {
-        return false;
+        // CJS failed — will try ESM in async path
+        return null;
     }
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
-    const sdk = require("@modelcontextprotocol/sdk/client/index.js");
-    const Client = sdk.Client ?? sdk.default?.Client;
+}
+/**
+ * Enable MCP client instrumentation by auto-resolving the Client class.
+ * Works in CJS projects. For ESM projects, prefer passing the Client class directly.
+ */
+export function enableMcpClientInstrumentation(
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+ClientClass) {
+    const Client = ClientClass ?? resolveClientClass();
+    return Client ? patchClient(Client) : false;
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function patchClient(Client) {
     if (!Client?.prototype)
         return false;
+    if (typeof Client.prototype.callTool !== "function")
+        return false;
     if (Client.prototype[PATCHED_FLAG])
         return true;
     const proto = Client.prototype;
@@ -75,6 +93,11 @@ export function enableMcpClientInstrumentation() {
         }
         catch (error) {
             endSpanError(span, error);
+            // JSON-RPC -32601 = Method not found = agent hallucinated a tool name
+            const code = error?.code;
+            if (code === -32601) {
+                recordMcpToolHallucination(toolName);
+            }
             throw error;
         }
     };

package/dist/mcp/index.d.ts

@@ -3,3 +3,4 @@ export type { TraceSamplingOptions, ToadEyeMiddlewareDispose, } from "./middlewa
 export type { ToadMcpOptions } from "./types.js";
 export { MCP_METHODS } from "./spans.js";
 export { enableMcpClientInstrumentation, disableMcpClientInstrumentation, } from "./client.js";
+export { recordMcpToolHallucination } from "./metrics.js";

package/dist/mcp/index.js

@@ -1,3 +1,4 @@
 export { toadEyeMiddleware, traceSampling } from "./middleware.js";
 export { MCP_METHODS } from "./spans.js";
 export { enableMcpClientInstrumentation, disableMcpClientInstrumentation, } from "./client.js";
+export { recordMcpToolHallucination } from "./metrics.js";

package/dist/mcp/metrics.d.ts

@@ -10,6 +10,7 @@ export declare function recordMcpToolCall(toolName: string, durationMs: number,
 export declare function recordMcpToolError(toolName: string, errorType: string): void;
 export declare function recordMcpResourceRead(uri: string): void;
 export declare function recordMcpSessionStart(): void;
+export declare function recordMcpToolHallucination(toolName: string): void;
 export declare function recordMcpSessionEnd(): void;
 /** Reset MCP metrics state — must be called from shutdown() alongside resetMetrics(). */
 export declare function resetMcpMetrics(): void;

package/dist/mcp/metrics.js

@@ -13,6 +13,7 @@ const METER_NAME = "toad-eye-mcp";
 let toolDuration;
 let toolCalls;
 let toolErrors;
+let toolHallucinations;
 let resourceReads;
 let sessionActive;
 let toolCallers;
@@ -32,6 +33,9 @@ function ensureInit() {
     toolErrors = meter.createCounter(GEN_AI_METRICS.MCP_TOOL_ERRORS, {
         description: "MCP tool errors by tool name and error type",
     });
+    toolHallucinations = meter.createCounter(GEN_AI_METRICS.MCP_TOOL_HALLUCINATIONS, {
+        description: "Agent tried to call a non-existent tool (JSON-RPC -32601)",
+    });
     resourceReads = meter.createCounter(GEN_AI_METRICS.MCP_RESOURCE_READS, {
         description: "MCP resource read count by URI",
     });
@@ -79,6 +83,13 @@ export function recordMcpSessionStart() {
     ensureInit();
     sessionActive.add(1);
 }
+export function recordMcpToolHallucination(toolName) {
+    ensureInit();
+    toolHallucinations.add(1, {
+        "gen_ai.tool.name": toolName,
+        "mcp.method.name": MCP_METHODS.TOOLS_CALL,
+    });
+}
 export function recordMcpSessionEnd() {
     ensureInit();
     sessionActive.add(-1);