opentel-mcp 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,142 @@
 # Changelog
 
+## 0.11.0
+
+**⚠️ Type change, not a runtime behavior change — read this first.**
+`ModelPricing` is now a discriminated union
+(`{pricingKind: 'chat', inputPer1M, outputPer1M, currency} |
+{pricingKind: 'embedding', inputPer1M, currency}`) instead of a single
+shape with both token fields always present. A TypeScript consumer with
+an existing custom `pricingTable`/`pricing` object typed against the old
+shape will see a compile error requiring `pricingKind` on each entry.
+**Runtime behavior for those same objects is unchanged**: `calculateCost()`
+treats a missing or unrecognized `pricingKind` as `'chat'`, exactly the
+behavior every pre-v0.11.0 entry already had. See ADR 016
+(`docs/adr/016-pricing-override-and-staleness.md`) point 1.
+
+### Added — Pricing table override and staleness signalling (Phase 1 of 2)
+
+`DEFAULT_PRICING` had the same disease this whole library exists to fix
+elsewhere: a hardcoded snapshot with no signal when it's wrong or stale.
+This release closes that. Full design: ADR 016
+(`docs/adr/016-pricing-override-and-staleness.md`).
+
+- **Embedding model support.** `DEFAULT_PRICING` gains OpenAI
+  `text-embedding-3-small`/`text-embedding-3-large`/`text-embedding-ada-002`,
+  Cohere `cohere-embed-v3`, and Bedrock `amazon-titan-embed-v2`.
+  Embeddings are input-token-only — rather than modeling that as
+  `outputPer1M: 0` (indistinguishable from a data-entry bug), a new
+  `pricingKind: 'chat' | 'embedding'` discriminator makes it explicit; an
+  `'embedding'` entry has no `outputPer1M` field at all, and
+  `calculateCost()` never reads `outputTokens` for one (still validated as
+  a non-negative finite number, just never charged for).
+- **`costTracking.pricing`: per-model merge over defaults.** New option,
+  a *partial* pricing table merged per-model OVER `pricingTable ??
+  DEFAULT_PRICING` — each key you supply replaces that model's entire
+  pricing entry, every model you don't name is untouched. This is now the
+  recommended way to correct a stale price or add a model
+  `DEFAULT_PRICING` doesn't know about, without spreading the whole
+  default table by hand (the old workaround the README used to teach).
+  `costTracking.pricingTable` keeps its existing full-replace behavior,
+  unchanged, for the narrower "I want only my own models" case — see ADR
+  016 point 2 for why both exist.
+- **`mcp.tool.pricing_status` span + metric attribute.** One of `"known"`
+  | `"unknown"` | `"user_override"`, set whenever token usage was
+  extracted at all — even with no model detected (`"unknown"` in that
+  case), unlike the existing model/cost attributes. Added to the
+  `mcp.tool.tokens.total` / `mcp.tool.cost.total` metrics too, so a
+  dashboard can compute "% of tokens/spend unpriced" as a direct
+  aggregation instead of inferring it from missing data. Provenance-based:
+  `"user_override"` means the model's key came from your
+  `pricing`/`pricingTable`, regardless of whether the numbers you supplied
+  happen to match `DEFAULT_PRICING`'s own entry.
+- **Staleness signalling.** `DEFAULT_PRICING_LAST_VERIFIED` (also
+  exported) names the table's last-checked date; once it's more than 90
+  days old, `instrumentMcpServer()` fires a one-time `diag.warn()`, and,
+  when `setupNodeSdk: true`, also attaches an
+  `mcp.pricing.default_table_last_verified` resource attribute. Both only
+  fire when `DEFAULT_PRICING` is actually contributing to the effective
+  table — a caller who fully replaced it via `pricingTable` isn't using
+  our defaults, so a warning about them would be misleading.
+  `isDefaultPricingStale(now?, thresholdDays?)` (also exported) is the
+  pure function behind the warning, for callers who want to check it
+  themselves.
+- **Bedrock region caveat, documented not modeled.** Bedrock pricing
+  varies by region; `DEFAULT_PRICING`'s Bedrock entries (Nova, and the new
+  Titan embedding entry) assume us-east-1 list price and the table is not
+  region-keyed — no tool-result usage shape this package recognizes
+  carries a region signal to key a lookup on. Documented loudly in the
+  README and in `pricing.js`; override via `costTracking.pricing` for a
+  different region. See ADR 016 point 5.
+- `calculateCost()` gained defensive validation for malformed pricing
+  entries (missing/negative/non-numeric `inputPer1M`/`outputPer1M`),
+  since `pricing`/`pricingTable` now make it reachable with
+  caller-supplied shapes it previously never had to distrust — degrades
+  to `null`, same as an unknown model, never throws.
+
+### Added — W3C Trace Context propagation over MCP `_meta` (Phase 2 of 2, server-side only)
+
+The most-complained-about gap in agent observability: an agent's own
+trace (LangGraph or otherwise) and the MCP server's trace for the tool
+call it made were always two disconnected traces, with no edge between
+them. Full design, including the sampling and conflicting-context
+decisions below: ADR 017 (`docs/adr/017-trace-context-propagation.md`).
+
+- **`tools/call` requests carrying a valid W3C `traceparent` in
+  `params._meta` now become a child of the calling agent's own span**,
+  joining what were two disconnected traces into one — under both MCP v1
+  and v2, with zero configuration and no new option. `tracestate` is
+  propagated too, when present. Works for any client already emitting
+  `traceparent` via a standard OTel SDK's `propagation.inject()` in any
+  language — this isn't Node/JS-specific on the client side, only on
+  which side of the wire this release implements.
+- **The upstream sampling decision is honored automatically, by
+  construction, with no sampling logic written for this feature**: the
+  extracted `SpanContext` is marked `isRemote: true` with the real parsed
+  `traceFlags`, which is exactly what the SDK's own default
+  `ParentBasedSampler` already keys its remote-parent decision off of. A
+  not-sampled upstream `traceparent` means this tool-call span is not
+  recorded or exported, matching the calling agent's own choice — see the
+  ADR's "Sampling" section for why forcing sampling regardless was
+  considered and rejected.
+- **A `_meta`-extracted context always replaces, never merges with, an
+  already-active local context** (e.g. an ambient HTTP-server span from
+  auto-instrumentation on a Streamable HTTP transport) — the message-level
+  `_meta` context is the semantically correct parent for one tool call,
+  full stop, regardless of what transport-level span it happened to
+  arrive inside. See the ADR's "Conflicting `_meta.traceparent`" section.
+- **Absent, malformed, or unparseable `_meta`/`traceparent` produces
+  behavior that is byte-identical to pre-v0.11.0** — not merely
+  equivalent to it: confirmed by reading both `NoopTracer` and the real
+  SDK `Tracer`'s own `startActiveSpan()` fallback (`ctx ?? context.active()`),
+  which is exactly what this feature's `extractTraceContext()` returns
+  for every case that isn't a valid `traceparent`. No `diag.warn()` for
+  the common "client doesn't send `_meta.traceparent`" case — see the
+  ADR's "no warn spam" constraint.
+- **Zero new dependencies.** `@opentelemetry/core`'s
+  `W3CTraceContextPropagator` was the obvious reference implementation
+  and was deliberately not taken as a dependency, per
+  `CONTRIBUTING.md`'s "no new dependencies without discussion first" —
+  everything needed except the traceparent regex itself (~10 lines,
+  matching `@opentelemetry/core`'s own validation field-for-field) was
+  already available from `@opentelemetry/api`, already a peer dependency
+  — including `createTraceState()`, a fully spec-validated `tracestate`
+  parser. Full reasoning: ADR 017's "No new dependency" section.
+- **Server-side extraction only.** The client-side shim that would let a
+  Node/Python agent framework *set* `_meta.traceparent` on outgoing calls
+  is explicitly out of scope for this phase — extraction is independently
+  useful today, for free, to any client whose own tooling already sets
+  `_meta` in this shape. Tracked as future work, not implied as solved.
+
+Also fixed in this release: two places (`index.d.ts`'s
+`instrumentMcpServer()` docblock, and this file's own v0.10.0 entry
+below) still described `docs/known-gaps.md` entries 6/7/8 using language
+that read as still-open, or as scoped out of v0.10.0 — both were stale.
+Entries 7 and 8 have been fully fixed since v0.10.0 with no open caveats;
+entry 6's fallback-session-id half is fixed too, narrowed to a smaller,
+genuinely-still-open remainder (see the corrected v0.10.0 entry below and
+`index.d.ts`'s updated docblock for the accurate, current accounting).
+
 ## 0.10.0
 
 **⚠️ Behavior change, unrelated to the feature below — read this first.**
@@ -60,15 +197,32 @@ new was added for this, since ADR 012's original design already covers
 this exact deployment shape, v2 just makes it the default instead of an
 edge case.
 
-**Two gaps not closed this release, both tracked in `docs/known-gaps.md`
-with a "Status update (v0.10.0)" note:** Agent Thrash Detection's fallback
-session id still doesn't survive v2's per-request factory pattern even
-with `instanceKey` set (entry 6 — real session ids work fine either way),
-and `isSingleConnectionTransport()`'s transport-detection heuristic still
-misclassifies the transport `createMcpHandler` builds internally (entry
-8, live as of this release, not merely forward-looking). Both were
-explicitly scoped out of this round, not overlooked; workaround for
-either: `thrashDetection: { enabled: false }`.
+**Correction (recorded here rather than silently edited): both gaps below
+were actually closed in this same v0.10.0 release, not left open.** The
+paragraph originally here said entries 6 and 8 (`docs/known-gaps.md`)
+were scoped out of this round — true of the round that produced the text
+above, not of what actually shipped. A follow-up investigation, completed
+before v0.10.0 was cut, folded both fixes back in: `isSingleConnectionTransport()`
+no longer misclassifies the transport `createMcpHandler` builds internally
+(entry 8 — fully fixed: v2 now requires positive confirmation,
+`transport.constructor.name === 'StdioServerTransport'`, instead of
+inferring single-connection from an absent `sessionId` property), and
+Agent Thrash Detection's fallback session id is now registry-backed via
+`instanceKey` (entry 6's fallback-id gap — fixed: repeated
+`instrumentMcpServer()` calls sharing an `instanceKey` now reuse the same
+generated id instead of a fresh one per call). Both fixes shipped in the
+same commit, in a specific order — fixing detection (entry 8) before
+sharing the fallback id (entry 6) — since sharing it first would have made
+entry 8's false positive worse, not better.
+
+**What remains genuinely open, narrower than either original gap:**
+`thrashSessionState` (whether a server has ever proven itself
+session-aware) still isn't registry-backed, and — structurally, not a
+bug this library can fix — MCP spec 2026-07-28 removes protocol-level
+sessions entirely, so no configuration of this library can produce a
+*real* session id for a spec-2026-07-28-native deployment in the first
+place. See ADR 015's final "Update ... Findings 3 and 8 landed here too"
+section and `docs/known-gaps.md` entries 6 and 8 for the full accounting.
 
 ## 0.9.0
 

package/README.md

@@ -495,19 +495,20 @@ point, or JSON-in-text inside `content[0].text`) automatically gets
 `mcp.tool.tokens.*` / `mcp.tool.model` / `mcp.tool.cost.*` span
 attributes, priced against `DEFAULT_PRICING`.
 
-### Advanced: custom pricing, a custom extractor, and a budget guardrail
+### Advanced: overriding pricing, a custom extractor, and a budget guardrail
 
 ```js
-import { instrumentMcpServer, DEFAULT_PRICING } from 'opentel-mcp';
+import { instrumentMcpServer } from 'opentel-mcp';
 
 instrumentMcpServer(server, {
   serviceName: 'my-mcp-server',
   costTracking: {
-    // Extend or override DEFAULT_PRICING — e.g. price an internal model
-    // it doesn't know about, or correct stale numbers.
-    pricingTable: {
-      ...DEFAULT_PRICING,
-      'my-internal-model': { inputPer1M: 1.0, outputPer1M: 2.0, currency: 'USD' },
+    // Merged per-model OVER DEFAULT_PRICING — correct a stale price or add
+    // a model DEFAULT_PRICING doesn't know about, without having to spread
+    // the whole default table yourself. Everything you don't name here is
+    // untouched. See "Overriding pricing" below.
+    pricing: {
+      'my-internal-model': { pricingKind: 'chat', inputPer1M: 1.0, outputPer1M: 2.0, currency: 'USD' },
     },
     // Recognize your own tool result shape. Return null for anything you
     // don't recognize — never throw (see src/cost/extractor.js).
@@ -526,6 +527,41 @@ instrumentMcpServer(server, {
 });
 ```
 
+### Overriding pricing (v0.11.0+)
+
+Two ways to change what `costTracking` prices against, composing as
+`{ ...(pricingTable ?? DEFAULT_PRICING), ...pricing }` — see ADR 016
+(`docs/adr/016-pricing-override-and-staleness.md`) for the full reasoning:
+
+- **`costTracking.pricing`** — a *partial* table, merged **per-model**
+  over `DEFAULT_PRICING` (or over `pricingTable`, if you set both). Each
+  key you supply replaces that one model's entire pricing entry; every
+  model you don't name keeps its default price. This is the recommended
+  way to correct a stale number or add a model — enterprises on
+  committed-use discounts, AWS EDP, Bedrock provisioned throughput, or
+  Azure OpenAI negotiated rates should use this to reflect what they
+  actually pay, not list price.
+- **`costTracking.pricingTable`** — *fully replaces* `DEFAULT_PRICING`.
+  Use this when you want an effective table containing **only** your own
+  models, none of `DEFAULT_PRICING`'s.
+
+A model priced via either option reports `pricing_status: 'user_override'`
+(see the span attributes table below) instead of `'known'`.
+
+### Embedding models (v0.11.0+)
+
+Embeddings are input-token-only — there's no "output" to price. Rather
+than modeling that as `outputPer1M: 0` (indistinguishable from a
+data-entry bug), `ModelPricing` carries an explicit
+`pricingKind: 'chat' | 'embedding'` discriminator; an `'embedding'` entry
+has no `outputPer1M` field at all, and `calculateCost()` never reads
+`outputTokens` for one. `DEFAULT_PRICING` includes OpenAI
+`text-embedding-3-small`/`text-embedding-3-large`/`text-embedding-ada-002`,
+Cohere `cohere-embed-v3`, and Bedrock `amazon-titan-embed-v2` out of the
+box. A pre-v0.11.0 custom pricing entry with no `pricingKind` field is
+still treated as `'chat'` at runtime — only the TypeScript type is
+stricter, not the runtime.
+
 ### Span attributes
 
 | Attribute | Standard OTel? | Description | Example |
@@ -535,19 +571,23 @@ instrumentMcpServer(server, {
 | `mcp.tool.tokens.total` | Custom | input + output | 1500 |
 | `mcp.tool.model` | Custom | Detected model name | "claude-sonnet-5" |
 | `gen_ai.response.model` | Standard (GenAI semconv)[^5] | Same value as `mcp.tool.model`, co-emitted for dashboard compatibility | "claude-sonnet-5" |
+| `mcp.tool.pricing_status` | Custom[^7] | `"known"` \| `"unknown"` \| `"user_override"` — set whenever token usage was extracted, even with no model detected | "known" |
 | `mcp.tool.cost.usd` | Custom | Estimated cost, from `calculateCost()` | 0.0105 |
 | `mcp.tool.cost.currency` | Custom | Always `"USD"` today | "USD" |
 | `mcp.tool.cost.budget_exceeded` | Custom | `true` once a configured `costTracking.budget` limit is crossed | true |
 | `mcp.tool.cost.budget_scope` | Custom | Which budget scope tripped: `"session"` \| `"tool"` (session wins if both did) | "session" |
 
 [^5]: `gen_ai.response.model` is a real OTel GenAI semantic convention attribute ("the name of the model that generated the response") — but this span is an MCP tool-call span (`gen_ai.operation.name: execute_tool`), not a dedicated LLM request/response span, so co-emitting it here is a **pragmatic dashboard-compatibility choice, not a spec-pure emission**. It's set purely so off-the-shelf GenAI dashboards (Grafana, SigNoz, Honeycomb) that filter/group by `gen_ai.response.model` pick these spans up without any opentel-mcp-specific configuration. Full reasoning in `src/attributes.js`'s `ATTR_GEN_AI_RESPONSE_MODEL` docblock.
+[^7]: `mcp.tool.pricing_status` is provenance-based, not value-based: `"user_override"` means the model's key was present in your `costTracking.pricing`/`pricingTable`, whether or not the numbers you supplied happen to match `DEFAULT_PRICING`. `"unknown"` covers both "no model detected" and "model detected but not priceable" (unrecognized, or a malformed override entry) — see ADR 016 point 4.
 
-The four token/model attributes are set together or not at all; the two
-cost attributes only appear when a model was detected *and* it resolves
-in the configured `pricingTable`; the two budget attributes only appear
-when a cost was calculated *and* a configured limit was crossed. Source
-of truth: `src/attributes.js` and `src/instrument.js`'s
-`applyCostAttribution()`.
+The four token/model attributes are set together or not at all;
+`mcp.tool.pricing_status` is set whenever usage was extracted at all
+(unlike the model/cost attributes, it's present even with no model
+detected); the two cost attributes only appear when a model was detected
+*and* it resolves in the effective pricing table; the two budget
+attributes only appear when a cost was calculated *and* a configured
+limit was crossed. Source of truth: `src/attributes.js` and
+`src/instrument.js`'s `applyCostAttribution()`.
 
 ### Metrics
 
@@ -557,21 +597,38 @@ registered, `enableMetrics: false` opts out of these too.
 
 | Metric | Type | Unit | Attributes | Emitted when |
 |---|---|---|---|---|
-| `mcp.tool.tokens.total` | Counter | tokens | `gen_ai.tool.name`, `mcp.tool.model`[^6] | Usage detected in the tool result |
-| `mcp.tool.cost.total` | Counter | USD | `gen_ai.tool.name`, `mcp.tool.model`[^6] | Cost calculated (model resolved in `pricingTable`) |
-
-[^6]: `mcp.tool.model` is only added when a model was detected — the same optional-attribute cardinality pattern `mcp.failure.category` already uses on the other four metrics.
-
-### Pricing accuracy
-
-> **Pricing table last verified 2026-07-29.** Users **MUST** override
-> `pricingTable` for production accuracy — provider pricing changes
-> frequently and opentel-mcp does not guarantee `DEFAULT_PRICING` stays
-> current.
-
-`DEFAULT_PRICING` (`src/cost/pricing.js`) covers 15+ models across five
-providers — Anthropic, OpenAI, Google, AWS Bedrock, and DeepSeek — as a
-convenience default, not a maintained price list.
+| `mcp.tool.tokens.total` | Counter | tokens | `gen_ai.tool.name`, `mcp.tool.model`[^6], `mcp.tool.pricing_status` | Usage detected in the tool result |
+| `mcp.tool.cost.total` | Counter | USD | `gen_ai.tool.name`, `mcp.tool.model`[^6], `mcp.tool.pricing_status` | Cost calculated (model resolved in the effective pricing table) |
+
+[^6]: `mcp.tool.model` is only added when a model was detected — the same optional-attribute cardinality pattern `mcp.failure.category` already uses on the other four metrics. `mcp.tool.pricing_status` is always added — a fixed, closed 3-value enum, well within this package's metric-label cardinality discipline (see `COST_METRIC_SAFE_ATTRIBUTES` in `src/attributes.js`).
+
+Grouping `mcp.tool.tokens.total` by `mcp.tool.pricing_status` answers "what
+fraction of tokens/spend is running through models we can't price" as a
+direct query, instead of inferring it from missing `mcp.tool.cost.*` data.
+
+### Pricing accuracy and staleness
+
+> **`DEFAULT_PRICING` is a best-effort snapshot, not a maintained price
+> list.** Provider pricing changes frequently and varies by region/contract
+> — `opentel-mcp` does not guarantee it stays current, and says so at
+> runtime, not just here: once `DEFAULT_PRICING` (checked via
+> `DEFAULT_PRICING_LAST_VERIFIED`, also exported) is more than 90 days
+> past its last-verified date, `instrumentMcpServer()` fires a one-time
+> `diag.warn()` naming that date — and, when `setupNodeSdk: true`, also
+> attaches an `mcp.pricing.default_table_last_verified` resource
+> attribute, so long-running deployments can alert on it directly. Both
+> only fire when `DEFAULT_PRICING` is actually contributing to your
+> effective table (i.e. you haven't fully replaced it via `pricingTable`)
+> — see ADR 016 point 3.
+
+`DEFAULT_PRICING` (`src/cost/pricing.js`) covers 20+ models — chat and
+embedding — across six providers: Anthropic, OpenAI, Google, Cohere, AWS
+Bedrock, and DeepSeek. **Bedrock entries (Nova and Titan embeddings)
+assume us-east-1 list pricing** — Bedrock pricing varies by region and
+this table is not region-keyed (no reliable region signal exists in any
+tool-result usage shape this package recognizes to key a lookup on — see
+ADR 016 point 5); override via `costTracking.pricing` for a different
+region.
 
 ### Extending it
 
@@ -581,7 +638,12 @@ convenience default, not a maintained price list.
   TokenUsage | null`, never throwing) to recognize anything else.
 - `calculateCost(inputTokens, outputTokens, model, pricingTable)` is also
   exported directly, for recomputing cost outside the instrumentation
-  hot path (e.g. over historical spans).
+  hot path (e.g. over historical spans). Malformed pricing entries
+  (missing/negative/non-numeric `inputPer1M`/`outputPer1M`) degrade to
+  `null`, same as an unknown model — never throws.
+- `isDefaultPricingStale(now?, thresholdDays?)` (also exported) is the
+  pure function backing the staleness warning above, if you want to check
+  it yourself (e.g. in a startup health check).
 - Disable everything in this section with `costTracking: { enabled:
   false }`; tracing, metrics, and fingerprinting are all unaffected.
 - Budget tracking (`costTracking.budget`) is in-memory and scoped to one
@@ -1525,6 +1587,84 @@ 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.
 
+## Trace Context Propagation (v0.11.0+)
+
+The most-complained-about gap in agent observability: an agent framework
+(LangGraph or otherwise) calls a tool on your MCP server, and you get two
+disconnected traces — the agent's own trace dies at the tool boundary,
+and the server's trace for what the tool actually did starts fresh, with
+no edge between them. Debugging a slow or failing agent run means
+manually correlating timestamps across two separate traces (or two
+separate services in the same backend) instead of looking at one.
+
+opentel-mcp closes the server-side half of this: when a `tools/call`
+request carries a valid [W3C `traceparent`](https://www.w3.org/TR/trace-context/)
+in `params._meta`, the tool-call span becomes a **child of the calling
+agent's own span** — the same trace, not two. `tracestate` is propagated
+too, when present.
+
+### Zero-config — nothing to opt into
+
+There's no `traceContext: { enabled: false }` option, deliberately: this
+is unconditional, because there's nothing for an operator to want to turn
+off. Any client that already emits `traceparent` via a standard OTel
+SDK's `propagation.inject()` — in any language, this isn't Node-specific
+on the client side — gets linked traces the moment it copies that string
+into `_meta.traceparent` on its outgoing `tools/call` request:
+
+```json
+{
+  "method": "tools/call",
+  "params": {
+    "name": "search_docs",
+    "arguments": { "query": "..." },
+    "_meta": {
+      "traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
+      "tracestate": "vendorname=opaquevalue"
+    }
+  }
+}
+```
+
+A client that doesn't set `_meta.traceparent` (today's overwhelming
+majority, until client-side shims exist — see "What's not built yet"
+below) sees **zero change of any kind** — confirmed byte-identical to
+pre-v0.11.0 behavior, not merely "should behave the same."
+
+### The upstream sampling decision is honored automatically
+
+If the calling agent's own trace wasn't sampled (the `traceparent`'s
+flags byte has the sampled bit unset), this tool-call span isn't recorded
+or exported either — matching the agent's own choice, via the OTel SDK's
+own default `ParentBasedSampler`, which already inspects a remote
+parent's `traceFlags` for exactly this. opentel-mcp writes no sampling
+logic of its own for this — see ADR 017's "Sampling" section
+(`docs/adr/017-trace-context-propagation.md`) for why forcing sampling
+regardless was considered and rejected.
+
+### Conflicting or pre-existing context
+
+If your transport's own auto-instrumentation (e.g.
+`@opentelemetry/instrumentation-http` on a Streamable HTTP server) has
+already put some other span active by the time this package's handler
+runs, a valid `_meta.traceparent` **replaces it outright** — it is never
+merged. The `_meta`-carried context is message-scoped (this one logical
+agent operation); the transport-level span is connection/request-scoped
+and isn't the right parent for it. Full reasoning: ADR 017's
+"Conflicting `_meta.traceparent`" section.
+
+### What's not built yet
+
+**Server-side extraction only.** There is no client-side shim in this
+package (yet) for a Node or Python agent framework to *set*
+`_meta.traceparent` on its own outgoing calls — you need a client that
+already does this itself (or does it via your own glue code:
+`propagation.inject(context.active(), meta, ...)` from your OTel SDK,
+writing into `_meta` before the call). Extraction is independently
+useful today, for free, to any client that already sets `_meta` in this
+shape; the client-side half is tracked as future work, not implied as
+solved by this release.
+
 ## Configuration
 
 All options passed to `instrumentMcpServer(server, options)`. Source of

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opentel-mcp",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "One-line OpenTelemetry instrumentation for Model Context Protocol (MCP) servers",
   "type": "module",
   "main": "src/index.js",
@@ -74,6 +74,7 @@
   "devDependencies": {
     "@modelcontextprotocol/server": "^2.0.0",
     "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/context-async-hooks": "^2.9.0",
     "@opentelemetry/sdk-metrics": "^2.9.0",
     "@opentelemetry/sdk-trace-base": "^2.9.0",
     "@vitest/coverage-v8": "^2.1.9",

package/src/attributes.js

@@ -168,3 +168,48 @@ export const MCP_TOOL_COST_BUDGET_SCOPE_SESSION = 'session';
 
 /** Well-known mcp.tool.cost.budget_scope value: costTracking.budget.perToolUsd was exceeded. */
 export const MCP_TOOL_COST_BUDGET_SCOPE_TOOL = 'tool';
+
+// --- Pricing provenance (v0.11.0, non-spec, ADR 016) ---
+//
+// docs/adr/016-pricing-override-and-staleness.md. Lets a dashboard answer
+// "what fraction of spend/tokens is unpriced" as a direct query instead of
+// an inference from missing mcp.tool.cost.* attributes.
+
+/**
+ * Whether the model detected for this tool call resolved to a known price.
+ * Set whenever token usage was extracted at all (same gating as
+ * ATTR_MCP_TOOL_TOKENS_INPUT/OUTPUT/TOTAL) — present even when no model was
+ * detected, unlike ATTR_MCP_TOOL_MODEL/ATTR_MCP_TOOL_COST_USD. One of
+ * MCP_TOOL_PRICING_STATUS_KNOWN / _UNKNOWN / _USER_OVERRIDE.
+ */
+export const ATTR_MCP_TOOL_PRICING_STATUS = 'mcp.tool.pricing_status';
+
+/** Well-known mcp.tool.pricing_status value: no model was detected, or the detected model has no pricing entry. */
+export const MCP_TOOL_PRICING_STATUS_UNKNOWN = 'unknown';
+
+/** Well-known mcp.tool.pricing_status value: priced against an unmodified DEFAULT_PRICING entry. */
+export const MCP_TOOL_PRICING_STATUS_KNOWN = 'known';
+
+/** Well-known mcp.tool.pricing_status value: priced against a caller-supplied costTracking.pricing/pricingTable entry. */
+export const MCP_TOOL_PRICING_STATUS_USER_OVERRIDE = 'user_override';
+
+/**
+ * Attribute keys safe to attach to mcp.tool.tokens.total / mcp.tool.cost.total
+ * metric labels, for the cost/pricing domain specifically. Mirrors the
+ * governance pattern fingerprint/attributes.js's METRIC_SAFE_ATTRIBUTES and
+ * schema-drift/attributes.js's own same-named export already established
+ * for their domains — this domain gets its own list rather than borrowing
+ * either of those (mixing an unrelated domain's cardinality reasoning in
+ * here would obscure which ADR covers which attribute). Not re-exported
+ * from index.js, same as schema-drift's — internal governance, not public
+ * API. mcp.tool.model remains governed the way it already was, an inline
+ * cardinality comment in metrics.js, not a list entry here — see ADR 016
+ * point 4 for why that attribute's boundedness argument doesn't fit a
+ * fixed-enum list cleanly the way this one does.
+ *
+ * @type {readonly string[]}
+ */
+export const COST_METRIC_SAFE_ATTRIBUTES = Object.freeze([ATTR_MCP_TOOL_PRICING_STATUS]);
+
+/** Resource attribute (setupNodeSdk: true only) naming DEFAULT_PRICING's lastVerified date. See ADR 016 point 3. */
+export const ATTR_MCP_PRICING_DEFAULT_TABLE_LAST_VERIFIED = 'mcp.pricing.default_table_last_verified';

package/src/config.js

@@ -4,8 +4,9 @@
  */
 
 import { diag } from '@opentelemetry/api';
-import { DEFAULT_PRICING } from './cost/pricing.js';
+import { DEFAULT_PRICING, DEFAULT_PRICING_LAST_VERIFIED, isDefaultPricingStale } from './cost/pricing.js';
 import { defaultExtractor } from './cost/extractor.js';
+import { normalizeModelName } from './cost/calculator.js';
 import { resolveThrashConfig } from './thrash/config.js';
 import { resolveSchemaDriftConfig } from './schema-drift/config.js';
 
@@ -13,9 +14,16 @@ import { resolveSchemaDriftConfig } from './schema-drift/config.js';
  * @typedef {object} CostTrackingOptions
  * @property {boolean} [enabled=true] - Set to false to disable cost/token span attributes and the
  *   mcp.tool.tokens.total / mcp.tool.cost.total metrics entirely.
- * @property {import('./cost/pricing.js').PricingTable} [pricingTable] - Overrides DEFAULT_PRICING
- *   (src/cost/pricing.js). Supply your own table to price models DEFAULT_PRICING doesn't know about, or to
- *   correct stale pricing — see that module's docblock.
+ * @property {import('./cost/pricing.js').PricingTable} [pricingTable] - Fully replaces DEFAULT_PRICING (or,
+ *   if `pricing` below is also set, replaces the base table `pricing` is merged over). Supply your own table
+ *   when you want an effective table containing ONLY your own models. For correcting/adding a few models
+ *   while keeping the rest of DEFAULT_PRICING, prefer `pricing` instead — see ADR 016
+ *   (docs/adr/016-pricing-override-and-staleness.md) point 2.
+ * @property {Partial<import('./cost/pricing.js').PricingTable>} [pricing] - Partial pricing table, merged
+ *   per-model OVER `pricingTable ?? DEFAULT_PRICING` — each key you supply replaces that model's entire
+ *   ModelPricing entry; every model you don't name is untouched. The recommended way to correct stale
+ *   pricing or add a model DEFAULT_PRICING doesn't know about. A model priced via this option (or via
+ *   `pricingTable`) reports `pricing_status: 'user_override'` — see ADR 016 point 2.
  * @property {import('./cost/extractor.js').UsageExtractor} [extractor] - Overrides defaultExtractor
  *   (src/cost/extractor.js). Supply your own to recognize a tool result shape defaultExtractor doesn't.
  * @property {import('./cost/budget.js').BudgetConfig} [budget] - Per-session and per-tool cumulative-cost
@@ -113,6 +121,24 @@ export function __resetServiceNameWarnedForTests() {
   warnedServiceNameIgnored = false;
 }
 
+// Guards the DEFAULT_PRICING staleness diagnostic below (ADR 016 point 3),
+// same one-per-process pattern as warnedServiceNameIgnored above.
+let warnedPricingStale = false;
+
+// Test-only, same purpose as __resetServiceNameWarnedForTests above. Not
+// part of the public API.
+export function __resetPricingStaleWarnedForTests() {
+  warnedPricingStale = false;
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is Record<string, unknown>}
+ */
+function isPlainObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
 // ADR 012, Phase 2: the first env var this codebase reads for a bare
 // top-level InstrumentOptions field, not one nested inside a feature's own
 // sub-config (contrast OTEL_MCP_THRASH_*/OTEL_MCP_SCHEMA_DRIFT_*, both
@@ -171,6 +197,50 @@ export function resolveOptions(options) {
   }
 
   const rawCostTracking = opts.costTracking ?? {};
+  const costTrackingEnabled = rawCostTracking.enabled ?? true;
+
+  // ADR 016 point 2: pricingTable (when supplied) is the BASE table,
+  // fully replacing DEFAULT_PRICING; pricing (when supplied) is then
+  // merged per-model OVER that base — a plain object spread is exactly
+  // "per-model, not top-level replacement" here, since each spread key is
+  // one model. Non-object pricingTable/pricing values (a caller's typo,
+  // e.g. a string or null) are silently ignored rather than spread, same
+  // "malformed config degrades, never crashes" discipline calculateCost()
+  // itself follows for a malformed individual entry.
+  const hasCustomPricingTable = isPlainObject(rawCostTracking.pricingTable);
+  const hasPricingOverride = isPlainObject(rawCostTracking.pricing);
+  const basePricingTable = hasCustomPricingTable ? rawCostTracking.pricingTable : DEFAULT_PRICING;
+  const pricingTable = hasPricingOverride ? { ...basePricingTable, ...rawCostTracking.pricing } : basePricingTable;
+
+  // ADR 016 point 4: which normalized model keys came from the caller's
+  // own config surface (pricingTable and/or pricing), for the
+  // mcp.tool.pricing_status 'known' vs 'user_override' distinction —
+  // computed once here, not per call. Provenance-based: a key counts as
+  // an override because the caller named it, regardless of whether the
+  // value they supplied happens to match DEFAULT_PRICING's own entry.
+  const pricingOverrideKeys = new Set();
+  if (hasCustomPricingTable) {
+    for (const key of Object.keys(rawCostTracking.pricingTable)) pricingOverrideKeys.add(normalizeModelName(key));
+  }
+  if (hasPricingOverride) {
+    for (const key of Object.keys(rawCostTracking.pricing)) pricingOverrideKeys.add(normalizeModelName(key));
+  }
+
+  // ADR 016 point 3: only warn when DEFAULT_PRICING is actually
+  // contributing to the effective table — a caller who fully replaced it
+  // via pricingTable isn't using our defaults at all, so a staleness
+  // warning about them would be misleading. Gated on costTrackingEnabled
+  // too: no cost tracking happens at all otherwise, so DEFAULT_PRICING's
+  // age is moot.
+  if (costTrackingEnabled && !hasCustomPricingTable && !warnedPricingStale && isDefaultPricingStale()) {
+    warnedPricingStale = true;
+    diag.warn(
+      `opentel-mcp: DEFAULT_PRICING was last verified ${DEFAULT_PRICING_LAST_VERIFIED}, more than 90 days ago. ` +
+        'Provider list pricing may have changed since. Override costTracking.pricing (merged per-model over ' +
+        'DEFAULT_PRICING) for models whose pricing you need to keep current — see ADR 016, ' +
+        'docs/adr/016-pricing-override-and-staleness.md.',
+    );
+  }
 
   return {
     serviceName: opts.serviceName,
@@ -180,8 +250,10 @@ export function resolveOptions(options) {
     setupNodeSdk,
     fingerprinting: opts.fingerprinting ?? true,
     costTracking: {
-      enabled: rawCostTracking.enabled ?? true,
-      pricingTable: rawCostTracking.pricingTable ?? DEFAULT_PRICING,
+      enabled: costTrackingEnabled,
+      pricingTable,
+      pricingOverrideKeys,
+      usingDefaultPricing: !hasCustomPricingTable,
       extractor: rawCostTracking.extractor ?? defaultExtractor,
       budget: rawCostTracking.budget,
     },