@mcpmesh/sdk 2.3.0 → 2.5.0

package/dist/proxy.js

@@ -5,11 +5,13 @@
  */
 import { AsyncLocalStorage } from "node:async_hooks";
 import { zodToJsonSchema } from "zod-to-json-schema";
-import { generateSpanId, publishTraceSpan, createTraceHeaders, matchesPropagateHeader, injectTraceContext, } from "./tracing.js";
+import { generateSpanId, publishTraceSpan, createTraceHeaders, matchesPropagateHeader, injectTraceAndHeaders, } from "./tracing.js";
 import { isTimeoutError } from "./timeout-utils.js";
 import { getDispatcher } from "./http-pool.js";
 import { currentJob } from "./job-context.js";
 import { awaitJobCancel } from "@mcpmesh/core";
+import { createDebug } from "./debug.js";
+const debugProxy = createDebug("proxy");
 /** Default CallOptions for internal callers that don't go through createProxy. */
 export const DEFAULT_CALL_OPTIONS = {
     timeout: 30_000,
@@ -162,19 +164,29 @@ export function createProxy(endpoint, capability, functionName, kwargs) {
     return proxyFn;
 }
 /**
- * Call an MCP tool via HTTP POST.
+ * Build the shared MCP `tools/call` request setup used by both the buffered
+ * (`callMcpTool`) and streaming (`streamMcpTool`) paths.
  *
- * Uses the MCP HTTP Streamable protocol:
- * POST /mcp with JSON-RPC 2.0 payload.
- * Includes distributed tracing: propagates trace context and publishes spans.
+ * Handles endpoint normalization, trace-context capture, merged-header build,
+ * fallback trace injection, payload assembly, effective-timeout resolution and
+ * header assembly. The streaming caller passes `opts.progressToken` so the
+ * payload gets `params._meta.progressToken` (the buffered caller omits it).
+ *
+ * Header insertion order is byte-identical to the pre-extraction code:
+ * customHeaders → Content-Type/Accept → trace headers → mergedHeaders →
+ * conditional X-Mesh-Timeout.
+ *
+ * `defaultTimeout` is the per-path fallback applied when the resolved timeout is
+ * non-positive (DEFAULT_CALL_OPTIONS.timeout for buffered,
+ * DEFAULT_CALL_OPTIONS.streamTimeout for stream).
  */
-export async function callMcpTool(endpoint, toolName, args, options, capability, extraHeaders) {
+function buildMcpRequest(endpoint, toolName, args, options, extraHeaders, defaultTimeout, opts) {
     // Ensure endpoint ends with /mcp
     const mcpEndpoint = endpoint.endsWith("/mcp")
         ? endpoint
         : `${endpoint.replace(/\/$/, "")}/mcp`;
-    // Tracing: create span for this outgoing proxy call
-    // Use AsyncLocalStorage to get trace context for the current async execution
+    // Tracing: create span for this outgoing proxy call.
+    // Use AsyncLocalStorage to get trace context for the current async execution.
     const traceCtx = getCurrentTraceContext();
     const spanId = traceCtx ? generateSpanId() : null;
     const startTime = Date.now() / 1000;
@@ -188,32 +200,8 @@ export async function callMcpTool(endpoint, toolName, args, options, capability,
             }
         }
     }
-    // Build arguments with trace context injection via Rust core
-    let argsWithTrace;
-    if (traceCtx && spanId) {
-        try {
-            const argsJson = JSON.stringify(args ?? {});
-            const headersJson = Object.keys(mergedHeaders).length > 0 ? JSON.stringify(mergedHeaders) : undefined;
-            const injectedJson = injectTraceContext(argsJson, traceCtx.traceId, spanId, headersJson);
-            argsWithTrace = JSON.parse(injectedJson);
-        }
-        catch {
-            // Fallback to manual injection
-            argsWithTrace = { ...(args ?? {}) };
-            argsWithTrace._trace_id = traceCtx.traceId;
-            argsWithTrace._parent_span = spanId;
-            if (Object.keys(mergedHeaders).length > 0) {
-                argsWithTrace._mesh_headers = mergedHeaders;
-            }
-        }
-    }
-    else {
-        argsWithTrace = { ...(args ?? {}) };
-        // Still inject propagated headers even without trace context
-        if (Object.keys(mergedHeaders).length > 0) {
-            argsWithTrace._mesh_headers = mergedHeaders;
-        }
-    }
+    // Build arguments with trace context injection (Rust core, manual fallback)
+    const argsWithTrace = injectTraceAndHeaders(args ?? {}, traceCtx, spanId, mergedHeaders);
     const payload = {
         jsonrpc: "2.0",
         id: generateRequestId(),
@@ -221,6 +209,7 @@ export async function callMcpTool(endpoint, toolName, args, options, capability,
         params: {
             name: toolName,
             arguments: argsWithTrace,
+            ...(opts?.progressToken ? { _meta: { progressToken: opts.progressToken } } : {}),
         },
     };
     // Use X-Mesh-Timeout from propagated headers to override client timeout (#769).
@@ -234,57 +223,94 @@ export async function callMcpTool(endpoint, toolName, args, options, capability,
             effectiveTimeout = meshTimeoutMs;
         }
     }
-    let lastError = null;
+    // A partial caller options object (or a caller passing timeout<=0) could leave
+    // this undefined or non-positive — that would cause setTimeout to fire on the
+    // next tick and abort the call immediately. Fall back to the path default.
+    if (typeof effectiveTimeout !== "number" || effectiveTimeout <= 0) {
+        effectiveTimeout = defaultTimeout;
+    }
     const bodyStr = JSON.stringify(payload);
     const requestBytes = Buffer.byteLength(bodyStr, "utf8");
+    // Build headers: custom headers first, then protocol-required headers override.
+    // FastMCP stateless HTTP requires BOTH content types in Accept (it returns SSE
+    // for streaming responses; missing application/json yields 406 Not Acceptable).
+    const headers = {
+        ...(options.customHeaders ?? {}),
+        "Content-Type": "application/json",
+        Accept: "application/json, text/event-stream",
+    };
+    // Propagate trace context (higher priority)
+    if (traceCtx && spanId) {
+        Object.assign(headers, createTraceHeaders(traceCtx.traceId, spanId));
+    }
+    // Inject merged headers (highest priority)
+    for (const [key, value] of Object.entries(mergedHeaders)) {
+        headers[key] = value;
+    }
+    // Set X-Mesh-Timeout for registry proxy (#769). If already propagated, keep it.
+    if (!headers["X-Mesh-Timeout"] && !headers["x-mesh-timeout"]) {
+        const callTimeout = process.env.MCP_MESH_CALL_TIMEOUT || String(Math.floor(options.timeout / 1000));
+        headers["X-Mesh-Timeout"] = callTimeout;
+    }
+    return { mcpEndpoint, bodyStr, requestId: payload.id, requestBytes, headers, effectiveTimeout, traceCtx, spanId, startTime };
+}
+/**
+ * Wire per-job cancel propagation (#886) onto an outbound AbortController.
+ *
+ * When the handler executing this outbound call is running under a MeshJob
+ * context AND the registry forwards a cancel via POST /jobs/{id}/cancel, fire
+ * the outbound AbortController so in-flight fetch is cancelled instead of
+ * stalling on socket reads. Fire-and-forget — the listener races against fetch
+ * completion / timeout; whichever wins, the others become no-ops
+ * (`controller.abort()` is idempotent and the dangling Promise resolves
+ * immediately once the registry entry is gone).
+ */
+function wireJobCancel(controller) {
+    const jobSnap = currentJob();
+    if (jobSnap?.jobId) {
+        awaitJobCancel(jobSnap.jobId)
+            .then(() => {
+            if (!controller.signal.aborted) {
+                controller.abort();
+            }
+        })
+            .catch(() => {
+            // Defensive: napi rejection here would be unusual (the Rust
+            // implementation only awaits a CancellationToken), but a
+            // runtime shutdown mid-await could surface one. Swallow —
+            // the worst case is that the outbound fetch isn't proactively
+            // aborted, and the existing timeout / fetch-completion path
+            // still applies.
+        });
+    }
+}
+/**
+ * Call an MCP tool via HTTP POST.
+ *
+ * Uses the MCP HTTP Streamable protocol:
+ * POST /mcp with JSON-RPC 2.0 payload.
+ * Includes distributed tracing: propagates trace context and publishes spans.
+ */
+export async function callMcpTool(endpoint, toolName, args, options, capability, extraHeaders) {
+    const { mcpEndpoint, bodyStr, requestBytes, headers, effectiveTimeout, traceCtx, spanId, startTime, } = buildMcpRequest(endpoint, toolName, args, options, extraHeaders, DEFAULT_CALL_OPTIONS.timeout);
+    let lastError = null;
+    // Response size of the most recent attempt that got far enough to read a
+    // body — carried onto the post-loop aggregate error span so a failed call's
+    // span still reports payload size (per-attempt spans used to carry it).
+    let lastResponseBytes;
     for (let attempt = 0; attempt < options.maxAttempts; attempt++) {
+        // Abort timer covers the WHOLE attempt — connect, headers, AND body
+        // read — and is cleared in `finally` (issue #1163 LOW-5). Previously
+        // it was cleared right after `fetch` resolved, so (a) a fetch
+        // rejection leaked one armed timer per retry for the rest of the
+        // timeout window, and (b) the body read (response.text() / SSE) was
+        // unbounded by the call timeout. Keeping the controller armed until
+        // the body is consumed makes an over-deadline body read abort and
+        // surface through the existing isTimeoutError path below.
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), effectiveTimeout);
         try {
-            const controller = new AbortController();
-            const timeoutId = setTimeout(() => controller.abort(), effectiveTimeout);
-            // Wire per-job cancel propagation (#886). When the handler executing
-            // this outbound call is running under a MeshJob context AND the
-            // registry forwards a cancel via POST /jobs/{id}/cancel, fire the
-            // outbound AbortController so in-flight fetch is cancelled instead
-            // of stalling on socket reads. Fire-and-forget — the listener races
-            // against fetch completion / timeout; whichever wins, the others
-            // become no-ops (`controller.abort()` is idempotent and the dangling
-            // Promise resolves immediately once the registry entry is gone).
-            const jobSnap = currentJob();
-            if (jobSnap?.jobId) {
-                awaitJobCancel(jobSnap.jobId)
-                    .then(() => {
-                    if (!controller.signal.aborted) {
-                        controller.abort();
-                    }
-                })
-                    .catch(() => {
-                    // Defensive: napi rejection here would be unusual (the Rust
-                    // implementation only awaits a CancellationToken), but a
-                    // runtime shutdown mid-await could surface one. Swallow —
-                    // the worst case is that the outbound fetch isn't proactively
-                    // aborted, and the existing timeout / fetch-completion path
-                    // still applies.
-                });
-            }
-            // Build headers: custom headers first, then protocol-required headers override
-            const headers = {
-                ...(options.customHeaders ?? {}),
-                "Content-Type": "application/json",
-                Accept: "application/json, text/event-stream",
-            };
-            // Propagate trace context (higher priority)
-            if (traceCtx && spanId) {
-                Object.assign(headers, createTraceHeaders(traceCtx.traceId, spanId));
-            }
-            // Inject merged headers (highest priority)
-            for (const [key, value] of Object.entries(mergedHeaders)) {
-                headers[key] = value;
-            }
-            // Set X-Mesh-Timeout for registry proxy (#769). If already propagated, keep it.
-            if (!headers["X-Mesh-Timeout"] && !headers["x-mesh-timeout"]) {
-                const callTimeout = process.env.MCP_MESH_CALL_TIMEOUT || String(Math.floor(options.timeout / 1000));
-                headers["X-Mesh-Timeout"] = callTimeout;
-            }
+            wireJobCancel(controller);
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
             const fetchOptions = {
                 method: "POST",
@@ -298,7 +324,6 @@ export async function callMcpTool(endpoint, toolName, args, options, capability,
                 fetchOptions.dispatcher = dispatcher;
             }
             const response = await fetch(mcpEndpoint, fetchOptions);
-            clearTimeout(timeoutId);
             if (!response.ok) {
                 throw new Error(`MCP call failed: ${response.status} ${response.statusText}`);
             }
@@ -308,47 +333,81 @@ export async function callMcpTool(endpoint, toolName, args, options, capability,
                 throw new Error(`Response size ${contentLength} bytes exceeds limit of ${options.maxResponseSize} bytes`);
             }
             const contentType = response.headers.get("content-type") ?? "";
-            // Handle SSE streaming response
+            // Handle SSE streaming response.
+            //
+            // Span accounting (#1202): spans are per-call, not per-attempt. Error
+            // paths in this loop body throw WITHOUT publishing — the outer catch
+            // owns the non-retryable single-span paths (abort/timeout,
+            // ProxyTimeoutError) and the post-loop aggregate owns retried-then-
+            // exhausted errors. Publishing here too would emit multiple spans
+            // sharing one spanId.
             if (contentType.includes("text/event-stream")) {
-                const sseResult = await parseSSEResponse(response);
                 // Estimate response size from content-length header (exact size not available for SSE)
                 const sseResponseBytes = contentLength > 0 ? contentLength : undefined;
+                lastResponseBytes = sseResponseBytes;
+                const sseResult = await readSSEResponseToContent(response);
                 // Publish success span
-                publishProxySpan(traceCtx, spanId, startTime, toolName, capability, endpoint, true, null, typeof sseResult, requestBytes, sseResponseBytes);
+                publishProxySpan(traceCtx, spanId, startTime, toolName, capability, endpoint, true, null, typeof sseResult, requestBytes, sseResponseBytes, attempt + 1);
                 return sseResult;
             }
             // Handle JSON response — read as text to measure byte size
             const responseText = await response.text();
             const responseBytes = Buffer.byteLength(responseText, "utf8");
+            lastResponseBytes = responseBytes;
             const result = JSON.parse(responseText);
             if (result.error) {
                 const errorMsg = result.error.message ?? JSON.stringify(result.error);
-                // Publish error span
-                publishProxySpan(traceCtx, spanId, startTime, toolName, capability, endpoint, false, errorMsg, "error", requestBytes, responseBytes);
                 throw new Error(`MCP error: ${errorMsg}`);
             }
+            // Surface tool-level errors. An MCP CallToolResult with isError === true
+            // carries the failure message in its content; the JSON-RPC envelope above
+            // is success in that case. Throw so callers (LLM provider, tool proxy)
+            // re-wrap it instead of returning the error text as a successful result.
+            const toolErrMsg = toolErrorMessage(result.result);
+            if (toolErrMsg !== null) {
+                throw new Error(`MCP tool error: ${toolErrMsg}`);
+            }
             // Extract content from result
             const content = extractContent(result.result);
             // Publish success span
-            publishProxySpan(traceCtx, spanId, startTime, toolName, capability, endpoint, true, null, typeof content, requestBytes, responseBytes);
+            publishProxySpan(traceCtx, spanId, startTime, toolName, capability, endpoint, true, null, typeof content, requestBytes, responseBytes, attempt + 1);
             return content;
         }
         catch (err) {
             lastError = err instanceof Error ? err : new Error(String(err));
             // Don't retry on abort (timeout)
             if (isTimeoutError(lastError)) {
-                publishProxySpan(traceCtx, spanId, startTime, toolName, capability, endpoint, false, "timeout", "error", requestBytes);
+                publishProxySpan(traceCtx, spanId, startTime, toolName, capability, endpoint, false, "timeout", "error", requestBytes, undefined, attempt + 1);
                 throw new Error(`MCP call timed out after ${effectiveTimeout}ms`);
             }
-            // Retry on network errors
+            // Don't retry on the proxy's in-band timeout marker either (#1201):
+            // the X-Mesh-Timeout budget is definitively spent, so a retry would
+            // burn another full budget against an exchange the proxy already cut.
+            // Same accounting as the local abort above: one error span, immediate
+            // throw — the message names the proxy budget, matching meshctl's
+            // report of the same cut.
+            if (lastError instanceof ProxyTimeoutError) {
+                publishProxySpan(traceCtx, spanId, startTime, toolName, capability, endpoint, false, lastError.message, "error", requestBytes, undefined, attempt + 1);
+                throw lastError;
+            }
+            // Retry everything else (network, HTTP, protocol, and tool-level
+            // errors) until attempts are exhausted; only the abort/timeout case
+            // above is non-retryable. No span here (#1202) — the post-loop
+            // aggregate publishes once for the whole call.
+            debugProxy(`attempt ${attempt + 1}/${options.maxAttempts} failed for ${toolName} at ${endpoint}: ${lastError.message}`);
             if (attempt < options.maxAttempts - 1) {
                 await sleep(options.retryDelay * Math.pow(options.retryBackoff, attempt));
                 continue;
             }
         }
+        finally {
+            clearTimeout(timeoutId);
+        }
     }
-    // All retries failed
-    publishProxySpan(traceCtx, spanId, startTime, toolName, capability, endpoint, false, lastError?.message ?? "unknown", "error", requestBytes);
+    // All retries failed — the single aggregate error span for this call
+    // (#1202): carries the last attempt's error and response size, plus the
+    // attempts count when retries were configured.
+    publishProxySpan(traceCtx, spanId, startTime, toolName, capability, endpoint, false, lastError?.message ?? "unknown", "error", requestBytes, lastResponseBytes, options.maxAttempts);
     throw lastError ?? new Error("MCP call failed");
 }
 /**
@@ -376,120 +435,17 @@ export async function callMcpTool(endpoint, toolName, args, options, capability,
  * ``fetch`` is aborted via ``AbortController`` and the reader is released.
  */
 export async function* streamMcpTool(endpoint, toolName, args, options, capability, extraHeaders) {
-    // Ensure endpoint ends with /mcp
-    const mcpEndpoint = endpoint.endsWith("/mcp")
-        ? endpoint
-        : `${endpoint.replace(/\/$/, "")}/mcp`;
-    // Tracing: create span for this outgoing proxy stream call
-    const traceCtx = getCurrentTraceContext();
-    const spanId = traceCtx ? generateSpanId() : null;
-    const startTime = Date.now() / 1000;
-    // Build merged headers: session propagated + per-call (per-call wins, filtered by allowlist)
-    const propagatedHeaders = getCurrentPropagatedHeaders();
-    const mergedHeaders = { ...propagatedHeaders };
-    if (extraHeaders) {
-        for (const [key, value] of Object.entries(extraHeaders)) {
-            if (matchesPropagateHeader(key)) {
-                mergedHeaders[key.toLowerCase()] = value;
-            }
-        }
-    }
-    // Build arguments with trace context injection via Rust core
-    let argsWithTrace;
-    if (traceCtx && spanId) {
-        try {
-            const argsJson = JSON.stringify(args ?? {});
-            const headersJson = Object.keys(mergedHeaders).length > 0 ? JSON.stringify(mergedHeaders) : undefined;
-            const injectedJson = injectTraceContext(argsJson, traceCtx.traceId, spanId, headersJson);
-            argsWithTrace = JSON.parse(injectedJson);
-        }
-        catch {
-            argsWithTrace = { ...(args ?? {}) };
-            argsWithTrace._trace_id = traceCtx.traceId;
-            argsWithTrace._parent_span = spanId;
-            if (Object.keys(mergedHeaders).length > 0) {
-                argsWithTrace._mesh_headers = mergedHeaders;
-            }
-        }
-    }
-    else {
-        argsWithTrace = { ...(args ?? {}) };
-        if (Object.keys(mergedHeaders).length > 0) {
-            argsWithTrace._mesh_headers = mergedHeaders;
-        }
-    }
-    // Generate progress token to correlate notifications with this call
+    // Generate progress token to correlate notifications with this call.
+    // The request id comes back from buildMcpRequest (it built the payload) so the
+    // final-result matching below stays in sync with the wire id.
     const progressToken = generateProgressToken();
-    const requestId = generateRequestId();
-    const payload = {
-        jsonrpc: "2.0",
-        id: requestId,
-        method: "tools/call",
-        params: {
-            name: toolName,
-            arguments: argsWithTrace,
-            _meta: { progressToken },
-        },
-    };
-    // Use X-Mesh-Timeout from propagated headers to override client timeout (#769)
-    let effectiveTimeout = options.timeout;
-    const meshTimeoutStr = mergedHeaders["x-mesh-timeout"];
-    if (meshTimeoutStr) {
-        const meshTimeoutMs = parseInt(meshTimeoutStr, 10) * 1000;
-        if (!isNaN(meshTimeoutMs) && meshTimeoutMs > 0) {
-            effectiveTimeout = meshTimeoutMs;
-        }
-    }
-    // Stream timeout defaults are usually generous (300s) but a partial caller
-    // options object could leave this undefined or non-positive — that would
-    // cause setTimeout to fire on next tick and abort the stream immediately.
-    // Fall back to the buffered call default in that case.
-    if (typeof effectiveTimeout !== "number" || effectiveTimeout <= 0) {
-        effectiveTimeout = DEFAULT_CALL_OPTIONS.streamTimeout;
-    }
-    const bodyStr = JSON.stringify(payload);
-    const requestBytes = Buffer.byteLength(bodyStr, "utf8");
+    const { mcpEndpoint, bodyStr, requestId, requestBytes, headers, effectiveTimeout, traceCtx, spanId, startTime, } = buildMcpRequest(endpoint, toolName, args, options, extraHeaders, DEFAULT_CALL_OPTIONS.streamTimeout, { progressToken });
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), effectiveTimeout);
-    // Wire per-job cancel propagation (#886). See callMcpTool above for
-    // rationale; same pattern applied to the streaming path so a cancel
-    // arriving mid-stream aborts the SSE reader instead of waiting for
-    // the next chunk / streamTimeout (default 300s).
-    const jobSnap = currentJob();
-    if (jobSnap?.jobId) {
-        awaitJobCancel(jobSnap.jobId)
-            .then(() => {
-            if (!controller.signal.aborted) {
-                controller.abort();
-            }
-        })
-            .catch(() => {
-            // Defensive: napi rejection here would be unusual (the Rust
-            // implementation only awaits a CancellationToken), but a
-            // runtime shutdown mid-await could surface one. Swallow — the
-            // worst case is that the outbound fetch isn't proactively
-            // aborted, and the existing timeout / fetch-completion path
-            // still applies.
-        });
-    }
-    // Build headers — FastMCP stateless HTTP requires BOTH content types in
-    // Accept (it returns SSE for streaming responses; missing application/json
-    // here yields 406 Not Acceptable). Matches the buffered callMcpTool path.
-    const headers = {
-        ...(options.customHeaders ?? {}),
-        "Content-Type": "application/json",
-        Accept: "application/json, text/event-stream",
-    };
-    if (traceCtx && spanId) {
-        Object.assign(headers, createTraceHeaders(traceCtx.traceId, spanId));
-    }
-    for (const [key, value] of Object.entries(mergedHeaders)) {
-        headers[key] = value;
-    }
-    if (!headers["X-Mesh-Timeout"] && !headers["x-mesh-timeout"]) {
-        const callTimeout = process.env.MCP_MESH_CALL_TIMEOUT || String(Math.floor(options.timeout / 1000));
-        headers["X-Mesh-Timeout"] = callTimeout;
-    }
+    // Wire per-job cancel propagation (#886) — same pattern as callMcpTool so a
+    // cancel arriving mid-stream aborts the SSE reader instead of waiting for the
+    // next chunk / streamTimeout (default 300s).
+    wireJobCancel(controller);
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const fetchOptions = {
         method: "POST",
@@ -522,70 +478,46 @@ export async function* streamMcpTool(endpoint, toolName, args, options, capabili
             throw new Error(`MCP stream call: expected text/event-stream response, got: ${sseContentType || "<no Content-Type header>"}`);
         }
         reader = response.body.getReader();
-        const decoder = new TextDecoder();
-        let buffer = "";
-        let streamDone = false;
-        while (!streamDone) {
-            const { done, value } = await reader.read();
-            if (done)
-                break;
-            // Normalize CRLF to LF so the same parser handles either line ending
-            buffer += decoder.decode(value, { stream: true }).replace(/\r\n/g, "\n");
-            // SSE events are separated by blank lines (\n\n)
-            let sep;
-            while ((sep = buffer.indexOf("\n\n")) !== -1) {
-                const rawEvent = buffer.slice(0, sep);
-                buffer = buffer.slice(sep + 2);
-                // Collect data: lines from this event (per spec, multi-line data joined by \n)
-                const dataLines = [];
-                for (const line of rawEvent.split("\n")) {
-                    if (line.startsWith("data: ")) {
-                        dataLines.push(line.slice(6));
-                    }
-                    else if (line.startsWith("data:")) {
-                        // Allow "data:" with no space (defensive)
-                        dataLines.push(line.slice(5));
+        for await (const data of iterateSSEEvents(reader)) {
+            // Parse the JSON-RPC message
+            let msg;
+            try {
+                msg = JSON.parse(data);
+            }
+            catch {
+                // Ignore non-JSON data events (defensive)
+                continue;
+            }
+            // Progress notification: yield message if it matches our token
+            if (msg.method === "notifications/progress" && msg.params) {
+                if (msg.params.progressToken === progressToken) {
+                    // FastMCP sends ``message``; some implementations may send ``data``
+                    const chunk = typeof msg.params.message === "string"
+                        ? msg.params.message
+                        : typeof msg.params.data === "string"
+                            ? msg.params.data
+                            : null;
+                    if (chunk !== null) {
+                        yield chunk;
                     }
                 }
-                if (dataLines.length === 0)
-                    continue;
-                const data = dataLines.join("\n");
-                if (!data)
-                    continue;
-                // Parse the JSON-RPC message
-                let msg;
-                try {
-                    msg = JSON.parse(data);
-                }
-                catch {
-                    // Ignore non-JSON data events (defensive)
-                    continue;
-                }
-                // Progress notification: yield message if it matches our token
-                if (msg.method === "notifications/progress" && msg.params) {
-                    if (msg.params.progressToken === progressToken) {
-                        // FastMCP sends ``message``; some implementations may send ``data``
-                        const chunk = typeof msg.params.message === "string"
-                            ? msg.params.message
-                            : typeof msg.params.data === "string"
-                                ? msg.params.data
-                                : null;
-                        if (chunk !== null) {
-                            yield chunk;
-                        }
-                    }
-                    continue;
+                continue;
+            }
+            // Final response for our request: end the stream
+            if (msg.id !== undefined && msg.id === requestId) {
+                if (msg.error) {
+                    const em = msg.error.message ?? JSON.stringify(msg.error);
+                    throw new Error(`MCP error: ${em}`);
                 }
-                // Final response for our request: end the stream
-                if (msg.id !== undefined && msg.id === requestId) {
-                    if (msg.error) {
-                        const em = msg.error.message ?? JSON.stringify(msg.error);
-                        throw new Error(`MCP error: ${em}`);
-                    }
-                    // result arrived — done; do NOT yield the buffered final result
-                    streamDone = true;
-                    break;
+                // Surface tool-level errors on the final result (mirrors callMcpTool):
+                // a producer tool that throws mid-stream ends with isError === true
+                // and must not look like a clean end-of-stream.
+                const streamToolErrMsg = toolErrorMessage(msg.result);
+                if (streamToolErrMsg !== null) {
+                    throw new Error(`MCP tool error: ${streamToolErrMsg}`);
                 }
+                // result arrived — done; do NOT yield the buffered final result
+                break;
             }
         }
     }
@@ -639,8 +571,12 @@ function generateProgressToken() {
 }
 /**
  * Helper to publish a proxy call span (fire and forget).
+ *
+ * `attempts` is the number of call attempts this span aggregates; it is
+ * recorded on the span only when greater than 1 (i.e. retries actually
+ * happened), keeping single-attempt spans unchanged.
  */
-function publishProxySpan(traceCtx, spanId, startTime, _toolName, _capability, endpoint, success, error, resultType, requestBytes, responseBytes) {
+function publishProxySpan(traceCtx, spanId, startTime, _toolName, _capability, endpoint, success, error, resultType, requestBytes, responseBytes, attempts) {
     if (!traceCtx || !spanId)
         return;
     const endTime = Date.now() / 1000;
@@ -664,14 +600,103 @@ function publishProxySpan(traceCtx, spanId, startTime, _toolName, _capability, e
         meshPositions: [],
         requestBytes,
         responseBytes,
+        ...(attempts !== undefined && attempts > 1 ? { callAttempts: attempts } : {}),
     }).catch(() => {
         // Silently ignore publish errors
     });
 }
 /**
- * Parse SSE response from MCP HTTP Streamable transport.
+ * Split an SSE byte stream into raw `data:` payload strings.
+ *
+ * Reads from the given reader, normalizes CRLF→LF, separates events on blank
+ * lines (`\n\n`), and joins each event's `data:` lines per the SSE spec.
+ * Empty/data-less events are skipped. Yields one string per event so callers
+ * can JSON-parse and dispatch without re-implementing the framing.
  */
-async function parseSSEResponse(response) {
+async function* iterateSSEEvents(reader) {
+    const decoder = new TextDecoder();
+    let buffer = "";
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        // Normalize CRLF to LF so the same parser handles either line ending
+        buffer += decoder.decode(value, { stream: true }).replace(/\r\n/g, "\n");
+        // SSE events are separated by blank lines (\n\n)
+        let sep;
+        while ((sep = buffer.indexOf("\n\n")) !== -1) {
+            const rawEvent = buffer.slice(0, sep);
+            buffer = buffer.slice(sep + 2);
+            // Collect data: lines from this event (per spec, multi-line data joined by \n)
+            const dataLines = [];
+            for (const line of rawEvent.split("\n")) {
+                if (line.startsWith("data: ")) {
+                    dataLines.push(line.slice(6));
+                }
+                else if (line.startsWith("data:")) {
+                    // Allow "data:" with no space (defensive)
+                    dataLines.push(line.slice(5));
+                }
+            }
+            if (dataLines.length === 0)
+                continue;
+            const data = dataLines.join("\n");
+            if (!data)
+                continue;
+            yield data;
+        }
+    }
+}
+/**
+ * Extract the failure message from an MCP CallToolResult with
+ * ``isError === true``, or return null when the result is not a tool-level
+ * error. Shared by callMcpTool's JSON and SSE paths (and streamMcpTool's
+ * final-result handling) so every transport surfaces tool errors with the
+ * exact same `MCP tool error: …` shape — they can't drift apart.
+ */
+function toolErrorMessage(innerResult) {
+    if (innerResult && typeof innerResult === "object" && innerResult.isError === true) {
+        const toolErr = extractContent(innerResult);
+        return typeof toolErr === "string" ? toolErr : JSON.stringify(toolErr);
+    }
+    return null;
+}
+/**
+ * Terminal SSE comment frame the registry proxy appends when the upstream
+ * exchange is cut by the X-Mesh-Timeout budget mid-stream (#1201). Emitted as
+ * `: mesh-proxy-timeout budget=<N>s`. Comment frames are invisible to
+ * conforming SSE clients per the SSE spec, which makes this a spec-compliant
+ * in-band timeout signal.
+ * Keep in sync with proxyTimeoutCommentMarker in
+ * src/core/registry/ent_handlers.go and sseProxyTimeoutMarker in
+ * src/core/cli/call.go. The literal is pinned by
+ * src/core/registry/proxy_stream_test.go and the consumer tests in
+ * src/__tests__/proxy-sse-no-data.test.ts — a drift in either package breaks
+ * the partner's tests.
+ */
+const SSE_PROXY_TIMEOUT_MARKER = ": mesh-proxy-timeout";
+/**
+ * Thrown when an SSE stream ends without a result frame AND the registry
+ * proxy's timeout marker was seen: the X-Mesh-Timeout budget is definitively
+ * spent. callMcpTool classifies this like its local abort-timeouts — NOT
+ * retried (a retry would burn another full budget against an exchange the
+ * proxy already cut) and exactly one error span via the timeout accounting
+ * path — so the runtime-side report agrees with meshctl's for the same cut.
+ */
+class ProxyTimeoutError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ProxyTimeoutError";
+    }
+}
+/**
+ * Read an SSE response from the MCP HTTP Streamable transport down to its
+ * final content (the JSON-RPC `result`).
+ *
+ * Distinct from `sse.ts`'s `parseSSEResponse` (string→object, Rust-core-backed):
+ * this consumes a whole `Response` body and returns the extracted content.
+ */
+async function readSSEResponseToContent(response) {
     const reader = response.body?.getReader();
     if (!reader) {
         throw new Error("No response body");
@@ -679,6 +704,56 @@ async function parseSSEResponse(response) {
     const decoder = new TextDecoder();
     let buffer = "";
     let result = "";
+    let sawResult = false;
+    let proxyTimeoutBudget = null;
+    let proxyTimeoutSignaled = false;
+    // Handle a single SSE line. Comment frames (":"-prefixed, e.g.
+    // sse-starlette's `: ping - <ts>` keepalives) and other non-data lines are
+    // ignored per the SSE spec — only `data:` frames carry payload (#1201) —
+    // except the proxy's terminal timeout marker, which is tracked so a
+    // result-less stream end can be reported as a definitive timeout.
+    const handleLine = (line) => {
+        if (line.startsWith(SSE_PROXY_TIMEOUT_MARKER)) {
+            proxyTimeoutSignaled = true;
+            proxyTimeoutBudget = /budget=([0-9.]+s)/.exec(line)?.[1] ?? null;
+            return;
+        }
+        if (!line.startsWith("data:"))
+            return;
+        // Per the SSE spec the colon may be followed by zero or one space:
+        // strip the field name, then at most one leading space.
+        let data = line.slice(5);
+        if (data.startsWith(" "))
+            data = data.slice(1);
+        if (data === "[DONE]")
+            return;
+        let event;
+        try {
+            event = JSON.parse(data);
+        }
+        catch {
+            // Ignore parse errors for non-JSON data events
+            return;
+        }
+        // Handle JSON-RPC response — mirror callMcpTool's JSON path exactly so
+        // callers can't distinguish transports: protocol-level error first,
+        // then tool-level isError, then content extraction.
+        const jsonRpcEvent = event;
+        if (jsonRpcEvent.error) {
+            throw new Error(`MCP error: ${jsonRpcEvent.error.message ?? JSON.stringify(jsonRpcEvent.error)}`);
+        }
+        // Key-presence (not truthiness) so legitimately falsy results
+        // (null, "", 0) are extracted just like the JSON path does. Events
+        // without a `result` key (e.g. notifications) are skipped.
+        if (event && typeof event === "object" && "result" in event) {
+            const toolErrMsg = toolErrorMessage(jsonRpcEvent.result);
+            if (toolErrMsg !== null) {
+                throw new Error(`MCP tool error: ${toolErrMsg}`);
+            }
+            sawResult = true;
+            result = extractContent(jsonRpcEvent.result);
+        }
+    };
     while (true) {
         const { done, value } = await reader.read();
         if (done)
@@ -688,28 +763,26 @@ async function parseSSEResponse(response) {
         const lines = buffer.split("\n");
         buffer = lines.pop() ?? ""; // Keep incomplete line
         for (const line of lines) {
-            if (line.startsWith("data: ")) {
-                const data = line.slice(6);
-                if (data === "[DONE]")
-                    continue;
-                try {
-                    const event = JSON.parse(data);
-                    // Handle JSON-RPC response
-                    const jsonRpcEvent = event;
-                    if (jsonRpcEvent.result) {
-                        result = extractContent(jsonRpcEvent.result);
-                    }
-                    else if (jsonRpcEvent.error) {
-                        throw new Error(`MCP error: ${jsonRpcEvent.error.message ?? JSON.stringify(jsonRpcEvent.error)}`);
-                    }
-                }
-                catch (e) {
-                    // Ignore parse errors for non-JSON data events
-                    if (!(e instanceof SyntaxError))
-                        throw e;
-                }
-            }
+            handleLine(line);
+        }
+    }
+    // Drain anything left in the decoder and buffer: a stream that ends
+    // without a trailing newline still has its last line pending here.
+    buffer += decoder.decode();
+    for (const line of buffer.split("\n")) {
+        handleLine(line);
+    }
+    // A stream that ended without ANY result frame is a cut exchange — e.g.
+    // the registry proxy's X-Mesh-Timeout budget expired mid-stream and only
+    // keepalive comment frames arrived (#1201). That must surface as an error,
+    // never as an empty-string success. When the proxy's terminal marker was
+    // seen, the cut is a definitive timeout (non-retryable); without it, the
+    // generic protocol error below stays retryable.
+    if (!sawResult) {
+        if (proxyTimeoutSignaled) {
+            throw new ProxyTimeoutError(`MCP call timed out: registry proxy X-Mesh-Timeout budget${proxyTimeoutBudget ? ` (${proxyTimeoutBudget})` : ""} expired before the agent sent a response`);
         }
+        throw new Error("MCP SSE stream ended without a result frame (connection closed or proxy timeout before the agent responded)");
     }
     return result;
 }