@nylorun/runtime 0.19.1-beta → 0.21.0-beta

package/dist/mcp/connect.js

@@ -1,14 +1,157 @@
+import { AsyncLocalStorage } from "node:async_hooks";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
-import { schemaFromJSON } from "@nylorun/core/define";
-import { guardedFetch } from "../tenant/outbound.js";
-import { modelToolName, } from "./snapshot.js";
-/** An SDK `Client` as an `McpClient`. */
-export function sdkClient(client) {
+import { ErrorCode, McpError } from "@modelcontextprotocol/sdk/types.js";
+import { MCP_TOOL_DEFAULTS, SERVER_INSTRUCTIONS_MAX_CHARS, mcpToolSettings, schemaFromJSON, } from "@nylorun/core/define";
+import { scrub, scrubValues } from "../redact.js";
+import { guardedFetch, MAX_RESPONSE_BYTES, OutboundFailed, OutboundRefused, } from "../tenant/outbound.js";
+import { credentialSecrets } from "../vault/headers.js";
+import { normalizeToolName, } from "./snapshot.js";
+/** How much of a failed answer's body the model sees. */
+export const MCP_ERROR_BODY_CHARS = 2_000;
+/**
+ * The largest `tools/call` answer the gate holds (R2b C11): 8 MiB, an HTTP tool's cap. Core
+ * stores what does not fit a tool result as an artifact (`tenant/tool-results.ts`).
+ */
+export const MCP_RESULT_MAX_BYTES = MAX_RESPONSE_BYTES;
+/** A tool call that failed with a code the model can act on (R2b C7). */
+export class McpCallFailed extends Error {
+    failure;
+    constructor(failure) {
+        super(failure.message);
+        this.failure = failure;
+        this.name = "McpCallFailed";
+    }
+    get code() {
+        return this.failure.code;
+    }
+    /** The failure the gate answered, as the class the loop's own call would have thrown. */
+    static from(failure) {
+        return failure.code === "credential_rejected" && failure.server !== undefined
+            ? new CredentialRejected(failure.server, failure.vault)
+            : new McpCallFailed(failure);
+    }
+    /** The failed tool outcome the model sees. */
+    outcome() {
+        const failure = this.failure;
+        return {
+            kind: "failed",
+            code: failure.code,
+            message: failure.message,
+            retryable: failure.retryable,
+            ...(failure.server === undefined ? {} : { server: failure.server }),
+            ...(failure.vault === undefined ? {} : { vault: failure.vault }),
+            ...(failure.redacted ? { redacted: failure.redacted } : {}),
+        };
+    }
+}
+/**
+ * A request the server answered `401` (R2b C1): it rejected the vault's credential, or wanted one
+ * and got none. Never retried, since nothing the gate holds changes between tries (Q4). A tool
+ * call that meets it fails with `credential_rejected` for the model to see; at discovery it is the
+ * server's `failed` diagnostic.
+ */
+export class CredentialRejected extends McpCallFailed {
+    server;
+    vault;
+    challenge;
+    constructor(server, 
+    /** The scope of the vault whose credential was sent; absent when none was. */
+    vault, 
+    /**
+     * The answer's `WWW-Authenticate`, which may name the server's protected-resource metadata
+     * (RFC 9728 `resource_metadata`): a tool preview reads it (R2b C12). Never shown to the model.
+     */
+    challenge) {
+        super({
+            code: "credential_rejected",
+            message: vault === undefined
+                ? `The MCP server '${server}' answered HTTP 401: it needs a credential, and the session's vaults hold none for it`
+                : `The MCP server '${server}' answered HTTP 401: it rejected the credential from the ${vault} vault`,
+            sent: true,
+            retryable: false,
+            server,
+            ...(vault === undefined ? {} : { vault }),
+        });
+        this.server = server;
+        this.vault = vault;
+        this.challenge = challenge;
+        this.name = "CredentialRejected";
+    }
+}
+/**
+ * A request its connection can no longer make, refused before it reached a tool: the server
+ * answered `404` to the connection's `Mcp-Session-Id` (the session is gone, MCP 2025-06-18
+ * "Session Management"), or the credential's `via` now sends the server's requests elsewhere.
+ * Whoever holds the connection drops it, opens it again and sends the call once more (R2b C7).
+ * When that fails too, it is `mcp.unreachable`: nothing ran.
+ */
+export class McpConnectionStale extends McpCallFailed {
+    constructor(server, reason) {
+        super({
+            code: "mcp.unreachable",
+            message: `The MCP server '${server}' ${reason}, and the call was not sent`,
+            sent: false,
+            retryable: true,
+        });
+        this.name = "McpConnectionStale";
+    }
+}
+/** A tool call that never reached its server: its connection could not be opened. */
+export function unreachable(server, error) {
+    if (error instanceof McpCallFailed)
+        return error;
+    return unreachableFailure(server, error instanceof Error ? error.message : String(error));
+}
+/** The operation a request of the transport's fetch belongs to. */
+const tracking = new AsyncLocalStorage();
+function tracked(call, run) {
+    const tracker = {
+        secrets: new Set(),
+        sent: false,
+        settled: false,
+        ...(call ? { calling: new AbortController() } : {}),
+    };
+    return tracking.run(tracker, () => run(tracker));
+}
+/**
+ * An SDK `Client` as an `McpClient`. Its answers and failures carry no credential value sent
+ * with them (R2b C8), and a failed call is an `McpCallFailed` (C7).
+ */
+export function sdkClient(client, serverName) {
     return {
-        listTools: (params, options) => client.listTools(params, options?.signal ? { signal: options.signal } : undefined),
-        callTool: (params, options) => client.callTool(params, undefined, options?.signal ? { signal: options.signal } : undefined),
+        listTools: (params, options) => tracked(false, async (tracker) => {
+            try {
+                const page = await client.listTools(params, options?.signal ? { signal: options.signal } : undefined);
+                return scrubbed(page, tracker);
+            }
+            catch (error) {
+                throw scrubError(error, tracker);
+            }
+        }),
+        callTool: (params, options) => tracked(true, async (tracker) => {
+            const lost = tracker.calling.signal;
+            try {
+                const result = (await client.callTool(params, undefined, {
+                    signal: options?.signal ? AbortSignal.any([options.signal, lost]) : lost,
+                }));
+                // An answer the stream did not count (an `sse` server answers on its event stream).
+                if (Buffer.byteLength(JSON.stringify(result)) > MCP_RESULT_MAX_BYTES)
+                    throw tooLargeFailure(serverName);
+                const answer = scrubValues(result, [...tracker.secrets]);
+                return { result: answer.value, ...(answer.redacted > 0 ? { redacted: answer.redacted } : {}) };
+            }
+            catch (error) {
+                // A cancel or a shutdown: the caller decides what it means.
+                if (options?.signal?.aborted)
+                    throw error;
+                throw scrubError(failureOf(serverName, error, tracker), tracker);
+            }
+            finally {
+                tracker.settled = true;
+            }
+        }),
     };
 }
 export async function openMcpServer(input) {
@@ -20,76 +163,192 @@ export async function openMcpServer(input) {
             initial.credentialIds;
         throw error;
     }
-    const fetchImpl = authorizedFetch(input.server, authorize, input.policy ?? {});
-    const url = new URL(input.server.url);
+    // A credential with `via` sends the server's requests there (R2b C2); the manifest's URL still
+    // names the server for its credential, its tools and its diagnostics.
+    const url = new URL(endpointOf(input.server, initial));
+    const fetchImpl = authorizedFetch(input.server, url, authorize, input.policy ?? {});
     const transport = input.server.type === "sse"
         ? new SSEClientTransport(url, { fetch: fetchImpl })
         : new StreamableHTTPClientTransport(url, { fetch: fetchImpl });
     const client = createClient();
-    await client.connect(transport);
-    return { client: sdkClient(client), close: () => client.close() };
+    const { instructions, serverInfo } = await tracked(false, async (tracker) => {
+        try {
+            await client.connect(transport, input.signal ? { signal: input.signal } : undefined);
+        }
+        catch (error) {
+            // Nothing holds a connection that never opened: end whatever its transport started.
+            void client.close().catch(() => undefined);
+            throw scrubError(error, tracker);
+        }
+        const info = client.getServerVersion();
+        return {
+            instructions: serverInstructions(client.getInstructions(), [...tracker.secrets]),
+            serverInfo: info ? scrubbed({ ...info }, tracker) : undefined,
+        };
+    });
+    return {
+        client: sdkClient(client, input.server.name),
+        ...(instructions === undefined ? {} : { instructions }),
+        ...(serverInfo === undefined ? {} : { serverInfo }),
+        close: () => client.close(),
+    };
 }
+/**
+ * What a server's `initialize` said to do with its tools, for the note on its deferred tools
+ * (R2b C10): cut to `SERVER_INSTRUCTIONS_MAX_CHARS`, without a credential value sent (C8).
+ */
+export function serverInstructions(text, secrets) {
+    if (typeof text !== "string" || text.trim().length === 0)
+        return undefined;
+    return scrubValues(text.trim().slice(0, SERVER_INSTRUCTIONS_MAX_CHARS), secrets).value;
+}
+/**
+ * Lists a server's tools under the names the model knows them by (R2b C6): `server__tool` where
+ * that is a name every provider accepts, else `normalizeToolName`'s, listed in `renamed`. A name
+ * taken by a declared tool or an earlier server's tool omits the tool; a renamed tool that
+ * collides gets the hash suffix first.
+ */
 export async function listMcpTools(client, input) {
-    const tools = [];
-    const omitted = [];
+    const listed = [];
     let cursor;
     for (let page = 0; page < 100; page += 1) {
-        const listed = await client.listTools(cursor ? { cursor } : undefined, input.signal ? { signal: input.signal } : undefined);
-        for (const tool of listed.tools) {
-            if (typeof tool.name !== "string" || tool.name.length === 0)
-                continue;
-            const name = modelToolName(input.serverName, tool.name);
-            const inputSchema = usableSchema(tool.inputSchema);
-            if (!inputSchema || input.taken.has(name)) {
-                omitted.push(name);
-                continue;
-            }
-            const outputSchema = tool.outputSchema
-                ? usableSchema(tool.outputSchema)
-                : undefined;
-            input.taken.add(name);
-            tools.push({
-                capabilityId: input.capabilityId,
-                serverName: input.serverName,
-                serverToolName: tool.name,
-                name,
-                ...(typeof tool.description === "string" && tool.description.length > 0
-                    ? { description: tool.description }
-                    : {}),
-                inputSchema,
-                ...(outputSchema === undefined ? {} : { outputSchema }),
-            });
-        }
-        cursor = listed.nextCursor;
+        const answer = await client.listTools(cursor ? { cursor } : undefined, input.signal ? { signal: input.signal } : undefined);
+        listed.push(...answer.tools);
+        cursor = answer.nextCursor;
         if (!cursor)
             break;
     }
-    return { tools, omitted };
+    const server = input.server;
+    const listedNames = new Set(listed.map((tool) => tool.name));
+    // Servers change their lists, so a key naming no tool is a diagnostic, not a failure.
+    const unknownTools = Object.keys(server?.tools ?? {}).filter((key) => key !== MCP_TOOL_DEFAULTS && !listedNames.has(key));
+    let disabled = 0;
+    const omitted = [];
+    const candidates = [];
+    for (const tool of listed) {
+        if (typeof tool.name !== "string" || tool.name.length === 0)
+            continue;
+        if (server && !mcpToolSettings(server, tool.name).enabled) {
+            disabled += 1;
+            continue;
+        }
+        const inputSchema = usableSchema(tool.inputSchema);
+        if (inputSchema)
+            candidates.push({ tool, inputSchema });
+        else
+            omitted.push(normalizeToolName(input.serverName, tool.name));
+    }
+    // Names that need no change first, so a renamed tool never takes the name of another of the
+    // server's tools.
+    const names = new Map();
+    const renamed = [];
+    for (const candidate of candidates) {
+        const name = normalizeToolName(input.serverName, candidate.tool.name);
+        if (name !== `${input.serverName}__${candidate.tool.name}`)
+            continue;
+        if (input.taken.has(name))
+            omitted.push(name);
+        else {
+            input.taken.add(name);
+            names.set(candidate, name);
+        }
+    }
+    for (const candidate of candidates) {
+        const raw = `${input.serverName}__${candidate.tool.name}`;
+        let name = normalizeToolName(input.serverName, candidate.tool.name);
+        if (name === raw)
+            continue;
+        if (input.taken.has(name))
+            name = normalizeToolName(input.serverName, candidate.tool.name, { suffixed: true });
+        if (input.taken.has(name)) {
+            omitted.push(name);
+            continue;
+        }
+        input.taken.add(name);
+        names.set(candidate, name);
+        renamed.push({ serverToolName: candidate.tool.name, name });
+    }
+    const tools = [];
+    for (const candidate of candidates) {
+        const name = names.get(candidate);
+        if (name === undefined)
+            continue;
+        const { tool, inputSchema } = candidate;
+        const outputSchema = tool.outputSchema ? usableSchema(tool.outputSchema) : undefined;
+        const annotations = retryHints(tool.annotations);
+        tools.push({
+            capabilityId: input.capabilityId,
+            serverName: input.serverName,
+            serverToolName: tool.name,
+            name,
+            ...(typeof tool.description === "string" && tool.description.length > 0
+                ? { description: tool.description }
+                : {}),
+            inputSchema,
+            ...(outputSchema === undefined ? {} : { outputSchema }),
+            ...(annotations === undefined ? {} : { annotations }),
+        });
+    }
+    return { tools, omitted, renamed, disabled, unknownTools };
 }
+/**
+ * One tool call and what it came to. Rejects with `McpConnectionStale` when the connection must
+ * be opened again (the caller retries once), and with any error that leaves the call's fate
+ * unknown.
+ */
 export async function callMcpTool(client, serverToolName, args, options = {}) {
-    const result = await client.callTool({
-        name: serverToolName,
-        arguments: args && typeof args === "object" && !Array.isArray(args)
-            ? args
-            : {},
-    }, options);
+    let answer;
+    try {
+        answer = await client.callTool({
+            name: serverToolName,
+            arguments: args && typeof args === "object" && !Array.isArray(args)
+                ? args
+                : {},
+        }, {
+            ...(options.key === undefined ? {} : { key: options.key }),
+            ...(options.signal ? { signal: options.signal } : {}),
+        });
+    }
+    catch (error) {
+        if (!(error instanceof McpCallFailed))
+            throw error;
+        // The connection's to handle: its holder opens it again and sends the call once more.
+        if (error instanceof McpConnectionStale)
+            throw error;
+        // Sent, then lost: the tool may have run. Calling it again is the model's choice only for a
+        // tool the server says is safe to repeat; any other waits for an operator.
+        if (error.code === "mcp.lost" && !options.retrySafe)
+            throw new Error(error.message);
+        // Otherwise the outcome is known: the model sees it.
+        return error.outcome();
+    }
+    const { result } = answer;
+    const redacted = answer.redacted ? { redacted: answer.redacted } : {};
     if ("isError" in result && result.isError) {
         return {
             kind: "failed",
             code: "mcp.tool",
             message: textContent(result.content) || "MCP tool failed",
+            ...redacted,
         };
     }
     if ("structuredContent" in result && result.structuredContent !== undefined)
-        return { kind: "completed", output: result.structuredContent };
-    const text = "content" in result ? textContent(result.content) : undefined;
+        return { kind: "completed", output: result.structuredContent, ...redacted };
+    // Text alone is the text. With an image, audio or a resource in it, every part stays, and core
+    // stores the bytes as artifacts before anything records them (R2b C11, `tenant/tool-results.ts`).
+    const text = "content" in result && onlyText(result.content) ? textContent(result.content) : undefined;
     if (text !== undefined)
-        return { kind: "completed", output: text };
+        return { kind: "completed", output: text, ...redacted };
     return {
         kind: "completed",
         output: "content" in result ? result.content : result,
+        ...redacted,
     };
 }
+function onlyText(content) {
+    return (Array.isArray(content) &&
+        content.every((part) => !!part && typeof part === "object" && part.type === "text"));
+}
 export function diagnosticFromError(capabilityId, serverName, error) {
     const credentialIds = error && typeof error === "object" && "credentialIds" in error
         ? error.credentialIds
@@ -107,7 +366,8 @@ export function diagnosticFromError(capabilityId, serverName, error) {
     const code = error && typeof error === "object" && "code" in error
         ? error.code
         : undefined;
-    const unauthorized = code === 401 ||
+    const unauthorized = error instanceof CredentialRejected ||
+        code === 401 ||
         (error instanceof Error && /\b401\b/.test(error.message));
     return {
         capabilityId,
@@ -123,11 +383,21 @@ export function diagnosticFromError(capabilityId, serverName, error) {
 function createClient() {
     return new Client({ name: "nylorun-runtime", version: "0.6.0" }, { capabilities: {} });
 }
-function authorizedFetch(server, authorize, policy) {
+/** Where `server`'s requests go: the credential's `via`, else the URL the manifest names. */
+function endpointOf(server, result) {
+    return result.status === "authorized" && result.via !== undefined ? result.via : server.url;
+}
+/**
+ * The transport's fetch: each request to `endpoint`'s origin carries the credential read for it
+ * now. A `401` answer is `CredentialRejected`, and a POST's other error statuses are
+ * `McpCallFailed`. Under a tracked operation it records the credential values it sends, whether
+ * a POST was sent, and a tool call's answer lost after it was.
+ */
+function authorizedFetch(server, endpoint, authorize, policy) {
     const send = guardedFetch(policy, { stream: true });
     return async (url, init) => {
         const target = typeof url === "string" ? url : url.href;
-        if (!sameOrigin(target, server.url))
+        if (!sameOrigin(target, endpoint.href))
             throw new Error("MCP request origin does not match the declared server");
         const result = await authorize(server.url);
         if (result.status === "refused") {
@@ -136,17 +406,230 @@ function authorizedFetch(server, authorize, policy) {
                 result.credentialIds;
             throw error;
         }
+        // A credential whose `via` changed since the connection opened: never send it elsewhere.
+        if (!sameOrigin(endpointOf(server, result), endpoint.href))
+            throw new McpConnectionStale(server.name, "is now reached at another address (its credential's via changed)");
         const headers = new Headers();
         for (const [key, value] of Object.entries(server.headers ?? {}))
             headers.set(key, value);
         new Headers(init?.headers).forEach((value, key) => headers.set(key, value));
+        // Credential headers, the identity header included, replace manifest headers of the same name.
         if (result.status === "authorized")
             for (const [key, value] of Object.entries(result.headers))
                 headers.set(key, value);
-        // No redirects, and the address checked on what is connected to (`tenant/outbound.ts`).
-        return send(target, { ...init, headers });
+        const tracker = tracking.getStore();
+        if (tracker && result.status === "authorized")
+            for (const secret of credentialSecrets(result.headers, result.identity))
+                tracker.secrets.add(secret);
+        const post = (init?.method ?? "GET").toUpperCase() === "POST";
+        let response;
+        try {
+            // No redirects, and the address checked on what is connected to (`tenant/outbound.ts`).
+            response = await send(target, { ...init, headers });
+        }
+        catch (error) {
+            if (tracker && post && error instanceof OutboundFailed && error.sent)
+                tracker.sent = true;
+            throw error;
+        }
+        if (tracker && post)
+            tracker.sent = true;
+        if (response.status === 401) {
+            await response.body?.cancel().catch(() => undefined);
+            throw new CredentialRejected(server.name, result.status === "authorized" ? result.vault : undefined, response.headers.get("www-authenticate") ?? undefined);
+        }
+        // The server ended the connection's session: the tool never saw the request.
+        if (post && response.status === 404 && headers.has("mcp-session-id")) {
+            await response.body?.cancel().catch(() => undefined);
+            throw new McpConnectionStale(server.name, "ended the connection's session (HTTP 404)");
+        }
+        // A GET's error status (405: no event stream) is the SDK's to read.
+        if (post && !response.ok)
+            throw statusFailure(server.name, response.status, await bodyText(response));
+        return tracker?.calling && post && response.body ? watched(response, tracker) : response;
     };
 }
+/** Error statuses after which the same request may work. */
+const RETRYABLE_STATUSES = new Set([408, 429, 502, 503, 504]);
+/** A POST the server answered with an error status: its JSON-RPC error, or the status. */
+function statusFailure(server, status, body) {
+    const rpc = rpcErrorOf(body);
+    if (status !== 403 && rpc)
+        return rpcFailure(server, `MCP error ${rpc.code}: ${rpc.message}`);
+    const text = body.length > MCP_ERROR_BODY_CHARS ? `${body.slice(0, MCP_ERROR_BODY_CHARS)}…` : body;
+    return new McpCallFailed({
+        code: status === 403 ? "mcp.forbidden" : "mcp.status",
+        message: `The MCP server '${server}' answered HTTP ${status}${text ? `: ${text}` : ""}`,
+        sent: true,
+        retryable: RETRYABLE_STATUSES.has(status),
+    });
+}
+function rpcFailure(server, message) {
+    return new McpCallFailed({
+        code: "mcp.error",
+        message: `The MCP server '${server}' answered an error: ${message.slice(0, MCP_ERROR_BODY_CHARS)}`,
+        sent: true,
+        retryable: false,
+    });
+}
+function unreachableFailure(server, detail) {
+    return new McpCallFailed({
+        code: "mcp.unreachable",
+        message: `The MCP server '${server}' could not be reached, and the call was not sent: ${detail.slice(0, MCP_ERROR_BODY_CHARS)}`,
+        sent: false,
+        retryable: true,
+    });
+}
+function lostFailure(server, detail) {
+    return new McpCallFailed({
+        code: "mcp.lost",
+        message: `The connection to the MCP server '${server}' was lost after the call was sent, so it may have run: ${detail.slice(0, MCP_ERROR_BODY_CHARS)}`,
+        sent: true,
+        retryable: true,
+    });
+}
+function tooLargeFailure(server) {
+    return new McpCallFailed({
+        code: "mcp.too-large",
+        message: `The MCP server '${server}' answered more than ${MCP_RESULT_MAX_BYTES} bytes, the most a tool result may hold, so the answer was not kept`,
+        sent: true,
+        retryable: false,
+    });
+}
+/** What a tool call's failure means (R2b C7). */
+function failureOf(server, error, tracker) {
+    if (error instanceof McpCallFailed)
+        return error;
+    if (tracker.tooLarge)
+        return tooLargeFailure(server);
+    const detail = error instanceof Error ? error.message : String(error);
+    if (tracker.lost !== undefined)
+        return lostFailure(server, tracker.lost);
+    if (error instanceof OutboundRefused)
+        return unreachableFailure(server, detail);
+    if (error instanceof OutboundFailed)
+        return error.sent ? lostFailure(server, detail) : unreachableFailure(server, detail);
+    if (error instanceof McpError) {
+        // Sent, and no answer came in time.
+        if (error.code === ErrorCode.RequestTimeout)
+            return lostFailure(server, detail);
+        if (error.code === ErrorCode.ConnectionClosed)
+            return tracker.sent ? lostFailure(server, detail) : unreachableFailure(server, detail);
+        return rpcFailure(server, detail);
+    }
+    // An answer that could not be read leaves the call's fate unknown, as a lost one does.
+    return tracker.sent ? lostFailure(server, detail) : unreachableFailure(server, detail);
+}
+/** `value` with the operation's credential values replaced (R2b C8). */
+function scrubbed(value, tracker) {
+    return tracker.secrets.size === 0 ? value : scrub(value, [...tracker.secrets], { valuesOnly: true });
+}
+/** `error` with no credential value in its message (R2b C8). */
+function scrubError(error, tracker) {
+    if (tracker.secrets.size === 0)
+        return error;
+    if (error instanceof McpCallFailed) {
+        const message = scrubValues(error.failure.message, [...tracker.secrets]);
+        if (message.redacted === 0)
+            return error;
+        return new McpCallFailed({
+            ...error.failure,
+            message: message.value,
+            redacted: (error.failure.redacted ?? 0) + message.redacted,
+        });
+    }
+    if (error instanceof Error)
+        error.message = scrubbed(error.message, tracker);
+    return error;
+}
+/**
+ * A tool call's answer whose body reports its loss (R2b C7): a stream that breaks after the
+ * request was sent ends the call as lost, now, instead of at the SDK's request timeout. One that
+ * passes `MCP_RESULT_MAX_BYTES` ends it as `mcp.too-large` (C11), before more of it is read.
+ */
+function watched(response, tracker) {
+    const source = response.body.getReader();
+    let received = 0;
+    const body = new ReadableStream({
+        async pull(controller) {
+            let next;
+            try {
+                next = await source.read();
+            }
+            catch (error) {
+                if (!tracker.settled && tracker.lost === undefined && !tracker.tooLarge) {
+                    tracker.lost = error instanceof Error ? error.message : String(error);
+                    tracker.calling?.abort(new Error(tracker.lost));
+                }
+                controller.error(error);
+                return;
+            }
+            if (next.done)
+                return controller.close();
+            received += next.value.byteLength;
+            if (received > MCP_RESULT_MAX_BYTES) {
+                tracker.tooLarge = true;
+                const error = new Error(`The answer passed ${MCP_RESULT_MAX_BYTES} bytes`);
+                tracker.calling?.abort(error);
+                controller.error(error);
+                void source.cancel(error).catch(() => undefined);
+                return;
+            }
+            controller.enqueue(next.value);
+        },
+        cancel: (reason) => source.cancel(reason),
+    });
+    return new Response(body, {
+        status: response.status,
+        statusText: response.statusText,
+        headers: response.headers,
+    });
+}
+/** The start of an error answer's body. */
+async function bodyText(response) {
+    if (!response.body)
+        return "";
+    const reader = response.body.getReader();
+    const chunks = [];
+    let size = 0;
+    try {
+        while (size < 4 * MCP_ERROR_BODY_CHARS) {
+            const next = await reader.read();
+            if (next.done)
+                break;
+            chunks.push(next.value);
+            size += next.value.byteLength;
+        }
+    }
+    catch {
+        // What arrived is enough to say why.
+    }
+    finally {
+        void reader.cancel().catch(() => undefined);
+    }
+    return Buffer.concat(chunks).toString("utf8").trim();
+}
+/** A JSON-RPC error answer's code and message. */
+function rpcErrorOf(body) {
+    try {
+        const parsed = JSON.parse(body);
+        const error = parsed?.error;
+        if (error && typeof error.code === "number" && typeof error.message === "string")
+            return { code: error.code, message: error.message };
+    }
+    catch {
+        // Not JSON: an HTTP error status.
+    }
+    return undefined;
+}
+/** The hints that calling a tool again is safe, when the server gives any. */
+function retryHints(annotations) {
+    const readOnly = annotations?.readOnlyHint === true;
+    const idempotent = annotations?.idempotentHint === true;
+    if (!readOnly && !idempotent)
+        return undefined;
+    return { ...(readOnly ? { readOnlyHint: true } : {}), ...(idempotent ? { idempotentHint: true } : {}) };
+}
 function sameOrigin(requestUrl, serverUrl) {
     try {
         return new URL(requestUrl).origin === new URL(serverUrl).origin;