veryfront 0.1.1289-rc.25708 → 0.1.1289-rc.25721

package/esm/src/tool/remote-mcp.js

@@ -1,4 +1,12 @@
+import * as dntShim from "../../_dnt.shims.js";
+import { VERSION } from "../utils/version-constant.js";
 import { defineOwnDataProperty } from "../security/own-data-property.js";
+import { allPrivatePromises, chainPrivatePromise } from "../security/private-promise.js";
+import { mapPrivateArray } from "../security/private-array.js";
+import { testPrivateRegExp } from "../security/private-regexp.js";
+import { privateTextEndsWith, privateTextStartsWith, privateTextTrim, } from "../security/private-text.js";
+import { createPrivateSet } from "../security/private-set.js";
+import { createPrivateWeakStore } from "../security/private-weak-store.js";
 import { NETWORK_ERROR, TIMEOUT_ERROR } from "../errors/index.js";
 import { readMcpToolDiscoveryMetadata } from "./discovery-metadata.js";
 import { getApiBaseUrlEnv } from "../config/env.js";
@@ -36,6 +44,25 @@ const NativeURL = URL;
 // The resolved headers can carry a bearer (the platform source's run token, a
 // user source's OAuth token), so they are only touched through members
 // captured before project code loaded.
+const NativeMap = Map;
+const NativeUint8Array = Uint8Array;
+const MapPrototypeGet = Map.prototype.get;
+const MapPrototypeSet = Map.prototype.set;
+const MapPrototypeHas = Map.prototype.has;
+const MapPrototypeDelete = Map.prototype.delete;
+const MapPrototypeClear = Map.prototype.clear;
+const MapPrototypeValues = Map.prototype.values;
+const MapPrototypeIterator = Map.prototype[Symbol.iterator];
+const MapIteratorNext = Object.getPrototypeOf(new Map().entries()).next;
+const HeadersPrototypeForEach = Headers.prototype.forEach;
+const digest = dntShim.crypto.subtle.digest.bind(dntShim.crypto.subtle);
+const encodeUtf8 = TextEncoder.prototype.encode.bind(UTF8_ENCODER);
+const nativeBtoa = btoa;
+const nativeFromCodePoint = String.fromCodePoint;
+const nativeIsSafeInteger = Number.isSafeInteger;
+const objectHasOwn = Object.hasOwn;
+const nativeIsArray = Array.isArray;
+const typedArrayLengthGetter = Object.getOwnPropertyDescriptor(Object.getPrototypeOf(Uint8Array.prototype), "length").get;
 const HeadersPrototypeSet = Headers.prototype.set;
 const HeadersPrototypeGet = Headers.prototype.get;
 const HeadersPrototypeDelete = Headers.prototype.delete;
@@ -50,11 +77,22 @@ const urlHashGetter = Object.getOwnPropertyDescriptor(NativeURL.prototype, "hash
 const urlOriginGetter = Object.getOwnPropertyDescriptor(NativeURL.prototype, "origin")?.get;
 const urlPathnameGetter = Object.getOwnPropertyDescriptor(NativeURL.prototype, "pathname")?.get;
 class RemoteMCPHttpError extends Error {
-    constructor(status) {
+    status;
+    modernError;
+    constructor(status, modernError = false) {
         super(`Remote MCP request failed (${status})`);
+        this.status = status;
+        this.modernError = modernError;
         this.name = "RemoteMCPHttpError";
     }
 }
+/** Internal signal: a session was (re)negotiated mid-pagination, so discovery restarts. */
+class RemoteMCPDiscoveryRestart extends Error {
+    constructor() {
+        super("Remote MCP tools/list must restart in the renewed session");
+        this.name = "RemoteMCPDiscoveryRestart";
+    }
+}
 class RemoteMCPOAuthExpiredHttpError extends RemoteMCPHttpError {
     constructor(status) {
         super(status);
@@ -63,7 +101,7 @@ class RemoteMCPOAuthExpiredHttpError extends RemoteMCPHttpError {
 }
 const JSON_RPC_TOOL_ERROR_RESULT = Symbol("veryfront.remote-mcp.json-rpc-tool-error");
 function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
+    return typeof value === "object" && value !== null && !nativeIsArray(value);
 }
 function isJsonRpcErrorObject(value) {
     return isRecord(value) &&
@@ -130,15 +168,15 @@ function isJsonStructureWithin(value, maxDepth, maxNodes) {
     }
     return true;
 }
-function normalizeParameters(inputSchema, toolName) {
-    const snapshot = snapshotBoundedJsonValue(inputSchema);
+function normalizeParameters(schema, toolName, kind = "input") {
+    const snapshot = snapshotBoundedJsonValue(schema);
     if (!snapshot.success ||
         !isRecord(snapshot.value) ||
         !isJsonStructureWithin(snapshot.value, MAX_REMOTE_MCP_TOOL_SCHEMA_DEPTH, MAX_REMOTE_MCP_TOOL_SCHEMA_NODES) ||
         serializedByteLength(snapshot.value) > MAX_REMOTE_MCP_TOOL_SCHEMA_BYTES) {
-        throw protocolError(`Remote MCP tools/list returned a malformed input schema for tool "${toolName}"`);
+        throw protocolError(`Remote MCP tools/list returned a malformed ${kind} schema for tool "${toolName}"`);
     }
-    if (Object.keys(snapshot.value).length === 0) {
+    if (kind === "input" && Object.keys(snapshot.value).length === 0) {
         return { type: "object", properties: {} };
     }
     return snapshot.value;
@@ -158,6 +196,9 @@ function normalizeToolDefinition(entry, index) {
         name: entry.name,
         description: entry.description,
         parameters: normalizeParameters(entry.inputSchema, entry.name),
+        ...(entry.outputSchema === undefined
+            ? {}
+            : { outputSchema: normalizeParameters(entry.outputSchema, entry.name, "output") }),
     };
     // Navigation hints only. Invalid metadata is ignored rather than rejecting the tool.
     const discovery = readMcpToolDiscoveryMetadata(entry);
@@ -584,9 +625,9 @@ function validateEndpoint(endpoint) {
     }
     return reflectApply(urlHrefGetter, url, []);
 }
-async function postJsonRpc(endpoint, headers, body, requestFetch, callerSignal, maxResponseBytes) {
+async function postJsonRpc(endpoint, headers, body, requestFetch, callerSignal, maxResponseBytes, onResponse) {
     const expectedId = body.id;
-    if (typeof expectedId !== "string" || expectedId.length === 0) {
+    if (expectedId !== undefined && (typeof expectedId !== "string" || expectedId.length === 0)) {
         throw new TypeError("Remote MCP JSON-RPC request id must be a non-empty string");
     }
     const serializedBody = serializeJsonRpcRequest(body);
@@ -610,7 +651,20 @@ async function postJsonRpc(endpoint, headers, body, requestFetch, callerSignal,
             if (isOauthExpiredMessage(detail)) {
                 throw new RemoteMCPOAuthExpiredHttpError(response.status);
             }
-            throw new RemoteMCPHttpError(response.status);
+            let modernError = false;
+            try {
+                const payload = JSON.parse(text);
+                modernError = isRecord(payload) && isRecord(payload.error) &&
+                    (payload.error.code === -32020 || payload.error.code === -32021 ||
+                        payload.error.code === -32022 || payload.error.code === -32601);
+            }
+            catch { /* Legacy servers can return plain text errors. */ }
+            throw new RemoteMCPHttpError(response.status, modernError);
+        }
+        onResponse?.(response);
+        if (expectedId === undefined) {
+            discardResponseBody(response);
+            return undefined;
         }
         return await parseJsonRpcResponse(response, expectedId, maxResponseBytes, requestScope.signal);
     }
@@ -742,69 +796,545 @@ function buildRunContextMeta(context, endpoint) {
     }
     return Object.keys(meta).length > 0 ? meta : undefined;
 }
+const MODERN_MCP_VERSION = "2026-07-28";
+const LEGACY_MCP_VERSIONS = ["2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05"];
+const MCP_CLIENT_INFO = { name: "veryfront", version: VERSION };
+/** Validate a minted session identifier without consulting mutable RegExp methods. */
+function isValidMcpSessionId(sessionId) {
+    return !!sessionId && sessionId.length <= 4096 && testPrivateRegExp(/^[\x21-\x7e]+$/, sessionId);
+}
+function encodeMcpHeader(value) {
+    if (testPrivateRegExp(/^[\x20-\x7e]*$/, value) && privateTextTrim(value) === value &&
+        !(privateTextStartsWith(value, "=?base64?") && privateTextEndsWith(value, "?=")))
+        return value;
+    const bytes = encodeUtf8(value);
+    let binary = "";
+    const length = reflectApply(typedArrayLengthGetter, bytes, []);
+    for (let index = 0; index < length; index++) {
+        binary += nativeFromCodePoint(bytes[index]);
+    }
+    return `=?base64?${nativeBtoa(binary)}?=`;
+}
+/** Build the headers and body for one JSON-RPC request in a modern or legacy session. */
+function buildMcpRequest(headers, body, session, annotations) {
+    const finalHeaders = copyNativeHeaders(headers);
+    const version = session?.version ?? MODERN_MCP_VERSION;
+    reflectApply(HeadersPrototypeSet, finalHeaders, ["MCP-Protocol-Version", version]);
+    reflectApply(HeadersPrototypeSet, finalHeaders, ["Mcp-Method", body.method]);
+    const params = isRecord(body.params) ? body.params : {};
+    reflectApply(HeadersPrototypeDelete, finalHeaders, ["Mcp-Name"]);
+    if (typeof params.name === "string") {
+        if (!session && isRecord(params.arguments)) {
+            addMcpParameterHeaders(finalHeaders, annotations?.get(params.name) ?? [], params.arguments);
+        }
+        reflectApply(HeadersPrototypeSet, finalHeaders, ["Mcp-Name", encodeMcpHeader(params.name)]);
+    }
+    if (session?.sessionId) {
+        reflectApply(HeadersPrototypeSet, finalHeaders, ["Mcp-Session-Id", session.sessionId]);
+    }
+    if (session)
+        return { headers: finalHeaders, body };
+    return {
+        headers: finalHeaders,
+        body: {
+            ...body,
+            params: {
+                ...params,
+                _meta: {
+                    ...(isRecord(params._meta) ? params._meta : {}),
+                    "io.modelcontextprotocol/protocolVersion": version,
+                    "io.modelcontextprotocol/clientInfo": MCP_CLIENT_INFO,
+                    "io.modelcontextprotocol/clientCapabilities": {},
+                },
+            },
+        },
+    };
+}
+/** Whether a failed request may negotiate or renew a legacy session. */
+function shouldNegotiateSession(error, session, operation) {
+    if (!(error instanceof RemoteMCPHttpError) ||
+        error instanceof RemoteMCPOAuthExpiredHttpError || error.modernError)
+        return false;
+    // Only discovery may treat an unrecognized 400 as a legacy server; a tool
+    // call could have taken effect before failing, so it is never replayed.
+    if (!session)
+        return operation !== "execution" && error.status === 400;
+    return !!session.sessionId && error.status === 404;
+}
+/** Accumulate paginated tools/list results under the aggregate catalog bounds. */
+function createToolListAccumulator() {
+    const annotations = new Map();
+    const definitions = [];
+    // Every returned definition counts toward the bound, including tools
+    // excluded below for invalid header annotations.
+    const names = new Set();
+    const seenCursors = new Set();
+    return {
+        annotations,
+        definitions,
+        accept(page) {
+            if (names.size + page.length > MAX_REMOTE_MCP_TOOL_DEFINITIONS) {
+                throw protocolError(`Remote MCP tools/list cannot contain more than ${MAX_REMOTE_MCP_TOOL_DEFINITIONS} tools`);
+            }
+            for (const definition of page) {
+                if (names.has(definition.name)) {
+                    throw protocolError(`Remote MCP tools/list returned duplicate tool name "${definition.name}"`);
+                }
+                names.add(definition.name);
+                const headers = readMcpParameterHeaders(definition.parameters);
+                if (!headers)
+                    continue;
+                annotations.set(definition.name, headers);
+                definitions.push(definition);
+            }
+        },
+        advance(cursor) {
+            if (seenCursors.has(cursor)) {
+                throw protocolError(`Remote MCP tools/list returned repeated pagination cursor "${cursor}"`);
+            }
+            seenCursors.add(cursor);
+            return cursor;
+        },
+    };
+}
+/** Best-effort session cleanup is bounded in aggregate so teardown cannot stall a run. */
+const REMOTE_MCP_SESSION_CLEANUP_BUDGET_MS = 5_000;
+/** Send one session DELETE; resolves with the failure instead of rejecting. */
+async function deleteMcpSession(cleanup, getRequestFetch, budget) {
+    const scope = createRequestSignalScope(budget);
+    try {
+        const headers = copyNativeHeaders(cleanup.headers);
+        reflectApply(HeadersPrototypeDelete, headers, ["Mcp-Method"]);
+        const requestFetch = getRequestFetch(cleanup.endpoint);
+        const init = createNativeRequestInit(undefined, {
+            method: "DELETE",
+            headers,
+            signal: scope.signal,
+            redirect: "error",
+        });
+        // The retained Authorization and Mcp-Session-Id must not reach replaced
+        // Request or Headers members, exactly as for the POST dispatch.
+        assertNativeRequestProcessing();
+        const response = await requestFetch(cleanup.endpoint, init);
+        discardResponseBody(response);
+        if (!response.ok && response.status !== 404 && response.status !== 405) {
+            return new RemoteMCPHttpError(response.status);
+        }
+        return undefined;
+    }
+    catch (error) {
+        return error ?? new Error("Remote MCP session cleanup failed");
+    }
+    finally {
+        scope.dispose();
+    }
+}
+/**
+ * Send DELETE for every retained session concurrently under one aggregate
+ * budget. Returns the first failure, if any, after all attempts settle.
+ */
+async function terminateMcpSessions(cleanups, getRequestFetch) {
+    if (cleanups.length === 0)
+        return undefined;
+    const budget = new AbortController();
+    const timer = setTimeout(() => budget.abort(new DOMException(`Remote MCP session cleanup exceeded ${REMOTE_MCP_SESSION_CLEANUP_BUDGET_MS}ms`, "TimeoutError")), REMOTE_MCP_SESSION_CLEANUP_BUDGET_MS);
+    let outcomes;
+    try {
+        outcomes = await allPrivatePromises(mapPrivateArray(cleanups, (cleanup) => deleteMcpSession(cleanup, getRequestFetch, budget.signal)));
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    for (const outcome of outcomes) {
+        if (outcome !== undefined)
+            return outcome;
+    }
+    return undefined;
+}
+/** Validate one schema-declared header annotation, or return undefined if invalid. */
+function readHeaderAnnotation(value, path, reachable, names) {
+    const name = value["x-mcp-header"];
+    if (!reachable || typeof name !== "string")
+        return undefined;
+    if (!/^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/.test(name) || names.has(name.toLowerCase())) {
+        return undefined;
+    }
+    const type = value.type;
+    if (type !== "string" && type !== "integer" && type !== "boolean")
+        return undefined;
+    return { path, name, type };
+}
+/** Inspect only bounded, normalized JSON schemas, never application objects. */
+function readMcpParameterHeaders(schema) {
+    const result = [];
+    const names = new Set();
+    let valid = true;
+    function visit(value, path, reachable) {
+        if (Array.isArray(value)) {
+            for (const item of value)
+                visit(item, path, false);
+            return;
+        }
+        if (!isRecord(value))
+            return;
+        if (Object.hasOwn(value, "x-mcp-header")) {
+            const annotation = readHeaderAnnotation(value, path, reachable, names);
+            if (annotation) {
+                names.add(annotation.name.toLowerCase());
+                result.push(annotation);
+            }
+            else {
+                valid = false;
+            }
+        }
+        for (const [key, child] of Object.entries(value)) {
+            if (key === "properties" && isRecord(child))
+                visitProperties(child, path, reachable);
+            else if (key !== "x-mcp-header")
+                visit(child, path, false);
+        }
+    }
+    function visitProperties(properties, path, reachable) {
+        for (const [name, property] of Object.entries(properties)) {
+            visit(property, [...path, name], reachable);
+        }
+    }
+    if (Object.hasOwn(schema, "x-mcp-header"))
+        return undefined;
+    // The root is an object container. Only its properties can carry annotations.
+    if (isRecord(schema.properties)) {
+        for (const [name, property] of Object.entries(schema.properties))
+            visit(property, [name], true);
+        for (const [name, value] of Object.entries(schema)) {
+            if (name !== "properties")
+                visit(value, [], false);
+        }
+    }
+    else {
+        for (const value of Object.values(schema))
+            visit(value, [], false);
+    }
+    return valid ? result : undefined;
+}
+function addMcpParameterHeaders(headers, annotations, args) {
+    for (const annotation of annotations) {
+        let value = args;
+        for (const segment of annotation.path) {
+            value = isRecord(value) && objectHasOwn(value, segment) ? value[segment] : undefined;
+        }
+        if (value === undefined || value === null)
+            continue;
+        if ((annotation.type === "integer" && !nativeIsSafeInteger(value)) ||
+            (annotation.type !== "integer" && typeof value !== annotation.type)) {
+            throw protocolError("Remote MCP tool header parameter has an invalid type");
+        }
+        reflectApply(HeadersPrototypeSet, headers, [
+            `Mcp-Param-${annotation.name}`,
+            // A template literal converts these primitives without calling project code.
+            encodeMcpHeader(`${value}`),
+        ]);
+    }
+}
+async function remoteMcpSessionKey(endpoint, headers, runId) {
+    // Native Headers iteration is sorted. Length prefixes prevent collisions;
+    // raw credentials never enter mutable Array/JSON hooks or cache keys.
+    let identity = `${endpoint.length}:${endpoint}${runId?.length ?? 0}:${runId ?? ""}`;
+    reflectApply(HeadersPrototypeForEach, headers, [(value, name) => {
+            identity += `${name.length}:${name}${value.length}:${value}`;
+        }]);
+    const hash = await digest("SHA-256", encodeUtf8(identity));
+    const bytes = new NativeUint8Array(hash);
+    const hex = "0123456789abcdef";
+    let key = "";
+    for (let index = 0; index < 32; index++) {
+        const byte = bytes[index];
+        key += hex[byte >>> 4] + hex[byte & 15];
+    }
+    return key;
+}
+/** Keep retained session credentials away from project-patched Map methods. */
+function createPrivateMcpMap() {
+    const map = new NativeMap();
+    defineOwnDataProperty(map, "get", (key) => reflectApply(MapPrototypeGet, map, [key]));
+    defineOwnDataProperty(map, "set", (key, value) => reflectApply(MapPrototypeSet, map, [key, value]));
+    defineOwnDataProperty(map, "has", (key) => reflectApply(MapPrototypeHas, map, [key]));
+    defineOwnDataProperty(map, "delete", (key) => reflectApply(MapPrototypeDelete, map, [key]));
+    defineOwnDataProperty(map, "clear", () => reflectApply(MapPrototypeClear, map, []));
+    defineOwnDataProperty(map, "values", () => reflectApply(MapPrototypeValues, map, []));
+    defineOwnDataProperty(map, Symbol.iterator, () => {
+        const iterator = reflectApply(MapPrototypeIterator, map, []);
+        return { next: () => reflectApply(MapIteratorNext, iterator, []) };
+    });
+    return map;
+}
+let mcpProtocolProofSequence = 0;
+function proveMcpProtocol(protocol) {
+    return { protocol, sequence: ++mcpProtocolProofSequence };
+}
+const SHARED_MCP_PROTOCOL_STATE = Symbol("veryfront.remote-mcp.shared-protocol-state");
+const sharedMcpProtocolStates = createPrivateWeakStore();
+/**
+ * Share endpoint protocol knowledge across sources derived from this config.
+ *
+ * A composite that routes some calls through a source with extra credentials
+ * (terminal or mutation authority) discovers tools only through its ordinary
+ * source. Sources created from configs spread from the returned value fall back
+ * to the protocol and header annotations that discovery recorded for the same
+ * endpoint, so their first call neither probes a legacy server with a call that
+ * cannot be replayed nor omits schema-declared headers.
+ */
+export function shareRemoteMCPProtocolState(config) {
+    const token = Object.freeze({});
+    sharedMcpProtocolStates.set(token, {
+        protocols: createPrivateMcpMap(),
+        parameterHeaders: createPrivateMcpMap(),
+    });
+    return { ...config, [SHARED_MCP_PROTOCOL_STATE]: token };
+}
+function readSharedMcpProtocolState(config) {
+    if (!objectHasOwn(config, SHARED_MCP_PROTOCOL_STATE))
+        return undefined;
+    const token = config[SHARED_MCP_PROTOCOL_STATE];
+    return typeof token === "object" && token !== null
+        ? sharedMcpProtocolStates.get(token)
+        : undefined;
+}
 function createRemoteMCPToolSourceWithFetch(config, getRequestFetch) {
     const id = config.id ?? "remote-mcp";
     const listMethod = config.listMethod ?? "tools/list";
     const callMethod = config.callMethod ?? "tools/call";
-    return {
-        id,
-        async listTools(context) {
-            const endpoint = validateEndpoint(await resolveValue(config.endpoint, context));
-            const headers = await resolveHeaders(config.headers, context);
-            const listMeta = config.listMeta === undefined ? undefined : Object.fromEntries(Object.entries(config.listMeta).filter(([key]) => key !== "tool_call_admission"));
-            const definitions = [];
-            const definitionNames = new Set();
-            const seenCursors = new Set();
-            let cursor;
-            for (let page = 0; page < MAX_REMOTE_MCP_TOOL_LIST_PAGES; page += 1) {
-                const requestId = `${id}:tools:list`;
-                const payload = await postJsonRpc(endpoint, headers, {
+    const sessions = createPrivateMcpMap();
+    let nextCleanupId = 0;
+    const cleanupRequests = createPrivateMcpMap();
+    const initializing = createPrivateMcpMap();
+    const parameterHeaders = createPrivateMcpMap();
+    // The protocol each endpoint+credential identity last proved: "legacy" after
+    // a negotiated session, "modern" after a sessionless request succeeded. A
+    // tool call for a new run of a legacy identity initializes first instead of
+    // probing with a modern request, because an ambiguous call failure is never
+    // replayed.
+    const protocols = createPrivateMcpMap();
+    const shared = readSharedMcpProtocolState(config);
+    const leases = createPrivateSet();
+    function recordProtocol(identityKey, endpoint, protocol) {
+        const proof = proveMcpProtocol(protocol);
+        protocols.set(identityKey, proof);
+        shared?.protocols.set(endpoint, proof);
+    }
+    /**
+     * The most recent proof for this identity or, through a shared config, for
+     * the endpoint. A legacy session negotiated before a later modern proof is
+     * stale: the server accepts sessionless requests and may have dropped it.
+     */
+    function currentProtocol(identityKey, endpoint) {
+        const own = protocols.get(identityKey);
+        const other = shared?.protocols.get(endpoint);
+        if (!own)
+            return other?.protocol;
+        if (!other)
+            return own.protocol;
+        return other.sequence > own.sequence ? other.protocol : own.protocol;
+    }
+    async function withLease(runId, operation) {
+        const lease = { runId, closed: false };
+        leases.add(lease);
+        try {
+            return await operation(lease);
+        }
+        finally {
+            leases.delete(lease);
+        }
+    }
+    async function initialize(key, endpoint, headers, requestFetch, signal, runId, identityKey) {
+        const pending = initializing.get(key);
+        if (pending)
+            return await pending;
+        const promise = (async () => {
+            const initHeaders = copyNativeHeaders(headers);
+            reflectApply(HeadersPrototypeDelete, initHeaders, ["Mcp-Session-Id"]);
+            reflectApply(HeadersPrototypeDelete, initHeaders, ["MCP-Protocol-Version"]);
+            reflectApply(HeadersPrototypeSet, initHeaders, ["Mcp-Method", "initialize"]);
+            reflectApply(HeadersPrototypeDelete, initHeaders, ["Mcp-Name"]);
+            let sessionId;
+            let cleanupHeaders;
+            const requestId = `${id}:initialize`;
+            const payload = await postJsonRpc(endpoint, initHeaders, {
+                jsonrpc: "2.0",
+                id: requestId,
+                method: "initialize",
+                params: {
+                    protocolVersion: LEGACY_MCP_VERSIONS[0],
+                    capabilities: {},
+                    clientInfo: MCP_CLIENT_INFO,
+                },
+            }, requestFetch, signal, MAX_REMOTE_MCP_CALL_RESPONSE_BYTES, (response) => {
+                sessionId = reflectApply(HeadersPrototypeGet, response.headers, ["Mcp-Session-Id"]) ??
+                    undefined;
+                if (isValidMcpSessionId(sessionId)) {
+                    // The server has minted a session even if parsing or validation fails.
+                    cleanupHeaders = copyNativeHeaders(initHeaders);
+                    reflectApply(HeadersPrototypeSet, cleanupHeaders, ["Mcp-Session-Id", sessionId]);
+                    reflectApply(HeadersPrototypeSet, cleanupHeaders, [
+                        "MCP-Protocol-Version",
+                        LEGACY_MCP_VERSIONS[0],
+                    ]);
+                    cleanupRequests.set(++nextCleanupId, {
+                        sourceKey: key,
+                        endpoint,
+                        headers: cleanupHeaders,
+                        sessionId,
+                        runId,
+                    });
+                }
+            });
+            const result = getJsonRpcResult(payload, requestId);
+            if (!isRecord(result) || typeof result.protocolVersion !== "string" ||
+                !LEGACY_MCP_VERSIONS.includes(result.protocolVersion)) {
+                throw protocolError("Remote MCP initialize returned an unsupported protocol version");
+            }
+            if (sessionId !== undefined && !isValidMcpSessionId(sessionId)) {
+                throw protocolError("Remote MCP initialize returned an invalid session identifier");
+            }
+            const session = { version: result.protocolVersion, sessionId };
+            reflectApply(HeadersPrototypeSet, initHeaders, ["MCP-Protocol-Version", session.version]);
+            if (cleanupHeaders) {
+                reflectApply(HeadersPrototypeSet, cleanupHeaders, [
+                    "MCP-Protocol-Version",
+                    session.version,
+                ]);
+            }
+            if (sessionId)
+                reflectApply(HeadersPrototypeSet, initHeaders, ["Mcp-Session-Id", sessionId]);
+            reflectApply(HeadersPrototypeSet, initHeaders, ["Mcp-Method", "notifications/initialized"]);
+            await postJsonRpc(endpoint, initHeaders, {
+                jsonrpc: "2.0",
+                method: "notifications/initialized",
+            }, requestFetch, signal, MAX_REMOTE_MCP_CALL_RESPONSE_BYTES);
+            sessions.set(key, session);
+            recordProtocol(identityKey, endpoint, "legacy");
+            return session;
+        })();
+        initializing.set(key, promise);
+        try {
+            return await promise;
+        }
+        finally {
+            initializing.delete(key);
+        }
+    }
+    async function request(options, lease) {
+        const { endpoint, headers, requestFetch, signal, maxBytes, operation, runId } = options;
+        const snapshot = snapshotBoundedJsonValue(options.body, MAX_REMOTE_MCP_REQUEST_BYTES);
+        if (!snapshot.success || !isRecord(snapshot.value)) {
+            throw new TypeError("Remote MCP JSON-RPC request must be a bounded JSON object");
+        }
+        const body = snapshot.value;
+        const key = await remoteMcpSessionKey(endpoint, headers, runId);
+        // Schema annotations and protocol support describe the endpoint and
+        // credentials, not a run, so they hold for calls under any run.
+        const identityKey = await remoteMcpSessionKey(endpoint, headers);
+        // Session setup never uses a call-only transport such as hosted admission.
+        const sessionFetch = getRequestFetch(endpoint);
+        const establish = () => {
+            // Disposal may have run while this request awaited the server. A session
+            // minted now would outlive the cleanup that already finished.
+            if (lease.closed)
+                throw new Error("Remote MCP source was disposed during the request");
+            return initialize(key, endpoint, headers, sessionFetch, signal, runId, identityKey);
+        };
+        const send = (session) => {
+            const annotations = parameterHeaders.get(identityKey) ??
+                shared?.parameterHeaders.get(endpoint);
+            const built = buildMcpRequest(headers, body, session, annotations);
+            return postJsonRpc(endpoint, built.headers, built.body, requestFetch, signal, maxBytes);
+        };
+        if (initializing.has(key))
+            await initializing.get(key);
+        let session = sessions.get(key);
+        const protocol = currentProtocol(identityKey, endpoint);
+        if (session && protocol === "modern") {
+            // Negotiated before a later sessionless success; the server may have dropped it.
+            sessions.delete(key);
+            session = undefined;
+        }
+        if (!session && operation === "execution" && protocol === "legacy") {
+            // Initialization happens before the call is sent, so a failure here never
+            // leaves a side-effecting request to replay.
+            session = await establish();
+        }
+        try {
+            const result = await send(session);
+            if (!session) {
+                // A sessionless success proves the modern protocol, so a later call
+                // must not initialize a session the server may no longer accept.
+                recordProtocol(identityKey, endpoint, "modern");
+            }
+            return result;
+        }
+        catch (error) {
+            if (!shouldNegotiateSession(error, session, operation))
+                throw error;
+            if (session && sessions.get(key) === session)
+                sessions.delete(key);
+            if (session && currentProtocol(identityKey, endpoint) === "modern") {
+                // A concurrent request proved sessionless support while this one used
+                // its rejected session; a new legacy handshake would fail there.
+                if (operation === "discovery-page")
+                    throw new RemoteMCPDiscoveryRestart();
+                return await send();
+            }
+            const renewed = sessions.get(key) ?? await establish();
+            // A pagination cursor belongs to the session that issued it.
+            if (operation === "discovery-page")
+                throw new RemoteMCPDiscoveryRestart();
+            return await send(renewed);
+        }
+    }
+    async function listPages(endpoint, headers, listMeta, context, lease) {
+        const catalog = createToolListAccumulator();
+        let cursor;
+        for (let page = 0; page < MAX_REMOTE_MCP_TOOL_LIST_PAGES; page += 1) {
+            const requestId = `${id}:tools:list`;
+            const params = {
+                ...(cursor !== undefined ? { cursor } : {}),
+                ...(listMeta !== undefined ? { _meta: listMeta } : {}),
+            };
+            const payload = await request({
+                endpoint,
+                headers,
+                body: {
                     jsonrpc: "2.0",
                     id: requestId,
                     method: listMethod,
-                    ...(cursor !== undefined || listMeta !== undefined
-                        ? {
-                            params: {
-                                ...(cursor !== undefined ? { cursor } : {}),
-                                ...(listMeta !== undefined ? { _meta: listMeta } : {}),
-                            },
-                        }
-                        : {}),
-                }, getRequestFetch(endpoint), context?.abortSignal, MAX_REMOTE_MCP_TOOL_LIST_RESPONSE_BYTES);
-                const result = getJsonRpcResult(payload, requestId);
-                const { definitions: pageDefinitions, nextCursor } = normalizeToolListPage(result);
-                if (definitions.length + pageDefinitions.length >
-                    MAX_REMOTE_MCP_TOOL_DEFINITIONS) {
-                    throw protocolError(`Remote MCP tools/list cannot contain more than ${MAX_REMOTE_MCP_TOOL_DEFINITIONS} tools`);
-                }
-                for (const definition of pageDefinitions) {
-                    if (definitionNames.has(definition.name)) {
-                        throw protocolError(`Remote MCP tools/list returned duplicate tool name "${definition.name}"`);
-                    }
-                    definitionNames.add(definition.name);
-                    definitions.push(definition);
-                }
-                if (nextCursor === undefined) {
-                    return definitions;
-                }
-                if (seenCursors.has(nextCursor)) {
-                    throw protocolError(`Remote MCP tools/list returned repeated pagination cursor "${nextCursor}"`);
-                }
-                seenCursors.add(nextCursor);
-                cursor = nextCursor;
-                if (page === MAX_REMOTE_MCP_TOOL_LIST_PAGES - 1) {
-                    throw protocolError(`Remote MCP tools/list exceeded ${MAX_REMOTE_MCP_TOOL_LIST_PAGES} pages`);
-                }
+                    ...(Object.keys(params).length > 0 ? { params } : {}),
+                },
+                requestFetch: getRequestFetch(endpoint),
+                signal: context?.abortSignal,
+                maxBytes: MAX_REMOTE_MCP_TOOL_LIST_RESPONSE_BYTES,
+                operation: cursor === undefined ? "discovery" : "discovery-page",
+                runId: context?.runId,
+            }, lease);
+            const { definitions, nextCursor } = normalizeToolListPage(getJsonRpcResult(payload, requestId));
+            catalog.accept(definitions);
+            if (nextCursor === undefined) {
+                parameterHeaders.set(await remoteMcpSessionKey(endpoint, headers), catalog.annotations);
+                shared?.parameterHeaders.set(endpoint, catalog.annotations);
+                return catalog.definitions;
             }
-            throw protocolError(`Remote MCP tools/list exceeded ${MAX_REMOTE_MCP_TOOL_LIST_PAGES} pages`);
-        },
-        async executeTool(toolName, args, context) {
-            const endpoint = validateEndpoint(await resolveValue(config.endpoint, context));
-            const headers = await resolveHeaders(config.headers, context);
-            const meta = buildRunContextMeta(context, endpoint);
-            const requestId = `${id}:tools:call:${toolName}`;
-            try {
-                const payload = await postJsonRpc(endpoint, headers, {
+            cursor = catalog.advance(nextCursor);
+        }
+        throw protocolError(`Remote MCP tools/list exceeded ${MAX_REMOTE_MCP_TOOL_LIST_PAGES} pages`);
+    }
+    async function executeWithLease(toolName, args, context, lease) {
+        const endpoint = validateEndpoint(await resolveValue(config.endpoint, context));
+        const headers = await resolveHeaders(config.headers, context);
+        const meta = buildRunContextMeta(context, endpoint);
+        const requestId = `${id}:tools:call:${toolName}`;
+        try {
+            const payload = await request({
+                endpoint,
+                headers,
+                body: {
                     jsonrpc: "2.0",
                     id: requestId,
                     method: callMethod,
@@ -813,30 +1343,100 @@ function createRemoteMCPToolSourceWithFetch(config, getRequestFetch) {
                         arguments: args,
                         ...(meta ? { _meta: meta } : {}),
                     },
-                }, getHostedToolCallAdmissionRequestFetch(endpoint) ?? getRequestFetch(endpoint), context?.abortSignal, MAX_REMOTE_MCP_CALL_RESPONSE_BYTES);
-                const result = getJsonRpcResult(payload, requestId, true);
-                if (isJsonRpcToolErrorResult(result)) {
-                    return preserveToolExecutionErrorMarker(normalizeKnownToolError(result.result, toolName, endpoint, context));
+                },
+                requestFetch: getHostedToolCallAdmissionRequestFetch(endpoint) ??
+                    getRequestFetch(endpoint),
+                signal: context?.abortSignal,
+                maxBytes: MAX_REMOTE_MCP_CALL_RESPONSE_BYTES,
+                operation: "execution",
+                runId: context?.runId,
+            }, lease);
+            const result = getJsonRpcResult(payload, requestId, true);
+            if (isJsonRpcToolErrorResult(result)) {
+                return preserveToolExecutionErrorMarker(normalizeKnownToolError(result.result, toolName, endpoint, context));
+            }
+            // The response text is already bounded, so one string may use the whole response.
+            const resultSnapshot = snapshotBoundedParsedJsonValue(result, MAX_REMOTE_MCP_CALL_RESPONSE_BYTES);
+            if (!resultSnapshot.success) {
+                throw protocolError("Remote MCP tools/call returned an unbounded JSON result");
+            }
+            return normalizeCallToolResult({
+                result: resultSnapshot.value,
+                toolName,
+                endpoint,
+                context,
+            });
+        }
+        catch (error) {
+            const normalizedError = normalizeKnownToolException(error, toolName, endpoint, context);
+            if (normalizedError) {
+                return normalizedError;
+            }
+            throw error;
+        }
+    }
+    return {
+        id,
+        async dispose(context) {
+            // Requests still waiting on the server may not negotiate a session after
+            // this point; handshakes already running are awaited and terminated.
+            for (const lease of leases) {
+                if (!context || lease.runId === context.runId)
+                    lease.closed = true;
+            }
+            const handshakes = [];
+            for (const entry of initializing) {
+                defineOwnDataProperty(handshakes, handshakes.length, { settled: entry[1] });
+            }
+            await allPrivatePromises(mapPrivateArray(handshakes, (handshake) => chainPrivatePromise(handshake.settled, () => undefined, () => undefined)));
+            const selected = [];
+            // Native iterator entries are indexed directly. Destructuring would call
+            // a project-patched Array iterator with the retained session credentials.
+            for (const entry of cleanupRequests) {
+                const cleanup = entry[1];
+                if (context && cleanup.runId !== context.runId)
+                    continue;
+                sessions.delete(cleanup.sourceKey);
+                cleanupRequests.delete(entry[0]);
+                defineOwnDataProperty(selected, selected.length, cleanup);
+            }
+            const firstError = await terminateMcpSessions(selected, getRequestFetch);
+            if (!context) {
+                sessions.clear();
+                parameterHeaders.clear();
+                protocols.clear();
+            }
+            if (firstError !== undefined)
+                throw firstError;
+        },
+        listTools(context) {
+            // The lease spans configuration resolution and every page, so disposal
+            // during any of those awaits closes it.
+            return withLease(context?.runId, async (lease) => {
+                const endpoint = validateEndpoint(await resolveValue(config.endpoint, context));
+                const headers = await resolveHeaders(config.headers, context);
+                const listMeta = config.listMeta === undefined ? undefined : Object.fromEntries(Object.entries(config.listMeta).filter(([key]) => key !== "tool_call_admission"));
+                // A session renewed mid-pagination invalidates earlier cursors, so the
+                // catalog is rebuilt from the first page, at most once.
+                try {
+                    return await listPages(endpoint, headers, listMeta, context, lease);
                 }
-                // The response text is already bounded, so one string may use the whole response.
-                const resultSnapshot = snapshotBoundedParsedJsonValue(result, MAX_REMOTE_MCP_CALL_RESPONSE_BYTES);
-                if (!resultSnapshot.success) {
-                    throw protocolError("Remote MCP tools/call returned an unbounded JSON result");
+                catch (error) {
+                    if (!(error instanceof RemoteMCPDiscoveryRestart))
+                        throw error;
                 }
-                return normalizeCallToolResult({
-                    result: resultSnapshot.value,
-                    toolName,
-                    endpoint,
-                    context,
-                });
-            }
-            catch (error) {
-                const normalizedError = normalizeKnownToolException(error, toolName, endpoint, context);
-                if (normalizedError) {
-                    return normalizedError;
+                try {
+                    return await listPages(endpoint, headers, listMeta, context, lease);
                 }
-                throw error;
-            }
+                catch (error) {
+                    if (!(error instanceof RemoteMCPDiscoveryRestart))
+                        throw error;
+                    throw protocolError("Remote MCP session was renewed again during tools/list pagination");
+                }
+            });
+        },
+        executeTool(toolName, args, context) {
+            return withLease(context?.runId, (lease) => executeWithLease(toolName, args, context, lease));
         },
     };
 }