opentel-mcp 0.16.0 → 0.17.0

package/CHANGELOG.md

@@ -1,5 +1,96 @@
 # Changelog
 
+## 0.17.0
+
+Staleness detection: a read tool that returns data older than its own
+freshness window now shows up, even though the call succeeded. Suggested by
+the r/mcp community. Opt-in per tool; tools that don't report freshness
+are untouched. No new metric label keys.
+
+### Added
+
+- **Staleness detection (ADR 027, `docs/adr/027-staleness-detection.md`).**
+  A tool reports freshness in its result's `_meta` under
+  `FRESHNESS_META_KEY` (`'io.github.thirumalaiboobathi.opentel-mcp/freshness'`,
+  a reverse-DNS key per the MCP spec): `{ asOf, maxAgeMs }` or
+  `{ asOf, freshUntil }` (both allowed; the earlier deadline wins).
+  `asOf`/`freshUntil` are epoch milliseconds or ISO 8601 strings with a
+  timezone. Every successful `tools/call` carrying it gets:
+  - span attributes `mcp.tool.freshness.verdict` (`fresh` | `stale` |
+    `unknown`), `.data_age_ms`, `.max_age_ms`, `.limit_source`
+    (`max_age_ms` | `fresh_until` | `config`) and, for `unknown`,
+    `.unknown_reason` (`invalid_as_of` | `future_as_of` | `missing_window`
+    | `invalid_window`);
+  - `+1` on the new `mcp.tool.stale_responses` counter (label:
+    `gen_ai.tool.name` only) when stale.
+  - **Stale is not an error:** span status stays `OK`, no `error.type`,
+    never a silent failure, ToolOutcome stays `SUCCESS`.
+  - Responses without the key get no verdict and no attributes.
+    `isError: true` responses are skipped.
+  - Malformed input (epoch seconds, timezone-less ISO strings, negative
+    windows, `freshUntil` before `asOf`, `asOf` more than 5 s in the
+    future, throwing getters…) never throws: it yields `unknown` with a
+    reason and at most one `diag.warn` per tool.
+  - Only `asOf`, `maxAgeMs` and `freshUntil` under that one key are read;
+    content and other `_meta` fields are never read for this, and raw
+    values never reach spans, metrics or logs (canary-tested).
+- **`staleness` option.** `staleness.tools[toolName].maxAgeMs` overrides a
+  tool's own window (config can't supply `asOf`); `staleness.enabled:
+  false` turns the feature off. On by default, which is a no-op for tools
+  that don't report freshness.
+- **Types:** `FRESHNESS_META_KEY`, `FreshnessMeta` (autocomplete for the
+  `_meta` value), `FreshnessTimestamp`, `FreshnessVerdict`, and
+  `InstrumentOptions.staleness`.
+
+### Security
+
+- **Credentials are scrubbed from recorded exceptions, in every mode.**
+  Bearer and Basic tokens, AWS access key ids, `sk-`/`sk-proj-`/`sk-ant-`,
+  Stripe, `ghp_`/`github_pat_`, Slack `xox…` and Google `AIza…` keys, JWTs,
+  passwords in URLs (`https://user:<password>@host`), and the values of keys like
+  `token=`, `api_key=`, `access_token=`, `password=`, `client_secret` are
+  replaced with `<SECRET>`. Ordinary words and ids (`token expired`, UUIDs,
+  commit hashes) are left alone.
+- **Behavior change: the default `errorRecording.mode: 'full'` is no
+  longer raw and uncapped.** It still records the error's type, message and
+  stack, keeping ids, paths, URLs and line numbers, but with credentials
+  scrubbed as above, the message capped at 4096 characters and the stack at
+  16384 (a ` …[truncated by opentel-mcp]` marker shows where).
+  `exception.type` is capped at 128 characters, as in `'normalized'` mode.
+  Ordinary errors are recorded exactly as before. There is no switch back
+  to unscrubbed output. To record *less*, use `'normalized'`, `'none'`, or
+  a `redactor`.
+- **Fingerprints change only for errors that contain a credential.** The
+  same patterns now run first in `'normalized'` mode and in fingerprinting,
+  so two errors that differ only by a leaked token now share one
+  fingerprint (before, each token value made its own). Expect a one-time
+  regrouping of those errors only.
+- A thrown value whose properties throw when read (e.g. a throwing
+  `message` getter) now still marks the span `ERROR`; before, the span was
+  left with no status.
+- New test: one canary test runs every feature at once (fingerprinting,
+  cost and budget, thrash, schema drift, unactionable errors,
+  resources/prompts coverage, staleness) on SDK v1 and v2, `Server` and
+  `McpServer`, and checks that no tool argument, result content, `_meta`
+  value, resource URI, prompt argument or request `_meta` reaches any span,
+  metric or diag log. Nothing leaked; no code change was needed.
+- New `SECURITY.md` at the repository root: private vulnerability reporting
+  and what the library does and doesn't record.
+
+### Changed
+
+- The cost extractor and staleness detection now read `result._meta`
+  through one shared accessor (`src/result-meta.js`). Extraction behavior is
+  unchanged.
+- Dev-mode metrics (`setupNodeSdk: true`) print 13 instruments, up from 12.
+- README examples and `examples/hello-mcpserver` use `registerTool()`
+  instead of the deprecated `server.tool()`.
+- README's configuration table now lists `unactionableErrors`, `coverage`
+  and `staleness`; the misplaced `unactionableErrors` doc comment in
+  `index.d.ts` is back on its own option.
+- Test: the flush-on-exit "capped at 1000 ms" check now allows up to 5 s
+  (half the uncapped 10 s), so a loaded CI runner can't fail it.
+
 ## 0.16.0
 
 Finishes what 0.15 started. Telemetry now survives the way MCP clients

package/README.md

@@ -77,7 +77,7 @@ import { z } from 'zod';
 
 const server = new McpServer({ name: 'my-server', version: '1.0.0' });
 
-// Wraps every tool registered below. Must run BEFORE server.tool() —
+// Wraps every tool registered below. Must run BEFORE server.registerTool() —
 // see "Ordering constraint" below for why.
 instrumentMcpServer(server, {
   serviceName: 'my-mcp-server', // shows up on your traces
@@ -85,7 +85,7 @@ instrumentMcpServer(server, {
 });
 
 // A normal tool, registered exactly as usual.
-server.tool('echo', { text: z.string() }, async ({ text }) => ({
+server.registerTool('echo', { inputSchema: { text: z.string() } }, async ({ text }) => ({
   content: [{ type: 'text', text: `you said: ${text}` }],
 }));
 
@@ -300,7 +300,7 @@ problem" above) — exactly like the quickstart's `echo` tool, but with
 `isError: true` added and no `throw` involved:
 
 ```js
-server.tool('fetch_weather', { city: z.string() }, async ({ city }) => ({
+server.registerTool('fetch_weather', { inputSchema: { city: z.string() } }, async ({ city }) => ({
   isError: true,
   content: [{ type: 'text', text: `couldn't reach the weather service for ${city}` }],
 }));
@@ -399,11 +399,12 @@ The four base `mcp.tool.*` call/duration metrics below, via
 registered — **except under `setupNodeSdk: true`, which registers one for
 you (v0.15.0+); see "Dev-mode metrics" below.** Set `enableMetrics: false`
 to opt out even when one is (dev-mode included); tracing is unaffected
-either way. Source of truth: `src/metrics.js`. Twelve metrics exist
-across the library in total — this section's four, plus two cost/token
-metrics ("Cost & Token Attribution" below), five Agent Thrash Detection
-metrics ("Agent Thrash Detection" below), and one schema-drift metric
-("Tool schema drift detection" below).
+either way. Source of truth: `src/metrics.js`. Thirteen `mcp.tool.*`
+metrics exist across the library in total — this section's four, plus two
+cost/token metrics ("Cost & Token Attribution" below), five Agent Thrash
+Detection metrics ("Agent Thrash Detection" below), one schema-drift metric
+("Tool schema drift detection" below), and `mcp.tool.stale_responses`
+("Staleness detection" below).
 
 | Metric | Type | Unit | Attributes | Emitted when |
 |---|---|---|---|---|
@@ -579,6 +580,181 @@ See `dashboards/grafana-mcp-health.json` and `dashboards/dev/` in the repo
 for a full worked example (dashboard JSON + a script that exercises this
 exact setup end to end).
 
+## Staleness detection (v0.17.0)
+
+A read tool can return data older than it should be: a quote from four
+minutes ago, yesterday's bars after today's session opened. The call
+succeeds, the span is green, and the agent acts on stale data with full
+confidence. opentel-mcp can flag that, if the tool says how fresh its data
+is. The tool is the source of truth, because only it knows its own data
+cadence. Config is only an override. (Suggested by the r/mcp community.)
+
+**It's opt-in, per tool.** A tool adds one key to its result's `_meta`:
+
+```js
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { instrumentMcpServer, FRESHNESS_META_KEY } from 'opentel-mcp';
+import { z } from 'zod';
+
+const server = new McpServer({ name: 'market-data', version: '1.0.0' });
+
+// Before any registerTool() call.
+instrumentMcpServer(server, {
+  serviceName: 'market-data',
+  setupNodeSdk: true, // dev mode: prints spans to stderr
+});
+
+// Stand-in for your real feed. This quote is 4 minutes old.
+async function fetchQuote(symbol) {
+  return { symbol, price: 101.5, timestamp: Date.now() - 4 * 60_000 };
+}
+
+server.registerTool(
+  'get_quote',
+  { description: 'Latest quote for a symbol', inputSchema: { symbol: z.string() } },
+  async ({ symbol }) => {
+    const quote = await fetchQuote(symbol);
+    return {
+      content: [{ type: 'text', text: JSON.stringify(quote) }],
+      _meta: {
+        [FRESHNESS_META_KEY]: {
+          asOf: quote.timestamp, // when the data is from: epoch ms, or ISO 8601 with a timezone
+          maxAgeMs: 5_000, // a quote is fresh for 5 seconds
+        },
+      },
+    };
+  },
+);
+
+await server.connect(new StdioServerTransport());
+```
+
+Save it as `server.js` and send it one call:
+
+```bash
+echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_quote","arguments":{"symbol":"ACME"}}}' | node server.js
+```
+
+The span on stderr (from a real run) is still `OK`, and now says why the
+answer shouldn't be trusted:
+
+```
+name: 'tools/call get_quote'
+attributes: {
+  ...
+  'mcp.tool.freshness.verdict': 'stale',
+  'mcp.tool.freshness.data_age_ms': 240001,
+  'mcp.tool.freshness.max_age_ms': 5000,
+  'mcp.tool.freshness.limit_source': 'max_age_ms'
+},
+status: { code: 1 }   // OK: stale data isn't an error
+[opentel-mcp metrics] mcp.tool.stale_responses{gen_ai.tool.name=get_quote} = 1
+```
+
+### The `_meta` contract
+
+`FRESHNESS_META_KEY` is `'io.github.thirumalaiboobathi.opentel-mcp/freshness'`
+(a reverse-DNS key, as the MCP spec recommends for custom `_meta` keys).
+Its value:
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `asOf` | epoch **milliseconds**, or ISO 8601 string **with** `Z`/`±hh:mm` | When the data is from (the quote's timestamp, the bar's close), not when the tool ran. Required. |
+| `maxAgeMs` | number ≥ 0 | How long the data stays fresh. |
+| `freshUntil` | same as `asOf` | An absolute deadline, for windows that aren't a fixed duration. |
+
+Give `asOf` plus `maxAgeMs`, `freshUntil`, or both. With both, the
+**earlier deadline wins**. For data that's good until the trading session
+closes:
+
+```js
+_meta: {
+  [FRESHNESS_META_KEY]: {
+    asOf: bars.closeTime,              // '2026-10-12T20:00:00Z'
+    freshUntil: nextSessionClose,      // '2026-10-13T20:00:00Z'
+  },
+},
+```
+
+TypeScript users get autocomplete from the exported `FreshnessMeta` type:
+`{ asOf, maxAgeMs } satisfies FreshnessMeta`.
+
+### Overriding a tool's window from config
+
+```js
+instrumentMcpServer(server, {
+  staleness: {
+    tools: {
+      get_quote: { maxAgeMs: 2_000 }, // replaces get_quote's own maxAgeMs/freshUntil
+    },
+  },
+});
+```
+
+The override replaces the tool's window entirely (`limit_source` becomes
+`config`). It can't supply `asOf`: a response without the freshness key
+gets no verdict, whatever the config says. An invalid value (negative,
+non-finite) is ignored with one `diag.warn`. `staleness: { enabled: false }`
+turns the whole feature off.
+
+### What gets emitted
+
+| Attribute | Type | When |
+| --- | --- | --- |
+| `mcp.tool.freshness.verdict` | `fresh` \| `stale` \| `unknown` | The tool sent the freshness key |
+| `mcp.tool.freshness.data_age_ms` | integer ms | `asOf` was readable |
+| `mcp.tool.freshness.max_age_ms` | integer ms | A verdict exists: the effective window (deadline minus `asOf`) |
+| `mcp.tool.freshness.limit_source` | `max_age_ms` \| `fresh_until` \| `config` | A verdict exists |
+| `mcp.tool.freshness.unknown_reason` | `invalid_as_of` \| `future_as_of` \| `missing_window` \| `invalid_window` | Verdict is `unknown` |
+
+Plus one counter, `mcp.tool.stale_responses` (label: `gen_ai.tool.name`),
+`+1` per stale response.
+
+- **Tools that don't report freshness get nothing.** No attribute, no
+  verdict; never `fresh`, never `stale`. Their spans are unchanged.
+- **Stale isn't an error.** Span status stays `OK`, there's no
+  `error.type`, and it's never counted as a silent failure. Alert on the
+  verdict or the counter, not on error rate.
+- **`isError: true` responses are skipped.** They're already failures.
+- **Malformed freshness never breaks a call.** It gets `unknown` with a
+  reason, at most one `diag.warn` per tool, and the result goes back to
+  the client untouched. Common mistakes it catches: epoch **seconds**
+  instead of milliseconds, an ISO string with no timezone, `asOf` more than
+  5 s in the future (up to 5 s is treated as clock skew), and `freshUntil`
+  before `asOf`.
+- **Privacy:** only `asOf`, `maxAgeMs` and `freshUntil` under that one key
+  are read. Result content and other `_meta` fields are never read for
+  this, and raw values are never emitted, only the derived numbers
+  (checked by a canary test in `test/staleness.test.js`).
+- **Data age is span-only**, never a metric label.
+
+### Seeing it in the dashboard
+
+`opentel-mcp-ui` 0.3.0+ shows the data age in its feed, a **Stale data**
+filter, and stale rate as a fifth health-grade signal. Start it, then point
+the server above at it with one more option:
+
+```bash
+npx opentel-mcp-ui    # dashboard at http://127.0.0.1:4319
+```
+
+```js
+instrumentMcpServer(server, {
+  serviceName: 'market-data',
+  setupNodeSdk: true,
+  exporterUrl: 'http://127.0.0.1:4319/v1/traces', // send spans to the dashboard too
+});
+```
+
+Each run of the `echo … | node server.js` command above now shows up in the
+dashboard's feed and under **Stale data**. The tool gets a grade once it has
+10 calls, and the stale-data signal joins it once 10 of those carried a
+`fresh` or `stale` verdict, so send the command ten times. With every call
+stale, `get_quote` grades **F**, "set by stale data 100% (F)".
+
+Design and every edge case: [ADR 027](../../docs/adr/027-staleness-detection.md).
+
 ## Failure Fingerprinting (v0.4.0+)
 
 Groups logically identical failures under one stable identifier, even
@@ -663,7 +839,11 @@ per-call-site wrapping; tracked in the roadmap below.
 **What this controls, and who needs it.** Whenever a `tools/call`/
 `tools/list` handler throws, this library records the thrown error's
 message and stack trace onto the span it creates for that call — by
-default, exactly as the tool wrote them, no redaction. If your tools call
+default, as the tool wrote them, except that recognizable credentials
+(Bearer/Basic tokens, AWS key ids, `sk-`/`ghp_`/`xox…` API keys, JWTs,
+passwords in URLs, `token=`/`api_key=`/`password=` values) are replaced
+with `<SECRET>` and the message and stack are capped at 4096 and 16384
+characters (v0.17.0). If your tools call
 third-party services, wrap unaudited dependencies, or you otherwise don't
 control every string a tool might throw, that's a real channel for
 whatever those errors happen to contain (an email address, an internal
@@ -683,7 +863,7 @@ span:
 
 | Mode | `exception.message` / status message | `exception.stacktrace` | When to use |
 |---|---|---|---|
-| `'full'` (default) | Raw `err.message`, unmodified | Raw `err.stack`, unmodified | Today's behavior, unchanged — matches what every other OTel-instrumented library in the same trace does for the same kind of event |
+| `'full'` (default) | Raw `err.message`, credentials → `<SECRET>`, capped at 4096 chars (v0.17.0) | Raw `err.stack`, same scrubbing, capped at 16384 chars | Everything else kept: ids, paths, URLs, line numbers. Before v0.17.0 both were unmodified |
 | `'normalized'` | `normalizeMessage(err.message)` — the exact scrubbing pipeline (`src/fingerprint/normalize/message.js`) fingerprinting already runs before hashing: UUIDs, emails, URLs, IPs, timestamps, filesystem paths, hex runs, quoted ids | Reconstructed from `parseAndNormalizeStack()` (`src/fingerprint/normalize/stack.js`) — keeps every function name/file/line, strips only the local `cwd` prefix (and collapses `node_modules` package versions) | Tool results come from third-party or unaudited MCP servers and you want the same scrubbing fingerprinting already trusts, applied to the raw exception content too |
 | `'none'` | Not set — `span.setStatus({ code: ERROR })` with no message, the same pattern already used for tool-level `isError: true` failures | Not set | You rely entirely on `mcp.failure.*` (category/fingerprint/signature — already hashed/normalized) and don't want any free-text exception content on the span at all |
 
@@ -2221,11 +2401,13 @@ found')`, or a tool result puts a credential in a field this library
 reads, that content is exactly what reaches your telemetry backend. Three
 channels carry it:
 
-- **`span.recordException(err)` / `span.setStatus({ message })`** on every
+- **The `exception` event / `span.setStatus({ message })`** on every
   thrown `tools/call`/`tools/list` error — `exception.message` and
-  `exception.stacktrace` are set from `err.message`/`err.stack` verbatim
-  by default. `errorRecording.mode` controls this; see "Error recording"
-  above.
+  `exception.stacktrace` are set from `err.message`/`err.stack` by
+  default, with recognizable credentials replaced by `<SECRET>` and
+  lengths capped (v0.17.0), but otherwise unchanged: a customer's name or
+  any other free text in a message still reaches the span.
+  `errorRecording.mode` controls this; see "Error recording" above.
 - **`mcp.tool.model` / `gen_ai.response.model`** — a tool result's own
   declared model field, admitted once it passes a length/character-shape
   check (v0.13.0). The check bounds shape, not content: a well-formed but
@@ -2319,9 +2501,10 @@ so they're spelled out instead of forced into one bucket.
 | `mcp.failure.fingerprint` / `.signature` / `.category` / `.origin` / `.channel` | span attr (2 also metric labels) | library-computed | hashes/enums — the governed core this project has kept clean since v0.4.0 |
 | `mcp.failure.error_class` | span attr | **blend — tool-controlled, capped only** | `err.name`, length-capped at 128 characters but, unlike everything hashed into the fingerprint, *not* pattern-scrubbed — a documented, deliberate tradeoff (`docs/known-gaps.md` entry 10) |
 | `mcp.failure.unactionable` / `.content_length_bucket` | span attr | library-computed | a boolean and a 5-value enum derived from the trimmed text LENGTH and non-text item COUNT of an `isError: true` result — no text is read for anything but its length (ADR 025, v0.16.0) |
+| `mcp.tool.freshness.verdict` / `.data_age_ms` / `.max_age_ms` / `.limit_source` / `.unknown_reason` | span attr | library-computed | enums and integer ms derived from the tool's own `_meta[FRESHNESS_META_KEY]` `asOf`/`maxAgeMs`/`freshUntil`; raw values are never emitted, and no other `_meta` field or content is read (ADR 027, v0.17.0) |
 | `mcp.failure.validation_paths` | span attr | mostly library-computed (gated) | one legacy Zod-issue-rendering path can still carry a tool-controlled dynamic object key, now redacted to a `<KEY>` placeholder rather than closed structurally (`docs/known-gaps.md` entry 10, item 3) |
-| `exception.type` (event) | event attr | tool-controlled | length-capped only under `'normalized'` mode; uncapped under `'full'` (the native SDK call) |
-| `exception.message` / `.stacktrace` (event), status message | event attr + status | **blend — layered** | raw tool content under `'full'`; this library's `normalizeMessage()`/`parseAndNormalizeStack()` transform of that same content under `'normalized'`; optionally a host-supplied `errorRecording.redactor`'s output feeding *that*, first (v0.14.0) — the most layered-provenance attribute in the system |
+| `exception.type` (event) | event attr | tool-controlled | length-capped at 128 characters under both `'full'` and `'normalized'` (v0.17.0) |
+| `exception.message` / `.stacktrace` (event), status message | event attr + status | **blend — layered** | raw tool content under `'full'`, minus recognizable credentials and length-capped (v0.17.0); this library's `normalizeMessage()`/`parseAndNormalizeStack()` transform of that same content under `'normalized'`; optionally a host-supplied `errorRecording.redactor`'s output feeding *that*, first (v0.14.0) — the most layered-provenance attribute in the system |
 | `mcp.tool.schema_drift_detected` / `mcp.tool.thrash_detected` | boolean span attr | library-computed | only ever set to `true`; omitted on a clean call |
 | `mcp.tool.schema_drift.type` | event attr, metric label | library-computed | classifier enum |
 | `mcp.tool.schema_drift.previous_hash` / `.current_hash` | event attr | library-computed | a hash *of* tool-controlled content (the tool's own `inputSchema`), not the schema itself |
@@ -2399,6 +2582,9 @@ truth: `src/config.js`.
 | `thrashDetection` | object | see below | Controls Agent Thrash Detection[^10] — see "Agent Thrash Detection" above. Requires `fingerprinting: true` |
 | `schemaDrift` | object | see below | Controls tool schema drift detection[^11] — see "Tool schema drift detection" above. `enabled: true` by default changes `instrumentMcpServer()`'s throw behavior on upgrade — see that section's "Behavior change on upgrade" |
 | `errorRecording` | object | see below | Controls what raw exception content reaches `recordException()`/`setStatus()`[^12] — see "Error recording" above |
+| `unactionableErrors` | object | `{ enabled: true, minTextLength: 10 }` | `{ enabled?, minTextLength? }`: flags `isError: true` results with no usable text via `mcp.failure.unactionable` / `mcp.failure.content_length_bucket` (span-only). Env: `OTEL_MCP_UNACTIONABLE_ERRORS_ENABLED`, `OTEL_MCP_UNACTIONABLE_ERRORS_MIN_TEXT_LENGTH` — see "Errors your agent can't act on" above |
+| `coverage` | object | `{ resources: false, prompts: false }` | Opt-in tracing of `resources/*` and `prompts/*` — see "Resources and prompts" above |
+| `staleness` | object | `{ enabled: true }` | `{ enabled?, tools?: { [toolName]: { maxAgeMs } } }`: per-tool override of the freshness window a tool reports in `_meta` — see "Staleness detection" above |
 
 [^10]: `{ enabled?, threshold?, windowMs?, maxTrackedKeys?, entryTtlMs?, reEmitAfter?, assumeSingleSession? }`, all fields optional, individually defaulted, and individually overridable via an `OTEL_MCP_THRASH_*` env var — see "Agent Thrash Detection" → "Configuration" above for the full table.
 [^11]: `{ enabled?, maxTrackedTools? }`, all fields optional, individually defaulted, and individually overridable via an `OTEL_MCP_SCHEMA_DRIFT_*` env var — see "Tool schema drift detection" → "Configuration" above for the full table.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opentel-mcp",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "One-line OpenTelemetry instrumentation for Model Context Protocol (MCP) servers",
   "type": "module",
   "main": "src/index.js",

package/src/config.js

@@ -12,6 +12,7 @@ import { resolveSchemaDriftConfig } from './schema-drift/config.js';
 import { resolveErrorRecordingConfig } from './error-recording/config.js';
 import { resolveFlushTimeout } from './flush-on-exit.js';
 import { resolveUnactionableErrorsConfig } from './unactionable.js';
+import { resolveStalenessConfig } from './staleness.js';
 
 /**
  * @typedef {object} CostTrackingOptions
@@ -91,8 +92,9 @@ import { resolveUnactionableErrorsConfig } from './unactionable.js';
  *   what a THROWN exception (not a tool-level `isError: true` result, which never carries a JS Error and is
  *   unaffected) puts on the mcp.tool.call / tools/list span (ADR 019, docs/adr/019-raw-content-on-spans.md
  *   Part 1, v0.13.0): `{ mode: 'full' | 'normalized' | 'none' }`. Defaults to `{ mode: 'full' }` —
- *   byte-identical to every release before v0.13.0 (span.recordException(err) plus setStatus({ message:
- *   err.message }), uncapped). `'normalized'` reuses fingerprint/normalize/message.js's normalizeMessage()
+ *   the exception event span.recordException(err) would record plus setStatus({ message }), with credentials
+ *   scrubbed (fingerprint/normalize/secrets.js) and the message/stack capped at 4096/16384 characters (v0.17.0;
+ *   raw and uncapped before that). `'normalized'` reuses fingerprint/normalize/message.js's normalizeMessage()
  *   for the exception message and fingerprint/normalize/stack.js's parseAndNormalizeStack() for the
  *   stacktrace (cwd-stripped, node_modules-version-collapsed) — no new scrubbing pipeline. `'none'` sets
  *   only the ERROR status code, no message, no exception event — the same pattern already used for a
@@ -117,6 +119,12 @@ import { resolveUnactionableErrorsConfig } from './unactionable.js';
  *   (default 10) characters of text with no image/audio/resource item. `{ enabled: true, minTextLength: 10 }`
  *   by default; independent of `fingerprinting`. Span-only: never a metric label. Also settable via
  *   `OTEL_MCP_UNACTIONABLE_ERRORS_ENABLED` / `OTEL_MCP_UNACTIONABLE_ERRORS_MIN_TEXT_LENGTH` (lower precedence).
+ * @property {{ enabled?: boolean, tools?: Record<string, { maxAgeMs: number }> }} [staleness] - ADR 027
+ *   (docs/adr/027-staleness-detection.md): a tool reports freshness in
+ *   `result._meta['io.github.thirumalaiboobathi.opentel-mcp/freshness']` (`{ asOf, maxAgeMs | freshUntil }`) and
+ *   successful responses get `mcp.tool.freshness.*` span attributes plus the `mcp.tool.stale_responses`
+ *   counter. `tools[name].maxAgeMs` overrides that tool's own window (config can't supply `asOf`). On by
+ *   default; tools that don't report freshness are untouched. A stale response is NOT an error.
  * @property {{ resources?: boolean, prompts?: boolean }} [coverage] - ADR 026 (docs/adr/026-resources-prompts-coverage.md),
  *   opt-in, both off by default: also trace `resources/read`, `resources/list`, `resources/templates/list`
  *   (`resources: true`) and `prompts/get`, `prompts/list` (`prompts: true`). Spans are named by method
@@ -350,5 +358,6 @@ export function resolveOptions(options) {
     flushOnExit: setupNodeSdk ? resolveFlushOnExit(opts.flushOnExit) : null,
     unactionableErrors: resolveUnactionableErrorsConfig(opts.unactionableErrors),
     coverage: resolveCoverage(opts.coverage),
+    staleness: resolveStalenessConfig(opts.staleness),
   };
 }

package/src/cost/extractor.js

@@ -11,6 +11,7 @@
  */
 
 import { diag } from '@opentelemetry/api';
+import { isPlainObject, readResultMetaField } from '../result-meta.js';
 
 /**
  * @typedef {Object} TokenUsage
@@ -35,14 +36,6 @@ const TOKEN_FIELD_PAIRS = [
   ['inputTokens', 'outputTokens'],
 ];
 
-/**
- * @param {unknown} value
- * @returns {value is Record<string, unknown>}
- */
-function isPlainObject(value) {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
 /**
  * @param {unknown} value
  * @returns {value is number}
@@ -84,7 +77,7 @@ function readModel(root) {
   const candidates = [
     root.model,
     isPlainObject(root.usage) ? root.usage.model : undefined,
-    isPlainObject(root._meta) ? root._meta.model : undefined,
+    readResultMetaField(root, 'model'),
   ];
 
   for (const candidate of candidates) {
@@ -176,10 +169,8 @@ export function defaultExtractor(toolResult) {
       if (fromParsedRoot) return fromParsedRoot;
     }
 
-    if (isPlainObject(toolResult._meta)) {
-      const fromMeta = buildUsage(toolResult._meta.usage, toolResult);
-      if (fromMeta) return fromMeta;
-    }
+    const fromMeta = buildUsage(readResultMetaField(toolResult, 'usage'), toolResult);
+    if (fromMeta) return fromMeta;
 
     return null;
   } catch (error) {

package/src/error-recording/types.d.ts

@@ -62,12 +62,14 @@ export interface ErrorRecordingConfig {
    * unaffected by this option) puts on the `tools/call`/`tools/list`
    * span, per ADR 019 Part 1:
    *
-   * - `'full'` — `span.recordException(err)` plus `span.setStatus({
-   *   message: err.message })`, exactly as every release before
-   *   v0.13.0. `exception.message`/`exception.stacktrace` carry
-   *   `err.message`/`err.stack` verbatim, uncapped — matching the OTel
-   *   ecosystem's own default (see ADR 019's "What OpenTelemetry's own
-   *   semantic conventions say").
+   * - `'full'` — the same `exception` event `span.recordException(err)`
+   *   records, plus `span.setStatus({ message })`, from the raw
+   *   `err.message`/`err.stack` (ids, paths, URLs kept). Since v0.17.0,
+   *   credentials (Bearer/Basic tokens, AWS key ids, `sk-`/`ghp_`/`xox…`
+   *   keys, JWTs, URL passwords, `token=`/`api_key=`/`password=` values)
+   *   are replaced with `<SECRET>`, and the message/stack are capped at
+   *   4096/16384 characters. Before v0.17.0 they were verbatim and
+   *   uncapped.
    * - `'normalized'` — the same `exception` event shape, but
    *   `exception.message` is run through `normalizeMessage()`
    *   (`src/fingerprint/normalize/message.js` — the same

package/src/fingerprint/normalize/message.js

@@ -7,6 +7,7 @@
  */
 
 import { NORMALIZE_STEPS } from './patterns.js';
+import { scrubSecrets } from './secrets.js';
 
 // Exported as of v0.14.0 (ADR 020, docs/adr/020-redactor-hook.md, Decision
 // 5): errorRecording.redactor's own defensive output cap reuses this exact
@@ -26,7 +27,9 @@ export const MAX_INPUT_LENGTH = 2048;
  *   this again on its own output returns the same string.
  */
 export function normalizeMessage(raw) {
-  let result = raw.slice(0, MAX_INPUT_LENGTH);
+  // Credentials first (v0.17.0): a leaked token must neither reach the
+  // span nor split one error into a fingerprint per token value.
+  let result = scrubSecrets(raw.slice(0, MAX_INPUT_LENGTH));
   for (const { pattern, replacement } of NORMALIZE_STEPS) {
     result = result.replace(pattern, replacement);
   }

package/src/fingerprint/normalize/secrets.js

@@ -0,0 +1,93 @@
+/**
+ * @module fingerprint/normalize/secrets
+ *
+ * Credential scrubbing for error text (v0.17.0). Runs FIRST in
+ * normalizeMessage() (so fingerprints group by error shape rather than by
+ * leaked token) and is also applied, on its own, to `errorRecording.mode:
+ * 'full'` exception messages and stacks (instrument.js's
+ * recordThrownException()), which otherwise keep their ids, paths and URLs.
+ *
+ * Every pattern targets a recognizable credential SHAPE: a known prefix
+ * (AKIA, sk-, ghp_, xoxb-, eyJ…eyJ…), an auth scheme followed by a long
+ * token, credentials embedded in a URL, or a value assigned to a key whose
+ * name says it's a secret. Plain words, UUIDs, hashes and ordinary ids are
+ * deliberately left alone. This is not a general-purpose PII filter.
+ */
+
+/** What every scrubbed value is replaced with. */
+export const SECRET_PLACEHOLDER = '<SECRET>';
+
+// Key names whose value is a secret. Matched case-insensitively, as a
+// whole word (so `tokenizer=` or `secretary:` don't match).
+const SECRET_KEY_NAMES =
+  '(?:access[_-]?token|refresh[_-]?token|id[_-]?token|auth[_-]?token|token|x-api-key|api[_-]?key|apikey|' +
+  'client[_-]?secret|secret[_-]?key|secret|password|passwd|pwd|private[_-]?key|aws[_-]?secret[_-]?access[_-]?key|' +
+  'credentials?|signature|sig)';
+
+/** @type {readonly { pattern: RegExp, replacement: string }[]} */
+export const SECRET_STEPS = Object.freeze([
+  // Credentials inside a URL: scheme://<user>:<password>@host -> scheme://<SECRET>@host.
+  {
+    pattern: /\b([a-zA-Z][a-zA-Z0-9+.-]*:\/\/)[^\s/?#@"'<>:]+:[^\s/?#@"'<>]+@/g,
+    replacement: `$1${SECRET_PLACEHOLDER}@`,
+  },
+
+  // JSON Web Token: three base64url segments, the first two JSON objects ("eyJ").
+  {
+    pattern: /\beyJ[A-Za-z0-9_-]{5,}\.eyJ[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{10,}/g,
+    replacement: SECRET_PLACEHOLDER,
+  },
+
+  // HTTP auth schemes followed by a credential of at least 16 characters
+  // ("Bearer token missing" has no such credential and is left alone).
+  {
+    pattern: /\b(Bearer|Basic)\s+[A-Za-z0-9\-._~+/]{16,}=*/gi,
+    replacement: `$1 ${SECRET_PLACEHOLDER}`,
+  },
+
+  // AWS access key ids.
+  {
+    pattern: /\b(?:AKIA|ASIA|ABIA|ACCA)[0-9A-Z]{16}\b/g,
+    replacement: SECRET_PLACEHOLDER,
+  },
+
+  // Provider-prefixed API keys: OpenAI/Anthropic (sk-, sk-proj-, sk-ant-),
+  // Stripe (sk_live_/rk_test_…), GitHub (ghp_/gho_/ghu_/ghs_/ghr_,
+  // github_pat_), Slack (xoxa-/xoxb-/xoxp-/xoxr-/xoxs-), Google (AIza…).
+  {
+    pattern:
+      /\b(?:sk-(?:ant-|proj-)?[A-Za-z0-9_-]{20,}|[sr]k_(?:live|test)_[A-Za-z0-9]{16,}|gh[pousr]_[A-Za-z0-9]{30,}|github_pat_[A-Za-z0-9_]{20,}|xox[abprs]-[A-Za-z0-9-]{10,}|AIza[0-9A-Za-z_-]{35})/g,
+    replacement: SECRET_PLACEHOLDER,
+  },
+
+  // A secret-named key in a query string or assignment: ?token=…, &api_key=…,
+  // password=…, "client_secret": "…". `=` always counts; `:` only when the
+  // value is quoted or contains a digit, so "token: expired" stays readable.
+  {
+    pattern: new RegExp(`\\b(${SECRET_KEY_NAMES})(=)(["']?)[^\\s&"',;)]+`, 'gi'),
+    replacement: `$1$2$3${SECRET_PLACEHOLDER}`,
+  },
+  {
+    pattern: new RegExp(`\\b(${SECRET_KEY_NAMES})(["']?\\s*:\\s*)(["'])[^"'\\n]+\\3`, 'gi'),
+    replacement: `$1$2$3${SECRET_PLACEHOLDER}$3`,
+  },
+  {
+    pattern: new RegExp(`\\b(${SECRET_KEY_NAMES})(\\s*:\\s*)(?=[^\\s,;]*\\d)[^\\s,;]{4,}`, 'gi'),
+    replacement: `$1$2${SECRET_PLACEHOLDER}`,
+  },
+]);
+
+/**
+ * Replaces recognizable credentials in `text` with {@link SECRET_PLACEHOLDER}.
+ * Leaves everything else exactly as it was. Never throws on a string.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+export function scrubSecrets(text) {
+  let result = text;
+  for (const { pattern, replacement } of SECRET_STEPS) {
+    result = result.replace(pattern, replacement);
+  }
+  return result;
+}

package/src/index.d.ts

@@ -62,7 +62,7 @@ export interface InstrumentOptions {
    * **Also stands up a dev-mode `MeterProvider` (ADR 023,
    * `docs/adr/023-dev-mode-metrics.md`, v0.15.0+)**, gated additionally by
    * `enableMetrics` (above, default `true`): a `PeriodicExportingMetricReader`
-   * exporting all 12 `mcp.tool.*`/`mcp.tool.loop.*`/`mcp.tool.schema_drift.*`
+   * exporting all 13 `mcp.tool.*`/`mcp.tool.loop.*`/`mcp.tool.schema_drift.*`
    * instruments to stderr every 5 seconds, in a compact
    * `name{attrs} = value` format — never `@opentelemetry/sdk-metrics`'
    * own `ConsoleMetricExporter`, which writes to stdout and would corrupt
@@ -104,20 +104,6 @@ export interface InstrumentOptions {
    */
   flushOnExit?: boolean | { timeoutMs?: number };
 
-  /**
-   * ADR 025: on every `isError: true` result, sets the span attributes
-   * `mcp.failure.unactionable` (boolean) and
-   * `mcp.failure.content_length_bucket` (`'empty' | 'tiny' | 'short' |
-   * 'medium' | 'long'`). Computed only from the whitespace-trimmed length of
-   * the text items and the count of non-text items, never from the text
-   * itself. Unactionable means no content, or fewer than `minTextLength`
-   * characters of text with no image/audio/resource item. Span-only (never a
-   * metric label); independent of `fingerprinting`. Also settable via
-   * `OTEL_MCP_UNACTIONABLE_ERRORS_ENABLED` /
-   * `OTEL_MCP_UNACTIONABLE_ERRORS_MIN_TEXT_LENGTH` (lower precedence).
-   *
-   * @default { enabled: true, minTextLength: 10 }
-   */
   /**
    * ADR 026, opt-in (both off by default): also trace `resources/read`,
    * `resources/list`, `resources/templates/list` (`resources: true`) and
@@ -139,12 +125,51 @@ export interface InstrumentOptions {
     prompts?: boolean;
   };
 
+  /**
+   * ADR 025: on every `isError: true` result, sets the span attributes
+   * `mcp.failure.unactionable` (boolean) and
+   * `mcp.failure.content_length_bucket` (`'empty' | 'tiny' | 'short' |
+   * 'medium' | 'long'`). Computed only from the whitespace-trimmed length of
+   * the text items and the count of non-text items, never from the text
+   * itself. Unactionable means no content, or fewer than `minTextLength`
+   * characters of text with no image/audio/resource item. Span-only (never a
+   * metric label); independent of `fingerprinting`. Also settable via
+   * `OTEL_MCP_UNACTIONABLE_ERRORS_ENABLED` /
+   * `OTEL_MCP_UNACTIONABLE_ERRORS_MIN_TEXT_LENGTH` (lower precedence).
+   *
+   * @default { enabled: true, minTextLength: 10 }
+   */
   unactionableErrors?: {
     enabled?: boolean;
     /** Integer 0–200. `0` flags only empty (or whitespace-only) errors. @default 10 */
     minTextLength?: number;
   };
 
+  /**
+   * ADR 027 (docs/adr/027-staleness-detection.md): staleness detection. A
+   * tool reports how fresh its data is in
+   * `result._meta[FRESHNESS_META_KEY]` (see {@link FreshnessMeta}), and every
+   * successful `tools/call` that carries it gets `mcp.tool.freshness.*` span
+   * attributes (`verdict`: `fresh` | `stale` | `unknown`, `data_age_ms`,
+   * `max_age_ms`, `limit_source`, `unknown_reason`) and, when stale, `+1` on
+   * the `mcp.tool.stale_responses` counter (label: `gen_ai.tool.name`). A
+   * stale response is NOT an error: span status stays OK and it is never a
+   * silent failure. Tools that don't report freshness are untouched.
+   *
+   * @default { enabled: true }
+   */
+  staleness?: {
+    /** `false` turns the feature off: `_meta` isn't read. @default true */
+    enabled?: boolean;
+    /**
+     * Per-tool override of the freshness window, keyed by tool name. Replaces
+     * the tool's own `maxAgeMs`/`freshUntil`. Config can't supply `asOf`: a
+     * response without the freshness key still gets no verdict. An invalid
+     * value (negative, non-finite) is ignored with a `diag.warn`.
+     */
+    tools?: Record<string, { maxAgeMs: number }>;
+  };
+
   /**
    * Controls the `mcp.tool.tokens.*` / `mcp.tool.model` / `mcp.tool.cost.*` span attributes, the
    * `mcp.tool.tokens.total` / `mcp.tool.cost.total` metrics, and the optional per-session/per-tool budget
@@ -201,8 +226,9 @@ export interface InstrumentOptions {
    * `Error` and is unaffected by this option) puts on the `tools/call`/`tools/list` span (ADR 019,
    * `docs/adr/019-raw-content-on-spans.md` Part 1, v0.13.0).
    *
-   * Defaults to `{ mode: 'full' }` — byte-identical to every release before v0.13.0:
-   * `span.recordException(err)` plus `span.setStatus({ message: err.message })`, both uncapped.
+   * Defaults to `{ mode: 'full' }`: the exception event `span.recordException(err)` would record plus
+   * `span.setStatus({ message })`, from the raw message and stack but with credentials replaced by
+   * `<SECRET>` and the message/stack capped at 4096/16384 characters (v0.17.0; raw and uncapped before).
    * `'normalized'` reuses `normalizeException()` (`src/fingerprint/normalize/exception.js`) — the same
    * coercion + `normalizeMessage()`/`parseAndNormalizeStack()` step `computeFingerprint()`
    * (`src/fingerprint/compose.js`) uses for `mcp.failure.*` on the same `err` — for the exception message
@@ -546,3 +572,49 @@ export type { ErrorRecordingConfig, ErrorRecordingRedactor, ErrorRecordingRedact
 // not part of the public API.
 
 export type { ToolOutcome, ToolOutcomeCounts, ObservationIntegrity, ObservationState } from './observation/types.d.ts';
+
+// --- Staleness detection (ADR 027, src/staleness.js) ---
+
+/**
+ * The `result._meta` key a tool reports its data freshness under:
+ * `'io.github.thirumalaiboobathi.opentel-mcp/freshness'`. A reverse-DNS
+ * prefix, per the MCP spec's `_meta` key-name rules.
+ */
+export declare const FRESHNESS_META_KEY: 'io.github.thirumalaiboobathi.opentel-mcp/freshness';
+
+/** A timestamp: an ISO 8601 string WITH a timezone (`Z` or `±hh:mm`), or epoch milliseconds. */
+export type FreshnessTimestamp = string | number;
+
+/**
+ * The value a tool puts at `result._meta[FRESHNESS_META_KEY]`. `asOf` plus
+ * at least one of `maxAgeMs` / `freshUntil`; with both, the earlier
+ * deadline wins.
+ *
+ * @example
+ * return {
+ *   content: [{ type: 'text', text: JSON.stringify(quote) }],
+ *   _meta: {
+ *     [FRESHNESS_META_KEY]: { asOf: quote.timestamp, maxAgeMs: 5_000 } satisfies FreshnessMeta,
+ *   },
+ * };
+ */
+export type FreshnessMeta =
+  | {
+      /** When the data is from (not when the tool ran). */
+      asOf: FreshnessTimestamp;
+      /** How old the data may be and still count as fresh. Finite, >= 0. */
+      maxAgeMs: number;
+      /** Optional absolute deadline; the earlier of the two wins. */
+      freshUntil?: FreshnessTimestamp;
+    }
+  | {
+      /** When the data is from (not when the tool ran). */
+      asOf: FreshnessTimestamp;
+      /** Optional duration window; the earlier of the two wins. */
+      maxAgeMs?: number;
+      /** Absolute deadline, e.g. the close of the trading session. Not before `asOf`. */
+      freshUntil: FreshnessTimestamp;
+    };
+
+/** `mcp.tool.freshness.verdict`. */
+export type FreshnessVerdict = 'fresh' | 'stale' | 'unknown';

package/src/index.js

@@ -7,3 +7,5 @@ export { DEFAULT_CLASSIFIERS } from './fingerprint/classify/index.js';
 export { DEFAULT_PRICING, DEFAULT_PRICING_LAST_VERIFIED, isDefaultPricingStale } from './cost/pricing.js';
 export { defaultExtractor } from './cost/extractor.js';
 export { calculateCost } from './cost/calculator.js';
+
+export { FRESHNESS_META_KEY } from './staleness.js';

package/src/instrument.js

@@ -19,6 +19,7 @@ import { toSpanAttributes, ATTRIBUTE_KEYS } from './fingerprint/attributes.js';
 import { classifyFailureChannel } from './fingerprint/classify/channel.js';
 import { extractValidationPaths } from './fingerprint/classify/validation-paths.js';
 import { normalizeException, coerceError } from './fingerprint/normalize/exception.js';
+import { scrubSecrets } from './fingerprint/normalize/secrets.js';
 import { applyRedactor } from './error-recording/redactor.js';
 import { calculateCost, normalizeModelName, isValidModelId, describeInvalidModelId } from './cost/calculator.js';
 import { DEFAULT_PRICING_LAST_VERIFIED } from './cost/pricing.js';
@@ -33,6 +34,7 @@ import { detectObservationIntegrity } from './observation/integrity.js';
 import { InstanceRegistry } from './registry/instance-registry.js';
 import { registerFlushOnExit } from './flush-on-exit.js';
 import { applyUnactionableAttributes } from './unactionable.js';
+import { applyStaleness, createStalenessState } from './staleness.js';
 import {
   ATTR_MCP_METHOD_NAME,
   ATTR_GEN_AI_PROMPT_NAME,
@@ -514,6 +516,9 @@ export function instrumentMcpServer(input, options) {
   // not correctness-critical state, so a fresh instrumented server simply
   // gets a fresh warning budget rather than sharing one process-wide.
   const errorRecordingState = { warnedFailed: false };
+  // ADR 027: same "plain holder, not instanceKey-shared" reasoning — only
+  // the once-per-tool malformed-freshness warning lives here.
+  const stalenessState = createStalenessState();
   // Additive to instrumentMcpServer()'s existing return contract (the same
   // input object, for chaining — see this function's own docblock): a
   // getThrashSummary() method attached the same way shutdown() is, just
@@ -617,6 +622,8 @@ export function instrumentMcpServer(input, options) {
           costAttributionState,
           errorRecordingState,
           resolved.unactionableErrors,
+          resolved.staleness,
+          stalenessState,
         );
       } else if (schema === v1.ListToolsRequestSchema && schemaDriftDetector) {
         handler = wrapToolsListHandler(
@@ -677,6 +684,8 @@ export function instrumentMcpServer(input, options) {
           costAttributionState,
           errorRecordingState,
           resolved.unactionableErrors,
+          resolved.staleness,
+          stalenessState,
         );
       } else if (maybeHandler === undefined && method === TOOLS_LIST_METHOD && schemaDriftDetector) {
         handlerOrSchemas = wrapToolsListHandler(
@@ -1679,6 +1688,53 @@ function applyToolOutcomeThrown(toolOutcomeCounter) {
   }
 }
 
+/** v0.17.0: 'full' mode caps. Double 'normalized''s 2048-character message input, so 'full' stays the detailed mode. */
+export const MAX_FULL_EXCEPTION_MESSAGE_LENGTH = 4096;
+export const MAX_FULL_EXCEPTION_STACK_LENGTH = 16384;
+const TRUNCATION_MARKER = ' …[truncated by opentel-mcp]';
+
+/**
+ * @param {string} text
+ * @param {number} max
+ * @returns {string}
+ */
+function scrubAndCap(text, max) {
+  const scrubbed = scrubSecrets(text.length > max * 2 ? text.slice(0, max * 2) : text);
+  return scrubbed.length > max ? scrubbed.slice(0, max) + TRUNCATION_MARKER : scrubbed;
+}
+
+/**
+ * The 'full'-mode exception event, mirroring the installed SDK's own
+ * Span.recordException() (exception.type from `code`, else `name`;
+ * exception.message; exception.stacktrace), with scrubSecrets() applied
+ * and lengths capped. `attributes` is null when there is neither a type
+ * nor a message, where recordException() would also record nothing.
+ *
+ * @param {unknown} err
+ * @returns {{ attributes: Record<string, string> | null, statusMessage: string | undefined }}
+ */
+function describeFullException(err) {
+  /** @type {Record<string, string>} */
+  const attributes = {};
+  let statusMessage;
+  if (typeof err === 'string') {
+    attributes['exception.message'] = scrubAndCap(err, MAX_FULL_EXCEPTION_MESSAGE_LENGTH);
+  } else if (err) {
+    const e = /** @type {any} */ (err);
+    if (e.code) attributes['exception.type'] = String(e.code).slice(0, MAX_ERROR_CLASS_LENGTH);
+    else if (e.name) attributes['exception.type'] = String(e.name).slice(0, MAX_ERROR_CLASS_LENGTH);
+    if (typeof e.message === 'string' && e.message !== '') {
+      attributes['exception.message'] = scrubAndCap(e.message, MAX_FULL_EXCEPTION_MESSAGE_LENGTH);
+      statusMessage = attributes['exception.message'];
+    }
+    if (typeof e.stack === 'string' && e.stack !== '') {
+      attributes['exception.stacktrace'] = scrubAndCap(e.stack, MAX_FULL_EXCEPTION_STACK_LENGTH);
+    }
+  }
+  const hasAny = attributes['exception.type'] !== undefined || attributes['exception.message'] !== undefined;
+  return { attributes: hasAny ? attributes : null, statusMessage };
+}
+
 /**
  * Records a thrown exception onto `span` per `errorRecordingConfig.mode`
  * (ADR 019 Part 1, docs/adr/019-raw-content-on-spans.md, v0.13.0 Phase 1).
@@ -1689,12 +1745,15 @@ function applyToolOutcomeThrown(toolOutcomeCounter) {
  * SpanStatusCode.ERROR })` with no message, a few lines above in
  * wrapToolCallHandler — the exact pattern 'none' mode below reuses).
  *
- * - `'full'` (default): `span.recordException(err)` +
- *   `setStatus({ message: err?.message })` — byte-identical to every
- *   release before v0.13.0. This is the literal two-line call the
- *   catch blocks used inline before this function existed; taken
- *   unconditionally, with no new branching evaluated first, whenever
- *   mode is `'full'`.
+ * - `'full'` (default): the event `span.recordException(err)` would
+ *   record (`exception.type` from `code` else `name`, `exception.message`,
+ *   `exception.stacktrace`) plus `setStatus({ message })`, built by
+ *   describeFullException() with credentials scrubbed (scrubSecrets(),
+ *   `fingerprint/normalize/secrets.js`) and the message/stack capped at
+ *   MAX_FULL_EXCEPTION_MESSAGE_LENGTH / MAX_FULL_EXCEPTION_STACK_LENGTH
+ *   (v0.17.0). Ids, paths, URLs and line numbers are kept, which is what
+ *   still separates it from `'normalized'`. Before v0.17.0 this was the
+ *   native `recordException(err)` call, raw and uncapped.
  * - `'none'`: `setStatus({ code: ERROR })` only — no message, no
  *   `exception` event.
  * - `'normalized'`: a hand-built `exception` event carrying the same
@@ -1718,16 +1777,9 @@ function applyToolOutcomeThrown(toolOutcomeCounter) {
  *
  * `error.type` (`ATTR_ERROR_TYPE`, set by each call site immediately
  * after this call returns) is capped at `MAX_ERROR_CLASS_LENGTH`
- * regardless of mode — see each call site's own comment. The native
- * `exception.type` a `'full'`-mode `span.recordException(err)` call sets
- * internally is deliberately NOT capped here: `'full'` mode is defined
- * as byte-identical to pre-v0.13.0 behavior, so the native OTel SDK call
- * is left completely untouched, uncapped exception.type included. Only
- * `'normalized'` mode's hand-built event applies the cap to
- * `exception.type` too (mirroring `recordException()`'s own
- * `err.code?.toString() ?? err.name` derivation for what goes in that
- * field), since that event is already being constructed by hand either
- * way — there is no "untouched native call" to preserve for that mode.
+ * regardless of mode — see each call site's own comment. Since v0.17.0
+ * both hand-built events (`'full'` and `'normalized'`) cap
+ * `exception.type` the same way.
  *
  * Never throws — matches this library's fail-open discipline for
  * everything downstream of a real thrown error, the same guarantee
@@ -1821,12 +1873,22 @@ function recordThrownException(span, err, errorRecordingConfig, errorRecordingSt
       return;
     }
 
-    // 'full' (default) — byte-identical to pre-v0.13.0 behavior. Never
-    // references errorRecordingConfig.redactor at all (Decision 6).
-    span.recordException(err);
-    span.setStatus({ code: SpanStatusCode.ERROR, message: err?.message });
+    // 'full' (default): the same three attributes span.recordException(err)
+    // sets, from the raw message and stack, but with credentials scrubbed
+    // and each capped (v0.17.0). Keeps the ids, paths, URLs and line numbers
+    // 'normalized' strips. Never references errorRecordingConfig.redactor
+    // at all (Decision 6).
+    const full = describeFullException(err);
+    if (full.attributes) span.addEvent('exception', full.attributes);
+    span.setStatus({ code: SpanStatusCode.ERROR, message: full.statusMessage });
   } catch {
-    // Never throw — see this function's own docblock.
+    // Never throw — see this function's own docblock. Still mark the span
+    // failed when reading the error itself threw (e.g. a throwing getter).
+    try {
+      span.setStatus({ code: SpanStatusCode.ERROR });
+    } catch {
+      // ignore
+    }
   }
 }
 
@@ -1930,6 +1992,8 @@ function recordThrownException(span, err, errorRecordingConfig, errorRecordingSt
  *   through to applyCostAttribution() — see that function's own docblock and warnRejectedModel()'s.
  * @param {{ warnedFailed: boolean }} errorRecordingState - ADR 020 (v0.14.0 Phase 2): threaded through
  *   to recordThrownException()/applyRedactor() — see redactor.js's own docblock for what "once" means here.
+ * @param {import('./staleness.js').StalenessConfig} stalenessConfig - ADR 027: resolved `staleness` option.
+ * @param {{ warnedTools: Set<string> }} stalenessState - ADR 027: once-per-tool malformed-freshness warnings.
  */
 function wrapToolCallHandler(
   handler,
@@ -1950,6 +2014,8 @@ function wrapToolCallHandler(
   costAttributionState,
   errorRecordingState,
   unactionableErrorsConfig,
+  stalenessConfig,
+  stalenessState,
 ) {
   return (request, extra) => {
     const toolName = request?.params?.name;
@@ -2084,6 +2150,9 @@ function wrapToolCallHandler(
           );
         } else {
           span.setStatus({ code: SpanStatusCode.OK });
+          // ADR 027: freshness verdict from the tool's own _meta. Success
+          // branch only, and it never touches status: stale is not an error.
+          applyStaleness(span, metricsRecorder, toolName, result, stalenessConfig, stalenessState);
           applyCostAttribution(span, metricsRecorder, toolName, sessionId, result, costTracking, budgetTracker, costAttributionState);
           if (thrashSessionId !== null) {
             applyThrashSuccessClear(thrashConfig, thrashDetector, thrashSessionId, toolName);

package/src/metrics.js

@@ -77,6 +77,7 @@ import { ATTRIBUTE_KEYS } from './fingerprint/attributes.js';
  *   recordTokens: (toolName: string | undefined, model: string | undefined, totalTokens: number, pricingStatus: string) => void,
  *   recordCost: (toolName: string | undefined, model: string | undefined, costUsd: number, pricingStatus: string) => void,
  *   recordOperationDuration: (method: string, durationMs: number, errorType?: string) => void,
+ *   recordStaleResponse: (toolName: string | undefined) => void,
  * }}
  */
 export function setupMeter(packageVersion) {
@@ -113,7 +114,20 @@ export function setupMeter(packageVersion) {
     unit: 'ms',
   });
 
+  // ADR 027 (v0.17.0): successful responses whose data was older than the
+  // tool's own freshness window. gen_ai.tool.name only -- no new label key,
+  // and no verdict/age label (data age is span-only).
+  const staleResponses = meter.createCounter('mcp.tool.stale_responses', {
+    description:
+      'Number of successful MCP tool calls whose data was older than the freshness the tool reported (ADR 027). Not an error.',
+  });
+
   return {
+    recordStaleResponse(toolName) {
+      staleResponses.add(1, {
+        [ATTR_GEN_AI_TOOL_NAME]: toolName,
+      });
+    },
     recordOperationDuration(method, durationMs, errorType) {
       operationDuration.record(durationMs, {
         [ATTR_MCP_METHOD_NAME]: method,

package/src/result-meta.js

@@ -0,0 +1,34 @@
+/**
+ * @module result-meta
+ * The one place core reaches into a tool result's `_meta` (the MCP spec's
+ * extension point on every result).
+ *
+ * Shared by the cost extractor (`_meta.usage`, `_meta.model` —
+ * src/cost/extractor.js) and staleness detection (the freshness key —
+ * src/staleness.js, ADR 027). Reads exactly the key it's given and never
+ * enumerates `_meta`, so a feature only ever sees the field it asked for.
+ */
+
+/**
+ * @param {unknown} value
+ * @returns {value is Record<string, unknown>}
+ */
+export function isPlainObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * `result._meta[key]`, or `undefined` when `result` or its `_meta` isn't a
+ * plain object. Property access isn't guarded here (a throwing getter
+ * propagates), so callers keep their own try/catch, as both callers
+ * already do.
+ *
+ * @param {unknown} result
+ * @param {string} key
+ * @returns {unknown}
+ */
+export function readResultMetaField(result, key) {
+  if (!isPlainObject(result)) return undefined;
+  const meta = result._meta;
+  return isPlainObject(meta) ? meta[key] : undefined;
+}

package/src/staleness.js

@@ -0,0 +1,278 @@
+/**
+ * @module staleness
+ *
+ * ADR 027 (docs/adr/027-staleness-detection.md): flag successful tool
+ * responses whose data is older than the freshness the tool itself
+ * reported. The tool is the source of truth; `staleness.tools[name].maxAgeMs`
+ * in config is only an override.
+ *
+ * PRIVACY: reads `result._meta[FRESHNESS_META_KEY]` through the shared
+ * accessor (src/result-meta.js) and then only its `asOf`, `maxAgeMs` and
+ * `freshUntil` properties. Never enumerates `_meta`, never reads content,
+ * never emits a raw input value: only the derived age and window (numbers)
+ * and fixed enum strings reach the span.
+ *
+ * Staleness is not an error: nothing here touches span status, error.type
+ * or the silent-failure counter.
+ */
+
+import { diag } from '@opentelemetry/api';
+import { isPlainObject, readResultMetaField } from './result-meta.js';
+
+/**
+ * The `result._meta` key a tool reports freshness under. Reverse-DNS
+ * prefix per the MCP spec's `_meta` key rules (ADR 027, Step 0).
+ */
+export const FRESHNESS_META_KEY = 'io.github.thirumalaiboobathi.opentel-mcp/freshness';
+
+/** `fresh` | `stale` | `unknown`. Set only when the tool sent the freshness key. */
+export const ATTR_MCP_TOOL_FRESHNESS_VERDICT = 'mcp.tool.freshness.verdict';
+/** Integer ms: response time minus `asOf`. Span-only, never a metric. */
+export const ATTR_MCP_TOOL_FRESHNESS_DATA_AGE_MS = 'mcp.tool.freshness.data_age_ms';
+/** Integer ms: the effective window, deadline minus `asOf`. */
+export const ATTR_MCP_TOOL_FRESHNESS_MAX_AGE_MS = 'mcp.tool.freshness.max_age_ms';
+/** `max_age_ms` | `fresh_until` | `config`: which input set the deadline. */
+export const ATTR_MCP_TOOL_FRESHNESS_LIMIT_SOURCE = 'mcp.tool.freshness.limit_source';
+/** Why the verdict is `unknown`; one of UNKNOWN_REASONS. */
+export const ATTR_MCP_TOOL_FRESHNESS_UNKNOWN_REASON = 'mcp.tool.freshness.unknown_reason';
+
+export const VERDICTS = Object.freeze(['fresh', 'stale', 'unknown']);
+export const LIMIT_SOURCES = Object.freeze(['max_age_ms', 'fresh_until', 'config']);
+export const UNKNOWN_REASONS = Object.freeze(['invalid_as_of', 'future_as_of', 'missing_window', 'invalid_window']);
+
+/** `asOf` up to this far in the future is clock skew: age clamps to 0. */
+export const FUTURE_SKEW_TOLERANCE_MS = 5_000;
+
+/** A numeric timestamp below this (March 1973 as ms) is almost certainly epoch seconds. */
+const MIN_EPOCH_MS = 1e11;
+/** ECMAScript's Date range limit, in ms either side of the epoch. */
+const MAX_EPOCH_MS = 8.64e15;
+/** Longer strings aren't parsed at all. */
+const MAX_TIMESTAMP_LENGTH = 64;
+/** ISO 8601 date-time with a mandatory `Z` or `±hh:mm` offset. */
+const ISO_WITH_ZONE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d{1,9})?)?(?:Z|[+-]\d{2}:\d{2})$/;
+/** Cap on the per-server set of tool names already warned about. */
+const MAX_WARNED_TOOLS = 256;
+
+/**
+ * @typedef {object} StalenessConfig
+ * @property {boolean} enabled
+ * @property {Map<string, number>} overrides - tool name -> maxAgeMs override.
+ */
+
+/**
+ * Resolves the `staleness` option. Invalid override entries are dropped
+ * with one `diag.warn` each; never throws.
+ *
+ * @param {unknown} partial
+ * @returns {StalenessConfig}
+ */
+export function resolveStalenessConfig(partial) {
+  const overrides = new Map();
+  let enabled = true;
+  try {
+    const p = isPlainObject(partial) ? partial : {};
+    enabled = p.enabled !== false;
+    const tools = isPlainObject(p.tools) ? p.tools : {};
+    for (const toolName of Object.keys(tools)) {
+      const entry = tools[toolName];
+      const maxAgeMs = isPlainObject(entry) ? entry.maxAgeMs : undefined;
+      if (isValidMaxAge(maxAgeMs)) {
+        overrides.set(toolName, maxAgeMs);
+      } else {
+        diag.warn(
+          `opentel-mcp: staleness.tools[${JSON.stringify(toolName)}].maxAgeMs must be a finite number >= 0; ` +
+            "ignoring this override, so the tool's own freshness window applies. See ADR 027.",
+        );
+      }
+    }
+  } catch (err) {
+    diag.warn('opentel-mcp: could not read the staleness option; ignoring its overrides. See ADR 027.', err);
+  }
+  return { enabled, overrides };
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is number}
+ */
+function isValidMaxAge(value) {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0;
+}
+
+/**
+ * Epoch ms from an ISO 8601 string with a zone, or an epoch-ms number.
+ * `null` for anything else.
+ *
+ * @param {unknown} value
+ * @returns {number | null}
+ */
+export function parseTimestamp(value) {
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value) || value < MIN_EPOCH_MS || value > MAX_EPOCH_MS) return null;
+    return value;
+  }
+  if (typeof value === 'string') {
+    if (value.length > MAX_TIMESTAMP_LENGTH || !ISO_WITH_ZONE.test(value)) return null;
+    const ms = Date.parse(value);
+    return Number.isFinite(ms) ? ms : null;
+  }
+  return null;
+}
+
+/**
+ * @typedef {object} FreshnessAssessment
+ * @property {'fresh' | 'stale' | 'unknown'} verdict
+ * @property {number} [dataAgeMs]
+ * @property {number} [maxAgeMs]
+ * @property {'max_age_ms' | 'fresh_until' | 'config'} [limitSource]
+ * @property {'invalid_as_of' | 'future_as_of' | 'missing_window' | 'invalid_window'} [unknownReason]
+ * @property {string} [warning] - Set for a malformed input worth one diag.warn.
+ */
+
+/**
+ * The verdict for one freshness value. Pure; reads only `asOf`,
+ * `maxAgeMs` and `freshUntil` off `freshness`. Can throw only if one of
+ * those properties is a throwing getter; the caller catches.
+ *
+ * @param {unknown} freshness - `result._meta[FRESHNESS_META_KEY]`, known to be present.
+ * @param {number | undefined} overrideMaxAgeMs - From config; replaces the tool's window.
+ * @param {number} now - Epoch ms.
+ * @returns {FreshnessAssessment}
+ */
+export function assessFreshness(freshness, overrideMaxAgeMs, now) {
+  if (!isPlainObject(freshness)) {
+    return { verdict: 'unknown', unknownReason: 'invalid_as_of', warning: 'the freshness value is not an object' };
+  }
+
+  const rawAsOf = freshness.asOf;
+  const asOf = parseTimestamp(rawAsOf);
+  if (asOf === null) {
+    const looksLikeSeconds = typeof rawAsOf === 'number' && Number.isFinite(rawAsOf) && rawAsOf > 0 && rawAsOf < MIN_EPOCH_MS;
+    return {
+      verdict: 'unknown',
+      unknownReason: 'invalid_as_of',
+      warning: looksLikeSeconds
+        ? 'asOf looks like epoch seconds; it must be epoch milliseconds or an ISO 8601 string with a timezone'
+        : 'asOf is missing or unparseable; use epoch milliseconds or an ISO 8601 string with a timezone (Z or +hh:mm)',
+    };
+  }
+
+  const rawAge = now - asOf;
+  if (rawAge < -FUTURE_SKEW_TOLERANCE_MS) {
+    return { verdict: 'unknown', unknownReason: 'future_as_of', warning: 'asOf is more than 5 s in the future' };
+  }
+  const dataAgeMs = Math.max(0, Math.round(rawAge));
+
+  let deadline;
+  /** @type {FreshnessAssessment['limitSource']} */
+  let limitSource;
+  if (overrideMaxAgeMs !== undefined) {
+    deadline = asOf + overrideMaxAgeMs;
+    limitSource = 'config';
+  } else {
+    const rawMaxAge = freshness.maxAgeMs;
+    const rawFreshUntil = freshness.freshUntil;
+    const hasMaxAge = rawMaxAge !== undefined;
+    const hasFreshUntil = rawFreshUntil !== undefined;
+    if (!hasMaxAge && !hasFreshUntil) {
+      return {
+        verdict: 'unknown',
+        dataAgeMs,
+        unknownReason: 'missing_window',
+        warning: 'asOf was given without maxAgeMs or freshUntil',
+      };
+    }
+    const freshUntil = hasFreshUntil ? parseTimestamp(rawFreshUntil) : null;
+    if ((hasMaxAge && !isValidMaxAge(rawMaxAge)) || (hasFreshUntil && (freshUntil === null || freshUntil < asOf))) {
+      return {
+        verdict: 'unknown',
+        dataAgeMs,
+        unknownReason: 'invalid_window',
+        warning: 'maxAgeMs must be a finite number >= 0, and freshUntil a timestamp no earlier than asOf',
+      };
+    }
+    // Both given: the earlier deadline wins (ADR 027 §1).
+    const fromMaxAge = hasMaxAge ? asOf + /** @type {number} */ (rawMaxAge) : Infinity;
+    const fromFreshUntil = freshUntil ?? Infinity;
+    if (fromFreshUntil < fromMaxAge) {
+      deadline = fromFreshUntil;
+      limitSource = 'fresh_until';
+    } else {
+      deadline = fromMaxAge;
+      limitSource = 'max_age_ms';
+    }
+  }
+
+  // Cap so a huge window never overflows or reports a non-finite number.
+  const maxAgeMs = Math.round(Math.min(deadline, MAX_EPOCH_MS) - asOf);
+  // Skew within tolerance counts as "now == asOf".
+  const verdict = Math.max(now, asOf) > deadline ? 'stale' : 'fresh';
+  return { verdict, dataAgeMs, maxAgeMs, limitSource };
+}
+
+/**
+ * Per-instrumented-server state for the once-per-tool warning.
+ *
+ * @returns {{ warnedTools: Set<string> }}
+ */
+export function createStalenessState() {
+  return { warnedTools: new Set() };
+}
+
+/**
+ * Reads the freshness key off a successful result and, if present, sets
+ * the ADR 027 span attributes and counts a stale response. Never throws.
+ *
+ * @param {import('@opentelemetry/api').Span} span
+ * @param {{ recordStaleResponse: (toolName: string | undefined) => void } | null | undefined} metricsRecorder
+ * @param {string | undefined} toolName
+ * @param {unknown} result
+ * @param {StalenessConfig} config
+ * @param {{ warnedTools: Set<string> }} state
+ * @param {number} [now]
+ */
+export function applyStaleness(span, metricsRecorder, toolName, result, config, state, now = Date.now()) {
+  try {
+    if (!config?.enabled) return;
+    const freshness = readResultMetaField(result, FRESHNESS_META_KEY);
+    if (freshness === undefined) return;
+
+    const override = typeof toolName === 'string' ? config.overrides.get(toolName) : undefined;
+    const assessment = assessFreshness(freshness, override, now);
+
+    span.setAttribute(ATTR_MCP_TOOL_FRESHNESS_VERDICT, assessment.verdict);
+    if (assessment.dataAgeMs !== undefined) span.setAttribute(ATTR_MCP_TOOL_FRESHNESS_DATA_AGE_MS, assessment.dataAgeMs);
+    if (assessment.maxAgeMs !== undefined) span.setAttribute(ATTR_MCP_TOOL_FRESHNESS_MAX_AGE_MS, assessment.maxAgeMs);
+    if (assessment.limitSource) span.setAttribute(ATTR_MCP_TOOL_FRESHNESS_LIMIT_SOURCE, assessment.limitSource);
+    if (assessment.unknownReason) span.setAttribute(ATTR_MCP_TOOL_FRESHNESS_UNKNOWN_REASON, assessment.unknownReason);
+
+    if (assessment.verdict === 'stale') metricsRecorder?.recordStaleResponse(toolName);
+    if (assessment.warning) warnOnce(state, toolName, assessment.warning);
+  } catch {
+    // The thrown value isn't logged: it came from the tool's own object.
+    warnOnce(state, toolName, 'reading its freshness _meta threw');
+  }
+}
+
+/**
+ * At most one diag.warn per tool name per server; the set is capped so a
+ * flood of distinct names can't grow it. Never throws.
+ *
+ * @param {{ warnedTools: Set<string> } | undefined} state
+ * @param {string | undefined} toolName
+ * @param {string} problem
+ */
+function warnOnce(state, toolName, problem) {
+  try {
+    const key = typeof toolName === 'string' ? toolName : '';
+    if (!state || state.warnedTools.has(key) || state.warnedTools.size >= MAX_WARNED_TOOLS) return;
+    state.warnedTools.add(key);
+    diag.warn(
+      `opentel-mcp: tool ${JSON.stringify(key.slice(0, 128))} reported malformed freshness _meta (${problem}), ` +
+        'so its responses get no staleness verdict. Further problems with this tool are not logged. See ADR 027.',
+    );
+  } catch {
+    // Never throw into the tool-call path.
+  }
+}