@juspay/neurolink 9.54.6 → 9.54.8

package/dist/lib/server/routes/claudeProxyRoutes.js

@@ -15,6 +15,8 @@ import { join } from "node:path";
 import { buildStableClaudeCodeBillingHeader, CLAUDE_CLI_USER_AGENT, CLAUDE_CODE_OAUTH_BETAS, getOrCreateClaudeCodeIdentity, parseClaudeCodeUserId, } from "../../auth/anthropicOAuth.js";
 import { parseQuotaHeaders, saveAccountQuota, } from "../../proxy/accountQuota.js";
 import { buildClaudeError, ClaudeStreamSerializer, generateToolUseId, parseClaudeRequest, serializeClaudeResponse, } from "../../proxy/claudeFormat.js";
+import { tracers } from "../../telemetry/tracers.js";
+import { withSpan } from "../../telemetry/withSpan.js";
 import { ProxyTracer, recordFallbackAttempt } from "../../proxy/proxyTracer.js";
 import { createRawStreamCapture } from "../../proxy/rawStreamCapture.js";
 import { logBodyCapture, logRequest, logRequestAttempt, logStreamError, } from "../../proxy/requestLogger.js";
@@ -51,7 +53,7 @@ const MAX_TRANSIENT_SAME_ACCOUNT_RETRIES = 2;
 const TRANSIENT_SAME_ACCOUNT_RETRY_DELAYS_MS = [250, 1_000];
 /** Maximum upstream 429 attempts per account before rotating to the next account.
  *  Total attempts per account = this + 1 (the initial call plus this many retries). */
-const MAX_RATE_LIMIT_SAME_ACCOUNT_RETRIES = 5;
+const MAX_RATE_LIMIT_SAME_ACCOUNT_RETRIES = 10;
 /** Max time to sleep between 429 retries. Caps large upstream retry-after values
  *  so we don't hold the client connection open for minutes. */
 const MAX_RATE_LIMIT_RETRY_DELAY_MS = 30_000;
@@ -62,6 +64,10 @@ const UPSTREAM_FETCH_TIMEOUT_MS = 15 * 60 * 1000; // 15 minutes
 const accountRuntimeState = new Map();
 /** Track whether we've run the one-time startup prune. */
 let startupPruneDone = false;
+/** Default cooling period when retries are exhausted and upstream didn't
+ *  provide a retry-after header. Short enough to recover quickly, long
+ *  enough to avoid immediately hammering the same account. */
+const DEFAULT_COOLING_PERIOD_MS = 60_000;
 /** Advance the primary account index when the current primary is exhausted
  *  (429 retries exhausted or auth failure). This is what makes fill-first work:
  *  we stick to one account until it's unusable. Only advances when the exhausted
@@ -76,6 +82,33 @@ function advancePrimaryIfCurrent(accountKey, enabledCount, primaryAccountKey) {
     }
     primaryAccountIndex = (primaryAccountIndex + 1) % enabledCount;
 }
+/** If the configured home primary (index 0) is no longer cooling, reset
+ *  primaryAccountIndex back to 0 so traffic returns to the preferred account
+ *  once its rate limit window expires. Called at the start of each request. */
+function maybeResetPrimaryToHome(enabledAccounts) {
+    if (enabledAccounts.length <= 1 || primaryAccountIndex === 0) {
+        return;
+    }
+    const homeState = accountRuntimeState.get(enabledAccounts[0].key);
+    if (!homeState ||
+        !homeState.coolingUntil ||
+        Date.now() >= homeState.coolingUntil) {
+        // Home account is no longer cooling — reset to it
+        primaryAccountIndex = 0;
+        if (homeState?.coolingUntil) {
+            homeState.coolingUntil = undefined;
+            logger.always(`[proxy] home primary account=${enabledAccounts[0].label} cooling expired, resetting primaryAccountIndex to 0`);
+        }
+    }
+}
+/** Check if an account is currently in its cooling window. */
+function isAccountCooling(accountKey) {
+    const state = accountRuntimeState.get(accountKey);
+    return !!state?.coolingUntil && Date.now() < state.coolingUntil;
+}
+// ---------------------------------------------------------------------------
+// OAuth polyfill helpers (extracted to reduce block nesting)
+// ---------------------------------------------------------------------------
 const snapshotCache = new Map();
 const SNAPSHOT_CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
 const SNAPSHOT_STABLE_HEADERS = new Set([
@@ -2204,6 +2237,32 @@ async function handleAnthropicAuthRetry(args) {
             }
             const retryStatus = retryResp.status;
             const retryBody = await retryResp.text();
+            // Capture full response headers and body for all auth-retry errors.
+            // Redact sensitive headers and cap body size before persisting.
+            const retryRespHeaders = {};
+            retryResp.headers.forEach((value, key) => {
+                retryRespHeaders[key] = value;
+            });
+            const safeRetryHeaders = { ...retryRespHeaders };
+            delete safeRetryHeaders["authorization"];
+            delete safeRetryHeaders["x-api-key"];
+            const cappedRetryBody = retryBody.length > 4000
+                ? retryBody.slice(0, 4000) + "...[truncated]"
+                : retryBody;
+            tracer?.logUpstreamResponseHeaders(safeRetryHeaders);
+            tracer?.logUpstreamResponseBody(cappedRetryBody);
+            logProxyBody({
+                phase: "upstream_response",
+                headers: safeRetryHeaders,
+                body: cappedRetryBody,
+                bodySize: Buffer.byteLength(retryBody, "utf8"),
+                contentType: retryRespHeaders["content-type"] ?? "application/json",
+                account: account.label,
+                accountType: account.type,
+                attempt: attemptNumber,
+                responseStatus: retryStatus,
+                durationMs: Date.now() - fetchStartMs,
+            });
             authRetryError = `retry ${authRetry + 1}/${MAX_AUTH_RETRIES} failed with status ${retryStatus}`;
             currentLastError = retryBody;
             logger.debug(`[proxy] retry ${authRetry + 1} failed: ${retryStatus} ${retryBody.substring(0, 120)}`);
@@ -2775,7 +2834,7 @@ async function prepareAnthropicAccountAttempt(args) {
     };
 }
 async function fetchAnthropicAccountResponse(args) {
-    const { url, headers, finalBodyStr, account, accountState: _accountState2, enabledAccounts: _enabledAccounts, orderedAccounts: _orderedAccounts, tracer, logAttempt, currentLastError, currentSawRateLimit, currentSawNetworkError, upstreamSpan, } = args;
+    const { url, headers, finalBodyStr, account, accountState: _accountState2, enabledAccounts: _enabledAccounts, orderedAccounts: _orderedAccounts, tracer, logAttempt, logProxyBody, fetchStartMs, attemptNumber, currentLastError, currentSawRateLimit, currentSawNetworkError, upstreamSpan, } = args;
     let lastError = currentLastError;
     let sawRateLimit = currentSawRateLimit;
     let sawNetworkError = currentSawNetworkError;
@@ -2816,8 +2875,35 @@ async function fetchAnthropicAccountResponse(args) {
         sawRateLimit = true;
         const retryAfterMs = parseRetryAfterMs(response.headers.get("retry-after"));
         recordAttemptError(account.label, account.type, 429);
+        // Capture full response headers and body for diagnostics (parity with
+        // handleAnthropicNonOkResponse which does this for all other error statuses).
+        const errRespHeaders = {};
+        response.headers.forEach((value, key) => {
+            errRespHeaders[key] = value;
+        });
         lastError = await response.text();
-        logger.always(`[proxy] ← 429 account=${account.label} retry-after=${retryAfterMs}ms (upstream)`);
+        // Redact sensitive headers and cap body before persisting
+        const safe429Headers = { ...errRespHeaders };
+        delete safe429Headers["authorization"];
+        delete safe429Headers["x-api-key"];
+        const capped429Body = String(lastError).length > 4000
+            ? String(lastError).slice(0, 4000) + "...[truncated]"
+            : String(lastError);
+        tracer?.logUpstreamResponseHeaders(safe429Headers);
+        tracer?.logUpstreamResponseBody(capped429Body);
+        logProxyBody({
+            phase: "upstream_response",
+            headers: safe429Headers,
+            body: capped429Body,
+            bodySize: Buffer.byteLength(String(lastError), "utf8"),
+            contentType: errRespHeaders["content-type"] ?? "application/json",
+            account: account.label,
+            accountType: account.type,
+            attempt: attemptNumber,
+            responseStatus: 429,
+            durationMs: Date.now() - fetchStartMs,
+        });
+        logger.always(`[proxy] ← 429 account=${account.label} retry-after=${retryAfterMs}ms (upstream) ratelimit-status=${errRespHeaders["anthropic-ratelimit-unified-status"] ?? "unknown"}`);
         logAttempt(429, "rate_limit_error", String(lastError));
         tracer?.setError("rate_limit_error", String(lastError).slice(0, 500));
         tracer?.recordRetry(account.label, "rate_limit");
@@ -2866,9 +2952,13 @@ async function handleAnthropicRoutedClaudeRequest(args) {
         attemptNumber: 0,
     };
     const acctSelectionSpan = tracer?.startAccountSelection();
-    // No partition / cooldown gating — every account is always eligible.
-    // Retries are handled inline per-account using upstream retry-after.
-    accountLoop: for (const account of orderedAccounts) {
+    // Try to return to the home primary account if its cooling has expired.
+    maybeResetPrimaryToHome(enabledAccounts);
+    // Skip accounts that are still cooling from a recent 429-exhaustion,
+    // but keep them as last-resort if ALL accounts are cooling.
+    const nonCoolingAccounts = orderedAccounts.filter((a) => !isAccountCooling(a.key));
+    const effectiveAccounts = nonCoolingAccounts.length > 0 ? nonCoolingAccounts : orderedAccounts;
+    accountLoop: for (const account of effectiveAccounts) {
         const accountState = getOrCreateRuntimeState(account.key);
         let transientSameAccountRetries = 0;
         let rateLimitSameAccountRetries = 0;
@@ -2926,6 +3016,9 @@ async function handleAnthropicRoutedClaudeRequest(args) {
                 orderedAccounts,
                 tracer,
                 logAttempt,
+                logProxyBody,
+                fetchStartMs: preparedAttempt.fetchStartMs,
+                attemptNumber: loopState.attemptNumber,
                 currentLastError: loopState.lastError,
                 currentSawRateLimit: loopState.sawRateLimit,
                 currentSawNetworkError: loopState.sawNetworkError,
@@ -2948,8 +3041,11 @@ async function handleAnthropicRoutedClaudeRequest(args) {
                 // Rate-limit retries exhausted for this account — rotate
                 if (fetchResult.retrySameAccount &&
                     fetchResult.retryAfterMs !== undefined) {
+                    // Mark account as cooling so subsequent requests don't hammer it
+                    const coolingMs = Math.min(fetchResult.retryAfterMs || DEFAULT_COOLING_PERIOD_MS, DEFAULT_COOLING_PERIOD_MS);
+                    accountState.coolingUntil = Date.now() + coolingMs;
                     advancePrimaryIfCurrent(account.key, enabledAccounts.length, orderedAccounts[0]?.key);
-                    logger.always(`[proxy] exhausted ${MAX_RATE_LIMIT_SAME_ACCOUNT_RETRIES} rate-limit retries for account=${account.label}; rotating`);
+                    logger.always(`[proxy] exhausted ${MAX_RATE_LIMIT_SAME_ACCOUNT_RETRIES} rate-limit retries for account=${account.label}; cooling for ${coolingMs}ms, rotating`);
                     continue accountLoop;
                 }
                 // Transient error retry (network errors, 529 overloaded)
@@ -3052,6 +3148,10 @@ async function handleAnthropicRoutedClaudeRequest(args) {
                 }
                 break accountLoop;
             }
+            // Clear cooling on success — account is healthy again
+            if (accountState.coolingUntil) {
+                accountState.coolingUntil = undefined;
+            }
             const successResult = await handleAnthropicSuccessfulResponse({
                 ctx,
                 body,
@@ -3232,7 +3332,11 @@ export function createClaudeProxyRoutes(modelRouter, basePath = "", accountStrat
             {
                 method: "GET",
                 path: `${basePath}/v1/models`,
-                handler: async (_ctx) => {
+                handler: async (_ctx) => withSpan({
+                    name: "neurolink.http.claudeProxy.listModels",
+                    tracer: tracers.http,
+                    attributes: { "http.route": `${basePath}/v1/models` },
+                }, async () => {
                     const models = [
                         "claude-sonnet-4-20250514",
                         "claude-sonnet-4-5-20250929",
@@ -3248,7 +3352,7 @@ export function createClaudeProxyRoutes(modelRouter, basePath = "", accountStrat
                             owned_by: "anthropic",
                         })),
                     };
-                },
+                }),
                 description: "List available Claude models",
                 tags: ["claude-proxy", "models"],
             },
@@ -3258,9 +3362,16 @@ export function createClaudeProxyRoutes(modelRouter, basePath = "", accountStrat
             {
                 method: "POST",
                 path: `${basePath}/v1/messages/count_tokens`,
-                handler: async (ctx) => {
+                handler: async (ctx) => withSpan({
+                    name: "neurolink.http.claudeProxy.countTokens",
+                    tracer: tracers.http,
+                    attributes: {
+                        "http.route": `${basePath}/v1/messages/count_tokens`,
+                    },
+                }, async (span) => {
                     const body = ctx.body;
-                    if (!body?.model || !body?.messages) {
+                    if (typeof body?.model !== "string" ||
+                        !Array.isArray(body?.messages)) {
                         return buildClaudeError(400, "Missing required fields: model, messages");
                     }
                     // Simple estimation using character-to-token heuristic
@@ -3269,8 +3380,11 @@ export function createClaudeProxyRoutes(modelRouter, basePath = "", accountStrat
                         ? m.content
                         : JSON.stringify(m.content))
                         .join(" ");
-                    return { input_tokens: Math.ceil(text.length / 4) };
-                },
+                    const inputTokens = Math.ceil(text.length / 4);
+                    span.setAttribute("ai.model", body.model);
+                    span.setAttribute("gen_ai.usage.input_tokens", inputTokens);
+                    return { input_tokens: inputTokens };
+                }),
                 description: "Count tokens for a messages request",
                 tags: ["claude-proxy", "tokens"],
             },

package/dist/lib/server/routes/healthRoutes.js

@@ -2,6 +2,22 @@
  * Health Routes
  * Endpoints for health checks and system status
  */
+import { withSpan } from "../../telemetry/withSpan.js";
+import { tracers } from "../../telemetry/tracers.js";
+/**
+ * Wrap a health-route handler with an OTel span that records the route,
+ * request id, and overall health status.
+ */
+function tracedHealthHandler(name, route, fn) {
+    return (ctx) => withSpan({
+        name,
+        tracer: tracers.http,
+        attributes: {
+            "http.route": route,
+            "http.request.id": ctx.requestId ?? "",
+        },
+    }, () => fn(ctx));
+}
 /**
  * Create health check routes
  */
@@ -12,34 +28,41 @@ export function createHealthRoutes(basePath = "/api") {
             {
                 method: "GET",
                 path: `${basePath}/health`,
-                handler: async () => {
+                handler: tracedHealthHandler("neurolink.http.health.check", `${basePath}/health`, async () => {
                     return {
                         status: "ok",
                         timestamp: new Date().toISOString(),
                         uptime: process.uptime() * 1000,
                         version: process.env.npm_package_version || "unknown",
                     };
-                },
+                }),
                 description: "Basic health check",
                 tags: ["health"],
             },
             {
                 method: "GET",
                 path: `${basePath}/health/live`,
-                handler: async () => {
+                handler: tracedHealthHandler("neurolink.http.health.live", `${basePath}/health/live`, async () => {
                     // Liveness probe - just checks if the server is running
                     return {
                         status: "alive",
                         timestamp: new Date().toISOString(),
                     };
-                },
+                }),
                 description: "Kubernetes liveness probe",
                 tags: ["health"],
             },
             {
                 method: "GET",
                 path: `${basePath}/health/ready`,
-                handler: async (ctx) => {
+                handler: (ctx) => withSpan({
+                    name: "neurolink.http.health.ready",
+                    tracer: tracers.http,
+                    attributes: {
+                        "http.route": `${basePath}/health/ready`,
+                        "http.request.id": ctx.requestId ?? "",
+                    },
+                }, async (span) => {
                     // Readiness probe - checks if all dependencies are ready
                     const tools = await ctx.toolRegistry.listTools();
                     const hasTools = tools.length > 0;
@@ -56,6 +79,9 @@ export function createHealthRoutes(basePath = "/api") {
                         }
                     }
                     const isReady = hasTools || !hasExternalManager || externalServersReady;
+                    span.setAttribute("health.ready", isReady);
+                    span.setAttribute("health.tools_count", tools.length);
+                    span.setAttribute("health.external_servers_ready", externalServersReady);
                     return {
                         ready: isReady,
                         timestamp: new Date().toISOString(),
@@ -65,16 +91,24 @@ export function createHealthRoutes(basePath = "/api") {
                             externalServers: externalServersReady,
                         },
                     };
-                },
+                }),
                 description: "Kubernetes readiness probe",
                 tags: ["health"],
             },
             {
                 method: "GET",
                 path: `${basePath}/health/startup`,
-                handler: async (ctx) => {
+                handler: (ctx) => withSpan({
+                    name: "neurolink.http.health.startup",
+                    tracer: tracers.http,
+                    attributes: {
+                        "http.route": `${basePath}/health/startup`,
+                        "http.request.id": ctx.requestId ?? "",
+                    },
+                }, async (span) => {
                     // Startup probe - checks if the application has started successfully
                     const tools = await ctx.toolRegistry.listTools();
+                    span.setAttribute("health.tools_count", tools.length);
                     return {
                         started: true,
                         timestamp: new Date().toISOString(),
@@ -84,14 +118,21 @@ export function createHealthRoutes(basePath = "/api") {
                             externalServerManager: !!ctx.externalServerManager,
                         },
                     };
-                },
+                }),
                 description: "Kubernetes startup probe",
                 tags: ["health"],
             },
             {
                 method: "GET",
                 path: `${basePath}/health/detailed`,
-                handler: async (ctx) => {
+                handler: (ctx) => withSpan({
+                    name: "neurolink.http.health.detailed",
+                    tracer: tracers.http,
+                    attributes: {
+                        "http.route": `${basePath}/health/detailed`,
+                        "http.request.id": ctx.requestId ?? "",
+                    },
+                }, async (span) => {
                     const tools = await ctx.toolRegistry.listTools();
                     // Group tools by source
                     const toolsBySource = {};
@@ -162,23 +203,28 @@ export function createHealthRoutes(basePath = "/api") {
                             healthyCount: pool.getHealthyCount(),
                             strategy: pool.getStrategy(),
                         };
+                        span.setAttribute("health.proxy.accounts", allAccounts.length);
+                        span.setAttribute("health.proxy.healthy", pool.getHealthyCount());
                     }
+                    span.setAttribute("health.tools_count", tools.length);
+                    span.setAttribute("health.external_servers_count", externalServers.length);
+                    span.setAttribute("health.memory.heap_mb", Math.round(process.memoryUsage().heapUsed / 1024 / 1024));
                     return healthResponse;
-                },
+                }),
                 description: "Detailed health information",
                 tags: ["health"],
             },
             {
                 method: "GET",
                 path: `${basePath}/version`,
-                handler: async () => {
+                handler: tracedHealthHandler("neurolink.http.version", `${basePath}/version`, async () => {
                     return {
                         name: "@juspay/neurolink",
                         version: process.env.npm_package_version || "unknown",
                         node: process.version,
                         timestamp: new Date().toISOString(),
                     };
-                },
+                }),
                 description: "Get version information",
                 tags: ["health", "version"],
             },

package/dist/lib/server/routes/index.d.ts

@@ -2,7 +2,7 @@
  * Route Builders
  * Pre-built route definitions for common NeuroLink endpoints
  */
-import type { RouteDefinition, RouteGroup } from "../../types/index.js";
+import type { CreateRoutesOptions, RouteDefinition, RouteGroup } from "../../types/index.js";
 export { createAgentRoutes } from "./agentRoutes.js";
 export { createClaudeProxyRoutes } from "./claudeProxyRoutes.js";
 export { createHealthRoutes } from "./healthRoutes.js";
@@ -10,31 +10,6 @@ export { createMCPRoutes } from "./mcpRoutes.js";
 export { createMemoryRoutes } from "./memoryRoutes.js";
 export { createOpenApiRoutes } from "./openApiRoutes.js";
 export { createToolRoutes } from "./toolRoutes.js";
-/**
- * Options for creating routes
- */
-type CreateRoutesOptions = {
-    /** Enable OpenAPI/Swagger documentation endpoints (default: false) */
-    enableSwagger?: boolean;
-    /**
-     * Callback to get registered routes for OpenAPI spec generation.
-     * This callback is invoked at request time when the OpenAPI spec is accessed,
-     * allowing it to reflect all routes registered with the adapter.
-     *
-     * When using `registerAllRoutes`, this is automatically bound to `adapter.listRoutes()`
-     * if the adapter supports it and no custom callback is provided.
-     *
-     * If not provided (and adapter doesn't have listRoutes), the spec will use
-     * default endpoint definitions.
-     */
-    getRoutes?: () => RouteDefinition[];
-    /**
-     * Enable or disable the Claude-compatible proxy routes.
-     * When true, registers /v1/messages, /v1/models, and /v1/messages/count_tokens
-     * endpoints that accept Anthropic API format requests.
-     */
-    claudeProxy?: boolean;
-};
 /**
  * Create all standard routes
  * Convenience method that combines all route groups

package/dist/lib/server/routes/mcpRoutes.js

@@ -2,8 +2,41 @@
  * MCP Routes
  * Endpoints for MCP server management
  */
+import { SpanStatusCode } from "@opentelemetry/api";
 import { z } from "zod";
+import { withSpan } from "../../telemetry/withSpan.js";
+import { tracers } from "../../telemetry/tracers.js";
 import { createErrorResponse, ServerNameParamSchema, ToolArgumentsSchema, validateParams, validateRequest, } from "../utils/validation.js";
+/**
+ * Wrap a route handler with an OTel span for HTTP observability.
+ */
+function tracedMcpHandler(name, route, fn) {
+    return (ctx) => withSpan({
+        name,
+        tracer: tracers.http,
+        attributes: {
+            "http.route": route,
+            "http.request.id": ctx.requestId,
+        },
+    }, async (otelSpan) => {
+        const result = await fn(ctx);
+        // Detect returned error responses (not thrown) and mark span as failed.
+        // Only flag when the error value is truthy to avoid false positives
+        // from handlers that always include an `error` key (e.g. handleGetServer).
+        if (result && typeof result === "object") {
+            const errVal = result.error;
+            if (errVal !== undefined && errVal !== null) {
+                const errMsg = typeof errVal === "string"
+                    ? errVal
+                    : typeof errVal?.message === "string"
+                        ? errVal.message
+                        : "MCP handler error";
+                otelSpan.setStatus({ code: SpanStatusCode.ERROR, message: errMsg });
+            }
+        }
+        return result;
+    });
+}
 /**
  * MCP tool execution params schema
  */
@@ -291,49 +324,49 @@ export function createMCPRoutes(basePath = "/api") {
             {
                 method: "GET",
                 path: `${basePath}/mcp/servers`,
-                handler: handleListServers,
+                handler: tracedMcpHandler("neurolink.http.mcp.listServers", `${basePath}/mcp/servers`, handleListServers),
                 description: "List all MCP servers",
                 tags: ["mcp"],
             },
             {
                 method: "GET",
                 path: `${basePath}/mcp/servers/:name`,
-                handler: handleGetServer,
+                handler: tracedMcpHandler("neurolink.http.mcp.getServer", `${basePath}/mcp/servers/:name`, handleGetServer),
                 description: "Get MCP server status",
                 tags: ["mcp"],
             },
             {
                 method: "POST",
                 path: `${basePath}/mcp/servers/:name/reconnect`,
-                handler: handleReconnectServer,
+                handler: tracedMcpHandler("neurolink.http.mcp.reconnectServer", `${basePath}/mcp/servers/:name/reconnect`, handleReconnectServer),
                 description: "Reconnect to an MCP server",
                 tags: ["mcp"],
             },
             {
                 method: "DELETE",
                 path: `${basePath}/mcp/servers/:name`,
-                handler: handleRemoveServer,
+                handler: tracedMcpHandler("neurolink.http.mcp.removeServer", `${basePath}/mcp/servers/:name`, handleRemoveServer),
                 description: "Remove an MCP server",
                 tags: ["mcp"],
             },
             {
                 method: "GET",
                 path: `${basePath}/mcp/servers/:name/tools`,
-                handler: handleListServerTools,
+                handler: tracedMcpHandler("neurolink.http.mcp.listServerTools", `${basePath}/mcp/servers/:name/tools`, handleListServerTools),
                 description: "List tools from a specific MCP server",
                 tags: ["mcp", "tools"],
             },
             {
                 method: "POST",
                 path: `${basePath}/mcp/servers/:name/tools/:toolName/execute`,
-                handler: handleExecuteTool,
+                handler: tracedMcpHandler("neurolink.http.mcp.executeTool", `${basePath}/mcp/servers/:name/tools/:toolName/execute`, handleExecuteTool),
                 description: "Execute a tool from a specific MCP server",
                 tags: ["mcp", "tools"],
             },
             {
                 method: "GET",
                 path: `${basePath}/mcp/health`,
-                handler: handleMCPHealth,
+                handler: tracedMcpHandler("neurolink.http.mcp.health", `${basePath}/mcp/health`, handleMCPHealth),
                 description: "Health check for all MCP servers",
                 tags: ["mcp", "health"],
             },

package/dist/lib/server/routes/memoryRoutes.js

@@ -2,7 +2,22 @@
  * Memory Routes
  * Endpoints for conversation memory management
  */
+import { withSpan } from "../../telemetry/withSpan.js";
+import { tracers } from "../../telemetry/tracers.js";
 import { createErrorResponse, IdParamSchema, SessionIdParamSchema, validateParams, } from "../utils/validation.js";
+/**
+ * Wrap a route handler with an OTel span for HTTP observability.
+ */
+function tracedMemoryHandler(name, route, fn) {
+    return (ctx) => withSpan({
+        name,
+        tracer: tracers.http,
+        attributes: {
+            "http.route": route,
+            "http.request.id": ctx.requestId,
+        },
+    }, () => fn(ctx));
+}
 /**
  * Handler: Get messages for a session
  */
@@ -297,7 +312,7 @@ export function createMemoryRoutes(basePath = "/api") {
             {
                 method: "GET",
                 path: `${basePath}/memory/sessions/:id/messages`,
-                handler: handleGetSessionMessages,
+                handler: tracedMemoryHandler("neurolink.http.memory.getSessionMessages", `${basePath}/memory/sessions/:id/messages`, handleGetSessionMessages),
                 description: "Get messages for a session",
                 tags: ["memory"],
             },
@@ -305,7 +320,7 @@ export function createMemoryRoutes(basePath = "/api") {
             {
                 method: "GET",
                 path: `${basePath}/memory/sessions/:id`,
-                handler: handleGetSession,
+                handler: tracedMemoryHandler("neurolink.http.memory.getSession", `${basePath}/memory/sessions/:id`, handleGetSession),
                 description: "Get session by ID",
                 tags: ["memory"],
             },
@@ -313,35 +328,35 @@ export function createMemoryRoutes(basePath = "/api") {
             {
                 method: "GET",
                 path: `${basePath}/memory/sessions`,
-                handler: handleListSessions,
+                handler: tracedMemoryHandler("neurolink.http.memory.listSessions", `${basePath}/memory/sessions`, handleListSessions),
                 description: "List all conversation sessions",
                 tags: ["memory"],
             },
             {
                 method: "GET",
                 path: `${basePath}/memory/stats`,
-                handler: handleGetStats,
+                handler: tracedMemoryHandler("neurolink.http.memory.stats", `${basePath}/memory/stats`, handleGetStats),
                 description: "Get memory statistics",
                 tags: ["memory"],
             },
             {
                 method: "DELETE",
                 path: `${basePath}/memory/sessions/:sessionId`,
-                handler: handleClearSession,
+                handler: tracedMemoryHandler("neurolink.http.memory.clearSession", `${basePath}/memory/sessions/:sessionId`, handleClearSession),
                 description: "Clear a conversation session",
                 tags: ["memory"],
             },
             {
                 method: "DELETE",
                 path: `${basePath}/memory/sessions`,
-                handler: handleClearAllSessions,
+                handler: tracedMemoryHandler("neurolink.http.memory.clearAllSessions", `${basePath}/memory/sessions`, handleClearAllSessions),
                 description: "Clear all conversation sessions",
                 tags: ["memory"],
             },
             {
                 method: "GET",
                 path: `${basePath}/memory/health`,
-                handler: handleMemoryHealth,
+                handler: tracedMemoryHandler("neurolink.http.memory.health", `${basePath}/memory/health`, handleMemoryHealth),
                 description: "Check memory system health",
                 tags: ["memory", "health"],
             },