opentel-mcp 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,113 @@
 # 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

package/README.md

@@ -420,6 +420,209 @@ convenience default, not a maintained price list.
   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
@@ -434,6 +637,9 @@ truth: `src/config.js`.
 | `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`.
@@ -485,11 +691,12 @@ moved there from the main `semantic-conventions` repo, where the MCP
 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 — as of v0.5.0 — token/cost attribution and budget
-attributes) 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/`.
+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`
@@ -505,13 +712,16 @@ pragmatic choice rather than a spec-pure one.
 - Supports both low-level `Server` and high-level `McpServer` APIs
 - @modelcontextprotocol/sdk ^1.0.0
 - @opentelemetry/api ^1.9.0
-- 288 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: 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opentel-mcp",
-  "version": "0.5.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"

package/src/config.js

@@ -6,6 +6,7 @@
 import { diag } from '@opentelemetry/api';
 import { DEFAULT_PRICING } from './cost/pricing.js';
 import { defaultExtractor } from './cost/extractor.js';
+import { resolveThrashConfig } from './thrash/config.js';
 
 /**
  * @typedef {object} CostTrackingOptions
@@ -56,6 +57,14 @@ import { defaultExtractor } from './cost/extractor.js';
  *   src/metrics.js, and src/cost/budget.js). Defaults to `{ enabled: true, pricingTable: DEFAULT_PRICING,
  *   extractor: defaultExtractor }` with budget tracking off; any fields you omit from a partial object fall
  *   back to those defaults individually, so `{ enabled: false }` alone works.
+ * @property {Partial<import('./thrash/config.js').ThrashConfig>} [thrashDetection] - Controls Agent Thrash
+ *   Detection (v0.6.0): detecting when a tool is retried repeatedly with the same failure fingerprint, and
+ *   attributing the wasted tokens/cost to that loop (see instrument.js's applyThrashDetection() /
+ *   applyThrashSuccessClear(), src/thrash/detector.js, and src/thrash/emitter.js). Resolved via
+ *   resolveThrashConfig() (src/thrash/config.js) — same partial-overrides-individual-defaults behavior as
+ *   costTracking above. Requires `fingerprinting` to also be enabled (the default): thrash detection keys
+ *   off the same mcp.failure.fingerprint fingerprinting computes, so with fingerprinting off there is
+ *   nothing to key off and detection silently never fires, regardless of this option.
  */
 
 // Guards the "serviceName has no effect" diagnostic below so it fires once
@@ -111,5 +120,6 @@ export function resolveOptions(options) {
       extractor: rawCostTracking.extractor ?? defaultExtractor,
       budget: rawCostTracking.budget,
     },
+    thrashDetection: resolveThrashConfig(opts.thrashDetection),
   };
 }

package/src/index.d.ts

@@ -1,6 +1,7 @@
 import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { CostTrackingOptions } from './cost/types.d.ts';
+import type { ThrashConfig, ThrashSummary } from './thrash/types.d.ts';
 
 /**
  * Options for {@link instrumentMcpServer}.
@@ -68,6 +69,35 @@ export interface InstrumentOptions {
    * `{ enabled: false }` alone works. See {@link CostTrackingOptions} (`src/cost/types.d.ts`).
    */
   costTracking?: CostTrackingOptions;
+
+  /**
+   * Set to `false` to disable deep-failure fingerprinting. When enabled (the default), every thrown error
+   * and tool-level failure (`isError: true`) is run through `computeFingerprint()`
+   * (`src/fingerprint/compose.js`), adding `mcp.failure.*` span attributes and an `mcp.failure.category`
+   * attribute on the `mcp.tool.errors` / `mcp.tool.silent_failures` / `mcp.tool.duration` metrics.
+   * `computeFingerprint()` never throws, so this only trades a small amount of per-failure CPU for
+   * fingerprinting.
+   *
+   * `thrashDetection` (below) depends on this: it keys off the same `mcp.failure.fingerprint`
+   * fingerprinting computes, so with `fingerprinting: false` thrash detection silently never fires,
+   * regardless of `thrashDetection`'s own settings.
+   *
+   * @default true
+   */
+  fingerprinting?: boolean;
+
+  /**
+   * Controls Agent Thrash Detection (v0.6.0): detecting when a tool is retried repeatedly with the same
+   * failure fingerprint, and attributing the wasted tokens/cost to that loop (the 5 `mcp.tool.loop.*`
+   * metrics plus one `mcp.loop.detected` span event — see the README's "Agent Thrash Detection" section).
+   * Any fields you omit from a partial object fall back to their defaults individually, same as
+   * `costTracking` above. Requires `fingerprinting` to also be enabled (the default) — see that option's
+   * doc. See {@link ThrashConfig} (`src/thrash/types.d.ts`) for the full field list and defaults,
+   * including `assumeSingleSession`, which you should read carefully before enabling on any transport
+   * that might serve more than one client: getting it wrong merges unrelated clients' failures into
+   * false-positive loops.
+   */
+  thrashDetection?: Partial<ThrashConfig>;
 }
 
 /**
@@ -111,12 +141,22 @@ export type DuckTypedMcpServer = {
  *   created for it — call it during your process's own shutdown sequence to
  *   avoid losing buffered spans. `shutdown` is typed as optional because it
  *   is only attached at runtime when `setupNodeSdk` is `true`; check for its
- *   presence before calling.
+ *   presence before calling. The returned object also gets a
+ *   `getThrashSummary()` method (v0.6.0) returning a point-in-time,
+ *   in-process {@link ThrashSummary} — no OTel involved, nothing sent
+ *   anywhere; see the README's "Agent Thrash Detection" section. Unlike
+ *   `shutdown`, it's attached unconditionally (not gated behind
+ *   `setupNodeSdk`) — still typed as optional because it, like `shutdown`,
+ *   is never attached when `options.enabled` is `false` (nothing is
+ *   instrumented at all in that case).
  */
 export function instrumentMcpServer<T extends Server | McpServer | DuckTypedMcpServer>(
   server: T,
   options?: InstrumentOptions,
-): T & { shutdown?: () => Promise<void> };
+): T & {
+  shutdown?: () => Promise<void>;
+  getThrashSummary?: (options?: { topOffendersLimit?: number }) => ThrashSummary;
+};
 
 // --- Deep-failure fingerprinting (src/fingerprint/) ---
 //
@@ -129,6 +169,9 @@ export type {
   FailureOrigin,
   FingerprintResult,
   FingerprintInputs,
+  FingerprintContext,
+  Classifier,
+  ComputeFingerprintOptions,
 } from './fingerprint/types.d.ts';
 
 export { computeFingerprint } from './fingerprint/compose.js';
@@ -152,3 +195,14 @@ export type {
 export { DEFAULT_PRICING } from './cost/pricing.js';
 export { defaultExtractor } from './cost/extractor.js';
 export { calculateCost } from './cost/calculator.js';
+
+// --- Agent Thrash Detection (src/thrash/) ---
+//
+// Re-exported here so TypeScript consumers get these types from the
+// package root instead of reaching into src/thrash/* directly. See
+// src/thrash/types.d.ts for the full shape documentation. Unlike
+// src/cost/ and src/fingerprint/ above, no runtime values are re-exported
+// here yet — ThrashDetector and createThrashEmitter are internal to
+// instrument.js's wiring, not part of the public API.
+
+export type { ThrashConfig, ThrashDetectedEvent, ThrashSummary, ThrashOffender } from './thrash/types.d.ts';