opentel-mcp 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,158 @@
 # Changelog
 
+## 0.7.0
+
+Origin-aware failure classification for Agent Thrash Detection. Prompted by
+external review (Reddit) pointing out that failure detection only read the
+`isError` channel, missing JSON-RPC protocol-level failures. Verifying that
+report surfaced a separate, more consequential finding: a real false
+positive already live in every published version — output-validation
+failures (a server-side bug) being counted as agent thrash. Full
+investigation and design: ADR 007 (`docs/adr/007-protocol-error-channel.md`).
+
+Also investigates a second external report (u/Pleasant-Ad192): whether a
+different schema field failing validation each attempt (an agent
+converging) can be told apart from the same field failing repeatedly (an
+ambiguous tool schema). Finding: it mostly already can be, as a side
+effect of how failures are fingerprinted — see ADR 009
+(`docs/adr/009-field-level-convergence.md`) — now pinned down by
+regression tests and a diagnostic span attribute, with one real gap
+(partial convergence) still open pending a design decision.
+
+Known gaps and open questions this release didn't close: `docs/known-gaps.md`.
+
+### Fixed
+
+- **Output-validation failures were miscategorized and incorrectly counted
+  toward Agent Thrash Detection.** When a tool's own handler returned output
+  that didn't match its declared output schema, the resulting failure
+  (surfaced as `isError: true`, whether thrown directly or converted by the
+  high-level `McpServer`) landed in fingerprint category `validation` or
+  `internal` depending on the exact wording, and — since Agent Thrash
+  Detection shipped in v0.6.0 — was tracked exactly like a normal
+  business-logic failure. An agent retrying such a tool would eventually
+  cross the default threshold and get flagged as "thrashing," even though
+  the failure is entirely the tool author's bug: no argument the agent
+  supplies can ever fix a server that never returns valid structured
+  content. **Affected range: the miscategorization itself has been present
+  since v0.4.0 (deep-failure fingerprinting); the false-positive thrash
+  count has been present since v0.6.0 (Agent Thrash Detection), through the
+  last published release, v0.6.1.** Fixed by classifying which *channel* a
+  failure arrived on (see Added, below) and excluding the `protocol.output`
+  channel from thrash detection entirely — not merely relabeling it.
+
+### Added
+
+- **`mcp.failure.channel` span attribute** — one of `execution` |
+  `protocol.not_found` | `protocol.input` | `protocol.output` |
+  `protocol.other` | `unknown`, classifying which channel a tools/call
+  failure arrived on (`classifyFailureChannel()`,
+  `src/fingerprint/classify/channel.js`). Additive: never part of
+  `computeFingerprint()`'s hash input (see Unchanged, below) — deliberately
+  a separate attribute from the pre-existing `mcp.failure.origin`, which
+  means something different (`tool_error` \| `thrown` \| `transport`) and
+  has been hashed since v0.4.0.
+- **Per-channel Agent Thrash Detection thresholds**: `inputThreshold`
+  (default `5`, higher than the base `threshold`) for the `protocol.input`
+  channel — an agent retrying with different arguments after an
+  input-validation failure may be genuinely converging, not thrashing —
+  and `notFoundThreshold` (default `1`, an immediate flag) for
+  `protocol.not_found` — retrying a tool name that doesn't exist is never
+  convergence. Each independently overridable via its own env var
+  (`OTEL_MCP_THRASH_INPUT_THRESHOLD` / `OTEL_MCP_THRASH_NOT_FOUND_THRESHOLD`),
+  following the exact existing `OTEL_MCP_THRASH_*` pattern.
+- `FailureChannel` type, exported from the package root alongside the
+  existing `FailureCategory` / `FailureOrigin` types.
+- For high-level `McpServer` users specifically: since `McpServer` converts
+  most protocol-shaped failures (tool not found, disabled, input/output
+  validation) to `isError: true` before this library ever sees a thrown
+  error, `classifyFailureChannel()` also recovers the real channel from
+  that disguised form by reading the `MCP error {code}: ` wrapper
+  `McpError`'s constructor always applies, which `McpServer` preserves
+  verbatim. Without this, `protocol.output`'s exclusion (the fix above)
+  would only have applied to hand-rolled low-level `Server` apps, not to
+  `McpServer` — see the README's "Agent Thrash Detection" section and ADR
+  007's addendum for the full reachability picture and its limits.
+- **`mcp.failure.validation_paths` span attribute** — which schema
+  field(s) a Zod validation failure named, one dot-joined path per
+  failing issue (e.g. `["email", "user.profile.age"]`), best-effort
+  extracted from the same message text `classifyFailureChannel()` already
+  reads (`extractValidationPaths()`,
+  `src/fingerprint/classify/validation-paths.js`). Omitted entirely —
+  never set to an empty array — when nothing confidently parseable was
+  found. Span-only, permanently excluded from
+  `METRIC_SAFE_ATTRIBUTES`: field/path names are bounded per tool but
+  unbounded across every tool anyone registers, the same reasoning that
+  already keeps `mcp.failure.fingerprint`/`signature`/`error_class` off
+  metric labels. Full investigation and design: ADR 009
+  (`docs/adr/009-field-level-convergence.md`).
+
+### Unchanged
+
+- **Fingerprints (`mcp.failure.fingerprint` and every other
+  `FingerprintInputs` field) are byte-identical to v0.6.1 for the same
+  inputs.** The new `channel` dimension is deliberately kept out of
+  `computeFingerprint()`'s hash input (ADR 007) specifically so this
+  release cannot change any consumer's existing `mcp.failure.fingerprint`
+  values — a change there would silently break any alert or dashboard
+  built on fingerprint identity. Verified, not just asserted: by extracting
+  the actual, published `v0.6.1` git tag's `src/fingerprint/` tree via `git
+  archive` into an isolated directory and running its `computeFingerprint()`
+  directly, independent of this working tree, against six fixture inputs —
+  see `test/fingerprint/compose.fixtures.test.js`. If you have alerts or
+  dashboards keyed on `mcp.failure.fingerprint`, they keep working exactly
+  as they did on v0.6.1, with no changes required on your end.
+- **Field-level discrimination in Agent Thrash Detection is not a new
+  capability — it already worked, as a side effect of fingerprinting the
+  full Zod issues JSON, and was simply incidental until now.** A
+  validation failure repeating on the *same* schema field across attempts
+  already hashed to the *same* fingerprint (accumulating correctly toward
+  `inputThreshold`), and a *different* field failing each attempt already
+  hashed to a *different* fingerprint each time (never accumulating,
+  matching a converging agent). Investigated and confirmed in ADR 009; now
+  pinned down by regression tests
+  (`test/fingerprint/field-level-convergence.test.js`) so a future Zod or
+  SDK change that silently breaks it gets caught, rather than discovered
+  as a production regression. One real gap remains open and is *not*
+  fixed by this: partial convergence (fixing one of several failing
+  fields changes the issues array's shape and breaks fingerprint
+  continuity) — tracked in `docs/known-gaps.md`, pending a design ADR 009
+  did not settle on.
+
+### Documentation
+
+- `docs/known-gaps.md` (new): five tracked gaps this release didn't close,
+  each written as a ready-to-paste GitHub issue — field-level convergence
+  tracking, partial convergence in field-level validation, the
+  observation-liveness contract, the pre-handler parse-failure gap, and
+  how client-side retry caps interact with
+  detection thresholds.
+- README's "Agent Thrash Detection" section now covers channel-aware
+  thresholds, the `McpServer`-vs-low-level-`Server` reachability
+  difference (with ADR 007's full table), the pre-handler parse-failure
+  gap (deferred, not solved — closing it means revisiting ADR 001), and
+  the forwarded-error collision risk as a named known limitation.
+- README's "Failure Fingerprinting" section now documents
+  `mcp.failure.validation_paths` and states plainly that field-level
+  discrimination is a property of the fingerprint, not a separate
+  detector — see ADR 009.
+
+## 0.6.1
+
+### Fixed
+
+- `src/index.d.ts` re-exported values (`computeFingerprint`,
+  `toSpanAttributes`, `ATTRIBUTE_KEYS`, `METRIC_SAFE_ATTRIBUTES`,
+  `DEFAULT_CLASSIFIERS`, `DEFAULT_PRICING`, `defaultExtractor`,
+  `calculateCost`) from six `.js` modules that had no corresponding `.d.ts`
+  file, so any consumer with `strict`/`noImplicitAny` got a TS7016 error
+  just from importing the package. Added `src/fingerprint/compose.d.ts`,
+  `src/fingerprint/attributes.d.ts`, `src/fingerprint/classify/index.d.ts`,
+  `src/cost/pricing.d.ts`, `src/cost/extractor.d.ts`, and
+  `src/cost/calculator.d.ts`. Pre-existing since v0.4.0 (fingerprinting) and
+  v0.5.0 (cost tracking) — first caught verifying the v0.6.0 published
+  tarball.
+
 ## 0.6.0
 
 ### Added — Agent Thrash Detection

package/README.md

@@ -254,6 +254,8 @@ in `docs/adr/`.
 | mcp.failure.category | One of 8 categories (below) | "timeout" |
 | mcp.failure.origin | `tool_error` \| `thrown` \| `transport` | "thrown" |
 | mcp.failure.error_class | Error class / constructor name | "TypeError" |
+| mcp.failure.channel | `execution` \| `protocol.not_found` \| `protocol.input` \| `protocol.output` \| `protocol.other` \| `unknown` — see "Agent Thrash Detection" below | "protocol.input" |
+| mcp.failure.validation_paths | Which schema field(s) a Zod validation failure named, one dot-joined path per failing issue — omitted entirely when nothing parseable was found (ADR 009) | `["email", "user.profile.age"]` |
 
 Source of truth: `src/fingerprint/attributes.js`. Every category:
 
@@ -278,7 +280,26 @@ reach a fingerprint-derived value through
 `origin` (24 combinations max). There is no code path today that could
 accidentally attach `fingerprint`, `signature`, or `error_class` to a
 counter or histogram label. See `src/fingerprint/attributes.js` and ADR
-006's "Consequences" section.
+006's "Consequences" section. `mcp.failure.validation_paths` above is
+held to the exact same rule and for the exact same reason — field/path
+names are bounded per tool but unbounded across every tool anyone
+registers, so it is permanently excluded from `METRIC_SAFE_ATTRIBUTES`,
+span-only, no exceptions (ADR 009).
+
+**Field-level discrimination is a property of the fingerprint, not a
+separate detector.** Two validation failures on the *same* schema field
+normalize to the same message and hash to the *same* fingerprint, even
+across different invalid values tried; a failure on a *different* field
+normalizes differently and hashes to a *different* fingerprint. This
+already falls out of hashing the full Zod issues JSON (which embeds each
+failing field's path) — it is not a dedicated field-convergence detector,
+and `mcp.failure.validation_paths` doesn't change this behavior, it just
+makes it queryable instead of implicit in an opaque hash. See ADR 009
+(`docs/adr/009-field-level-convergence.md`) for the full investigation,
+including the one gap this doesn't cover: fixing one of several failing
+fields changes the issues array's shape, which changes the fingerprint
+even though another field is still failing underneath — tracked in
+`docs/known-gaps.md`, not solved here.
 
 **Extending it:** `computeFingerprint(err, ctx, opts)`
 (`src/fingerprint/compose.js`) accepts `opts.classifiers` to prepend your
@@ -420,7 +441,7 @@ 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)
+## 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
@@ -448,6 +469,104 @@ fingerprint inside 60 seconds gets flagged automatically. **Requires
 disabled, thrash detection silently never fires, regardless of
 `thrashDetection`'s own settings.
 
+### Channel-aware thresholds (v0.7.0)
+
+Not every repeated failure means the same thing. `mcp.failure.channel`
+(see "Span attributes" above) classifies *where* a tools/call failure
+actually came from, and thrash detection uses that classification to pick
+a different threshold per channel instead of treating every repeat
+identically:
+
+| `mcp.failure.channel` | What it means | Threshold |
+|---|---|---|
+| `execution` | The call reached the tool and the tool itself reports a business-logic failure (`isError: true`). Retrying an unchanged upstream failure identically **is** thrash. | `threshold` (default 3) — unchanged from v0.6.0 |
+| `protocol.input` | A JSON-RPC `InvalidParams` (-32602) whose message indicates the *agent* supplied bad arguments. An agent retrying with adjusted arguments may be genuinely converging on a correct call, not thrashing. | `inputThreshold` (default 5) — higher |
+| `protocol.not_found` | `MethodNotFound` (-32601), or `InvalidParams` indicating an unknown/disabled tool. Retrying a tool name that doesn't exist is never convergence — there's no "getting closer" to a tool that isn't there. | `notFoundThreshold` (default 1) — an immediate flag |
+| `protocol.output` | An `InvalidParams` (-32602) whose message indicates the **tool's own output** failed its declared output schema. This is the server author's bug — no argument the agent supplies can ever fix it. | **Excluded from thrash detection entirely.** Never counted, no matter how many times it repeats. |
+| `protocol.other` | Any other JSON-RPC error code, or an unrecognized `-32602` message shape. | `threshold` (same as `execution`) |
+| `unknown` | The failure doesn't confidently resemble either the execution or protocol shape. | `threshold` (same as `execution`) |
+
+**This closes a real false positive present in every published version
+through v0.6.1**: an output-validation bug — entirely the tool author's
+fault — that an agent naively retried was being counted as agent thrash
+before this release, because nothing distinguished it from an ordinary
+repeated business-logic failure. It no longer is. Full investigation and
+design rationale: ADR 007 (`docs/adr/007-protocol-error-channel.md`).
+
+Configure the two new thresholds the same way as every other
+`thrashDetection` field — see "Configuration" below.
+
+### Reachability: high-level `McpServer` vs. low-level `Server`
+
+**Read this before assuming `mcp.failure.channel` gives you full protocol
+visibility on every server.** How much of the table above you actually
+see depends on which server API you instrument, and the honest picture is
+more limited than "protocol errors are now detected everywhere":
+
+The high-level `McpServer` (`.tool()`/`.registerTool()` — the ergonomic,
+documented API most real MCP servers use) already catches nearly every
+protocol-shaped failure itself and converts it to `isError: true` *before*
+this library ever sees a thrown error — tool not found, tool disabled,
+input validation, output validation, or any other bug in a handler, all
+land as `isError: true`, with the sole exception of one narrow
+elicitation-flow error type. That means most of what `mcp.failure.channel`
+reveals for `McpServer` users was **already visible via `isError`** before
+this release — this feature isn't adding protocol-error detection where
+none existed; it's adding *sub-classification* on top of detection that,
+for the most part, already existed.
+
+| `mcp.failure.channel` value | High-level `McpServer` | Low-level `Server` (hand-rolled dispatcher) |
+|---|---|---|
+| `execution` | Reachable — and the *only* value most failures produced before this release (see below) | Reachable when the handler returns `{isError:true}` itself |
+| `protocol.not_found` | Not reachable via a raw thrown error (`McpServer` swallows it) — reachable only via the recovery mechanism below | Reachable directly |
+| `protocol.input` | Same — recovery-only | Reachable directly |
+| `protocol.output` | Same — recovery-only | Reachable directly |
+| `protocol.other` | Reachable via a raw thrown error only for one narrow elicitation-flow error code; not a general catch-all for `McpServer` | Reachable for any other code, or an unrecognized `-32602` message |
+| `unknown` | Effectively not reachable via a raw thrown error — `McpServer`'s catch swallows *any* error, not just protocol-shaped ones | Reachable for a thrown value with no error code at all |
+
+For the low-level `Server`, all six values are directly reachable, since
+nothing intercepts a thrown error before this library's own span/thrash
+wrapping runs — this attribute's richest, most direct value is for
+low-level `Server` users.
+
+For `McpServer` users, closing the false positive above (the point of
+this release) required a **recovery step**: `McpServer` preserves the
+original error's message verbatim when it converts a thrown error to
+`isError: true`, including the exact `MCP error {code}: ` wrapper its
+error class's constructor always adds. `classifyFailureChannel()` reads
+that wrapper back out of the disguised `isError: true` result and
+recovers the real channel from it, falling back to `execution` only when
+the message doesn't match that shape (i.e. it's a genuine, tool-authored
+business message, not a disguised protocol failure). This is what makes
+`protocol.output`'s exclusion actually work for `McpServer` users too —
+without it, the false positive this release fixes would only have been
+fixed for hand-rolled low-level `Server` apps.
+
+**This recovery step is inherently fragile**, coupled to matching the
+exact prose the installed SDK version happens to use — both the `MCP
+error {code}: ` wrapper and the `-32602` sub-case message markers
+(`"Input validation error:"`, `"Output validation error:"`, and the
+looser `"not found"`/`"disabled"` substring matches). If the SDK changes
+either format, the classifier degrades safely to `execution` (never a
+thrown error, never a wrong specific answer) rather than breaking — but a
+future SDK version could silently reopen part of the gap this release
+closes. See ADR 007's addendum for the full verification, including how
+this was confirmed against a real `McpServer` and a real Zod output
+schema before being fixed.
+
+**Known limitation — a forwarded/proxied error can collide with this
+recovery.** A tool that forwards another MCP call's error text verbatim
+(an orchestrator or proxy tool surfacing a downstream failure) could
+plausibly produce a message starting with the same `MCP error {code}: `
+wrapper, purely by coincidence of forwarding real McpError text. For most
+codes this is cosmetic (`protocol.other` shares `execution`'s threshold).
+The sharp case: a forwarded output-validation-shaped message would be
+**excluded from thrash detection entirely**, even though it may be a
+genuine, repeatable failure from the forwarding tool's own perspective —
+a false negative, not a false positive. Assessed as an acceptable,
+narrow risk for this release (see ADR 007's addendum for the full
+reasoning); revisit if this pattern turns out to be common in practice.
+
 ### Metrics
 
 Same API-only pattern as every other metric in this README — nothing
@@ -504,6 +623,22 @@ silently, never throws. Source of truth: `src/thrash/config.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 |
+| `inputThreshold` | `OTEL_MCP_THRASH_INPUT_THRESHOLD` | number | `5` | Per-origin threshold (ADR 007) for `mcp.failure.channel: protocol.input` — higher than `threshold`, since an agent retrying with adjusted arguments may be converging |
+| `notFoundThreshold` | `OTEL_MCP_THRASH_NOT_FOUND_THRESHOLD` | number | `1` | Per-origin threshold (ADR 007) for `mcp.failure.channel: protocol.not_found` — lower than `threshold`; retrying a nonexistent tool is never convergence |
+
+**A note on defaults and client-side retry caps.** Every threshold above
+assumes an effectively uncapped agent — one that keeps retrying an
+identically-failing call at least as many times as the threshold. Some
+agent frameworks impose their own client-side cap on same-arguments
+retries (e.g. giving up and reporting failure after 2 identical
+attempts). If an agent's own cap is lower than the relevant threshold
+(the default `threshold` is 3), that agent's thrashing never crosses the
+threshold and `mcp.tool.loop.detected` never fires for it — arguably
+correct in isolation (2 identical failures is a weaker signal than 3),
+but worth knowing before assuming detection is silently catching
+everything. If you know your agent framework caps retries at N, consider
+setting the relevant threshold to N. Tracked as an open question, not
+solved here: `docs/known-gaps.md`.
 
 ### Session id resolution — read this before setting `assumeSingleSession`
 
@@ -592,6 +727,32 @@ 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.
 
+### Known limitations
+
+**A malformed `tools/call` request produces zero telemetry — no span, no
+fingerprint, nothing.** If a request fails `CallToolRequestSchema`
+validation itself (e.g. a missing or wrongly-typed `name`/`arguments`
+field), the SDK's own request-parsing step throws *before*
+`instrumentMcpServer()`'s wrapped handler is ever invoked — there's no
+span to attach a status to and no error object reaches
+`computeFingerprint()`. This is invisible by construction: closing it
+means wrapping a layer above where this library currently patches
+(`setRequestHandler`'s `handler` argument), which is exactly the larger,
+less stable dependency surface ADR 001 chose not to depend on. **Deferred,
+not solved** — tracked in `docs/known-gaps.md`, and would need its own
+design pass (effectively revisiting ADR 001) rather than a patch-level
+fix.
+
+See `docs/known-gaps.md` for this gap in full, plus four more not fully
+covered by this release: field-level convergence tracking for
+`protocol.input` (distinguishing "ambiguous tool schema" from "agent is
+converging" — mostly already works as a side effect of fingerprinting,
+see "Failure Fingerprinting" above and ADR 009, but partial convergence
+within that is its own separate, still-open entry), an
+observation-liveness contract for `getThrashSummary()` (so "nothing
+failed" and "nothing is being observed at all" stop looking identical),
+and how client-side agent retry caps interact with the thresholds above.
+
 ### Benchmarks
 
 Two kinds, both under `bench/` and `test/thrash/`:
@@ -712,7 +873,7 @@ 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
-- 369 tests (`npm test`) — see `test/`
+- 498 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
 
@@ -722,6 +883,17 @@ pragmatic choice rather than a spec-pure one.
   and ADR 006.
 - v0.5: Cost & Token Attribution ✓ — see "Cost & Token Attribution" above.
 - v0.6: Agent Thrash Detection ✓ — see "Agent Thrash Detection" above.
+- v0.7: Channel-aware thrash detection ✓ — fixes a real false positive
+  (output-validation failures counted as thrash) present since v0.6.0; adds
+  `mcp.failure.channel` and per-channel thresholds. See "Agent Thrash
+  Detection" above and ADR 007. Also confirms (ADR 009) that field-level
+  discrimination for `protocol.input` failures already worked as a side
+  effect of fingerprinting — now regression-tested and surfaced via
+  `mcp.failure.validation_paths` (see "Failure Fingerprinting" above). Five
+  gaps this release didn't fully close — field-level convergence tracking,
+  partial convergence within it, an observation-liveness contract, the
+  pre-handler parse-failure gap, and client-side retry caps — are tracked
+  in `docs/known-gaps.md`, not silently dropped.
 - 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.6.0",
+  "version": "0.7.0",
   "description": "One-line OpenTelemetry instrumentation for Model Context Protocol (MCP) servers",
   "type": "module",
   "main": "src/index.js",
@@ -25,9 +25,11 @@
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "typecheck": "tsc --noEmit",
+    "verify:tarball": "node scripts/verify-tarball.js",
     "bench": "vitest bench --run",
     "prepack": "node scripts/strip-workspaces.js",
-    "postpack": "node scripts/restore-workspaces.js"
+    "postpack": "node scripts/restore-workspaces.js",
+    "prepublishOnly": "npm run verify:tarball"
   },
   "keywords": [
     "mcp",
@@ -64,6 +66,7 @@
     "@opentelemetry/sdk-trace-base": "^2.9.0",
     "@vitest/coverage-v8": "^2.1.9",
     "typescript": "^7.0.2",
-    "vitest": "^2.1.8"
+    "vitest": "^2.1.8",
+    "zod": "^4.4.3"
   }
 }

package/src/cost/calculator.d.ts

@@ -0,0 +1,13 @@
+import type { PricingTable } from './types.d.ts';
+
+/**
+ * Calculates the USD cost of a request from its input/output token counts, a
+ * model name, and a pricing table. Never throws: an unrecognized model or an
+ * invalid token count resolves to `null` rather than an exception.
+ */
+export function calculateCost(
+  inputTokens: number,
+  outputTokens: number,
+  model: string,
+  pricingTable: PricingTable,
+): number | null;

package/src/cost/extractor.d.ts

@@ -0,0 +1,8 @@
+import type { UsageExtractor } from './types.d.ts';
+
+/**
+ * Default {@link UsageExtractor}. Recognizes Anthropic/OpenAI/Bedrock usage
+ * field conventions, JSON-in-text content, and the MCP `_meta.usage`
+ * extension point. Never throws — returns `null` for any unrecognized shape.
+ */
+export const defaultExtractor: UsageExtractor;

package/src/cost/pricing.d.ts

@@ -0,0 +1,8 @@
+import type { PricingTable } from './types.d.ts';
+
+/**
+ * Static per-model token pricing used to estimate MCP tool-call cost, in USD
+ * per 1M tokens. A best-effort snapshot — callers who need accurate cost
+ * attribution should supply their own {@link PricingTable}.
+ */
+export const DEFAULT_PRICING: PricingTable;

package/src/fingerprint/attributes.d.ts

@@ -0,0 +1,20 @@
+import type { Attributes } from '@opentelemetry/api';
+import type { FingerprintResult } from './types.d.ts';
+
+/** The `mcp.failure.*` OpenTelemetry span attribute keys. */
+export const ATTRIBUTE_KEYS: Readonly<
+  Record<'FINGERPRINT' | 'SIGNATURE' | 'CATEGORY' | 'ORIGIN' | 'ERROR_CLASS' | 'CHANNEL' | 'VALIDATION_PATHS', string>
+>;
+
+/**
+ * Attribute keys safe to attach to metric labels — `category` and `origin`
+ * only; everything else in {@link ATTRIBUTE_KEYS} is unbounded or
+ * medium-cardinality and must stay span-only.
+ */
+export const METRIC_SAFE_ATTRIBUTES: readonly string[];
+
+/**
+ * Builds the span attributes for a fingerprinted failure. Never throws —
+ * returns `{}` if `result` is malformed in any way.
+ */
+export function toSpanAttributes(result: FingerprintResult): Attributes;

package/src/fingerprint/attributes.js

@@ -15,13 +15,35 @@
 /** @typedef {import('@opentelemetry/api').Attributes} Attributes */
 /** @typedef {import('./types.d.ts').FingerprintResult} FingerprintResult */
 
-/** @type {Readonly<Record<'FINGERPRINT' | 'SIGNATURE' | 'CATEGORY' | 'ORIGIN' | 'ERROR_CLASS', string>>} */
+/** @type {Readonly<Record<'FINGERPRINT' | 'SIGNATURE' | 'CATEGORY' | 'ORIGIN' | 'ERROR_CLASS' | 'CHANNEL' | 'VALIDATION_PATHS', string>>} */
 export const ATTRIBUTE_KEYS = Object.freeze({
   FINGERPRINT: 'mcp.failure.fingerprint',
   SIGNATURE: 'mcp.failure.signature',
   CATEGORY: 'mcp.failure.category',
   ORIGIN: 'mcp.failure.origin',
   ERROR_CLASS: 'mcp.failure.error_class',
+  /**
+   * ADR 007's channel dimension (`classifyFailureChannel()`,
+   * `fingerprint/classify/channel.js`): 'execution' | 'protocol.not_found'
+   * | 'protocol.input' | 'protocol.output' | 'protocol.other' | 'unknown'.
+   * Deliberately a DIFFERENT attribute from ORIGIN above — ORIGIN already
+   * carries FingerprintInputs' `origin` ('tool_error' | 'thrown' |
+   * 'transport'), hashed into the fingerprint since v0.4.0. CHANNEL is
+   * additive, set independently of computeFingerprint(), and never part
+   * of the hash — see ADR 007's "Where the new dimension lives".
+   */
+  CHANNEL: 'mcp.failure.channel',
+  /**
+   * ADR 009's diagnostic attribute (`extractValidationPaths()`,
+   * `fingerprint/classify/validation-paths.js`): one dot-joined path per
+   * failing Zod issue found in the message (e.g. `["email"]` or
+   * `["user.profile.age", "status"]`), best-effort and omitted entirely
+   * when nothing parseable was found — never an empty array. Like
+   * CHANNEL, additive and never part of the fingerprint hash: the path
+   * text is already implicit in the hashed normalized message (see ADR
+   * 009), so hashing it again would be redundant, not more correct.
+   */
+  VALIDATION_PATHS: 'mcp.failure.validation_paths',
 });
 
 /**
@@ -29,6 +51,21 @@ export const ATTRIBUTE_KEYS = Object.freeze({
  * {@link ATTRIBUTE_KEYS} is unbounded or medium-cardinality and must stay
  * span-only.
  *
+ * CHANNEL is deliberately NOT included here yet: ADR 007 doesn't decide
+ * metric-label safety for it one way or the other (it's silent on this
+ * file entirely), and per the Phase 2 instructions this omission should
+ * default to span-only rather than inventing a decision the ADR didn't
+ * make. It's a small closed set (6 values) and would likely qualify on
+ * cardinality grounds alone — revisit explicitly, in the ADR, before
+ * adding it here.
+ *
+ * VALIDATION_PATHS is explicitly, permanently excluded — this one IS
+ * decided, not merely deferred (ADR 009): field/path names are bounded
+ * per tool but unbounded across every tool anyone ever registers, and
+ * unbounded again across every deployment a shared metrics backend might
+ * aggregate — the exact same reasoning that already keeps FINGERPRINT/
+ * SIGNATURE/ERROR_CLASS off this list.
+ *
  * @type {readonly string[]}
  */
 export const METRIC_SAFE_ATTRIBUTES = Object.freeze([ATTRIBUTE_KEYS.CATEGORY, ATTRIBUTE_KEYS.ORIGIN]);

package/src/fingerprint/classify/channel.d.ts

@@ -0,0 +1,9 @@
+import type { FailureChannel } from '../types.d.ts';
+
+/**
+ * Determines which channel an MCP tools/call failure arrived on. Never
+ * throws — see `src/fingerprint/classify/channel.js`'s docblock for the
+ * full behavior, including recovery of a protocol failure McpServer has
+ * disguised as `isError: true`.
+ */
+export function classifyFailureChannel(failure: unknown): FailureChannel;