opentel-mcp 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,185 @@
 # Changelog
 
+## 0.6.0
+
+### Added — Agent Thrash Detection
+
+Detects when an agent retries the same tool with the same v0.4 failure
+fingerprint repeatedly, and attributes the wasted v0.5 tokens/cost to that
+loop — see the README's new "Agent Thrash Detection" section for the full
+picture, including the sessionId resolution rules below (the one thing
+most likely to be misconfigured).
+
+- Metrics, via the same `@opentelemetry/api`-only pattern as the existing
+  `mcp.tool.*` instruments: `mcp.tool.loop.detected` (counter),
+  `mcp.tool.loop.length` (histogram), `mcp.tool.loop.wasted_tokens`
+  (histogram, unit `tokens`), `mcp.tool.loop.wasted_cost_usd` (histogram,
+  unit `USD`), `mcp.tool.loop.duration` (histogram, unit `ms`). All five
+  carry only `gen_ai.tool.name` as a metric label — `mcp.failure.fingerprint`
+  and the new `mcp.loop.session_id` are deliberately excluded from every
+  metric (both are unbounded, per-caller values; see
+  `METRIC_SAFE_ATTRIBUTES`'s docblock in `src/fingerprint/attributes.js`).
+- One `mcp.loop.detected` span event on the currently active span (never a
+  new span), carrying full detail including `mcp.failure.fingerprint` and
+  `mcp.loop.session_id` — span events can carry unbounded attributes
+  safely, unlike metric labels.
+- `thrashDetection` option on `instrumentMcpServer()` (see `src/config.js`
+  and `src/thrash/config.js`): `{ enabled?, threshold?, windowMs?,
+  maxTrackedKeys?, entryTtlMs?, reEmitAfter?, assumeSingleSession? }`.
+  Every field independently overridable via an `OTEL_MCP_THRASH_*` env var
+  (first documented env-var-driven config pattern in this codebase).
+  Defaults: enabled, 3 consecutive same-fingerprint failures within 60s,
+  1000 max tracked keys (bounded LRU+TTL — see `src/thrash/store.js`), a
+  15-minute idle TTL, re-emit every 3 further failures past threshold,
+  `assumeSingleSession: false`.
+- **Requires `fingerprinting: true`** (the default): thrash detection keys
+  off the same `mcp.failure.fingerprint` fingerprinting computes, so with
+  fingerprinting disabled, detection silently never fires regardless of
+  `thrashDetection`'s own settings.
+- Safe-by-default session resolution. A generated per-connection fallback
+  session id is used only when a transport is structurally confirmed
+  single-connection (no `sessionId` property on `server.transport` — e.g.
+  stdio) or explicitly opted into via `thrashDetection.assumeSingleSession`
+  — **never** merging concurrent HTTP/SSE clients into one shared key,
+  which would otherwise fabricate false-positive loops out of unrelated
+  clients' failures. Once a server has been observed handing out a real
+  session id, a later call with none is skipped entirely rather than
+  falling back. A one-time `diag.warn` fires the first time the fallback
+  is actually used, naming which of the three conditions triggered it.
+- `bench/thrash-data-benchmark.js`: a runnable data benchmark (distinct
+  from the CPU/memory performance benchmark in
+  `test/thrash/benchmark.test.js`) measuring detection rate and wasted
+  cost against a real in-process MCP `Client`/`Server` pair, with a
+  `--sweep` mode across configured broken-tool rates and a closed-form
+  sanity check that aborts rather than shipping a row that deviates
+  beyond sampling noise. Two published, reproducible runs committed under
+  `bench/results/` — see the README for how to read them (they model
+  sensitivity to a reader-supplied failure rate, not a measurement of any
+  real deployment).
+- In-process summary: `instrumentMcpServer()`'s returned object gets a
+  `getThrashSummary()` method (`ThrashDetector.getSummary()` underneath)
+  — a zero-infrastructure way to check "is anything thrashing right now"
+  without a metrics backend or trace viewer. Returns `activeLoops` (loops
+  currently in the bounded store that have crossed `threshold` — bounded
+  by `maxTrackedKeys`, not a complete history) and `topOffenders` (up to 5
+  by default, configurable via `getThrashSummary({ topOffendersLimit })`,
+  sorted by `wastedCostUsd` descending), alongside `totalLoopsDetected` /
+  `totalWastedCostUsd` / `totalWastedTokensIn` / `totalWastedTokensOut` —
+  cumulative counters that, unlike the two above, survive LRU eviction
+  and TTL expiry (incremented at emit time, with delta-based accounting
+  so a loop that re-emits multiple times doesn't have its earlier calls'
+  cost double-counted). Never throws; an all-zero summary if
+  `thrashDetection` is disabled. Pure read — no effect on the hot path.
+  `src/thrash/store.js`'s `BoundedTtlMap` gained an `entries()` iterator
+  to support this (a minimal, necessary extension of its Phase 2 surface,
+  which was previously get/set/delete/size only).
+
+### Public API additions
+
+- Re-exported from the package root (`src/index.d.ts`, types only —
+  `ThrashDetector`/`createThrashEmitter` stay internal): `ThrashConfig`,
+  `ThrashDetectedEvent`, `ThrashSummary`, `ThrashOffender` (new
+  `src/thrash/types.d.ts`, mirrors the `src/cost/types.d.ts` /
+  `src/fingerprint/types.d.ts` pattern).
+- `instrumentMcpServer()`'s return type gained `getThrashSummary?: (options?: { topOffendersLimit?: number }) => ThrashSummary`,
+  alongside the existing `shutdown?`.
+- `fingerprinting` and `thrashDetection` (with all of `ThrashConfig`,
+  including `assumeSingleSession`) are now declared on `InstrumentOptions`
+  in `src/index.d.ts` — both worked at runtime since introduction but were
+  missing from the public type declarations until now. Also added:
+  `FingerprintContext`, `Classifier`, `ComputeFingerprintOptions` (the
+  types needed to type a custom `computeFingerprint()` classifier per the
+  README's "Extending it" section — same kind of gap, found in the same
+  audit).
+- `npm run typecheck` (`tsc --noEmit`, new `tsconfig.json`): type-checks
+  `src/index.d.ts` and the sibling `src/*/types.d.ts` files, plus a new
+  type-level test (`test/index.exports.test-d.ts`, using `expectTypeOf`)
+  asserting a consumer can construct `InstrumentOptions` with a partial
+  `thrashDetection` and a partial `fingerprinting` config. Does not
+  type-check the `.js` source itself (`checkJs: false`) — still no build
+  step, this only guards the hand-written public type declarations.
+
+### Changed (additive, non-breaking)
+
+- `applyCostAttribution()` (internal, `src/instrument.js`) now returns
+  `{ tokensIn, tokensOut, costUsd } | null` instead of `void`, so thrash
+  detection can reuse one call's already-computed cost figures instead of
+  re-running the extractor. Not part of the public API and not observable
+  from outside `instrument.js`; nothing in v0.5.0 read the previous
+  `undefined` return value.
+
+## 0.5.0
+
+### Added — Cost & Token Attribution
+
+- Span attributes, added on any tool call whose result carries recognizable
+  usage data: `mcp.tool.tokens.input`, `mcp.tool.tokens.output`,
+  `mcp.tool.tokens.total`, `mcp.tool.model`, `gen_ai.response.model`
+  (co-emitted alongside `mcp.tool.model` for GenAI-dashboard compatibility —
+  see README's "Cost & Token Attribution" section and the
+  `ATTR_GEN_AI_RESPONSE_MODEL` docblock in `src/attributes.js` for why this
+  is a pragmatic compatibility choice, not a spec-pure emission),
+  `mcp.tool.cost.usd`, and `mcp.tool.cost.currency`. All added by
+  `applyCostAttribution()` in `src/instrument.js`, wrapped in its own
+  try/catch — cost tracking can never break a span.
+- Two new metric instruments, via the same `@opentelemetry/api`-only
+  pattern as the four existing `mcp.tool.*` metrics: `mcp.tool.tokens.total`
+  (counter, unit `tokens`) and `mcp.tool.cost.total` (counter, unit `USD`),
+  both attributed by `gen_ai.tool.name` + `mcp.tool.model` (model only
+  added when detected, same optional-attribute pattern
+  `mcp.failure.category` already uses).
+- Per-session and per-tool budget guardrails (`costTracking.budget`,
+  `src/cost/budget.js`): in-memory cumulative-cost tracking, flags
+  `mcp.tool.cost.budget_exceeded` / `mcp.tool.cost.budget_scope`
+  (`"session"` | `"tool"`, session wins if both trip on the same call) on
+  the span once a configured `perSessionUsd`/`perToolUsd` limit is
+  crossed. **Observability only — never blocks or throws.** Calls with no
+  MCP session id (e.g. stdio transport) are skipped for session tracking
+  rather than lumped under a fallback key.
+- `DEFAULT_PRICING` (`src/cost/pricing.js`): a default pricing table
+  covering 15+ models across five providers — Anthropic, OpenAI, Google,
+  AWS Bedrock, and DeepSeek. **Last verified 2026-07-29 — provider pricing
+  changes frequently and this table is not guaranteed to stay current;
+  override `costTracking.pricingTable` for production accuracy.**
+- `defaultExtractor` (`src/cost/extractor.js`): recognizes Anthropic
+  (`usage.input_tokens`/`usage.output_tokens`), OpenAI
+  (`usage.prompt_tokens`/`usage.completion_tokens`), and Bedrock
+  (`usage.inputTokens`/`usage.outputTokens`) usage shapes, the MCP
+  `_meta.usage` extension point, and JSON-in-text inside
+  `content[0].text`. Never throws — unrecognized shapes resolve to `null`.
+  Pluggable via `costTracking.extractor` (type `UsageExtractor`) for
+  custom tool result formats.
+- `calculateCost()` (`src/cost/calculator.js`): normalizes a model name
+  (lowercase, strips a `provider/` prefix) and prices it against a
+  `PricingTable`. Returns `null` — never throws — for an unrecognized
+  model or invalid token counts.
+- `costTracking` option on `instrumentMcpServer()` (see `src/config.js`):
+  `{ enabled?: boolean; pricingTable?: PricingTable; extractor?:
+  UsageExtractor; budget?: { perSessionUsd?: number; perToolUsd?: number
+  } }`. Defaults to enabled, `DEFAULT_PRICING`, `defaultExtractor`, budget
+  tracking off. Any field can be overridden independently.
+
+### Public API additions
+
+Re-exported from the package root (`src/index.js` / `src/index.d.ts`):
+`DEFAULT_PRICING`, `defaultExtractor`, `calculateCost` (values), and
+`ModelPricing`, `PricingTable`, `UsageExtractor`, `TokenUsage`,
+`CostTrackingOptions` (types, from the new `src/cost/types.d.ts` —
+mirrors the `src/fingerprint/types.d.ts` pattern).
+
+### Docs
+
+- `gen_ai.tool.name`'s comment in `src/attributes.js` now explicitly notes
+  it's sourced from the OTel GenAI semantic conventions, not a custom
+  addition — the file already documented this at the module/section level,
+  but not on the constant itself, which read ambiguously next to the
+  custom attributes below it that do say so explicitly.
+- README: new "Cost & Token Attribution (v0.5.0)" section (motivation,
+  zero-config quick-start, advanced config example, span-attribute and
+  metric tables, pricing-accuracy note, extension points); intro tagline
+  and "Configuration"/"Semantic conventions"/"Roadmap"/"Compatibility"
+  sections updated to match.
+
 ## 0.3.0
 
 ### Added

package/README.md

@@ -1,7 +1,7 @@
 # opentel-mcp
 
 > Turn every MCP tool call into an OpenTelemetry trace — including the
-> failures your logs won't show you.
+> failures your logs won't show you, and what it cost in LLM tokens.
 
 [![CI](https://github.com/Thirumalaiboobathi/opentel-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Thirumalaiboobathi/opentel-mcp/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/opentel-mcp.svg)](https://www.npmjs.com/package/opentel-mcp)
@@ -9,10 +9,14 @@
 [![license](https://img.shields.io/npm/l/opentel-mcp.svg)](https://github.com/Thirumalaiboobathi/opentel-mcp/blob/main/LICENSE)
 
 opentel-mcp watches every tool call your MCP (Model Context Protocol)
-server handles: which tool ran, how long it took, and whether it worked.
-It reports that as OpenTelemetry (OTel) traces — the standard most
-dashboards already read. One function call; no changes to your tools'
-code.
+server handles: which tool ran, how long it took, whether it worked, and —
+when the tool result carries usage data — how many tokens it burned and
+what that cost. It reports all of that as OpenTelemetry (OTel) traces —
+the standard most dashboards already read. One function call; no changes
+to your tools' code.
+
+opentel-mcp is the only Node.js MCP instrumentation library that ties
+tool calls to LLM cost.
 
 ## The problem
 
@@ -288,6 +292,337 @@ examples/fingerprint-demo.js`). Not yet wired through
 `computeFingerprint` directly rather than configuring the automatic
 per-call-site wrapping; tracked in the roadmap below.
 
+## Cost & Token Attribution (v0.5.0)
+
+MCP tools increasingly wrap LLM calls themselves — a tool that
+summarizes a document, drafts a reply, or classifies a ticket usually
+does it by calling out to a model, and that call has a real dollar cost.
+Standard MCP/OTel instrumentation has no opinion on any of this: a trace
+shows a tool ran in 800ms and succeeded, with nothing about which model
+it used, how many tokens it burned, or what that cost. That's the AI
+FinOps gap in MCP observability today — cost and usage data exists
+inside the tool call, but nothing carries it out to your traces. opentel-mcp
+closes it: when a tool result carries recognizable usage data, the same
+span your other instrumentation already reads also gets token counts, the
+detected model, and an estimated USD cost.
+
+### Zero-config quick-start
+
+```js
+import { instrumentMcpServer } from 'opentel-mcp';
+
+instrumentMcpServer(server, {
+  serviceName: 'my-mcp-server',
+  setupNodeSdk: true, // dev mode: prints traces to your terminal
+});
+```
+
+That's it — `costTracking` defaults to enabled. Any tool result whose
+usage data matches one of `defaultExtractor`'s recognized conventions
+(Anthropic's `usage.input_tokens`/`usage.output_tokens`, OpenAI's
+`usage.prompt_tokens`/`usage.completion_tokens`, Bedrock's
+`usage.inputTokens`/`usage.outputTokens`, the MCP `_meta.usage` extension
+point, or JSON-in-text inside `content[0].text`) automatically gets
+`mcp.tool.tokens.*` / `mcp.tool.model` / `mcp.tool.cost.*` span
+attributes, priced against `DEFAULT_PRICING`.
+
+### Advanced: custom pricing, a custom extractor, and a budget guardrail
+
+```js
+import { instrumentMcpServer, DEFAULT_PRICING } from 'opentel-mcp';
+
+instrumentMcpServer(server, {
+  serviceName: 'my-mcp-server',
+  costTracking: {
+    // Extend or override DEFAULT_PRICING — e.g. price an internal model
+    // it doesn't know about, or correct stale numbers.
+    pricingTable: {
+      ...DEFAULT_PRICING,
+      'my-internal-model': { inputPer1M: 1.0, outputPer1M: 2.0, currency: 'USD' },
+    },
+    // Recognize your own tool result shape. Return null for anything you
+    // don't recognize — never throw (see src/cost/extractor.js).
+    extractor: (toolResult) => {
+      if (!toolResult?.tokenStats) return null;
+      const { in: inputTokens, out: outputTokens, modelId } = toolResult.tokenStats;
+      return { inputTokens, outputTokens, totalTokens: inputTokens + outputTokens, model: modelId };
+    },
+    // Observability guardrail, NOT enforcement — opentel-mcp never blocks
+    // or throws on a budget overrun, it just flags the span.
+    budget: {
+      perSessionUsd: 5, // flag once one MCP session's calls total > $5
+      perToolUsd: 1, // ...or once any single tool's calls total > $1
+    },
+  },
+});
+```
+
+### Span attributes
+
+| Attribute | Standard OTel? | Description | Example |
+|---|---|---|---|
+| `mcp.tool.tokens.input` | Custom | Input tokens consumed | 1000 |
+| `mcp.tool.tokens.output` | Custom | Output tokens produced | 500 |
+| `mcp.tool.tokens.total` | Custom | input + output | 1500 |
+| `mcp.tool.model` | Custom | Detected model name | "claude-sonnet-5" |
+| `gen_ai.response.model` | Standard (GenAI semconv)[^5] | Same value as `mcp.tool.model`, co-emitted for dashboard compatibility | "claude-sonnet-5" |
+| `mcp.tool.cost.usd` | Custom | Estimated cost, from `calculateCost()` | 0.0105 |
+| `mcp.tool.cost.currency` | Custom | Always `"USD"` today | "USD" |
+| `mcp.tool.cost.budget_exceeded` | Custom | `true` once a configured `costTracking.budget` limit is crossed | true |
+| `mcp.tool.cost.budget_scope` | Custom | Which budget scope tripped: `"session"` \| `"tool"` (session wins if both did) | "session" |
+
+[^5]: `gen_ai.response.model` is a real OTel GenAI semantic convention attribute ("the name of the model that generated the response") — but this span is an MCP tool-call span (`gen_ai.operation.name: execute_tool`), not a dedicated LLM request/response span, so co-emitting it here is a **pragmatic dashboard-compatibility choice, not a spec-pure emission**. It's set purely so off-the-shelf GenAI dashboards (Grafana, SigNoz, Honeycomb) that filter/group by `gen_ai.response.model` pick these spans up without any opentel-mcp-specific configuration. Full reasoning in `src/attributes.js`'s `ATTR_GEN_AI_RESPONSE_MODEL` docblock.
+
+The four token/model attributes are set together or not at all; the two
+cost attributes only appear when a model was detected *and* it resolves
+in the configured `pricingTable`; the two budget attributes only appear
+when a cost was calculated *and* a configured limit was crossed. Source
+of truth: `src/attributes.js` and `src/instrument.js`'s
+`applyCostAttribution()`.
+
+### Metrics
+
+Two more `mcp.tool.*` metrics, via the same API-only pattern as the four
+in "Metrics" above — nothing recorded until a `MeterProvider` is
+registered, `enableMetrics: false` opts out of these too.
+
+| Metric | Type | Unit | Attributes | Emitted when |
+|---|---|---|---|---|
+| `mcp.tool.tokens.total` | Counter | tokens | `gen_ai.tool.name`, `mcp.tool.model`[^6] | Usage detected in the tool result |
+| `mcp.tool.cost.total` | Counter | USD | `gen_ai.tool.name`, `mcp.tool.model`[^6] | Cost calculated (model resolved in `pricingTable`) |
+
+[^6]: `mcp.tool.model` is only added when a model was detected — the same optional-attribute cardinality pattern `mcp.failure.category` already uses on the other four metrics.
+
+### Pricing accuracy
+
+> **Pricing table last verified 2026-07-29.** Users **MUST** override
+> `pricingTable` for production accuracy — provider pricing changes
+> frequently and opentel-mcp does not guarantee `DEFAULT_PRICING` stays
+> current.
+
+`DEFAULT_PRICING` (`src/cost/pricing.js`) covers 15+ models across five
+providers — Anthropic, OpenAI, Google, AWS Bedrock, and DeepSeek — as a
+convenience default, not a maintained price list.
+
+### Extending it
+
+- `defaultExtractor` (also exported) recognizes the five conventions
+  listed under "Zero-config quick-start" above; pass your own
+  `costTracking.extractor` (a `UsageExtractor`: `(toolResult) =>
+  TokenUsage | null`, never throwing) to recognize anything else.
+- `calculateCost(inputTokens, outputTokens, model, pricingTable)` is also
+  exported directly, for recomputing cost outside the instrumentation
+  hot path (e.g. over historical spans).
+- Disable everything in this section with `costTracking: { enabled:
+  false }`; tracing, metrics, and fingerprinting are all unaffected.
+- Budget tracking (`costTracking.budget`) is in-memory and per
+  `instrumentMcpServer()` call — it resets on process restart, and
+  session-scoped limits are skipped gracefully (not enforced against a
+  fallback key) for transports with no session id, like stdio.
+
+## Agent Thrash Detection (v0.6.0)
+
+Watches for the same tool failing with the same v0.4 failure fingerprint
+several times in a row inside one session — the pattern an LLM agent
+produces when it keeps retrying a call that can't succeed. When that
+crosses a threshold, it attributes the tokens and cost (v0.5) burned by
+the whole retry loop to one event, instead of leaving it scattered across
+N indistinguishable failed-tool-call spans.
+
+### Zero-config quick-start
+
+```js
+import { instrumentMcpServer } from 'opentel-mcp';
+
+instrumentMcpServer(server, {
+  serviceName: 'my-mcp-server',
+  setupNodeSdk: true,
+});
+```
+
+That's it — `thrashDetection` defaults to enabled, same as `fingerprinting`
+and `costTracking`. Any tool that fails 3 times in a row with the same
+fingerprint inside 60 seconds gets flagged automatically. **Requires
+`fingerprinting: true`** (also the default): detection keys off the same
+`mcp.failure.fingerprint` fingerprinting computes, so with fingerprinting
+disabled, thrash detection silently never fires, regardless of
+`thrashDetection`'s own settings.
+
+### Metrics
+
+Same API-only pattern as every other metric in this README — nothing
+recorded until a `MeterProvider` is registered.
+
+| Metric | Type | Unit | Attributes | Emitted when |
+|---|---|---|---|---|
+| `mcp.tool.loop.detected` | Counter | — | `gen_ai.tool.name` | A loop crosses `threshold`, and again every `reEmitAfter` failures past it |
+| `mcp.tool.loop.length` | Histogram | — | `gen_ai.tool.name` | Same |
+| `mcp.tool.loop.wasted_tokens` | Histogram | tokens | `gen_ai.tool.name` | Same |
+| `mcp.tool.loop.wasted_cost_usd` | Histogram | USD | `gen_ai.tool.name` | Same |
+| `mcp.tool.loop.duration` | Histogram | ms | `gen_ai.tool.name` | Same |
+
+Every metric above carries **only** `gen_ai.tool.name`. `mcp.failure.fingerprint`
+and `mcp.loop.session_id` are deliberately excluded from every one of them
+— both are unbounded, per-caller values (a new bug is a new fingerprint,
+forever; a new session is a new session id, forever), so putting either on
+a metric label would turn every distinct bug or session into its own
+permanent time series. See `METRIC_SAFE_ATTRIBUTES`'s docblock in
+`src/fingerprint/attributes.js`. Full detail is still available — on the
+span event below, where high-cardinality attributes are safe.
+
+### Span event: `mcp.loop.detected`
+
+Added to the **currently active span** (never a new one) each time a loop
+metric above fires.
+
+| Attribute | Description |
+|---|---|
+| `mcp.loop.length` | Consecutive same-fingerprint failures in the loop, at the moment of this emission |
+| `mcp.loop.wasted_tokens_in` | Cumulative input tokens burned by the loop so far |
+| `mcp.loop.wasted_tokens_out` | Cumulative output tokens burned by the loop so far |
+| `mcp.loop.wasted_cost_usd` | Cumulative estimated USD cost burned by the loop so far |
+| `mcp.loop.duration_ms` | Elapsed ms between the loop's first and most recent failure |
+| `mcp.loop.first_span_id` | Span id of the loop's first failure |
+| `mcp.loop.first_trace_id` | Trace id of the loop's first failure |
+| `mcp.loop.session_id` | The session this loop belongs to |
+| `mcp.failure.fingerprint` | The shared fingerprint (see "Failure Fingerprinting" above) |
+
+### Configuration
+
+All fields of `thrashDetection`, each independently overridable by its own
+`OTEL_MCP_THRASH_*` env var (first env-var-driven config in this
+codebase) — precedence is explicit option field, then env var, then
+default; an invalid/unparseable env value falls back to the default
+silently, never throws. Source of truth: `src/thrash/config.js`.
+
+| Option | Env var | Type | Default | Description |
+|---|---|---|---|---|
+| `enabled` | `OTEL_MCP_THRASH_ENABLED` | boolean | `true` | `false` disables thrash detection entirely |
+| `threshold` | `OTEL_MCP_THRASH_THRESHOLD` | number | `3` | Consecutive same-fingerprint failures required to trigger detection |
+| `windowMs` | `OTEL_MCP_THRASH_WINDOW_MS` | number | `60000` | Failures must fall inside this rolling window to count toward the same loop |
+| `maxTrackedKeys` | `OTEL_MCP_THRASH_MAX_TRACKED_KEYS` | number | `1000` | LRU cap on the bounded store (`src/thrash/store.js`) |
+| `entryTtlMs` | `OTEL_MCP_THRASH_ENTRY_TTL_MS` | number | `900000` | How long an idle tracked key survives before expiry |
+| `reEmitAfter` | `OTEL_MCP_THRASH_RE_EMIT_AFTER` | number | `3` | Re-emit every N further failures past `threshold` (e.g. 3, 6, 9, ...) instead of once |
+| `assumeSingleSession` | `OTEL_MCP_THRASH_ASSUME_SINGLE_SESSION` | boolean | `false` | Force-permits the fallback session id even when the transport can't be determined — see below |
+
+### Session id resolution — read this before setting `assumeSingleSession`
+
+**This is the one setting most likely to get misconfigured, so this
+section is deliberately explicit.** Thrash detection needs a session
+boundary to group repeated failures under — merge two different clients'
+failures into one bucket and you get a false-positive loop that never
+happened to either client individually.
+
+MCP sessions have a transport-provided id (`extra.sessionId`) on
+session-oriented transports, but stdio has none — there's exactly one
+connection for the process's whole lifetime instead. The resolution rules,
+in order:
+
+1. **A real `extra.sessionId` always wins**, and permanently marks the
+   server as session-aware.
+2. **Once a server has been observed handing out a real session id, a
+   later call with none is skipped entirely** — never merged into a
+   shared fallback key, even if `assumeSingleSession` is set. A server
+   that has proven it hands out real session ids doesn't get to fall back
+   just because one particular call lacked one.
+3. **Before any real session id has ever been observed**, a generated
+   per-connection fallback id is used only when:
+   - the transport is **structurally confirmed single-connection** — no
+     `sessionId` property on `server.transport` at all (e.g. stdio's
+     `StdioServerTransport`, which has no session concept whatsoever), or
+   - **you set `assumeSingleSession: true`** — an explicit opt-in for
+     transports the auto-detection can't see (e.g. a custom `Transport`
+     implementation), where you already know every connection is 1:1.
+
+   Otherwise — an undetermined, potentially multi-client transport, with
+   `assumeSingleSession` left at its default `false` — detection is
+   **skipped silently** for that call rather than guessing.
+
+**The risk of getting this wrong:** if you set `assumeSingleSession: true`
+on a transport that's actually serving multiple concurrent clients (a
+typical HTTP/SSE deployment behind a load balancer, for instance), their
+failures get merged into one shared session key. Three unrelated clients
+each failing once looks identical to one client failing three times in a
+row — a false-positive `mcp.loop.detected` event that never happened to
+any real session. Only set `assumeSingleSession: true` when you have
+independent knowledge that the transport is genuinely 1:1 (a custom
+in-process transport, a dedicated single-tenant connection, etc.) — never
+as a blanket "make the warning go away" setting. A one-time `diag.warn`
+fires the first time the fallback is actually used on a given server,
+naming exactly which of the three conditions above triggered it, so you
+have a chance to catch a wrong assumption before it produces bad data.
+
+### In-process summary
+
+For a zero-infrastructure quick check — no metrics backend, no trace
+viewer, just "is anything thrashing right now" — the object
+`instrumentMcpServer()` returns gets a `getThrashSummary()` method:
+
+```js
+const server = instrumentMcpServer(new Server(...), { serviceName: 'my-mcp-server' });
+
+// ...later, e.g. in a health-check handler or just to eyeball it:
+console.log(server.getThrashSummary());
+// {
+//   activeLoops: 1,
+//   totalLoopsDetected: 4,
+//   totalWastedCostUsd: 0.09,
+//   totalWastedTokensIn: 3600,
+//   totalWastedTokensOut: 900,
+//   topOffenders: [
+//     { toolName: 'lookup_customer', fingerprint: 'a3f4c8e2b1d09f77', loops: 3, wastedCostUsd: 0.03, wastedTokensIn: 900, wastedTokensOut: 225 },
+//   ],
+// }
+```
+
+No OTel involved — nothing sent anywhere, safe to call from application
+code. Never throws; returns an all-zero summary if `thrashDetection` is
+disabled, or if instrumentation is disabled entirely (in which case
+`getThrashSummary` isn't attached at all — check for its presence, same
+as `shutdown`).
+
+**`activeLoops` and `topOffenders` are bounded by `maxTrackedKeys`, and
+are not a complete history.** They reflect only what's currently sitting
+in the bounded LRU+TTL store this instant — a loop that got evicted (past
+`maxTrackedKeys`) or expired (past `entryTtlMs`) since it was last
+detected won't appear in either, even though it really happened.
+`totalLoopsDetected` and `totalWasted*`, by contrast, are cumulative
+counters that survive both eviction and expiry — they answer "how much
+has this process wasted since it started" (or since the last call to an
+internal `reset()`), not "what's currently active." Don't read
+`topOffenders` as an audit log; read the cumulative totals for that.
+
+### Benchmarks
+
+Two kinds, both under `bench/` and `test/thrash/`:
+
+- **Performance** (`test/thrash/benchmark.test.js`, runs as part of
+  `npm test`): CPU/memory overhead of the detection code itself.
+- **Data** (`bench/thrash-data-benchmark.js`, a standalone script — its
+  own header docblock documents every `--flag`, including `--sweep`):
+  how often a *configured* mix of healthy/broken tool calls results in a
+  detected loop, and what it would cost. Two runs are committed under
+  `bench/results/` as a reproducibility reference —
+  [`published-seed-42.json`](bench/results/published-seed-42.json)
+  / [`.txt`](bench/results/published-seed-42.txt) (a single run) and
+  [`published-sweep-seed-42.json`](bench/results/published-sweep-seed-42.json)
+  / [`.md`](bench/results/published-sweep-seed-42.md) (a sweep across
+  `brokenToolRate` values 0.02–0.25).
+
+  **Read the sweep table as a model you parameterize with your own
+  observed failure rate, not as a measurement of real-world deployments.**
+  `brokenToolRate` is an input the table's reader supplies — every row is
+  a configured assumption, not something measured from production
+  traffic. There is no single headline percentage here to quote as "how
+  often agents thrash" — the whole point of the sweep is that the answer
+  depends entirely on your own failure rate, which this benchmark cannot
+  know. Both committed files carry a full methodology block (how sessions
+  were isolated, that retries are scripted rather than driven by a real
+  LLM agent loop, the exact retry/token-growth assumptions, the model and
+  price used, and every known limitation that could inflate the numbers)
+  and an exact `node bench/thrash-data-benchmark.js ...` command to
+  reproduce them byte-for-byte.
+
 ## Configuration
 
 All options passed to `instrumentMcpServer(server, options)`. Source of
@@ -301,7 +636,12 @@ truth: `src/config.js`.
 | `enabled` | boolean | `true` | `false` disables all instrumentation |
 | `enableMetrics` | boolean | `true` | `false` disables `mcp.tool.*` metrics only |
 | `fingerprinting` | boolean | `true` | `false` disables `mcp.failure.*` attributes |
+| `costTracking` | object | see below | Controls cost/token attribution[^9] — see "Cost & Token Attribution" above |
+| `thrashDetection` | object | see below | Controls Agent Thrash Detection[^10] — see "Agent Thrash Detection" above. Requires `fingerprinting: true` |
+
+[^10]: `{ enabled?, threshold?, windowMs?, maxTrackedKeys?, entryTtlMs?, reEmitAfter?, assumeSingleSession? }`, all fields optional, individually defaulted, and individually overridable via an `OTEL_MCP_THRASH_*` env var — see "Agent Thrash Detection" → "Configuration" above for the full table.
 
+[^9]: `{ enabled?: boolean; pricingTable?: PricingTable; extractor?: UsageExtractor; budget?: { perSessionUsd?: number; perToolUsd?: number } }`, all fields optional and individually defaulted — `{ enabled: true, pricingTable: DEFAULT_PRICING, extractor: defaultExtractor }` with budget tracking off.
 [^2]: Required only when `setupNodeSdk` is `true`. Has no effect otherwise — the host app's registered `TracerProvider` owns the resource; passing it anyway logs a one-time `diag.warn`.
 [^3]: Creates and registers a `NodeTracerProvider` that always prints to stderr (safe alongside stdio-transport servers — ADR 003), additionally exporting via OTLP/HTTP if `exporterUrl` is set.
 [^4]: Only takes effect when `setupNodeSdk` is `true`.
@@ -348,13 +688,21 @@ until `1.0`, tracked in release notes rather than silently shipped.
 
 opentel-mcp follows those conventions (published by the OTel GenAI SIG,
 moved there from the main `semantic-conventions` repo, where the MCP
-conventions are now deprecated) for everything they define, and adds two
+conventions are now deprecated) for everything they define, and adds
 namespaces of its own where they don't yet: `mcp.tool.*` (call-count and
-duration metrics) and `mcp.failure.*` (failure fingerprinting). Both are
-documented as non-spec at every attribute (`src/attributes.js`,
-`src/fingerprint/attributes.js`), and are candidates to fold into the
-spec's own metrics/error vocabulary if it grows an equivalent. Full
-reasoning: ADR 004 in `docs/adr/`.
+duration metrics, and — as of v0.5.0 — token/cost attribution and budget
+attributes), `mcp.failure.*` (failure fingerprinting), and — as of
+v0.6.0 — `mcp.tool.loop.*` / `mcp.loop.*` (Agent Thrash Detection). All
+are documented as non-spec at every attribute (`src/attributes.js`,
+`src/fingerprint/attributes.js`, `src/thrash/attributes.js`), and are
+candidates to fold into the spec's own metrics/error vocabulary if it
+grows an equivalent. Full reasoning: ADR 004 in `docs/adr/`.
+
+One exception, also in `src/attributes.js`: `gen_ai.response.model` *is*
+a real spec attribute, co-emitted alongside the custom `mcp.tool.model`
+purely for compatibility with GenAI dashboards that already query it —
+see the "Cost & Token Attribution" section above for why that's a
+pragmatic choice rather than a spec-pure one.
 
 ## Compatibility
 
@@ -364,16 +712,19 @@ reasoning: ADR 004 in `docs/adr/`.
 - Supports both low-level `Server` and high-level `McpServer` APIs
 - @modelcontextprotocol/sdk ^1.0.0
 - @opentelemetry/api ^1.9.0
-- 127 tests (`npm test`) — see `test/`
+- 369 tests (`npm test`) — see `test/`
+- `npm run typecheck` (`tsc --noEmit`) type-checks the public `.d.ts`
+  surface (`src/index.d.ts` and friends) — see CONTRIBUTING.md
 
 ## Roadmap
 
 - v0.4: Deep Failure Fingerprinting ✓ — see "Failure Fingerprinting" above
   and ADR 006.
-- v0.5: Failure clustering + regression detection
-- Future: recovery hints, root-cause chaining across parent spans,
-  alignment with the OTel GenAI SIG's MCP semantic conventions when
-  published
+- v0.5: Cost & Token Attribution ✓ — see "Cost & Token Attribution" above.
+- v0.6: Agent Thrash Detection ✓ — see "Agent Thrash Detection" above.
+- Future: failure clustering + regression detection; recovery hints;
+  root-cause chaining across parent spans; alignment with the OTel GenAI
+  SIG's MCP semantic conventions when published
 - Also still tracked, not silently dropped: exposing `computeFingerprint`'s
   `classifiers`/`stackFrames` options through `instrumentMcpServer()`
   itself; opt-in `gen_ai.tool.call.arguments` support with a redaction

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opentel-mcp",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "One-line OpenTelemetry instrumentation for Model Context Protocol (MCP) servers",
   "type": "module",
   "main": "src/index.js",
@@ -24,6 +24,7 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
     "bench": "vitest bench --run",
     "prepack": "node scripts/strip-workspaces.js",
     "postpack": "node scripts/restore-workspaces.js"