opentel-mcp 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,135 @@
 # Changelog
 
+## 0.12.0
+
+Agent Thrash Detection gains a new, narrower session-identity fallback for
+calls that carry no real session id but do carry a client-propagated W3C
+trace context. This release also fixes two real bugs in the tail-sampling
+recipe v0.8.0 introduced, and adds visibility for a silent budget-tracking
+gap found during that same investigation. Full design for the fallback
+tier: ADR 018 (`docs/adr/018-trace-id-as-thrash-fallback.md`).
+
+### Added — trace id as a thrash-detection session-id fallback (ADR 018)
+
+- **New tier in `resolveThrashSessionId()`** (`src/instrument.js`), reached
+  only when no real session id has ever been observed on this server, and
+  evaluated before the existing generated-UUID/skip fallback: if a
+  `tools/call` request's span has a validly-extracted REMOTE parent — i.e.
+  `request.params._meta` carried a valid W3C `traceparent` that
+  `extractTraceContext()` (ADR 017) turned into a remote `SpanContext` —
+  that parent's trace id is used as the session-id candidate for
+  thrash-detection grouping. Gated on
+  `trace.getSpanContext(parentContext)?.isRemote === true`, never on a
+  span's own `traceId` read unconditionally — a root span's trace id is
+  freshly, randomly generated on every call, and reading it unconditionally
+  would have silently turned today's honest "skip, undetermined" into
+  "always produce a session id that never matches the previous call's,"
+  which is worse than skipping. See the ADR's "THE TRAP" for the full
+  argument.
+- Real `extra.sessionId` still wins unconditionally in every case
+  (steps 1–2 of the resolution order untouched, byte for byte) — a trace
+  id is only ever consulted for a call that has no real session id at all.
+- Does **not** set `thrashSessionState.hasSeenRealSessionId` — that flag
+  means "this transport hands out real session identity," a permanent
+  per-server fact; a trace id being present on one call is a per-call fact
+  about that one client's behavior, not proof about the transport.
+- No new `diag.warn()` for this tier, deliberately — unlike the
+  generated-UUID fallback (which warns because it's this library guessing
+  an unproven assumption about transport topology), a trace-id candidate
+  is real, client-supplied data with no operator action item to flag, and
+  warning on every occurrence — potentially far more often than the
+  once-per-server UUID warning — would just train operators to ignore this
+  library's warnings generally.
+- No changes to `ThrashDetector`/`thrash/detector.js` — its composite key
+  already treats `sessionId` as opaque.
+
+  **Read the constraint before assuming this closes stateless MCP's
+  session gap.** This tier only fires when the calling *client* chooses to
+  propagate trace context into `_meta.traceparent` — today, per ADR 018's
+  investigation, that means third-party OTel instrumentation
+  (`@arizeai/openinference-instrumentation-mcp` and equivalents) wrapping
+  **v1-based** SDK clients, not either MCP SDK's own built-in behavior, and
+  **no v2-targeting instrumentation was found to exist anywhere**. **This
+  does NOT close `docs/known-gaps.md` entry 6's structural finding** — a
+  v2/2026-07-28-native deployment whose client doesn't propagate
+  `_meta.traceparent` (the default, unconfigured case for essentially
+  every v2 client today) gets nothing new from this release: the exact
+  same `null`/skip behavior as before. See the README's "Session id
+  resolution" section and ADR 018's "Adoption caveat" for the full scope.
+
+### Added — `mcp.tool.schema_drift_detected` span attribute
+
+- New boolean span attribute, set alongside (never instead of) the
+  existing `mcp.tool.schema_drift.detected` span event
+  (`schema-drift/emitter.js`) — the same resolution ADR 011 already
+  applied to thrash detection (`mcp.tool.thrash_detected`) for the
+  identical event-vs-attribute ambiguity: whether a Collector
+  `tailsamplingprocessor`'s `boolean_attribute` policy can match
+  span-*event* data (as opposed to top-level span attributes) could not be
+  confirmed either way (Go source, not installed in this repository). Only
+  ever set to `true`, and only when drift was actually detected — never
+  explicitly set `false`.
+
+### Fixed — tail-sampling recipe referenced a non-existent span attribute
+
+- The README's `tailsamplingprocessor` recipe recommended keying a
+  `boolean_attribute` policy on `mcp.tool.schema_drift.detected` — but
+  that string was only ever a span *event* name and a metric counter name
+  (`schema-drift/attributes.js`), never passed to `span.setAttribute()`
+  anywhere in this package. As documented, that policy could never have
+  matched anything. Fixed by the new `mcp.tool.schema_drift_detected`
+  attribute above.
+- Also added a `string_attribute` policy on `mcp.tool.pricing_status =
+  "unknown"` — v0.11.0's "confidently wrong zero" problem reappearing at
+  the sampling layer: an unpriced call has real extracted token usage but
+  no `mcp.tool.cost.usd`, indistinguishable from a genuinely free call to
+  a numeric-threshold policy.
+- Recipe YAML extracted to `docs/recipes/tail-sampling.yaml` (repo-only,
+  not published — the same carve-out `dashboards/` already has), with a
+  new cross-check test (`test/recipes/tail-sampling-attributes.test.js`)
+  asserting every attribute a policy references is a real, exported
+  constant AND actually passed to `span.setAttribute()` — the check that
+  would have caught this bug automatically. The README now references the
+  file instead of duplicating it, and states plainly that attribute
+  *names* are cross-checked but Collector policy *behavior* itself has not
+  been run end to end (no Docker/Collector available in this project's dev
+  environment).
+- `docs/known-gaps.md` entry 9 (new): an unpriced call never reaches
+  `budgetTracker.recordAndCheck()`, so budget guardrails cannot trip on
+  unpriced spend regardless of amount. The visibility half is fixed in
+  this same release — see "Added" below — but the underlying accounting
+  behavior is not; what should happen to an unpriced call's budget
+  accounting is a real design question, deliberately left open.
+
+### Added — visibility for unpriced spend against a configured budget (known-gaps entry 9)
+
+- **Two new one-time `diag.warn()` diagnostics in `createBudgetTracker()`**
+  (`src/cost/budget.js`), no behavior change and no new public surface:
+  one fires at construction whenever `perSessionUsd`/`perToolUsd` is
+  configured at all, stating plainly that unpriced calls won't count
+  toward it; the other — a new `recordUnpriced(model)` method, called from
+  `applyCostAttribution()`'s existing `costUsd === null` branch
+  (`src/instrument.js`), the same branch that already sets
+  `mcp.tool.pricing_status: "unknown"` — fires the first time an unpriced
+  call under an active budget is actually observed, naming the model and
+  which scope(s) are configured. Both no-op when no budget is configured;
+  neither changes `BudgetCheckResult`'s shape or adds a span attribute.
+- **Deliberately diagnostics only — no fallback pricing was added.**
+  Making an unpriced call actually count toward a USD budget means
+  inventing a number for it, and a wrong invented price is a *different*
+  confidently-wrong number, not a fix — the same disease this warning
+  exists to flag, one layer up. See `docs/known-gaps.md` entry 9's
+  "Status update (v0.12.0)" for the full argument against building that
+  now, and why it stays open as a future, ADR-gated decision rather than
+  folded into this patch.
+- Both warnings share the budget tracker's own existing
+  once-per-tracker-instance granularity (`createBudgetTracker()`'s own
+  docblock) — under the default (no `instanceKey`), a fresh-server-per-request
+  deployment re-warns on every request for both, the same inherited-caveat
+  shape `docs/known-gaps.md` entry 6 documents for the thrash fallback
+  warning; a stable `instanceKey` shares one tracker, and one already-armed
+  warning, across calls, same as every other registry-backed tracker.
+
 ## 0.11.0
 
 **⚠️ Type change, not a runtime behavior change — read this first.**

package/README.md

@@ -658,6 +658,28 @@ region.
   on the span today, so "Fleet-wide fingerprint frequency" below has
   nothing to substitute with for this scope specifically. `perToolUsd` is
   unaffected — it never depended on session id.
+- **A budget only ever sees priced spend — an unpriced call (`mcp.tool.pricing_status:
+  "unknown"`) never reaches it at all, and never counts toward
+  `perSessionUsd`/`perToolUsd`, regardless of how many tokens it burned**
+  (`docs/known-gaps.md` entry 9). v0.12.0 makes this loud instead of
+  silent, but does not close it: setting a `budget` at all fires a one-time
+  `diag.warn()` naming the constraint up front, and the first time an
+  actual unpriced call happens while a budget is active, a second one-time
+  `diag.warn()` names the model and which scope(s) are configured. Both
+  are pure diagnostics — no new span attribute, no change to
+  `mcp.tool.cost.budget_exceeded`'s meaning, and an unpriced call still
+  contributes nothing to the running total. Deliberate: inventing a
+  fallback price for an unpriceable call would trade one confidently-wrong
+  number (silent zero) for a different one (a made-up price) — the exact
+  failure this attribute/warning pair exists to catch, one layer up. If
+  you're seeing either warning, the fix is the same one "Overriding
+  pricing" above already documents: add the model to `costTracking.pricing`.
+  Both warnings inherit the same per-tracker-instance granularity as the
+  budget tracker itself — see the item above and `src/cost/budget.js`'s
+  `createBudgetTracker()` docblock for exactly what that means under a
+  fresh-`Server`-per-request deployment (a stable `instanceKey` shares one
+  tracker, and one already-armed warning, across calls; without one, both
+  warnings re-fire on every request).
 
 ## Agent Thrash Detection (v0.6.0+)
 
@@ -895,8 +917,39 @@ in order:
    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:
+3. **(v0.12.0, ADR 018) Before any real session id has ever been observed,
+   and before the generated-fallback rule below runs**, if this call's
+   span has a validly-extracted REMOTE trace parent — i.e.
+   `request.params._meta` carried a valid W3C `traceparent` (see "Trace
+   Context Propagation" below) that resolved to a remote `SpanContext`,
+   not a freshly-generated root span — that parent's **trace id** is used
+   as the session-id candidate instead. Never reads a span's own `traceId`
+   unconditionally: a root span's trace id is fresh, random, and different
+   on every single call, so using it without confirming it was actually
+   inherited from a real upstream parent would silently turn "skip,
+   undetermined" into "always produce a session id that never matches the
+   previous call's" — quieter and worse than skipping. Does **not** mark
+   the server session-aware (`hasSeenRealSessionId` stays untouched) — a
+   trace id being present on one call is a fact about that one client's
+   behavior, not a proof about the transport itself.
+
+   **⚠️ Read this before assuming it closes the stateless-MCP session gap
+   below.** This only fires when the calling *client* chooses to
+   propagate trace context into `_meta.traceparent` — today, that means
+   third-party OTel instrumentation (e.g.
+   `@arizeai/openinference-instrumentation-mcp`) wrapping **v1-based** SDK
+   clients, not either MCP SDK's own built-in behavior; no
+   v2-targeting instrumentation exists yet. **It does not close
+   `docs/known-gaps.md` entry 6** — a v2/2026-07-28-native deployment
+   whose client doesn't propagate `_meta.traceparent` (the default,
+   unconfigured case for essentially every v2 client today) gets nothing
+   new here: the exact same skip behavior as before. Full investigation,
+   including why one trace is typically one agent turn (not a protocol
+   guarantee) and the residual merge risk this accepts: ADR 018
+   (`docs/adr/018-trace-id-as-thrash-fallback.md`).
+4. **Before any real session id has ever been observed, and no usable
+   trace id was found above**, 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
@@ -1231,6 +1284,25 @@ silently and only the metric still fires.
 | `mcp.tool.schema_drift.removed_fields` | Property names removed — present only when `type` is `field_removed` or `multiple` |
 | `mcp.tool.schema_drift.changed_fields` | Property names whose value changed — present only when `type` is `type_changed` or `multiple` |
 
+**Also sets a boolean span *attribute*, `mcp.tool.schema_drift_detected: true`**,
+on that same span, alongside the event above (v0.12.0, ADR 011 —
+`docs/adr/011-cost-aware-sampling.md`, the same resolution already applied
+to `mcp.tool.thrash_detected` above, for the identical reason). This
+exists for one specific consumer: an OpenTelemetry Collector's
+`tailsamplingprocessor`, whose `boolean_attribute` policy matches
+top-level span attributes — whether such a policy can also match
+span-*event* data was investigated and left genuinely unverified (no Go
+source to check against in this repository), so the attribute exists to
+remove that uncertainty entirely for anyone wiring up schema-drift-aware
+tail sampling. See "Cost-aware trace sampling (a Collector recipe, not a
+library feature)" below. Deliberately a different string from the
+`mcp.tool.schema_drift.detected` span event/metric name above, for the
+same reason `mcp.tool.thrash_detected` doesn't reuse `mcp.tool.loop.detected`'s
+string: the one reader who most needs this name to be unambiguous —
+someone writing a Collector tail-sampling policy — would otherwise see one
+bare string with no way to tell which of the two same-named signals
+they're keying on.
+
 ### Configuration
 
 All fields of `schemaDrift`, each independently overridable by its own
@@ -1493,86 +1565,52 @@ fundamentally bigger, more invasive ask than `instrumentMcpServer(server,
 options)`, and exactly the class of intervention this project has already
 ruled out elsewhere (never override a host's own OpenTelemetry setup).
 
-**What this package does instead: mark, don't decide.** Two of the three
+**What this package does instead: mark, don't decide.** Four of the five
 signals a tail-sampling policy needs already exist as plain span
-attributes with no changes required — `mcp.tool.cost.usd` (see "Cost &
-Token Attribution" above) and `mcp.tool.cost.budget_exceeded` (a
-cumulative budget guardrail, same section). The third,
-`mcp.tool.thrash_detected` — a boolean span attribute set alongside the
-existing `mcp.loop.detected` span event (see "Agent Thrash Detection" →
-"Span event" above) — is the one new addition this release makes,
-specifically so a tail-sampling policy has an unambiguous, attribute-level
-signal to key on. The actual decision — buffer a trace, evaluate a
-policy, keep or drop the whole thing — belongs to the OpenTelemetry
-Collector's `tailsamplingprocessor`, which already does this correctly,
-already handles the hard parts (per-trace span buffering across a wait
-window, multi-service traces, decision policies), and runs where it can
-see every span in a trace regardless of which process produced it —
-something this library, running inside one MCP server process, never can.
+attributes with no changes required — `mcp.tool.cost.usd` and
+`mcp.tool.pricing_status` (see "Cost & Token Attribution" above),
+`mcp.tool.cost.budget_exceeded` (a cumulative budget guardrail, same
+section), and `mcp.tool.thrash_detected` — a boolean span attribute set
+alongside the existing `mcp.loop.detected` span event (see "Agent Thrash
+Detection" → "Span event" above). The fifth, `mcp.tool.schema_drift_detected`
+— a boolean span attribute set alongside the existing
+`mcp.tool.schema_drift.detected` span event (see "Tool schema drift
+detection" → "Span event" above) — is the one new addition this release
+makes, for the identical reason `mcp.tool.thrash_detected` was added in
+the first place: a tail-sampling policy needs an unambiguous,
+attribute-level signal to key on, and a span *event* isn't confirmed
+matchable the same way (see below). The actual decision — buffer a trace,
+evaluate a policy, keep or drop the whole thing — belongs to the
+OpenTelemetry Collector's `tailsamplingprocessor`, which already does this
+correctly, already handles the hard parts (per-trace span buffering
+across a wait window, multi-service traces, decision policies), and runs
+where it can see every span in a trace regardless of which process
+produced it — something this library, running inside one MCP server
+process, never can.
 
 ### A working Collector config
 
-Real, pasteable `tailsamplingprocessor` config — not pseudo-config. Keeps
-any trace containing an expensive call, a budget-exceeded call, or a
-detected thrash loop; everything else gets an ordinary probabilistic
-sample. (Standard OpenTelemetry Collector Contrib syntax — external to
-this repository, so treat field names as this component's own documented
-contract, not something confirmed against code living here.)
-
-```yaml
-receivers:
-  otlp:
-    protocols:
-      grpc:
-      http:
-
-processors:
-  tail_sampling:
-    decision_wait: 10s
-    num_traces: 50000
-    expected_new_traces_per_sec: 10
-    policies:
-      # Keep any trace containing a call that cost more than $0.10.
-      - name: expensive-tool-calls
-        type: numeric_attribute
-        numeric_attribute:
-          key: mcp.tool.cost.usd
-          min_value: 0.10
-
-      # Keep any trace where a configured cost budget was crossed.
-      - name: budget-exceeded-calls
-        type: boolean_attribute
-        boolean_attribute:
-          key: mcp.tool.cost.budget_exceeded
-          value: true
-
-      # Keep any trace containing a detected agent thrash loop.
-      - name: thrash-loops
-        type: boolean_attribute
-        boolean_attribute:
-          key: mcp.tool.thrash_detected
-          value: true
-
-      # Everything else: an ordinary 10% probabilistic sample. Policies
-      # are OR'd together by the processor, so this doesn't reduce
-      # anything the three policies above already decided to keep — it
-      # only adds baseline visibility into the traces none of them matched.
-      - name: baseline-sample
-        type: probabilistic
-        probabilistic:
-          sampling_percentage: 10
-
-exporters:
-  otlp:
-    endpoint: your-backend:4317
-
-service:
-  pipelines:
-    traces:
-      receivers: [otlp]
-      processors: [tail_sampling]
-      exporters: [otlp]
-```
+The full, pasteable `tailsamplingprocessor` config lives in
+[`docs/recipes/tail-sampling.yaml`](../../docs/recipes/tail-sampling.yaml)
+— not duplicated here, so there's exactly one copy to keep in sync with
+this package's actual attribute names. (Standard OpenTelemetry Collector
+Contrib syntax — external to this repository, so treat field names as
+that component's own documented contract, not something confirmed against
+code living here.)
+
+It keeps any trace containing:
+
+| Policy | Type | Keys on | Why |
+|---|---|---|---|
+| `expensive-tool-calls` | `numeric_attribute` | `mcp.tool.cost.usd` ≥ `0.10` | A single call cost more than your threshold |
+| `budget-exceeded-calls` | `boolean_attribute` | `mcp.tool.cost.budget_exceeded` = `true` | A configured cumulative budget was crossed |
+| `thrash-loops` | `boolean_attribute` | `mcp.tool.thrash_detected` = `true` | An agent thrash loop was detected |
+| `schema-drift-events` | `boolean_attribute` | `mcp.tool.schema_drift_detected` = `true` | A tool's `inputSchema` changed between two `tools/list` calls |
+| `unpriced-calls` | `string_attribute` | `mcp.tool.pricing_status` = `"unknown"` | See below — a real, unpriced cost, not a cheap one |
+
+— everything else gets an ordinary 10% probabilistic sample (policies are
+OR'd together, so this doesn't reduce anything the policies above already
+kept; it only adds baseline visibility into what none of them matched).
 
 Point `instrumentMcpServer({ exporterUrl: 'http://localhost:4318/v1/traces' })`
 (or your host's own OTLP exporter configuration) at this Collector's
@@ -1580,12 +1618,55 @@ Point `instrumentMcpServer({ exporterUrl: 'http://localhost:4318/v1/traces' })`
 this policy before anything is exported downstream.
 
 **Adjust `min_value`/`sampling_percentage` to your own cost/volume
-profile** — `0.10` and `10%` above are illustrative starting points, not
-recommendations; `decision_wait`/`num_traces` should scale with your
-actual traffic volume (the Collector's own docs cover sizing these). If
-your schema-drift or two-axis observation signals matter for retention
-too, add `mcp.tool.schema_drift.detected` (boolean_attribute) as another
-OR'd policy the same way.
+profile** — `0.10` and `10%` in the recipe are illustrative starting
+points, not recommendations; `decision_wait`/`num_traces` should scale
+with your actual traffic volume (the Collector's own docs cover sizing
+these).
+
+**Why `unpriced-calls` is in here — the v0.11.0 "confidently wrong zero"
+problem, one layer up.** `mcp.tool.pricing_status` (ADR 016 point 4, "Cost
+& Token Attribution" → "Span attributes" above) exists because an
+unrecognized model must not be silently reported as costing nothing — it
+gets `"unknown"`, distinct from a genuinely free/untracked call. But a
+call with `mcp.tool.pricing_status: "unknown"` has real extracted token
+usage and *no* `mcp.tool.cost.usd` at all (unpriced calls never reach
+`mcp.tool.cost.usd`, by construction — see "Cost & Token Attribution"
+above). To the `expensive-tool-calls` policy above, an attribute that
+was never set is indistinguishable from a cost of exactly `0` — the same
+"confidently wrong" failure the pricing-provenance work fixed at the
+attribute level, reappearing here because a numeric-threshold policy has
+no way to see the difference between "cheap" and "unknown." The
+`unpriced-calls` policy closes that gap the same way `mcp.tool.pricing_status`
+closes it at the attribute level: an explicit signal instead of an
+inferred absence. (Cost tracking's other kind of absence — a plain-text
+result with no recognizable token usage at all — has no attribute of any
+kind, `mcp.tool.pricing_status` included, and is not what this policy is
+for: that call genuinely has no cost signal, which is expected, not a
+gap.)
+
+**What's verified here, and what isn't — read this before trusting this
+recipe blindly.** Every `mcp.tool.*` key in
+[`tail-sampling.yaml`](../../docs/recipes/tail-sampling.yaml) is
+cross-checked by
+[`test/recipes/tail-sampling-attributes.test.js`](test/recipes/tail-sampling-attributes.test.js)
+against this package's real, exported attribute constants — and,
+specifically, against which of them are actually passed to
+`span.setAttribute()` in `src/`, not merely a span-event or metric name
+that happens to look like an attribute. That test is what would have
+caught this recipe's own predecessor bug: an earlier version of this
+section recommended the schema-drift span *event* name as a
+`boolean_attribute` policy target, which could never have matched
+anything. **What is not verified: the actual behavior of this config
+against a real Collector.** `tailsamplingprocessor` is Contrib-only Go
+source with no npm package and nothing installed in this repository, and
+no Docker daemon was reachable in the environment this recipe was last
+revised in — unlike the Grafana dashboard (`dashboards/README.md`, "Generating
+sample data / verifying locally"), which was verified end to end against
+a real Prometheus + Grafana stack before shipping, this recipe has not
+had the equivalent live-Collector run. Treat the attribute names as
+trustworthy and the policy semantics as sourced from public OpenTelemetry
+Collector Contrib documentation, not as something this project has
+independently confirmed by running it.
 
 ## Trace Context Propagation (v0.11.0+)
 
@@ -2154,7 +2235,19 @@ pragmatic choice rather than a spec-pure one.
   `mcp.tool.cost.usd` / `mcp.tool.cost.budget_exceeded` attributes, plus
   a documented, pasteable OpenTelemetry Collector `tailsamplingprocessor`
   config that keeps expensive/budget-exceeded/thrashing traces alongside
-  a normal probabilistic sample for everything else.
+  a normal probabilistic sample for everything else. **Update (v0.12.0):**
+  the recipe YAML moved to `docs/recipes/tail-sampling.yaml` (README
+  references it rather than duplicating it), gained two more policies —
+  `mcp.tool.schema_drift_detected` (a new attribute, the same event/attribute
+  fix applied to schema drift) and `mcp.tool.pricing_status = "unknown"`
+  (closes a v0.11.0-adjacent gap: an unpriced call has real cost but no
+  `mcp.tool.cost.usd`, which a numeric-threshold policy can't tell apart
+  from a genuinely free one) — and is now cross-checked by a test
+  (`test/recipes/tail-sampling-attributes.test.js`) that fixes a real bug
+  this section previously had: it recommended the schema-drift span
+  *event* name as a `boolean_attribute` policy target, which could never
+  have matched anything. See "Cost-aware trace sampling" above for the
+  full detail, including what is and isn't verified.
 - v0.10.0: `@modelcontextprotocol/server` (MCP v2, protocol revision
   2026-07-28) support ✓ — see "MCP v2 support" above and ADR 015
   (`docs/adr/015-mcp-v2-support.md`). Spans, standard attributes, failure

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opentel-mcp",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "One-line OpenTelemetry instrumentation for Model Context Protocol (MCP) servers",
   "type": "module",
   "main": "src/index.js",
@@ -78,6 +78,7 @@
     "@opentelemetry/sdk-metrics": "^2.9.0",
     "@opentelemetry/sdk-trace-base": "^2.9.0",
     "@vitest/coverage-v8": "^2.1.9",
+    "js-yaml": "^4.3.1",
     "typescript": "^7.0.2",
     "vitest": "^2.1.8",
     "zod": "^4.4.3"

package/src/cost/budget.js

@@ -8,8 +8,23 @@
  * that limit (denying the call, alerting, etc.) is left entirely to
  * whatever consumes the resulting `mcp.tool.cost.budget_exceeded` span
  * attribute (see src/attributes.js).
+ *
+ * v0.12.0 (docs/known-gaps.md entry 9): a call whose model doesn't resolve
+ * to a price (`mcp.tool.pricing_status: "unknown"`) never reaches
+ * `recordAndCheck()` below at all — `applyCostAttribution()` only calls it
+ * when `costUsd !== null`. That's not new behavior here, and this release
+ * does not change it (see that entry's "confidently wrong number" reasoning
+ * for why inventing a fallback price would trade one silent-failure shape
+ * for another, not fix it) — it only adds two diagnostics so the gap is
+ * visible instead of silent: a construction-time warning that a configured
+ * budget won't see unpriced spend, and a first-occurrence warning naming
+ * the model the first time it actually happens. Both are pure
+ * `diag.warn()` calls; neither changes `BudgetCheckResult`, adds a span
+ * attribute, or alters `recordAndCheck()`'s existing behavior in any way.
  */
 
+import { diag } from '@opentelemetry/api';
+
 /**
  * @typedef {Object} BudgetConfig
  * @property {number} [perSessionUsd] - Cumulative-cost limit per MCP session id. Calls with no session id
@@ -75,20 +90,57 @@ function accumulate(map, key, amount) {
  * every time — a confirmed gap, not a hypothetical. See ADR 012,
  * docs/adr/012-tracker-lifecycle-and-shared-state.md. Restart the process
  * (or, for a long-lived server, build your own eviction on top) to reset
- * intentionally.
+ * intentionally. **The two v0.12.0 warnings below inherit this exact same
+ * granularity** — both live in this same closure, so both re-arm on every
+ * fresh construction. Under the default (no `instanceKey`), a
+ * fresh-server-per-request deployment re-warns on *every request* for
+ * both — the identical inherited-caveat shape `docs/known-gaps.md` entry 6
+ * documents for `thrashSessionState`'s fallback-session warning. Unlike
+ * that entry's gap, though, `instrument.js` already constructs this
+ * tracker via `getOrCreateTracker(resolved.instanceKey, 'budget', ...)` —
+ * so a caller who *does* set a stable `instanceKey` shares one tracker
+ * (and therefore one already-armed warning flag) across calls, the same as
+ * every other registry-backed tracker; only the no-`instanceKey` default
+ * case gets the repeated warning.
  *
  * @param {BudgetConfig | undefined} budget - costTracking.budget from config.js. Omitted/undefined limits
- *   mean that scope is never tracked or checked — recordAndCheck() becomes a pure no-op for it.
- * @returns {{ recordAndCheck: (sessionId: unknown, toolName: unknown, costUsd: number) => BudgetCheckResult }}
+ *   mean that scope is never tracked or checked — recordAndCheck() becomes a pure no-op for it, and neither
+ *   new v0.12.0 warning below ever fires.
+ * @returns {{
+ *   recordAndCheck: (sessionId: unknown, toolName: unknown, costUsd: number) => BudgetCheckResult,
+ *   recordUnpriced: (model: unknown) => void,
+ * }}
  */
 export function createBudgetTracker(budget) {
   const perSessionUsd = isFiniteNumber(budget?.perSessionUsd) ? budget.perSessionUsd : undefined;
   const perToolUsd = isFiniteNumber(budget?.perToolUsd) ? budget.perToolUsd : undefined;
+  const budgetConfigured = perSessionUsd !== undefined || perToolUsd !== undefined;
+
+  // v0.12.0, docs/known-gaps.md entry 9: fires at most once per tracker
+  // construction (see this function's own docblock for exactly what "once"
+  // means here) — a proactive heads-up that this budget, once configured,
+  // will silently ignore any call whose model never resolves to a price.
+  // Unconditional on whether that ever actually happens; see
+  // recordUnpriced() below for the reactive counterpart that fires only
+  // when it does.
+  if (budgetConfigured) {
+    try {
+      diag.warn(
+        'opentel-mcp: a costTracking.budget guardrail is configured, but it only accounts for calls whose model ' +
+          'resolves to a known price. A call whose usage is extracted but whose model is unrecognized or unpriced ' +
+          '(mcp.tool.pricing_status: "unknown") is never counted toward perSessionUsd/perToolUsd, regardless of its ' +
+          'real token cost — see docs/known-gaps.md entry 9.',
+      );
+    } catch {
+      // Never throw — see module docblock.
+    }
+  }
 
   /** @type {Map<string, number>} */
   const sessionCostMap = new Map();
   /** @type {Map<string, number>} */
   const toolCostMap = new Map();
+  let warnedUnpriced = false;
 
   return {
     recordAndCheck(sessionId, toolName, costUsd) {
@@ -118,5 +170,40 @@ export function createBudgetTracker(budget) {
         return { exceeded: false, scope: null };
       }
     },
+
+    /**
+     * v0.12.0, docs/known-gaps.md entry 9: the reactive counterpart to the
+     * construction-time warning above. Called from `applyCostAttribution()`
+     * (src/instrument.js) in the branch where a call's usage was extracted
+     * but its cost never resolved (`costUsd === null`, the same condition
+     * that sets `mcp.tool.pricing_status: "unknown"`) — i.e. exactly the
+     * calls `recordAndCheck()` above is never invoked for. No-op, silently,
+     * when no budget scope is configured (nothing to warn about) or once
+     * this tracker has already warned once (see this module's own
+     * granularity docblock on `createBudgetTracker()` for what "once"
+     * means here). Never throws, matching every other public method here.
+     *
+     * @param {unknown} model - usage.model from the extractor's result, possibly undefined (no model detected at all).
+     */
+    recordUnpriced(model) {
+      if (!budgetConfigured || warnedUnpriced) return;
+      warnedUnpriced = true;
+
+      try {
+        const scopes = [perSessionUsd !== undefined ? 'perSessionUsd' : null, perToolUsd !== undefined ? 'perToolUsd' : null]
+          .filter(Boolean)
+          .join(', ');
+        const modelDescription = isNonEmptyString(model) ? `"${model}"` : '(no model detected)';
+        diag.warn(
+          `opentel-mcp: a tool call using model ${modelDescription} did not resolve to a price and was not counted ` +
+            `toward the configured budget guardrail (${scopes}). Real spend may be higher than ` +
+            'mcp.tool.cost.budget_exceeded/budget_scope report. This warning fires once per tracker instance — see ' +
+            "this function's own docblock for what that means under a fresh-server-per-request deployment — and " +
+            'only when a budget is configured. See docs/known-gaps.md entry 9.',
+        );
+      } catch {
+        // Never throw — see module docblock.
+      }
+    },
   };
 }

package/src/instrument.js

@@ -764,7 +764,13 @@ function extractSessionAndRequestId(kind, extraOrCtx) {
  * (src/cost/budget.js) — if that reports the call pushed a configured
  * budget over its limit, sets mcp.tool.cost.budget_exceeded /
  * mcp.tool.cost.budget_scope. An unrecognized model silently skips cost
- * *and* budget attribution — the token attributes still land.
+ * *and* budget attribution — the token attributes still land. v0.12.0
+ * (docs/known-gaps.md entry 9): that "silently" is now only true of the
+ * span/metrics — the same branch calls `budgetTracker.recordUnpriced()`
+ * instead, which fires a one-time diag.warn() naming the model, but only
+ * when a budget is actually configured (a pure no-op otherwise). No
+ * behavior change: this is diagnostics only, not a new price or a new
+ * budget-exceeded condition.
  *
  * No-op when `costTracking.enabled` is false. Called from both the
  * isToolResultError and success branches below (there's a result to read
@@ -840,6 +846,14 @@ function applyCostAttribution(span, metricsRecorder, toolName, sessionId, result
         span.setAttribute(ATTR_MCP_TOOL_COST_BUDGET_EXCEEDED, true);
         span.setAttribute(ATTR_MCP_TOOL_COST_BUDGET_SCOPE, budgetResult.scope);
       }
+    } else {
+      // v0.12.0, docs/known-gaps.md entry 9: the same condition that set
+      // pricingStatus to "unknown" above — usage was extracted, but never
+      // reached recordAndCheck() at all, so a configured budget silently
+      // never saw it. recordUnpriced() no-ops unless a budget is actually
+      // configured, and warns at most once per tracker instance — see its
+      // own docblock (src/cost/budget.js).
+      budgetTracker.recordUnpriced(usage.model);
     }
 
     return { tokensIn: usage.inputTokens, tokensOut: usage.outputTokens, costUsd: costUsd ?? 0 };
@@ -999,9 +1013,33 @@ function describeFallbackReason(server, kind) {
  *      is set. A server that has proven it hands out real session ids
  *      does not get to fall back just because one particular call lacked
  *      one.
- *   3. Before any real sessionId has ever been observed: the generated
- *      per-connection fallback (`thrashConnectionFallbackSessionId`) is
- *      used when `thrashConfig.assumeSingleSession` is true, or when
+ *   2.5. (ADR 018, docs/adr/018-trace-id-as-thrash-fallback.md) Before any
+ *      real sessionId has ever been observed, and before step 3's
+ *      UUID/skip fallback runs: if this call's span has a validly
+ *      extracted REMOTE parent — i.e. `request.params._meta` carried a
+ *      valid W3C `traceparent` that `extractTraceContext()`
+ *      (src/tracecontext/extract.js) turned into a remote `SpanContext` —
+ *      use that parent's trace id as the session-id candidate. Gated on
+ *      `trace.getSpanContext(parentContext)?.isRemote === true`, never on
+ *      a span's own `traceId` in isolation: every span, root or child, has
+ *      a `traceId`, and a ROOT span's (no valid `traceparent` extracted)
+ *      is freshly, randomly generated on every single call — using it
+ *      unconditionally would silently turn today's honest "skip,
+ *      undetermined" into "always produce a session id that never matches
+ *      the previous call's," which is worse than skipping (see the ADR's
+ *      "THE TRAP"). Does NOT set `thrashSessionState.hasSeenRealSessionId`
+ *      — that flag means "this transport hands out real session
+ *      identity," a permanent per-server fact; a trace id being present
+ *      on one call is a per-call fact about that one client's behavior,
+ *      not proof about the transport (ADR 018's "Constraints accepted").
+ *      No diag.warn(): unlike step 3 below, this isn't a guess about
+ *      transport topology the operator can correct — it's real,
+ *      client-supplied data, strictly finer-grained than the fallback it
+ *      sits beside, with no operator action item to flag.
+ *   3. Before any real sessionId has ever been observed, and step 2.5
+ *      above didn't apply: the generated per-connection fallback
+ *      (`thrashConnectionFallbackSessionId`) is used when
+ *      `thrashConfig.assumeSingleSession` is true, or when
  *      `isSingleConnectionTransport(server)` reliably determines the
  *      transport is single-connection. Otherwise, skip — an undetermined
  *      transport is not assumed to be single-connection. The first time
@@ -1016,9 +1054,10 @@ function describeFallbackReason(server, kind) {
  * @param {string} thrashConnectionFallbackSessionId
  * @param {import('./thrash/config.js').ThrashConfig} thrashConfig
  * @param {'v1' | 'v2' | undefined} kind - Threaded through to isSingleConnectionTransport()/describeFallbackReason() — see their docblocks (ADR 015).
+ * @param {import('@opentelemetry/api').Context} parentContext - The span's parent context, as returned by extractTraceContext() (ADR 017) — checked here for a validly-extracted remote SpanContext (ADR 018, step 2.5).
  * @returns {string | null}
  */
-function resolveThrashSessionId(server, sessionId, thrashSessionState, thrashConnectionFallbackSessionId, thrashConfig, kind) {
+function resolveThrashSessionId(server, sessionId, thrashSessionState, thrashConnectionFallbackSessionId, thrashConfig, kind, parentContext) {
   if (sessionId !== undefined) {
     thrashSessionState.hasSeenRealSessionId = true;
     return sessionId;
@@ -1028,6 +1067,11 @@ function resolveThrashSessionId(server, sessionId, thrashSessionState, thrashCon
     return null;
   }
 
+  const remoteParentSpanContext = trace.getSpanContext(parentContext);
+  if (remoteParentSpanContext?.isRemote === true) {
+    return remoteParentSpanContext.traceId;
+  }
+
   if (thrashConfig.assumeSingleSession || isSingleConnectionTransport(server, kind)) {
     if (!thrashSessionState.hasWarnedFallbackUsed) {
       thrashSessionState.hasWarnedFallbackUsed = true;
@@ -1320,6 +1364,7 @@ function wrapToolCallHandler(
         thrashConnectionFallbackSessionId,
         thrashConfig,
         kind,
+        parentContext,
       );
 
       span.setAttribute(ATTR_MCP_METHOD_NAME, TOOLS_CALL_METHOD);

package/src/schema-drift/attributes.js

@@ -32,6 +32,38 @@
  */
 export const SPAN_EVENT_NAME_SCHEMA_DRIFT_DETECTED = 'mcp.tool.schema_drift.detected';
 
+/**
+ * Boolean span ATTRIBUTE, distinct from SPAN_EVENT_NAME_SCHEMA_DRIFT_DETECTED
+ * above (v0.12.0). Same ambiguity, same resolution ADR 011
+ * (docs/adr/011-cost-aware-sampling.md) already applied to thrash detection:
+ * whether an OpenTelemetry Collector `tailsamplingprocessor`'s
+ * `boolean_attribute` policy can match span-EVENT data (as opposed to
+ * top-level span attributes) could not be confirmed either way — the
+ * processor is Go source in a separate repository, not installed here. ADR
+ * 011 resolved that uncertainty for thrash by adding a parallel attribute,
+ * `ATTR_MCP_TOOL_THRASH_DETECTED` (thrash/attributes.js); this is the
+ * identical fix applied here, for the identical reason. (This one wasn't
+ * added alongside ADR 010/011 originally — a v0.12.0 recipe-verification
+ * pass found the README recommending SPAN_EVENT_NAME_SCHEMA_DRIFT_DETECTED
+ * itself as a `boolean_attribute` policy target, which cannot work, since
+ * that string was never anything but an event/metric name.)
+ *
+ * Deliberately NOT `mcp.tool.schema_drift.detected` (SPAN_EVENT_NAME_SCHEMA_DRIFT_DETECTED's
+ * own string) — reusing it would reintroduce the exact ambiguity this
+ * attribute exists to remove: a bare string with no way to tell, from the
+ * name alone, whether a given consumer is reading the event or the
+ * attribute. Named `mcp.tool.schema_drift_detected` (underscore, no dot
+ * before "detected"), mirroring `ATTR_MCP_TOOL_THRASH_DETECTED`'s own
+ * naming (thrash/attributes.js: `mcp.tool.thrash_detected`, not
+ * `mcp.tool.loop.detected`, for the same reason).
+ *
+ * Only ever set to `true`, and only when drift was actually detected on
+ * this call — never explicitly set `false` for a clean call, matching
+ * `ATTR_MCP_TOOL_THRASH_DETECTED`'s same "omit rather than set a
+ * negative/empty value" convention.
+ */
+export const ATTR_MCP_TOOL_SCHEMA_DRIFT_DETECTED = 'mcp.tool.schema_drift_detected';
+
 /** @type {Readonly<Record<'TYPE' | 'PREVIOUS_HASH' | 'CURRENT_HASH' | 'ADDED_FIELDS' | 'REMOVED_FIELDS' | 'CHANGED_FIELDS', string>>} */
 export const ATTRIBUTE_KEYS = Object.freeze({
   /**

package/src/schema-drift/emitter.js

@@ -15,7 +15,9 @@
  * instrument uses (`metrics.getMeter('opentel-mcp', packageVersion)` —
  * see src/metrics.js's own docblock on why a second getMeter() call
  * still reports under the same meter to any backend), plus one span
- * event on the currently active span.
+ * event and one boolean span attribute (v0.12.0, ADR 011,
+ * docs/adr/011-cost-aware-sampling.md — see ATTR_MCP_TOOL_SCHEMA_DRIFT_DETECTED's
+ * own docblock in ./attributes.js for why) on the currently active span.
  *
  * "No active span" handling follows the SAME precedent this module
  * mirrors, not an invented behavior: ADR 010's "What gets emitted"
@@ -38,7 +40,7 @@
 
 import { trace, metrics } from '@opentelemetry/api';
 import { ATTR_GEN_AI_TOOL_NAME } from '../attributes.js';
-import { SPAN_EVENT_NAME_SCHEMA_DRIFT_DETECTED, ATTRIBUTE_KEYS } from './attributes.js';
+import { SPAN_EVENT_NAME_SCHEMA_DRIFT_DETECTED, ATTR_MCP_TOOL_SCHEMA_DRIFT_DETECTED, ATTRIBUTE_KEYS } from './attributes.js';
 
 /** @typedef {import('./types.d.ts').SchemaDriftEvent} SchemaDriftEvent */
 
@@ -66,7 +68,12 @@ export function createSchemaDriftEmitter(packageVersion) {
      * full detail, including the previous/current hashes and (only when
      * non-empty, mirroring `mcp.failure.validation_paths`'s
      * omit-rather-than-set-empty discipline, ADR 009) the changed field
-     * names. Never throws: metrics and the span event are independently
+     * names, plus (v0.12.0, ADR 011) a boolean
+     * `mcp.tool.schema_drift_detected` span ATTRIBUTE on that same span —
+     * a Collector tail-sampling policy can key on it directly, without
+     * depending on whether span-event data is matchable at all (see
+     * ATTR_MCP_TOOL_SCHEMA_DRIFT_DETECTED's docblock in ./attributes.js).
+     * Never throws: metrics and the span event/attribute are independently
      * guarded, so a failure in one never suppresses the other, the same
      * fail-open philosophy as every other emitter in this codebase.
      *
@@ -98,6 +105,7 @@ export function createSchemaDriftEmitter(packageVersion) {
         if (event.changedFields?.length > 0) attrs[ATTRIBUTE_KEYS.CHANGED_FIELDS] = event.changedFields;
 
         span.addEvent(SPAN_EVENT_NAME_SCHEMA_DRIFT_DETECTED, attrs);
+        span.setAttribute(ATTR_MCP_TOOL_SCHEMA_DRIFT_DETECTED, true);
       } catch {
         // Never throw — see emit()'s docblock.
       }