hevy-mcp 5.0.3 → 5.0.5

package/dist/cli.mjs

@@ -4,12 +4,12 @@
 (function() {
 	try {
 		var e = "undefined" != typeof window ? window : "undefined" != typeof global ? global : "undefined" != typeof globalThis ? globalThis : "undefined" != typeof self ? self : {};
-		e.SENTRY_RELEASE = { id: "hevy-mcp@5.0.3" };
+		e.SENTRY_RELEASE = { id: "hevy-mcp@5.0.5" };
 		var n = new e.Error().stack;
 		n && (e._sentryDebugIds = e._sentryDebugIds || {}, e._sentryDebugIds[n] = "625c4c9c-e20d-40b3-96b1-4e799ef130f3", e._sentryDebugIdIdentifier = "sentry-dbid-625c4c9c-e20d-40b3-96b1-4e799ef130f3");
 	} catch (e) {}
 })();
-import { a as createSafeErrorDiagnostic, i as MissingHevyApiKeyError, n as runServer, o as flushTelemetry } from "./src-BGQCPTet.mjs";
+import { a as createSafeErrorDiagnostic, i as MissingHevyApiKeyError, n as runServer, o as flushTelemetry } from "./src-TBD9ENR3.mjs";
 //#region src/cli.ts
 runServer().catch(async (error) => {
 	if (error instanceof MissingHevyApiKeyError) console.error(error.message);

package/dist/index.mjs

@@ -4,10 +4,10 @@
 (function() {
 	try {
 		var e = "undefined" != typeof window ? window : "undefined" != typeof global ? global : "undefined" != typeof globalThis ? globalThis : "undefined" != typeof self ? self : {};
-		e.SENTRY_RELEASE = { id: "hevy-mcp@5.0.3" };
+		e.SENTRY_RELEASE = { id: "hevy-mcp@5.0.5" };
 		var n = new e.Error().stack;
 		n && (e._sentryDebugIds = e._sentryDebugIds || {}, e._sentryDebugIds[n] = "e9496b31-626b-4ad1-9416-47ba4ffd2995", e._sentryDebugIdIdentifier = "sentry-dbid-e9496b31-626b-4ad1-9416-47ba4ffd2995");
 	} catch (e) {}
 })();
-import { n as runServer, r as runStdioServer, t as createNodeMcpServer } from "./src-BGQCPTet.mjs";
+import { n as runServer, r as runStdioServer, t as createNodeMcpServer } from "./src-TBD9ENR3.mjs";
 export { createNodeMcpServer, runServer, runStdioServer };

package/dist/{src-BGQCPTet.mjs → src-TBD9ENR3.mjs}

@@ -4,17 +4,17 @@
 (function() {
 	try {
 		var e = "undefined" != typeof window ? window : "undefined" != typeof global ? global : "undefined" != typeof globalThis ? globalThis : "undefined" != typeof self ? self : {};
-		e.SENTRY_RELEASE = { id: "hevy-mcp@5.0.3" };
+		e.SENTRY_RELEASE = { id: "hevy-mcp@5.0.5" };
 		var n = new e.Error().stack;
-		n && (e._sentryDebugIds = e._sentryDebugIds || {}, e._sentryDebugIds[n] = "b75e442e-2372-4f08-83bb-f0c392f5101b", e._sentryDebugIdIdentifier = "sentry-dbid-b75e442e-2372-4f08-83bb-f0c392f5101b");
+		n && (e._sentryDebugIds = e._sentryDebugIds || {}, e._sentryDebugIds[n] = "f5270278-73ea-40fd-92e2-2ae5127e6780", e._sentryDebugIdIdentifier = "sentry-dbid-f5270278-73ea-40fd-92e2-2ae5127e6780");
 	} catch (e) {}
 })();
-import { createHmac, randomUUID, timingSafeEqual } from "node:crypto";
+import { createHmac, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
 import * as Sentry from "@sentry/node";
 import { SentryPropagator, SentrySampler, SentrySpanProcessor } from "@sentry/opentelemetry";
-import { SpanStatusCode, metrics, trace } from "@opentelemetry/api";
+import { SpanStatusCode, context, metrics, trace } from "@opentelemetry/api";
 import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
-import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
+import { AggregationTemporalityPreference, OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
 import { resourceFromAttributes } from "@opentelemetry/resources";
 import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
 import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
@@ -79,16 +79,59 @@ function sanitizeSentryMcpSpan(span) {
 * Sentry SDK: error events, performance traces, release tracking
 * OTel Collector → Honeycomb: performance traces, metrics
 */
+const PROCESS_FAILURE_TAXONOMY = {
+	uncaughtException: "uncaught_exception",
+	unhandledRejection: "unhandled_rejection"
+};
+const SAFE_EXCEPTION_TYPES = /* @__PURE__ */ new Set([
+	"AggregateError",
+	"DOMException",
+	"Error",
+	"EvalError",
+	"HevyHttpError",
+	"RangeError",
+	"ReferenceError",
+	"SyntaxError",
+	"TypeError",
+	"URIError",
+	"ProtocolError",
+	"ZodError"
+]);
+const SAFE_EXCEPTION_CODES = /* @__PURE__ */ new Set([
+	"EAI_AGAIN",
+	"ECONNABORTED",
+	"ECONNREFUSED",
+	"ECONNRESET",
+	"ENETUNREACH",
+	"ENOTFOUND",
+	"ERR_NETWORK",
+	"ERR_SOCKET_TIMEOUT",
+	"ETIMEDOUT",
+	"HEVY_INVALID_ENDPOINT",
+	"HEVY_REQUEST_ABORTED",
+	"HEVY_RETRY_EXHAUSTED"
+]);
 function normalizeTelemetryError(error) {
-	const name = error instanceof Error && error.name ? error.name : "Exception";
-	return new Error(name);
+	const candidate = error instanceof Error && typeof error.name === "string" ? error.name : void 0;
+	return { name: candidate && SAFE_EXCEPTION_TYPES.has(candidate) ? candidate : "UnknownError" };
+}
+function getSafeExceptionCode(error) {
+	if (!error || typeof error !== "object" || !("code" in error)) return void 0;
+	const code = error.code;
+	return typeof code === "string" && SAFE_EXCEPTION_CODES.has(code) ? code : void 0;
 }
 function recordTelemetryException(error, attributes, span) {
 	if (!telemetryEnabled) return;
 	try {
 		const target = span ?? trace.getActiveSpan();
 		if (!target) return;
-		target.recordException(normalizeTelemetryError(error));
+		const normalized = normalizeTelemetryError(error);
+		target.addEvent("exception", {
+			...attributes,
+			"exception.type": normalized.name
+		});
+		target.setAttribute("exception.type", normalized.name);
+		target.setAttribute("error.category", normalized.name);
 		if (attributes) target.setAttributes(attributes);
 		target.setStatus({ code: SpanStatusCode.ERROR });
 	} catch {}
@@ -97,9 +140,19 @@ function installProcessExceptionTracking(processLike = process) {
 	if (!telemetryEnabled) return () => {};
 	const recordProcessException = (source, error) => {
 		try {
-			tracer.startActiveSpan(`mcp.process.${source}`, (span) => {
-				recordTelemetryException(error, { "exception.source": source }, span);
-				span.end();
+			tracer.startActiveSpan(`mcp.process.${source}`, { attributes: { "mcp.span.category": "process" } }, (span) => {
+				try {
+					const code = getSafeExceptionCode(error);
+					recordTelemetryException(error, {
+						"exception.source": source,
+						"mcp.failure.phase": PROCESS_FAILURE_TAXONOMY[source],
+						"error.type": "MCP_PROCESS_EXCEPTION",
+						"error.category": "McpProcessFailure",
+						...code ? { "error.code": code } : {}
+					}, span);
+				} finally {
+					span.end();
+				}
 			});
 		} catch {}
 	};
@@ -116,14 +169,24 @@ function installProcessExceptionTracking(processLike = process) {
 	};
 }
 const name$1 = "hevy-mcp";
-const version$1 = "5.0.3";
+const version$1 = "5.0.5";
 const telemetryEnabled = process.env.HEVY_MCP_TELEMETRY !== "0";
 const collectorToken = "NH9vOela-HYreQxAbJa68cjEmORoEKM57EvneUDVcOo";
 const COLLECTOR_ENDPOINT = "https://otel.chrisdoc.dev/v1";
-const sentryRelease = process.env.SENTRY_RELEASE ?? `hevy-mcp@5.0.3`;
+const sentryRelease = process.env.SENTRY_RELEASE ?? `${name$1}@${version$1}`;
+function createServiceInstanceId(generate = randomUUID) {
+	try {
+		const generated = generate();
+		if (generated.length > 0 && generated.length <= 128) return generated;
+	} catch {}
+	return randomBytes(16).toString("hex");
+}
 const resource = resourceFromAttributes({
 	"service.name": name$1,
-	"service.version": version$1
+	"service.version": version$1,
+	"service.instance.id": createServiceInstanceId(),
+	"process.runtime.name": process.release.name,
+	"process.runtime.version": process.version
 });
 let currentUserHash;
 var UserHashSpanProcessor = class {
@@ -168,7 +231,8 @@ if (telemetryEnabled) {
 		readers: [new PeriodicExportingMetricReader({
 			exporter: new OTLPMetricExporter({
 				url: `${COLLECTOR_ENDPOINT}/metrics`,
-				headers: { Authorization: `Bearer ${collectorToken}` }
+				headers: { Authorization: `Bearer ${collectorToken}` },
+				temporalityPreference: AggregationTemporalityPreference.DELTA
 			}),
 			exportIntervalMillis: 1e4
 		})]
@@ -196,6 +260,8 @@ async function flushTelemetry(timeoutMs = 1e3) {
 }
 const tracer = trace.getTracer(name$1);
 const meter = metrics.getMeter(name$1);
+const serviceName = name$1;
+const serviceVersion = version$1;
 const SENTRY_USER_ID_CONTEXT = "hevy-mcp:sentry-user-id:v1";
 function setTelemetryUser(apiKey) {
 	if (!telemetryEnabled) return;
@@ -1004,6 +1070,35 @@ const SAFE_STATIC_ENDPOINTS = /* @__PURE__ */ new Set([
 	"/v1/workouts/count",
 	"/v1/workouts/events"
 ]);
+const EXPECTED_READ_404_ENDPOINTS = /* @__PURE__ */ new Set([
+	"/v1/body_measurements/:date",
+	"/v1/exercise_history/:exerciseTemplateId",
+	"/v1/exercise_templates/:exerciseTemplateId",
+	"/v1/routine_folders/:folderId",
+	"/v1/routines/:routineId",
+	"/v1/workouts/:workoutId"
+]);
+const EXPECTED_LIST_404_ENDPOINTS = /* @__PURE__ */ new Set([
+	"/v1/body_measurements",
+	"/v1/exercise_templates",
+	"/v1/routine_folders",
+	"/v1/routines",
+	"/v1/workouts",
+	"/v1/workouts/events"
+]);
+const SAFE_OBSERVATION_CODES = /* @__PURE__ */ new Set([
+	"EAI_AGAIN",
+	"ECONNABORTED",
+	"ECONNREFUSED",
+	"ECONNRESET",
+	"ENETUNREACH",
+	"ENOTFOUND",
+	"ERR_NETWORK",
+	"ERR_SOCKET_TIMEOUT",
+	"ETIMEDOUT",
+	HEVY_REQUEST_ABORTED_ERROR_CODE,
+	HEVY_RETRY_EXHAUSTED_ERROR_CODE
+]);
 const SAFE_DYNAMIC_ENDPOINTS = [
 	["/v1/body_measurements/", "/v1/body_measurements/:date"],
 	["/v1/exercise_history/", "/v1/exercise_history/:exerciseTemplateId"],
@@ -1049,9 +1144,11 @@ function getRequestContext(config) {
 	let endpoint = "unknown";
 	if (SAFE_STATIC_ENDPOINTS.has(rawEndpoint)) endpoint = rawEndpoint;
 	else endpoint = SAFE_DYNAMIC_ENDPOINTS.find(([prefix]) => rawEndpoint.startsWith(prefix))?.[1] ?? "unknown";
+	const page = config.params !== null && typeof config.params === "object" && "page" in config.params && typeof config.params.page === "number" ? config.params.page : void 0;
 	return {
 		method,
-		endpoint
+		endpoint,
+		page
 	};
 }
 function emitClientLog(logger, message) {
@@ -1061,11 +1158,49 @@ function emitClientLog(logger, message) {
 		console.error("Failed to emit structured Hevy API log");
 	}
 }
+function emitRequestStart(observer, observation) {
+	try {
+		return observer?.(observation) ?? void 0;
+	} catch {
+		return;
+	}
+}
+function finishRequestObservation(scope, observation) {
+	try {
+		scope?.finish(observation);
+	} catch {}
+}
 function emitRequestObservation(observer, observation) {
 	try {
 		observer?.(observation);
 	} catch {}
 }
+function runRequestObservation(scope, operation) {
+	if (!scope?.run) return operation();
+	let started = false;
+	const trackedOperation = () => {
+		started = true;
+		return operation();
+	};
+	try {
+		return scope.run(trackedOperation);
+	} catch (error) {
+		if (started) throw error;
+		return operation();
+	}
+}
+function emitRetryWait(observer, observation) {
+	try {
+		return observer?.(observation) ?? void 0;
+	} catch {
+		return;
+	}
+}
+function finishRetryWait(scope) {
+	try {
+		scope?.finish();
+	} catch {}
+}
 function parseRetryAfterMs(value) {
 	if (!value) return void 0;
 	const seconds = Number(value);
@@ -1122,7 +1257,7 @@ function createNativeClient(apiKey, baseUrl, options) {
 			...clientConfig,
 			...config
 		};
-		const { method, endpoint } = getRequestContext(normalized);
+		const { method, endpoint, page } = getRequestContext(normalized);
 		const url = buildUrl(baseUrl, normalized);
 		let retryCount = 0;
 		while (true) {
@@ -1132,43 +1267,53 @@ function createNativeClient(apiKey, baseUrl, options) {
 				code: HEVY_REQUEST_ABORTED_ERROR_CODE
 			});
 			const startedAt = Date.now();
+			const observationScope = emitRequestStart(options.onRequestStart, {
+				method,
+				endpoint,
+				retryCount
+			});
 			const controller = new AbortController();
 			const abortFromCaller = () => controller.abort();
 			normalized.signal?.addEventListener("abort", abortFromCaller, { once: true });
 			const timeout = setTimeout(() => controller.abort(), timeoutMs);
 			try {
-				const headers = new Headers({ "api-key": apiKey });
-				if (normalized.data !== void 0 && !(normalized.data instanceof FormData)) headers.set("content-type", "application/json");
-				const attemptDeadline = Date.now() + timeoutMs;
-				const response = await withTimeout(fetchImplementation(url, {
-					method,
-					headers,
-					redirect: "manual",
-					body: normalized.data instanceof FormData ? normalized.data : normalized.data === void 0 ? void 0 : JSON.stringify(normalized.data),
-					signal: controller.signal
-				}), Math.max(0, attemptDeadline - Date.now()), () => controller.abort());
-				const data = await withTimeout(parseResponseData(response), Math.max(0, attemptDeadline - Date.now()), () => controller.abort());
-				if (!response.ok) throw new HevyHttpError(`Hevy API request failed (HTTP ${response.status})`, {
-					status: response.status,
-					statusText: response.statusText,
-					data,
-					headers: response.headers,
-					method,
-					endpoint
-				});
-				emitRequestObservation(options.onRequestComplete, {
-					method,
-					endpoint,
-					status: response.status,
-					durationMs: Date.now() - startedAt,
-					retryCount
+				return await runRequestObservation(observationScope, async () => {
+					const headers = new Headers({ "api-key": apiKey });
+					if (normalized.data !== void 0 && !(normalized.data instanceof FormData)) headers.set("content-type", "application/json");
+					const attemptDeadline = Date.now() + timeoutMs;
+					const response = await withTimeout(fetchImplementation(url, {
+						method,
+						headers,
+						redirect: "manual",
+						body: normalized.data instanceof FormData ? normalized.data : normalized.data === void 0 ? void 0 : JSON.stringify(normalized.data),
+						signal: controller.signal
+					}), Math.max(0, attemptDeadline - Date.now()), () => controller.abort());
+					const data = await withTimeout(parseResponseData(response), Math.max(0, attemptDeadline - Date.now()), () => controller.abort());
+					if (!response.ok) throw new HevyHttpError(`Hevy API request failed (HTTP ${response.status})`, {
+						status: response.status,
+						statusText: response.statusText,
+						data,
+						headers: response.headers,
+						method,
+						endpoint
+					});
+					const observation = {
+						method,
+						endpoint,
+						status: response.status,
+						durationMs: Date.now() - startedAt,
+						retryCount,
+						outcome: "success"
+					};
+					finishRequestObservation(observationScope, observation);
+					emitRequestObservation(options.onRequestComplete, observation);
+					return {
+						data,
+						status: response.status,
+						statusText: response.statusText,
+						headers: response.headers
+					};
 				});
-				return {
-					data,
-					status: response.status,
-					statusText: response.statusText,
-					headers: response.headers
-				};
 			} catch (cause) {
 				const error = isHevyHttpError(cause) ? cause : new HevyHttpError(normalized.signal?.aborted ? "Hevy API request was canceled" : "Hevy API network request failed", {
 					method,
@@ -1176,24 +1321,31 @@ function createNativeClient(apiKey, baseUrl, options) {
 					code: normalized.signal?.aborted ? HEVY_REQUEST_ABORTED_ERROR_CODE : getNetworkCode(cause),
 					cause
 				});
+				const expectedReason = error.status === 404 && method === "GET" && EXPECTED_READ_404_ENDPOINTS.has(endpoint) ? "not_found" : error.status === 404 && method === "GET" && page !== void 0 && page > 1 && EXPECTED_LIST_404_ENDPOINTS.has(endpoint) ? "end_of_list" : void 0;
 				const canRetry = method === "GET" && isRetryable(error);
-				if (canRetry && retryCount >= maxGetRetries) {
+				const retryExhausted = canRetry && retryCount >= maxGetRetries;
+				if (retryExhausted) {
 					error.hevyRetryExhausted = true;
 					error.hevyRetryCount = retryCount;
 					error.code = HEVY_RETRY_EXHAUSTED_ERROR_CODE;
 				}
-				emitRequestObservation(options.onRequestComplete, {
+				const observation = {
 					method,
 					endpoint,
 					status: error.status ?? 0,
 					durationMs: Date.now() - startedAt,
 					retryCount,
+					outcome: expectedReason ? "expected" : canRetry && !retryExhausted ? "retryable_failure" : "terminal_failure",
+					...expectedReason ? { expectedReason } : {},
 					error: {
 						status: error.status,
-						code: error.code
+						code: typeof error.code === "string" && SAFE_OBSERVATION_CODES.has(error.code) ? error.code : void 0,
+						category: error.status === void 0 ? "NetworkError" : "HevyHttpError"
 					}
-				});
-				if (!canRetry) {
+				};
+				finishRequestObservation(observationScope, observation);
+				emitRequestObservation(options.onRequestComplete, observation);
+				if (!expectedReason && !canRetry) {
 					emitClientLog(options.onLog, {
 						level: "error",
 						logger: "hevy-api",
@@ -1206,7 +1358,7 @@ function createNativeClient(apiKey, baseUrl, options) {
 					});
 					throw error;
 				}
-				if (error.hevyRetryExhausted) throw error;
+				if (expectedReason || error.hevyRetryExhausted) throw error;
 				retryCount += 1;
 				const delayMs = getRetryDelayMs(error, retryCount);
 				emitClientLog(options.onLog, {
@@ -1222,7 +1374,19 @@ function createNativeClient(apiKey, baseUrl, options) {
 						endpoint
 					}
 				});
-				await sleep(delayMs);
+				await runRequestObservation(observationScope, async () => {
+					const retryWaitScope = emitRetryWait(options.onRetryWait, {
+						method,
+						endpoint,
+						retryCount,
+						delayMs
+					});
+					try {
+						await sleep(delayMs);
+					} finally {
+						finishRetryWait(retryWaitScope);
+					}
+				});
 			} finally {
 				clearTimeout(timeout);
 				normalized.signal?.removeEventListener("abort", abortFromCaller);
@@ -2680,7 +2844,7 @@ function registerHevyResources(server, runtime) {
 //#endregion
 //#region ../core/src/server-metadata.ts
 const SERVER_NAME = "hevy-mcp";
-const SERVER_VERSION = "5.0.3";
+const SERVER_VERSION = "5.0.5";
 const SERVER_INSTRUCTIONS = [
 	"Hevy MCP connects clients to the authenticated user's Hevy workout-tracking data, including workouts, routines, exercise templates, routine folders, body measurements, and profile information. HEVY_API_KEY must contain a valid Hevy API key for local stdio use.",
 	"Safety: all get-* and search-* tools are read-only. create-* and update-* tools mutate Hevy data. Creates are additive and non-idempotent, so repeating one can create duplicates. Updates can overwrite existing data. Delete operations are not available.",
@@ -4078,7 +4242,7 @@ function createErrorResponse(error, context) {
 		axios: axiosErrorContext ?? void 0
 	};
 	const formattedMessage = `${context ? `[${context}] ` : ""}Error: ${policy.message}`;
-	console.error(createMcpToolFailureEvent(context || "unknown", policy.type, diagnostic));
+	console.error(JSON.stringify(createMcpToolFailureEvent(context || "unknown", policy.type, diagnostic)));
 	return {
 		content: [{
 			type: "text",
@@ -4240,39 +4404,69 @@ var AsyncTtlCache = class {
 	ttlMs;
 	maxSize;
 	now;
+	observer;
 	entries = /* @__PURE__ */ new Map();
 	inFlight = /* @__PURE__ */ new Map();
 	requestCounter = 0;
 	constructor(options, now = Date.now) {
-		const { ttlMs, maxSize } = options;
+		const { ttlMs, maxSize, observer } = options;
 		if (ttlMs <= 0) throw new Error("Cache ttlMs must be greater than 0.");
 		if (maxSize <= 0) throw new Error("Cache maxSize must be greater than 0.");
 		this.ttlMs = ttlMs;
 		this.maxSize = maxSize;
 		this.now = now;
+		this.observer = observer;
+	}
+	startObservation(state) {
+		try {
+			return this.observer?.start({ state }) ?? void 0;
+		} catch {
+			return;
+		}
+	}
+	finishObservation(scope, metadata) {
+		try {
+			scope?.finish(metadata);
+		} catch {}
 	}
 	async getOrFetch(key, fetcher, options = {}) {
-		const { refresh = false } = options;
+		const { refresh = false, getObservationMetadata } = options;
+		let observationState = refresh ? "refresh" : "miss";
 		if (refresh) this.invalidate(key);
 		else {
 			const cachedEntry = this.entries.get(key);
 			if (cachedEntry !== void 0) {
 				if (cachedEntry.expiresAt > this.now()) {
 					this.markAsRecentlyUsed(key, cachedEntry);
+					const observationScope = this.startObservation("hit");
+					this.finishObservation(observationScope);
 					return cachedEntry.value;
 				}
 				this.entries.delete(key);
+				observationState = "expired";
 			}
 			const inFlightEntry = this.inFlight.get(key);
-			if (inFlightEntry !== void 0) return inFlightEntry.promise;
+			if (inFlightEntry !== void 0) {
+				const observationScope = this.startObservation("inflight_wait");
+				inFlightEntry.promise.then(() => this.finishObservation(observationScope), () => this.finishObservation(observationScope));
+				return inFlightEntry.promise;
+			}
 		}
 		const requestId = ++this.requestCounter;
+		const observationScope = this.startObservation(observationState);
 		const request = (async () => {
 			try {
 				const value = await fetcher();
 				if (this.isCurrentRequest(key, requestId)) this.setValue(key, value);
 				return value;
 			} finally {
+				let metadata;
+				try {
+					metadata = getObservationMetadata?.();
+				} catch {
+					metadata = void 0;
+				}
+				this.finishObservation(observationScope, metadata);
 				if (this.inFlight.get(key)?.requestId === requestId) this.inFlight.delete(key);
 			}
 		})();
@@ -4321,17 +4515,20 @@ var AsyncTtlCache = class {
 const EXERCISE_TEMPLATE_CATALOG_CACHE_KEY = "exercise-template-catalog";
 const EXERCISE_TEMPLATE_CATALOG_CACHE_TTL_MS = 300 * 1e3;
 const EXERCISE_TEMPLATE_CATALOG_CACHE_MAX_SIZE = 1;
-/** Create a cache owned by one MCP server/request lifecycle. */
-function createExerciseTemplateCatalog(hevyClient) {
+function createExerciseTemplateCatalog(hevyClient, cacheObserver) {
 	const cache = new AsyncTtlCache({
 		ttlMs: EXERCISE_TEMPLATE_CATALOG_CACHE_TTL_MS,
-		maxSize: EXERCISE_TEMPLATE_CATALOG_CACHE_MAX_SIZE
+		maxSize: EXERCISE_TEMPLATE_CATALOG_CACHE_MAX_SIZE,
+		observer: cacheObserver
 	});
 	return {
 		get(options = {}) {
 			const reason = options.refresh ? "explicit-refresh" : cache.size === 0 ? "initial-load" : "ttl-expired";
+			let observationMetadata;
+			let pagesLoaded = 0;
 			return cache.getOrFetch(EXERCISE_TEMPLATE_CATALOG_CACHE_KEY, async () => {
 				const catalog = await fetchAllPages(async (page, pageSize) => {
+					pagesLoaded = page;
 					const data = await hevyClient.getExerciseTemplates({
 						page,
 						pageSize
@@ -4341,9 +4538,17 @@ function createExerciseTemplateCatalog(hevyClient) {
 						pageCount: data?.page_count
 					};
 				}, 100);
+				observationMetadata = {
+					refreshReason: reason,
+					pageCountBucket: bucketCount(pagesLoaded),
+					itemCountBucket: bucketCount(catalog.length)
+				};
 				options.onRefreshed?.(catalog, reason);
 				return catalog;
-			}, options);
+			}, {
+				refresh: options.refresh,
+				getObservationMetadata: () => observationMetadata
+			});
 		},
 		reset() {
 			cache.clear();
@@ -4405,7 +4610,7 @@ function createHevyMcpServer(options) {
 	const client = options.createClient({ onLog: (event) => mcpLogger(event) });
 	const runtime = createToolRuntime({
 		client,
-		catalog: createExerciseTemplateCatalog(client),
+		catalog: createExerciseTemplateCatalog(client, options.cacheObserver),
 		logger: mcpLogger,
 		observer: options.observer
 	});
@@ -4530,13 +4735,15 @@ function extractMcpClientMetadata(message) {
 		protocolVersion: normalizeMetadata(params.protocolVersion)
 	};
 }
-function createMcpSessionContext(message, transport = "stdio") {
+function createMcpSessionContext(message, transport = "stdio", options = {}) {
+	const normalizedOptions = typeof options === "function" ? { generateTelemetrySessionId: options } : options;
 	return {
 		metadata: extractMcpClientMetadata(message),
-		startedAt: Date.now(),
+		startedAt: (normalizedOptions.now ?? Date.now)(),
 		toolCalls: 0,
 		hadToolFailure: false,
-		transport
+		transport,
+		telemetrySessionId: normalizedOptions.telemetrySessionId ?? (normalizedOptions.generateTelemetrySessionId ?? randomUUID)()
 	};
 }
 function runWithMcpSessionContext(context, callback) {
@@ -4545,6 +4752,9 @@ function runWithMcpSessionContext(context, callback) {
 function getSession() {
 	return contextStorage.getStore() ?? activeStdioSession;
 }
+function getCurrentMcpSessionId() {
+	return getSession()?.telemetrySessionId;
+}
 function metadataAttributes(metadata, transport) {
 	return {
 		client_name: metadata.name,
@@ -4985,6 +5195,38 @@ function debugLog(event, data) {
 }
 //#endregion
 //#region src/utils/hevy-client-observability.ts
+function safeErrorAttributes(observation) {
+	if (!observation.error) return {};
+	const code = observation.error.code;
+	return {
+		error_category: observation.error.category ?? "HevyHttpError",
+		...code && SAFE_OBSERVATION_CODES.has(code) ? { error_code: code } : {}
+	};
+}
+function startApiSpan(start) {
+	const sessionId = getCurrentMcpSessionId();
+	return tracer.startSpan(`hevy.api.${start.method}`, { attributes: {
+		"mcp.span.category": "api",
+		"http.request.method": start.method,
+		"hevy.api.endpoint": start.endpoint,
+		"hevy.api.retry_count_bucket": bucketCount(start.retryCount),
+		"mcp.transport": getCurrentMcpTransport(),
+		...sessionId ? { "mcp.session.id": sessionId } : {}
+	} });
+}
+function finishApiSpan(span, observation) {
+	const errorAttributes = safeErrorAttributes(observation);
+	if (observation.status > 0) span.setAttribute("http.response.status_code", observation.status);
+	span.setAttribute("hevy.api.outcome", observation.outcome);
+	if (observation.expectedReason) span.setAttribute("hevy.api.expected_reason", observation.expectedReason);
+	for (const [key, value] of Object.entries(errorAttributes)) span.setAttribute(key, value);
+	span.setStatus({ code: observation.outcome === "success" || observation.outcome === "expected" ? SpanStatusCode.OK : SpanStatusCode.ERROR });
+	if (observation.outcome !== "success" && observation.outcome !== "expected") span.addEvent("hevy.api.failure", {
+		"error.category": errorAttributes.error_category ?? "HevyHttpError",
+		...errorAttributes.error_code ? { "error.code": errorAttributes.error_code } : {}
+	});
+	span.end();
+}
 /** Node-only adapter; the Worker graph never imports telemetry or metrics. */
 function createNodeHevyClientOptions() {
 	const rawTimeout = process.env.HEVY_MCP_API_TIMEOUT;
@@ -4992,37 +5234,38 @@ function createNodeHevyClientOptions() {
 	const timeoutMs = Number.isFinite(parsedTimeout) && parsedTimeout > 0 ? Math.floor(parsedTimeout) : void 0;
 	return {
 		...timeoutMs ? { timeoutMs } : {},
+		onRequestStart(start) {
+			const span = startApiSpan(start);
+			return {
+				run(operation) {
+					return context.with(trace.setSpan(context.active(), span), operation);
+				},
+				finish(observation) {
+					finishApiSpan(span, observation);
+				}
+			};
+		},
 		onRequestComplete(observation) {
 			const retryCountBucket = bucketCount(observation.retryCount);
-			const diagnostic = observation.error ? createSafeErrorDiagnostic(observation.error) : void 0;
-			const safeErrorAttributes = diagnostic ? {
-				error_category: diagnostic.category,
-				...diagnostic.code ? { error_code: diagnostic.code } : {}
-			} : {};
-			const span = tracer.startSpan(`hevy.api.${observation.method}`, { attributes: {
-				"http.method": observation.method,
-				"http.status_code": observation.status,
-				"hevy.api.retry_count_bucket": retryCountBucket,
-				"hevy.api.endpoint": observation.endpoint
-			} });
-			span.setStatus({ code: observation.error ? SpanStatusCode.ERROR : SpanStatusCode.OK });
-			if (diagnostic) span.addEvent("hevy.api.failure", {
-				"error.category": diagnostic.category,
-				...diagnostic.code ? { "error.code": diagnostic.code } : {}
-			});
-			span.end();
+			const errorAttributes = safeErrorAttributes(observation);
 			apiCalls.add(1, {
 				method: observation.method,
 				endpoint: observation.endpoint,
 				status_code: observation.status,
 				retry_count_bucket: retryCountBucket,
-				...safeErrorAttributes
+				outcome: observation.outcome,
+				transport: getCurrentMcpTransport(),
+				...observation.expectedReason ? { expected_reason: observation.expectedReason } : {},
+				...errorAttributes
 			});
 			apiDuration.record(observation.durationMs, {
 				method: observation.method,
 				endpoint: observation.endpoint,
 				retry_count_bucket: retryCountBucket,
-				...safeErrorAttributes
+				outcome: observation.outcome,
+				transport: getCurrentMcpTransport(),
+				...observation.expectedReason ? { expected_reason: observation.expectedReason } : {},
+				...errorAttributes
 			});
 			debugLog("api_response", {
 				method: observation.method,
@@ -5030,13 +5273,43 @@ function createNodeHevyClientOptions() {
 				durationMs: observation.durationMs,
 				status: observation.status || null,
 				retryCountBucket,
-				...safeErrorAttributes
+				outcome: observation.outcome,
+				...errorAttributes
 			});
+		},
+		onRetryWait(observation) {
+			const sessionId = getCurrentMcpSessionId();
+			const span = tracer.startSpan("hevy.api.retry_wait", { attributes: {
+				"mcp.span.category": "api",
+				"http.request.method": observation.method,
+				"hevy.api.retry_count_bucket": bucketCount(observation.retryCount),
+				"hevy.api.retry_wait_ms": Math.max(0, Math.min(5e3, observation.delayMs)),
+				...sessionId ? { "mcp.session.id": sessionId } : {}
+			} });
+			return { finish: () => span.end() };
 		}
 	};
 }
+function createNodeCacheObserver() {
+	return { start(observation) {
+		const sessionId = getCurrentMcpSessionId();
+		const span = tracer.startSpan(`hevy.cache.${observation.state}`, { attributes: {
+			"mcp.span.category": "cache",
+			"hevy.cache.state": observation.state,
+			"mcp.transport": getCurrentMcpTransport(),
+			...sessionId ? { "mcp.session.id": sessionId } : {}
+		} });
+		return { finish(metadata) {
+			if (metadata?.refreshReason) span.setAttribute("hevy.cache.refresh_reason", metadata.refreshReason);
+			if (metadata?.pageCountBucket) span.setAttribute("hevy.cache.page_count_bucket", metadata.pageCountBucket);
+			if (metadata?.itemCountBucket) span.setAttribute("hevy.cache.item_count_bucket", metadata.itemCountBucket);
+			span.end();
+		} };
+	} };
+}
 //#endregion
 //#region src/utils/tool-observer.ts
+const DISCOVERY_TOOL_NAMES = /* @__PURE__ */ new Set(["search-routines"]);
 const WORKFLOW_PAGINATION_RESOURCES = /* @__PURE__ */ new Set([
 	"workouts",
 	"bodyMeasurements",
@@ -5059,8 +5332,11 @@ function metricAttributes(invocation, clientAttributes) {
 }
 function createAttributes(invocation) {
 	const clientMetadata = getCurrentMcpClientMetadata();
+	const isPrompt = invocation.kind === "prompt";
+	const sessionId = getCurrentMcpSessionId();
 	const attributes = {
-		[invocation.kind === "prompt" ? "mcp.prompt.name" : "mcp.tool.name"]: invocation.name,
+		"mcp.span.category": DISCOVERY_TOOL_NAMES.has(invocation.name) ? "discovery" : "tool",
+		[isPrompt ? "mcp.prompt.name" : "mcp.tool.name"]: invocation.name,
 		"mcp.operation.kind": invocation.kind ?? "tool",
 		...taxonomyAttributes(invocation),
 		"mcp.client.name": clientMetadata.name,
@@ -5068,7 +5344,8 @@ function createAttributes(invocation) {
 		"mcp.protocol.version": clientMetadata.protocolVersion,
 		"mcp.transport": getCurrentMcpTransport(),
 		"mcp.tool.args.key_count_bucket": invocation.argumentKeyCountBucket ?? "unknown",
-		"mcp.tool.args.keys": invocation.argumentKeys?.join(",") ?? ""
+		"mcp.tool.args.keys": invocation.argumentKeys?.join(",") ?? "",
+		...sessionId ? { "mcp.session.id": sessionId } : {}
 	};
 	for (const key of Object.keys(invocation.argumentPresence ?? {})) attributes[`mcp.tool.args.${key}.present`] = true;
 	for (const [key, bucket] of Object.entries(invocation.numericArgumentBuckets ?? {})) if (bucket !== void 0) attributes[`mcp.tool.args.${key}.bucket`] = bucket;
@@ -5106,14 +5383,16 @@ function resultMetricAttributes(completion) {
 	if (summary?.setCountBucket) attributes["mcp.tool.result.set_count_bucket"] = summary.setCountBucket;
 	return attributes;
 }
-function setSafeErrorAttributes(span, completion) {
+function setSafeErrorAttributes(span, invocation, completion) {
 	const diagnostic = completion.error;
 	const errorType = completion.errorType ?? "UNKNOWN_ERROR";
 	if (diagnostic) span.addEvent("mcp.tool.failure", {
+		"mcp.tool.name": invocation.name,
+		"error.type": errorType,
 		"error.category": diagnostic.category,
 		...diagnostic.code ? { "error.code": diagnostic.code } : {},
-		...diagnostic.status !== void 0 ? { "http.status_code": diagnostic.status } : {},
-		...diagnostic.method ? { "http.method": diagnostic.method } : {},
+		...diagnostic.status !== void 0 ? { "http.response.status_code": diagnostic.status } : {},
+		...diagnostic.method ? { "http.request.method": diagnostic.method } : {},
 		...diagnostic.endpoint ? { "hevy.api.endpoint": diagnostic.endpoint } : {}
 	});
 	span.setAttribute("error.type", errorType);
@@ -5130,8 +5409,8 @@ function captureSafeToolFailure(invocation, completion) {
 			scope.setTag("error.type", completion.errorType ?? "UNKNOWN_ERROR");
 			scope.setTag("error.category", category);
 			if (diagnostic?.code) scope.setTag("error.code", diagnostic.code);
-			if (diagnostic?.status !== void 0) scope.setTag("http.status_code", String(diagnostic.status));
-			if (diagnostic?.method) scope.setTag("http.method", diagnostic.method);
+			if (diagnostic?.status !== void 0) scope.setTag("http.response.status_code", String(diagnostic.status));
+			if (diagnostic?.method) scope.setTag("http.request.method", diagnostic.method);
 			if (diagnostic?.endpoint) scope.setTag("hevy.api.endpoint", diagnostic.endpoint);
 			scope.setContext(invocation.kind === "prompt" ? "mcpPrompt" : "mcpTool", {
 				context: invocation.name,
@@ -5185,26 +5464,35 @@ function createNodeToolObserver() {
 						activeSpan.setAttribute("mcp.tool.outcome", nextCompletion.outcome);
 						setResultAttributes(activeSpan, nextCompletion);
 						if (nextCompletion.outcome === "thrown_error") {
-							errorType = setSafeErrorAttributes(activeSpan, nextCompletion);
+							errorType = setSafeErrorAttributes(activeSpan, invocation, nextCompletion);
 							bestEffort(() => recordTelemetryException(new Error(nextCompletion.error?.category ?? errorType), {
 								[invocation.kind === "prompt" ? "mcp.prompt.name" : "mcp.tool.name"]: invocation.name,
 								"error.type": errorType ?? "UNKNOWN_ERROR",
 								"error.category": nextCompletion.error?.category ?? "UnknownError",
 								...nextCompletion.error?.code ? { "error.code": nextCompletion.error.code } : {},
-								...nextCompletion.error?.status !== void 0 ? { "http.status_code": nextCompletion.error.status } : {},
-								...nextCompletion.error?.method ? { "http.method": nextCompletion.error.method } : {},
+								...nextCompletion.error?.status !== void 0 ? { "http.response.status_code": nextCompletion.error.status } : {},
+								...nextCompletion.error?.method ? { "http.request.method": nextCompletion.error.method } : {},
+								...nextCompletion.error?.endpoint ? { "hevy.api.endpoint": nextCompletion.error.endpoint } : {}
+							}, activeSpan));
+						}
+						if (nextCompletion.outcome === "returned_error") {
+							activeSpan.addEvent("mcp.tool.failure", {
+								"mcp.tool.name": invocation.name,
+								"error.type": "UNKNOWN_ERROR",
+								"error.category": "McpToolReturnedError",
+								"error.code": "MCP_TOOL_RETURNED_ERROR"
+							});
+							activeSpan.setAttribute("error.type", "UNKNOWN_ERROR");
+							bestEffort(() => recordTelemetryException(new Error(nextCompletion.error?.category ?? "UnknownError"), {
+								[invocation.kind === "prompt" ? "mcp.prompt.name" : "mcp.tool.name"]: invocation.name,
+								"error.type": nextCompletion.errorType ?? "UNKNOWN_ERROR",
+								"error.category": nextCompletion.error?.category ?? "UnknownError",
+								...nextCompletion.error?.code ? { "error.code": nextCompletion.error.code } : {},
+								...nextCompletion.error?.status !== void 0 ? { "http.response.status_code": nextCompletion.error.status } : {},
+								...nextCompletion.error?.method ? { "http.request.method": nextCompletion.error.method } : {},
 								...nextCompletion.error?.endpoint ? { "hevy.api.endpoint": nextCompletion.error.endpoint } : {}
 							}, activeSpan));
 						}
-						if (nextCompletion.outcome === "returned_error") bestEffort(() => recordTelemetryException(new Error(nextCompletion.error?.category ?? "UnknownError"), {
-							[invocation.kind === "prompt" ? "mcp.prompt.name" : "mcp.tool.name"]: invocation.name,
-							"error.type": nextCompletion.errorType ?? "UNKNOWN_ERROR",
-							"error.category": nextCompletion.error?.category ?? "UnknownError",
-							...nextCompletion.error?.code ? { "error.code": nextCompletion.error.code } : {},
-							...nextCompletion.error?.status !== void 0 ? { "http.status_code": nextCompletion.error.status } : {},
-							...nextCompletion.error?.method ? { "http.method": nextCompletion.error.method } : {},
-							...nextCompletion.error?.endpoint ? { "hevy.api.endpoint": nextCompletion.error.endpoint } : {}
-						}, activeSpan));
 					}
 				} catch {} finally {
 					if (nextCompletion.outcome === "thrown_error") {
@@ -5385,14 +5673,17 @@ function deserializeMessageWithObservability(line, chunkSnapshot) {
 	const lineHadLeadingBom = line.startsWith(UTF8_BOM);
 	const normalizedLine = lineHadLeadingBom ? line.slice(1) : line;
 	const lineByteLength = Buffer.byteLength(line);
+	const sessionId = getCurrentMcpSessionId();
 	return tracer.startActiveSpan("mcp.stdio.deserialize", { attributes: {
+		"mcp.span.category": "protocol",
 		"mcp.transport": "stdio",
 		"mcp.stdio.parse.line.char_length": line.length,
 		"mcp.stdio.parse.line.byte_length": lineByteLength,
 		"mcp.stdio.parse.line.had_leading_bom": lineHadLeadingBom,
 		"mcp.stdio.parse.line.bom_stripped": lineHadLeadingBom,
 		"mcp.stdio.parse.chunk.last_byte_length": chunkSnapshot.lastChunkByteLength,
-		"mcp.stdio.parse.chunk.last_had_utf8_bom": chunkSnapshot.lastChunkStartsWithUtf8Bom
+		"mcp.stdio.parse.chunk.last_had_utf8_bom": chunkSnapshot.lastChunkStartsWithUtf8Bom,
+		...sessionId ? { "mcp.session.id": sessionId } : {}
 	} }, (span) => {
 		try {
 			const message = deserializeMessage(normalizedLine);
@@ -5402,6 +5693,8 @@ function deserializeMessageWithObservability(line, chunkSnapshot) {
 				if (typeof method === "string" && SAFE_MCP_METHODS[method] === true) span.setAttribute("mcp.method", method);
 				if (method === "initialize") {
 					const client = recordMcpSessionStart(message);
+					const sessionId = getCurrentMcpSessionId();
+					if (sessionId) span.setAttribute("mcp.session.id", sessionId);
 					span.setAttribute("mcp.client.name", client.name);
 					span.setAttribute("mcp.client.version", client.version);
 					span.setAttribute("mcp.protocol.version", client.protocolVersion);
@@ -5440,6 +5733,177 @@ function createInstrumentedStdioTransport(transport) {
 	return transport;
 }
 //#endregion
+//#region src/utils/sdk-observability.ts
+const sdkToolNameStorage = new AsyncLocalStorage();
+const SAFE_TOOL_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/u;
+const SDK_FAILURE_TAXONOMY = {
+	protocol: {
+		errorType: "UNKNOWN_ERROR",
+		errorCategory: "McpSdkProtocolFailure"
+	},
+	tool_call: {
+		errorType: "UNKNOWN_ERROR",
+		errorCategory: "McpSdkToolCallFailure"
+	},
+	validation: {
+		errorType: "VALIDATION_ERROR",
+		errorCategory: "McpSdkValidationFailure"
+	}
+};
+function createFailureAttributes(error, phase, errorType, errorCategory) {
+	const diagnostic = createSafeErrorDiagnostic(error);
+	return {
+		"mcp.failure.phase": phase,
+		"error.type": errorType,
+		"error.category": errorCategory,
+		...diagnostic.code ? { "error.code": diagnostic.code } : {},
+		...diagnostic.status !== void 0 ? { "http.response.status_code": diagnostic.status } : {},
+		...diagnostic.method ? { "http.request.method": diagnostic.method } : {},
+		...diagnostic.endpoint ? { "hevy.api.endpoint": diagnostic.endpoint } : {}
+	};
+}
+function enrichActiveSdkSpan(attributes) {
+	try {
+		trace.getActiveSpan()?.setAttributes(attributes);
+	} catch {}
+}
+function getSdkToolName(request) {
+	if (!request || typeof request !== "object") return "unknown";
+	const candidate = request.params?.name;
+	return typeof candidate === "string" && SAFE_TOOL_NAME_PATTERN.test(candidate) ? candidate : "unknown";
+}
+function markSdkToolFailure(span, error, toolName = sdkToolNameStorage.getStore() ?? "unknown", kind = "tool_call") {
+	const taxonomy = SDK_FAILURE_TAXONOMY[kind];
+	const attributes = createFailureAttributes(error, "sdk", taxonomy.errorType, taxonomy.errorCategory);
+	span.addEvent("mcp.tool.failure", {
+		"mcp.tool.name": toolName,
+		...attributes
+	});
+	span.setAttribute("error.type", taxonomy.errorType);
+	recordTelemetryException(error, attributes, span);
+	span.setStatus({ code: SpanStatusCode.ERROR });
+}
+function installProtocolErrorTracking(server, transport) {
+	const protocol = server.server;
+	if (!protocol) return;
+	const previous = protocol.onerror;
+	protocol.onerror = (error) => {
+		const taxonomy = SDK_FAILURE_TAXONOMY.protocol;
+		const attributes = createFailureAttributes(error, "sdk", taxonomy.errorType, taxonomy.errorCategory);
+		const activeSpan = trace.getActiveSpan();
+		const sessionId = getCurrentMcpSessionId();
+		if (activeSpan) {
+			activeSpan.addEvent("mcp.tool.failure", {
+				"mcp.tool.name": sdkToolNameStorage.getStore() ?? "unknown",
+				...attributes
+			});
+			recordTelemetryException(error, attributes, activeSpan);
+		} else tracer.startActiveSpan("mcp.sdk.failure", { attributes: {
+			"mcp.span.category": "protocol",
+			"mcp.transport": transport,
+			...sessionId ? { "mcp.session.id": sessionId } : {}
+		} }, (span) => {
+			span.addEvent("mcp.tool.failure", {
+				"mcp.tool.name": "unknown",
+				...attributes
+			});
+			recordTelemetryException(error, attributes, span);
+			span.end();
+		});
+		try {
+			previous?.(error);
+		} catch {}
+	};
+}
+function installValidationErrorTracking(server) {
+	const toolErrorHost = server;
+	const previousCreateToolError = toolErrorHost.createToolError;
+	if (!previousCreateToolError) return;
+	const createToolError = previousCreateToolError.bind(server);
+	toolErrorHost.createToolError = (message) => {
+		const result = createToolError(message);
+		const activeSpan = trace.getActiveSpan();
+		if (activeSpan) markSdkToolFailure(activeSpan, /* @__PURE__ */ new Error("MCP tool validation failed"), void 0, "validation");
+		return result;
+	};
+}
+function installInitializeEnrichment(handlers, transport) {
+	const initializeHandler = handlers.get("initialize");
+	if (!initializeHandler) return;
+	handlers.set("initialize", (request, extra) => {
+		enrichActiveSdkSpan({
+			"mcp.span.category": "protocol",
+			"mcp.transport": transport
+		});
+		return initializeHandler(request, extra);
+	});
+}
+function installToolCallTracking(handlers, transport) {
+	const toolHandler = handlers.get("tools/call");
+	if (!toolHandler) return;
+	handlers.set("tools/call", (request, extra) => {
+		const sessionId = getCurrentMcpSessionId();
+		const toolName = getSdkToolName(request);
+		const attributes = {
+			"mcp.span.category": "protocol",
+			"mcp.transport": transport,
+			"mcp.operation.kind": "tool",
+			"mcp.tool.name": toolName,
+			...sessionId ? { "mcp.session.id": sessionId } : {}
+		};
+		enrichActiveSdkSpan(attributes);
+		return sdkToolNameStorage.run(toolName, () => tracer.startActiveSpan("mcp.sdk.tools.call", { attributes }, async (span) => {
+			try {
+				const result = await toolHandler(request, extra);
+				if (result?.isError === true) {
+					span.setAttribute("mcp.tool.outcome", "returned_error");
+					span.setStatus({ code: SpanStatusCode.ERROR });
+				} else span.setStatus({ code: SpanStatusCode.OK });
+				return result;
+			} catch (error) {
+				markSdkToolFailure(span, error, toolName);
+				throw error;
+			} finally {
+				span.end();
+			}
+		}));
+	});
+}
+function installDiscoveryTracking(handlers) {
+	const discoveryHandler = handlers.get("server/discover");
+	if (!discoveryHandler) return;
+	handlers.set("server/discover", (request, extra) => {
+		const sessionId = getCurrentMcpSessionId();
+		return tracer.startActiveSpan("mcp.server.discover", { attributes: {
+			"mcp.span.category": "discovery",
+			"mcp.transport": getCurrentMcpTransport(),
+			...sessionId ? { "mcp.session.id": sessionId } : {}
+		} }, async (span) => {
+			try {
+				const result = await discoveryHandler(request, extra);
+				span.setStatus({ code: SpanStatusCode.OK });
+				return result;
+			} catch (error) {
+				const attributes = createFailureAttributes(error, "discovery", "UNKNOWN_ERROR", "McpServerDiscoveryFailure");
+				span.addEvent("mcp.discovery.failure", attributes);
+				recordTelemetryException(error, attributes, span);
+				throw error;
+			} finally {
+				span.end();
+			}
+		});
+	});
+}
+function installSdkErrorTracking(server, transport) {
+	installProtocolErrorTracking(server, transport);
+	installValidationErrorTracking(server);
+	const handlers = server.server?._requestHandlers;
+	if (!(handlers instanceof Map)) return;
+	installInitializeEnrichment(handlers, transport);
+	installToolCallTracking(handlers, transport);
+	installDiscoveryTracking(handlers);
+}
+//#endregion
 //#region src/utils/version-check.ts
 const CACHE_TTL_MS = 1440 * 60 * 1e3;
 const REQUEST_TIMEOUT_MS = 3e3;
@@ -5568,8 +6032,8 @@ function scheduleUpdateCheck(options, overrides = {}) {
 }
 //#endregion
 //#region src/index.ts
-const name = name$1;
-const version = version$1;
+const name = serviceName;
+const version = serviceVersion;
 const HELP_TEXT = [
 	"Usage:",
 	"  hevy-mcp [options]",
@@ -5629,6 +6093,46 @@ function getSafeValidationDiagnostic(error) {
 	const code = error.code;
 	return typeof code === "string" && SAFE_NETWORK_ERROR_CODES.has(code) ? code : void 0;
 }
+const LIFECYCLE_FAILURE_TAXONOMY = {
+	config: {
+		errorType: "MCP_SERVER_CONFIG_ERROR",
+		errorCategory: "McpServerConfigFailure"
+	},
+	api_key_validation: {
+		errorType: "MCP_API_KEY_VALIDATION_ERROR",
+		errorCategory: "McpApiKeyValidationFailure"
+	},
+	build: {
+		errorType: "MCP_SERVER_BUILD_ERROR",
+		errorCategory: "McpServerBuildFailure"
+	},
+	connect: {
+		errorType: "MCP_TRANSPORT_CONNECT_ERROR",
+		errorCategory: "McpTransportConnectFailure"
+	},
+	run: {
+		errorType: "MCP_SERVER_RUN_ERROR",
+		errorCategory: "McpServerRunFailure"
+	}
+};
+function createLifecycleFailureAttributes(error, phase) {
+	const diagnostic = createSafeErrorDiagnostic(error);
+	const taxonomy = LIFECYCLE_FAILURE_TAXONOMY[phase];
+	return {
+		"mcp.failure.phase": phase,
+		"error.type": taxonomy.errorType,
+		"error.category": taxonomy.errorCategory,
+		...diagnostic.code ? { "error.code": diagnostic.code } : {},
+		...diagnostic.status !== void 0 ? { "http.response.status_code": diagnostic.status } : {},
+		...diagnostic.method ? { "http.request.method": diagnostic.method } : {},
+		...diagnostic.endpoint ? { "hevy.api.endpoint": diagnostic.endpoint } : {}
+	};
+}
+function recordLifecycleFailure(span, error, phase) {
+	const attributes = createLifecycleFailureAttributes(error, phase);
+	span.addEvent("mcp.lifecycle.failure", attributes);
+	recordTelemetryException(error, attributes, span);
+}
 async function validateApiKey(apiKey) {
 	const startupProbeClient = createHevyClient({
 		apiKey,
@@ -5647,6 +6151,7 @@ async function validateApiKey(apiKey) {
 }
 function buildServer(apiKey, transport = "stdio") {
 	return tracer.startActiveSpan("mcp.server.build", { attributes: {
+		"mcp.span.category": "startup",
 		"mcp.server.name": name,
 		"mcp.server.version": version,
 		"mcp.transport": transport
@@ -5663,12 +6168,15 @@ function buildServer(apiKey, transport = "stdio") {
 					recordOutputs: false
 				}),
 				onToolsRegistered: (count) => span.setAttribute("mcp.tools.count", count),
-				observer: createNodeToolObserver()
+				observer: createNodeToolObserver(),
+				cacheObserver: createNodeCacheObserver()
 			});
+			installSdkErrorTracking(server, transport);
 			console.error("Hevy client initialized with API key");
 			span.setStatus({ code: SpanStatusCode.OK });
 			return server;
 		} catch (e) {
+			recordLifecycleFailure(span, e, "build");
 			span.setStatus({ code: SpanStatusCode.ERROR });
 			throw e;
 		} finally {
@@ -5697,7 +6205,11 @@ async function runStdioServer() {
 	const configuredApiKey = process.env.HEVY_API_KEY;
 	if (configuredApiKey) setTelemetryUser(configuredApiKey);
 	let connectAttempted = false;
-	await tracer.startActiveSpan("mcp.server.run", { attributes: { "mcp.transport": "stdio" } }, async (span) => {
+	let connectSucceeded = false;
+	await tracer.startActiveSpan("mcp.server.run", { attributes: {
+		"mcp.span.category": "startup",
+		"mcp.transport": "stdio"
+	} }, async (span) => {
 		try {
 			const apiKey = parseConfig(process.env).apiKey;
 			assertApiKey(apiKey);
@@ -5705,11 +6217,16 @@ async function runStdioServer() {
 			console.error("Starting MCP server in stdio mode");
 			const transport = createInstrumentedStdioTransport(new StdioServerTransport());
 			connectAttempted = true;
-			await tracer.startActiveSpan("mcp.server.connect", { attributes: { "mcp.transport": "stdio" } }, async (connectSpan) => {
+			await tracer.startActiveSpan("mcp.server.connect", { attributes: {
+				"mcp.span.category": "session",
+				"mcp.transport": "stdio"
+			} }, async (connectSpan) => {
 				try {
 					await server.connect(transport);
+					connectSucceeded = true;
 					connectSpan.setStatus({ code: SpanStatusCode.OK });
 				} catch (e) {
+					recordLifecycleFailure(connectSpan, e, "connect");
 					connectSpan.setStatus({ code: SpanStatusCode.ERROR });
 					throw e;
 				} finally {
@@ -5717,8 +6234,8 @@ async function runStdioServer() {
 				}
 			});
 			scheduleUpdateCheck({
-				packageName: name$1,
-				currentVersion: version$1
+				packageName: serviceName,
+				currentVersion: serviceVersion
 			});
 			installGracefulShutdown({
 				target: server,
@@ -5730,6 +6247,7 @@ async function runStdioServer() {
 			});
 			span.setStatus({ code: SpanStatusCode.OK });
 		} catch (e) {
+			if (!connectAttempted || connectSucceeded) recordLifecycleFailure(span, e, "run");
 			recordMcpSessionTermination(connectAttempted ? "connect_failure" : "startup_failure");
 			span.setStatus({ code: SpanStatusCode.ERROR });
 			cleanupProcessExceptionTracking();
@@ -5756,7 +6274,10 @@ async function runServer() {
 		return;
 	}
 	const cleanupProcessExceptionTracking = installProcessExceptionTracking();
-	await tracer.startActiveSpan("mcp.server.run", { attributes: { "mcp.transport": "http" } }, async (span) => {
+	await tracer.startActiveSpan("mcp.server.run", { attributes: {
+		"mcp.span.category": "startup",
+		"mcp.transport": "http"
+	} }, async (span) => {
 		let listening = false;
 		serverStartups.add(1, { version });
 		try {
@@ -5768,8 +6289,8 @@ async function runServer() {
 			listening = true;
 			console.error(`Starting MCP server in HTTP mode at ${options.host}:${options.port}/mcp`);
 			scheduleUpdateCheck({
-				packageName: name$1,
-				currentVersion: version$1
+				packageName: serviceName,
+				currentVersion: serviceVersion
 			});
 			installGracefulShutdown({
 				target: handle,
@@ -5780,6 +6301,7 @@ async function runServer() {
 			});
 			span.setStatus({ code: SpanStatusCode.OK });
 		} catch (error) {
+			recordLifecycleFailure(span, error, "run");
 			recordMcpSessionTermination(listening ? "unknown" : "startup_failure");
 			span.setStatus({ code: SpanStatusCode.ERROR });
 			cleanupProcessExceptionTracking();

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "hevy-mcp",
-	"version": "5.0.3",
+	"version": "5.0.5",
 	"private": false,
 	"description": "A Model Context Protocol (MCP) server implementation that interfaces with the Hevy fitness tracking app and its API.",
 	"repository": {

package/server.json

@@ -7,12 +7,12 @@
 		"url": "https://github.com/chrisdoc/hevy-mcp",
 		"source": "github"
 	},
-	"version": "5.0.3",
+	"version": "5.0.5",
 	"packages": [
 		{
 			"registryType": "npm",
 			"identifier": "hevy-mcp",
-			"version": "5.0.3",
+			"version": "5.0.5",
 			"transport": {
 				"type": "stdio"
 			},