Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

94.9 KB
Raw Blame
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0

from __future__ import annotations

import asyncio
import atexit
import concurrent.futures
import contextvars
import hashlib
import importlib
import ipaddress
import json
import mimetypes
import os
import re
import shlex
import shutil
import socket
import subprocess
import sys
import threading
import time
import uuid
from contextlib import contextmanager
from functools import wraps
from typing import Any, Optional, get_type_hints
from urllib.parse import urlsplit, urlunsplit
from weakref import WeakKeyDictionary

from loggers import get_logger
from utils.account_context import (
    OWNER_ACCOUNT_ID,
    account_thread,
    current_account_id,
    is_owner_context,
)

from core.inference import mcp_images

logger = get_logger(__name__)

MCP_TOOL_PREFIX = "mcp__"
_WINDOWS_BATCH_ALWAYS_UNSAFE_ARGUMENT_CHARS = frozenset('%!"\r\n')
_WINDOWS_BATCH_UNQUOTED_UNSAFE_ARGUMENT_CHARS = frozenset("&|<>^()")

# -- and the chat send re-hung for the full timeout -- on every message. Cool off for this long after a failure; much
# Failed probes are not cached but cool off, so a down server doesn't hang every send.
FAILED_PROBE_COOLOFF_SECONDS = 60.0
OAUTH_FAILED_PROBE_COOLOFF_SECONDS = 300.0

_oauth_token_store = None
_account_oauth_token_stores: dict[str, Any] = {}


def _managed_mcp_restricted() -> bool:
    return not is_owner_context()


def _account_key(value):
    if is_owner_context():
        return value
    return current_account_id(), value


def _public_mcp_addresses(url: str) -> list[str]:
    from fastapi import HTTPException
    from core.inference.providers import _metadata_address, _metadata_host, managed_private_url_hint
    from utils.managed_provider_url_settings import get_managed_private_provider_urls_allowed

    private_allowed = get_managed_private_provider_urls_allowed()
    detail = "Managed accounts may only use public-network HTTP MCP servers."
    if not private_allowed:
        detail += managed_private_url_hint()
    try:
        parsed = urlsplit(url)
        if parsed.scheme not in ("http", "https") or not parsed.hostname:
            raise ValueError("HTTP URL required")
        if parsed.username is not None or parsed.password is not None:
            raise ValueError("Use MCP headers for credentials")
        host = parsed.hostname
        if "%" in host:
            raise ValueError("Scoped addresses are not public")
        if _metadata_host(host):
            raise ValueError("Cloud metadata address")
        port = parsed.port or (443 if parsed.scheme == "https" else 80)
        addresses = socket.getaddrinfo(host, port, type = socket.SOCK_STREAM)
        if not addresses:
            raise ValueError("No addresses")
        for *_, sockaddr in addresses:
            address = ipaddress.ip_address(sockaddr[0])
            address = getattr(address, "ipv4_mapped", None) or address
            if _metadata_address(str(address)):
                raise ValueError("Cloud metadata address")
            if private_allowed:
                continue
            if not address.is_global or address.is_multicast or address.is_reserved:
                raise ValueError("Non-public address")
        return list(dict.fromkeys(sockaddr[0] for *_, sockaddr in addresses))
    except (OSError, ValueError, UnicodeError) as exc:
        raise HTTPException(status_code = 400, detail = detail) from exc


def validate_mcp_address(url: str) -> None:
    # Studio's own Decisions server is answered in process; with a local model no request leaves this machine.
    if not _managed_mcp_restricted() or (is_studio_decisions(url) and _local_decisions()):
        return
    if is_studio_tools(url):
        return
    if is_stdio(url):
        from fastapi import HTTPException
        raise HTTPException(
            status_code = 400,
            detail = "Only the installation owner may register local-command MCP servers.",
        )
    _public_mcp_addresses(url)


def _public_http_client_factory(**kwargs):
    """Pin public destinations, including redirects and OAuth discovery; SNI keeps the original hostname and proxy env vars are ignored so they cannot reach the LAN."""
    from mcp.shared._httpx_utils import create_mcp_http_client

    client_type = get_type_hints(create_mcp_http_client)["return"]
    http = importlib.import_module(client_type.__module__.split(".")[0])

    class PublicTransport(http.AsyncBaseTransport):
        def __init__(self):
            # Separate pools retain TLS identity when two names resolve to one IP.
            self.transports = {}

        async def handle_async_request(self, request):
            addresses = await asyncio.to_thread(_public_mcp_addresses, str(request.url))
            origin = (request.url.scheme, request.url.host, request.url.port)
            if origin not in self.transports:
                self.transports[origin] = http.AsyncHTTPTransport(trust_env = False)
            # localhost answers ::1 first while most local servers bind 127.0.0.1 only.
            for index, address in enumerate(addresses):
                pinned = http.Request(
                    method = request.method,
                    url = request.url.copy_with(host = address),
                    headers = request.headers,
                    stream = request.stream,
                    extensions = {**request.extensions, "sni_hostname": request.url.host},
                )
                try:
                    return await self.transports[origin].handle_async_request(pinned)
                except (http.ConnectError, http.ConnectTimeout):
                    if index == len(addresses) - 1:
                        raise

        async def aclose(self):
            for transport in self.transports.values():
                await transport.aclose()

    kwargs["trust_env"] = False
    kwargs["transport"] = PublicTransport()
    kwargs.setdefault("follow_redirects", True)
    if kwargs.get("timeout") is None:
        kwargs["timeout"] = http.Timeout(30.0, read = 300.0)
    return client_type(**kwargs)


def _tool_http_client_factory(**kwargs):
    """No read cap: _race_tool_call enforces each call's budget, which the SDK's 300s read timeout would cut short."""
    if _managed_mcp_restricted():
        client = _public_http_client_factory(**kwargs)
    else:
        from mcp.shared._httpx_utils import create_mcp_http_client
        kwargs.pop("follow_redirects", None)  # create_mcp_http_client sets its own redirect policy
        client = create_mcp_http_client(**kwargs)
    t = client.timeout
    client.timeout = type(t)(connect = t.connect, read = None, write = t.write, pool = t.pool)
    tracker = _SESSION_POSTS.get()
    if tracker is not None:
        tracker.install(client)
    return client


class _PostSlot:
    __slots__ = ("key", "token", "rid")

    def __init__(self, key):
        self.key, self.token, self.rid = key, None, None


class _PostTracker:
    """Open POSTs of a cached session, each bound to its call, so only an abandoned call's open reply counts."""

    def __init__(self):
        self.lock = threading.Lock()
        self.open: set = set()
        self.waiting: list = []  # dispatches whose POST is not sent yet, FIFO per (method, target)
        self.abandoned: dict = {}  # open POST token -> when its call was abandoned
        self.bound: dict = {}  # JSON-RPC id -> slot, so a redirected POST stays with its call
        self.installed = False

    def enqueue(self, slot: _PostSlot) -> None:
        # Called on the session loop as the call starts, so the FIFO follows the order the SDK sends in.
        if slot.key is not None:
            with self.lock:
                self.waiting.append(slot)

    def settle(self, slot: _PostSlot, abandoned: bool) -> None:
        with self.lock:
            if slot in self.waiting:
                self.waiting.remove(slot)
            if abandoned and slot.token in self.open:
                self.abandoned[slot.token] = time.monotonic()
            elif not abandoned and self.bound.get(slot.rid) is slot:
                del self.bound[slot.rid]

    def pending(self) -> Optional[tuple]:
        """(oldest abandonment time, count) of abandoned replies still open, else None."""
        with self.lock:
            if not self.abandoned:
                return None
            return min(self.abandoned.values()), len(self.abandoned)

    def _sent(self, token, key, rid) -> None:
        with self.lock:
            self.open.add(token)
            slot = self.bound.get(rid)
            if slot is not None and slot.key == key:
                slot.token = token
                return
            for slot in self.waiting:
                if slot.key == key:
                    slot.token, slot.rid = token, rid
                    self.waiting.remove(slot)
                    self.bound[rid] = slot
                    break

    def _closed(self, token) -> None:
        with self.lock:
            self.open.discard(token)
            self.abandoned.pop(token, None)

    def install(self, client) -> None:
        http = sys.modules[
            type(client).__module__.split(".")[0]
        ]  # already imported: it built ``client``
        tracker = self

        class Stream(http.AsyncByteStream):
            def __init__(self, inner, token):
                self.inner, self.token = inner, token

            async def __aiter__(self):
                async for chunk in self.inner:
                    yield chunk

            async def aclose(self):
                try:
                    await self.inner.aclose()
                finally:
                    tracker._closed(self.token)

        class Transport(http.AsyncBaseTransport):
            def __init__(self, inner):
                self.inner = inner

            async def handle_async_request(self, request):
                if request.method != "POST":
                    return await self.inner.handle_async_request(request)
                token, (key, rid) = object(), _rpc_target(request)
                if key is None or key[0] not in ("tools/call", "resources/read"):
                    # Only a call's reply may outlive the SDK's old read cap; probes and handshakes keep it.
                    request.extensions["timeout"] = {
                        **request.extensions.get("timeout", {}),
                        "read": _ABANDONED_REPLY_TIMEOUT,
                    }
                tracker._sent(token, key, rid)
                try:
                    response = await self.inner.handle_async_request(request)
                except BaseException:
                    tracker._closed(token)
                    raise
                response.stream = Stream(response.stream, token)
                return response

            async def aclose(self):
                await self.inner.aclose()

        # httpx has no public hook for a request ending without a response; unwrappable clients keep the deadline.
        if not hasattr(client, "_transport") or not isinstance(
            getattr(client, "_mounts", None), dict
        ):
            return
        client._transport = Transport(client._transport)
        client._mounts = {k: (v if v is None else Transport(v)) for k, v in client._mounts.items()}
        self.installed = True


def _rpc_target(request) -> tuple:
    """((JSON-RPC method, tool name or URI), id) of a request POST, else (None, None)."""
    try:
        msg = json.loads(request.content)
        if "id" not in msg or "method" not in msg:
            return None, None
        params = msg.get("params") or {}
        return (msg["method"], params.get("name") or params.get("uri")), msg["id"]
    except Exception:  # noqa: BLE001
        return None, None


# Set by _McpSession.connect so _tool_http_client_factory can hook the client the SDK builds for that session.
_SESSION_POSTS: contextvars.ContextVar[Optional[_PostTracker]] = contextvars.ContextVar(
    "mcp_session_posts", default = None
)


def is_stdio(address: str) -> bool:
    """A non-HTTP address is a local stdio command, e.g. 'npx -y
    @modelcontextprotocol/server-filesystem /path'."""
    return not address.strip().lower().startswith(("http://", "https://"))


def _split_windows_command_line(address: str) -> list[str]:
    """Parse Windows argv by the rules list2cmdline() writes, so trailing backslashes stay undoubled."""
    parts: list[str] = []
    current: list[str] = []
    in_quotes = False
    backslashes = 0
    arg_started = False
    i = 0

    while i < len(address):
        ch = address[i]
        if ch == "\\":
            backslashes += 1
            i += 1
            continue
        if ch == '"':
            current.extend("\\" * (backslashes // 2))
            if backslashes % 2:
                current.append('"')
            else:
                in_quotes = not in_quotes
            arg_started = True
            backslashes = 0
            i += 1
            continue
        # list2cmdline splits only on space and tab; other Unicode or control whitespace is argument data and must not be split.
        if ch in (" ", "\t") and not in_quotes:
            if backslashes:
                current.extend("\\" * backslashes)
                arg_started = True
                backslashes = 0
            if arg_started or current:
                parts.append("".join(current))
                current = []
                arg_started = False
            i += 1
            while i < len(address) and address[i] in (" ", "\t"):
                i += 1
            continue
        if backslashes:
            current.extend("\\" * backslashes)
            arg_started = True
            backslashes = 0
        current.append(ch)
        arg_started = True
        i += 1

    if backslashes:
        current.extend("\\" * backslashes)
        arg_started = True
    if in_quotes:
        raise ValueError("No closing quotation")
    if arg_started or current:
        parts.append("".join(current))
    return parts


def parse_stdio_command(address: str) -> list[str]:
    """Split a stdio command line into argv, shared so validation and transport quote alike."""
    posix = sys.platform != "win32"
    if posix:
        return shlex.split(address, posix = posix)
    if address.lstrip().startswith("'"):
        raise ValueError("Single-quoted executables are not supported on Windows")
    return _split_windows_command_line(address)


def join_stdio_command(parts: list[str]) -> str:
    """Inverse of parse_stdio_command: list2cmdline on Windows so paths round-trip, shlex.join elsewhere."""
    if sys.platform == "win32":
        return subprocess.list2cmdline(parts)
    return shlex.join(parts)


def _windows_batch_argument_is_unsafe(argument: str) -> bool:
    if _WINDOWS_BATCH_ALWAYS_UNSAFE_ARGUMENT_CHARS.intersection(argument):
        return True
    serialized = subprocess.list2cmdline([argument])
    is_quoted = serialized.startswith('"') and serialized.endswith('"')
    return not is_quoted and bool(
        _WINDOWS_BATCH_UNQUOTED_UNSAFE_ARGUMENT_CHARS.intersection(argument)
    )


def _session_log_id(url: str) -> str:
    """Non-secret log label: never log the raw address, since argv and query can hold credentials;
    use the executable basename or host plus a short digest"""
    digest = hashlib.sha256(url.encode()).hexdigest()[:12]
    if not is_stdio(url):
        try:
            label = urlsplit(url).hostname or "<url>"
        except Exception:  # noqa: BLE001
            label = "<invalid>"
        return f"{label}#{digest}"
    try:
        parts = parse_stdio_command(url)
        exe = os.path.basename(parts[0]) if parts else "<empty>"
    except Exception:  # noqa: BLE001
        exe = "<invalid>"
    return f"{exe}#{digest}"


def stdio_mcp_enabled() -> bool:
    """Stdio MCP spawns local processes outside the sandbox: loopback only via UNSLOTH_STUDIO_ALLOW_STDIO_MCP; Colab and network binds off unless set."""
    if _managed_mcp_restricted():
        return False
    if os.environ.get("UNSLOTH_STUDIO_ALLOW_STDIO_MCP") != "1":
        return False
    from state.tool_policy import get_tool_policy
    from utils.host_policy import loopback_default_active, remote_connector_active

    if loopback_default_active() and (remote_connector_active() or get_tool_policy() is False):
        return False
    return True


def stdio_mcp_disabled_reason() -> str:
    """Must name the actual cause: the env var would enable local commands on a published API."""
    if _managed_mcp_restricted():
        return "Only the installation owner may register local-command MCP servers."
    from state.tool_policy import get_tool_policy
    from utils.host_policy import loopback_default_active, remote_connector_active

    if os.environ.get("UNSLOTH_STUDIO_ALLOW_STDIO_MCP") == "1" and loopback_default_active():
        if remote_connector_active():
            return (
                "Local commands are disabled while Remote Access is on, because the "
                "server is reachable from outside this machine. Turn off Remote Access "
                "to use local MCP servers, or use an http:// or https:// URL instead."
            )
        if get_tool_policy() is False:
            return (
                "Local commands are disabled because tools are disabled for this "
                "server. Restart without --disable-tools, or use an http:// or "
                "https:// URL instead."
            )
    return (
        "Local commands aren't enabled on this server. To allow them, set "
        "UNSLOTH_STUDIO_ALLOW_STDIO_MCP=1 and restart Unsloth, or use an "
        "http:// or https:// URL instead."
    )


# OAuth needs minutes for browser sign-in; stdio allows first-run package download.
_HTTP_PROBE_TIMEOUT = 8.0
_OAUTH_PROBE_TIMEOUT = 305.0
_STDIO_PROBE_TIMEOUT = 60.0


def probe_timeout(address: str, use_oauth: bool) -> float:
    if use_oauth:
        return _OAUTH_PROBE_TIMEOUT
    return _STDIO_PROBE_TIMEOUT if is_stdio(address) else _HTTP_PROBE_TIMEOUT


def parse_server_headers(server: dict) -> Optional[dict]:
    """Parsed headers_json; for stdio servers this dict is the process env, not HTTP headers."""
    raw = server.get("headers_json")
    if not raw:
        return None
    try:
        parsed = json.loads(raw)
    except (json.JSONDecodeError, ValueError):
        return None
    return parsed if isinstance(parsed, dict) else None


def _oauth_store():
    global _oauth_token_store
    if not is_owner_context():
        from key_value.aio._utils.sanitization import AlwaysHashStrategy
        from key_value.aio.stores.filetree import FileTreeStore
        from utils.paths.storage_roots import account_path, ensure_dir

        account_id = current_account_id()
        if account_id not in _account_oauth_token_stores:
            _account_oauth_token_stores[account_id] = FileTreeStore(
                data_directory = ensure_dir(account_path("mcp-oauth-tokens")),
                key_sanitization_strategy = AlwaysHashStrategy(),
                collection_sanitization_strategy = AlwaysHashStrategy(),
            )
        return _account_oauth_token_stores[account_id]
    if _oauth_token_store is None:
        from key_value.aio._utils.sanitization import AlwaysHashStrategy
        from key_value.aio.stores.filetree import FileTreeStore
        from utils.paths.storage_roots import ensure_dir, studio_root

        # Hash keys: FileTreeStore treats '://' in raw URLs as nested directories.
        _oauth_token_store = FileTreeStore(
            data_directory = ensure_dir(studio_root() / "mcp-oauth-tokens"),
            key_sanitization_strategy = AlwaysHashStrategy(),
            collection_sanitization_strategy = AlwaysHashStrategy(),
        )
    return _oauth_token_store


def _strip_client_id_under_basic_auth(auth) -> None:
    """The SDK leaves client_id in the body under Basic auth; strict servers (Notion) read that as
    two auth methods -- RFC 6749 2.3 -- and 401. Safe to drop: 3.2.1 makes client_id a MAY once
    authenticated, and an unauthenticated client sends no header, so it keeps it."""
    context = getattr(auth, "context", None)
    prepare = getattr(context, "prepare_token_auth", None)
    if prepare is None:
        logger.warning("MCP OAuth: prepare_token_auth missing; client_id fixup skipped")
        return

    def prepare_token_auth(data, headers = None):
        data, headers = prepare(data, headers)
        if "Authorization" in headers:
            data = {k: v for k, v in data.items() if k != "client_id"}
        return data, headers

    try:
        context.prepare_token_auth = prepare_token_auth
    except Exception as exc:  # noqa: BLE001
        # The SDK reach-in must never break OAuth: without it only strict servers fail, as before.
        logger.warning("MCP OAuth: client_id fixup could not be applied: %s", exc)


def _oauth(
    url: str,
    oauth_client_id: Optional[str] = None,
    oauth_client_secret: Optional[str] = None,
):
    from fastmcp.client.auth import OAuth

    # A pre-registered client skips Dynamic Client Registration (Google's MCP servers have no /register).
    auth = OAuth(
        mcp_url = url,
        token_storage = _oauth_store(),
        client_id = oauth_client_id,
        client_secret = oauth_client_secret,
    )
    _strip_client_id_under_basic_auth(auth)
    return auth


async def clear_oauth_tokens_async(url: str) -> None:
    """Must clear tokens on delete, URL change or OAuth disable: fastmcp keys them by URL, so a re-register reuses the old token; errors must not 500."""
    try:
        await _oauth(url).token_storage_adapter.clear()
    except Exception as exc:  # noqa: BLE001
        logger.warning("Failed to clear OAuth tokens for %s: %s", url, exc)


_IS_WINDOWS = os.name == "nt"
_NODE_COMMANDS = frozenset({"node", "npm", "npx"})
_WINDOWS_LAUNCHER_SUFFIXES = (".cmd", ".exe", ".bat", ".ps1")


def _launcher_name(command: str) -> str:
    """argv[0] reduced to its bare launcher name, Windows suffix stripped."""
    name = os.path.basename(command).lower()
    for suffix in _WINDOWS_LAUNCHER_SUFFIXES:
        if name.endswith(suffix):
            return name[: -len(suffix)]
    return name


def _is_node_command(command: str) -> bool:
    """Whether argv[0] is a Node launcher, the only kind given the managed runtime."""
    return _launcher_name(command) in _NODE_COMMANDS


def _command_selects_runtime(command: Optional[str]) -> bool:
    """A path to a ``node`` launcher picks the runtime explicitly and runs regardless of PATH, so
    handing its children a different Node would only split the two."""
    return (
        command is not None and bool(os.path.dirname(command)) and _launcher_name(command) == "node"
    )


def _runtime_requirements(command: Optional[str]) -> tuple[bool, bool]:
    """Each launcher checks only what it runs, so npx never needs a separate npm executable on PATH."""
    name = _launcher_name(command) if command is not None else None
    if name == "node":
        return False, False
    if command is not None and os.path.dirname(command):
        return False, False
    if name == "npm":
        return True, False
    if name == "npx":
        return False, True
    return True, True


def _path_key(env: dict) -> str:
    """The env key holding PATH; Windows names are case-insensitive, so match any case there."""
    if _IS_WINDOWS:
        for key in env:
            if key.upper() == "PATH":
                return key
    return "PATH"


def _stdio_env(headers: Optional[dict], command: Optional[str] = None) -> Optional[dict]:
    """Stdio env: own vars plus the managed Node bin on PATH, so npx runs without system Node."""
    env = dict(headers or {})
    for key, value in env.items():
        if not isinstance(key, str) or not isinstance(value, str):
            raise ValueError("stdio environment names and values must be strings")
        if "\x00" in key or "\x00" in value:
            raise ValueError("stdio environment must not contain NUL characters")
        if "=" in key:
            raise ValueError("stdio environment variable names must not contain '='")
    key = _path_key(env)
    base = env.get(key)
    if isinstance(base, str) and not base:
        # An explicitly empty PATH is a deliberate sandbox: hand it over untouched.
        return env
    if command is not None and not _is_node_command(command):
        return env or None
    if _command_selects_runtime(command):
        return env or None
    if not isinstance(base, str):
        base = os.environ.get("PATH", "")
    try:
        from utils.node_runtime import path_with_managed_node
        require_npm, require_npx = _runtime_requirements(command)
        patched = path_with_managed_node(base, require_npm = require_npm, require_npx = require_npx)
    except (ImportError, OSError, ValueError):
        patched = base
    if patched and patched != env.get(key):
        env[key] = patched
    return env or None


def _stdio_argv(parts: list, env: Optional[dict]) -> list:
    """argv with argv[0] resolved against the child's PATH. Windows resolves the command against the
    parent environment before ``env`` applies, so a managed-only ``npx`` has to be handed over as
    a full path."""
    path_key = _path_key(env or {})
    explicit_path = env is not None and path_key in env
    path = (env or {}).get(path_key)
    if not isinstance(path, str):
        path = os.environ.get("PATH", "")
    try:
        resolved = shutil.which(parts[0], path = path)
    except OSError:
        resolved = None
    if _IS_WINDOWS and resolved is None and explicit_path and not os.path.dirname(parts[0]):
        raise ValueError(f"Cannot find {parts[0]!r} on the MCP server's configured PATH")
    executable = resolved or parts[0]
    if _IS_WINDOWS:
        suffix = os.path.splitext(executable)[1].lower()
        if suffix in {".cmd", ".bat"} and _launcher_name(executable) in {"npm", "npx"}:
            launcher_dir = os.path.dirname(executable)
            cli = os.path.join(
                launcher_dir,
                "node_modules",
                "npm",
                "bin",
                f"{_launcher_name(executable)}-cli.js",
            )
            sibling_node = os.path.join(launcher_dir, "node.exe")
            try:
                node = (
                    sibling_node
                    if os.path.isfile(sibling_node)
                    else shutil.which("node", path = path)
                )
                cli_exists = os.path.isfile(cli)
            except OSError:
                node = None
                cli_exists = False
            if node and cli_exists:
                # bypass cmd.exe so shell metacharacters remain literal argv.
                return [node, cli, *parts[1:]]
            raise ValueError(
                f"Cannot launch {executable!r} without its Node executable and npm CLI script"
            )
        if suffix in {".cmd", ".bat"} and any(
            _windows_batch_argument_is_unsafe(argument) for argument in parts[1:]
        ):
            raise ValueError(
                "Windows batch launchers cannot safely preserve these MCP command arguments; "
                "invoke the executable directly, or use node.exe with the JavaScript entry point"
            )
    return [executable, *parts[1:]]


def _local_decisions() -> bool:
    from core.systemone.catalog import parse_connection
    from utils.systemone_settings import get_model
    return parse_connection(get_model()) is None


def is_studio_decisions(url: str) -> bool:
    from routes.systemone import MCP_PATH
    from utils.host_policy import is_loopback_host

    parts = urlsplit(url)
    return (
        parts.scheme == "http"
        and is_loopback_host(parts.hostname or "")
        and parts.path.rstrip("/") == MCP_PATH
    )


def is_studio_tools(url: str) -> bool:
    from core.inference.studio_tools_mcp import STUDIO_TOOLS_MCP_PATH
    from utils.host_policy import is_loopback_host

    try:
        parts = urlsplit(url)
        host = parts.hostname or ""
    except ValueError:
        return False
    return (
        parts.scheme == "http"
        and is_loopback_host(host)
        and parts.path.rstrip("/") == STUDIO_TOOLS_MCP_PATH
    )


def _client(
    url: str,
    headers: Optional[dict],
    use_oauth: bool = False,
    **oauth,
):
    validate_mcp_address(url)
    from fastmcp import Client

    if is_studio_decisions(url):
        from routes.systemone import decisions_mcp
        return Client(decisions_mcp)

    if is_studio_tools(url):
        # Listing only: calls go through studio_tools_mcp.call, which binds the caller.
        from core.inference.studio_tools_mcp import chat_tools_mcp
        return Client(chat_tools_mcp())

    if is_stdio(url):
        # Belt-and-suspenders: never spawn unless stdio is enabled on this host.
        if not stdio_mcp_enabled():
            raise PermissionError("stdio MCP servers are disabled on this host")
        from fastmcp.client.transports import StdioTransport

        parts = parse_stdio_command(url)
        if not parts:
            raise ValueError(f"Empty stdio command: {url!r}")
        # keep_alive=False tears the subprocess down so a one-shot call leaves no orphan.
        env = _stdio_env(headers, parts[0])
        argv = _stdio_argv(parts, env)
        return Client(
            StdioTransport(
                command = argv[0],
                args = argv[1:],
                env = env,
                keep_alive = False,
            )
        )

    from fastmcp.client.transports import SSETransport, StreamableHttpTransport
    from fastmcp.mcp_config import infer_transport_type_from_url

    auth = _oauth(url, **oauth) if use_oauth else None

    transport_cls = (
        SSETransport if infer_transport_type_from_url(url) == "sse" else StreamableHttpTransport
    )
    if _managed_mcp_restricted() and auth is not None:
        auth.httpx_client_factory = _public_http_client_factory
    return Client(
        transport_cls(
            url = url,
            headers = headers or None,
            auth = auth,
            httpx_client_factory = _tool_http_client_factory,
        )
    )


def oauth_client_kwargs(row: dict) -> dict:
    # Empty unless configured, so test doubles of _client without these kwargs keep working.
    if not row.get("oauth_client_id"):
        return {}
    return {
        "oauth_client_id": row["oauth_client_id"],
        "oauth_client_secret": row.get("oauth_client_secret"),
    }


_SESSION_IDLE_TTL = 300.0
_SESSION_REAP_INTERVAL = 30.0
_STDIO_CONNECT_TIMEOUT = 60.0  # allows first-run `npx -y ...` package download
_SESSION_CLOSE_TIMEOUT = 10.0
_SESSION_WEDGE_MARGIN = 15.0
_SESSION_LIVENESS_TIMEOUT = 5.0
_CANCEL_UNWIND_TIMEOUT = 2.0
# With no read cap, a still-open abandoned reply is bounded by retiring its session after the old cap or a pile-up.
_ABANDONED_REPLY_TIMEOUT = 300.0
_MAX_ABANDONED_REPLIES = 8
# Idle HTTP sessions are re-proved with tools/list before the next dispatch, as servers may expire
# them (MCP lets a server terminate a session at any time) and no HTTP liveness probe exists
_HTTP_IDLE_RECHECK = 30.0
_DEFAULT_MAX_SESSIONS = 32


def _max_sessions_from_env() -> int:
    # Legacy stdio-specific name; still honoured for existing deployments.
    raw = os.environ.get("UNSLOTH_STUDIO_MAX_MCP_SESSIONS")
    if raw is None:
        raw = os.environ.get("UNSLOTH_STUDIO_MAX_STDIO_MCP_SESSIONS")
    if raw is None:
        return _DEFAULT_MAX_SESSIONS
    try:
        return max(1, int(raw))
    except ValueError:
        return _DEFAULT_MAX_SESSIONS


_MAX_SESSIONS = _max_sessions_from_env()


def _connect_window(url: str, timeout: Optional[float]) -> Optional[float]:
    """Only stdio gets the cold-start cap, since its first run may download a package; HTTP does not."""
    if timeout is None or not is_stdio(url):
        return timeout
    return min(timeout, _STDIO_CONNECT_TIMEOUT)


class _ConnectTimeout(asyncio.TimeoutError):
    """Ran out of time before the transport was up. Carries the window that actually expired, which
    is not the caller's timeout when stdio's cold-start cap is the tighter bound."""

    def __init__(self, window: Optional[float]):
        super().__init__()
        self.window = window


def _is_tool_error(exc: BaseException) -> bool:
    """Version-safe: fastmcp 3.0.2 has no dead probe. ToolError (tool ran and errored) leaves the
    transport alive, so the session is kept; other call_tool errors are transport-level"""
    try:
        from fastmcp.exceptions import ToolError
    except Exception:  # noqa: BLE001
        return False
    return isinstance(exc, ToolError)


def _is_protocol_error(exc: BaseException) -> bool:
    """A JSON-RPC error proves the connection is alive, so it must not retire the session."""
    for module, name in (
        ("mcp.shared.exceptions", "MCPError"),
        ("mcp.shared.exceptions", "McpError"),
    ):
        try:
            cls = getattr(__import__(module, fromlist = [name]), name, None)
        except Exception:  # noqa: BLE001
            continue
        if cls is not None and isinstance(exc, cls):
            # Only when the server sent an error object, not for a synthetic MCPError.
            return getattr(exc, "error", None) is not None
    return False


# HTTP 404 for an unknown Mcp-Session-Id, so the request never ran: the client SDK's "Session terminated"
# stand-in, or the server body mcp 2.x relays (Python SDK -32600 / TypeScript SDK -32001 "Session not found").
_SESSION_GONE_MESSAGES = ("Session terminated", "Session not found")
_SESSION_GONE_CODES = (32600, -32600, -32001)


def _is_session_terminated(exc: BaseException) -> bool:
    error = getattr(exc, "error", None)
    return (
        _is_protocol_error(exc)
        and getattr(error, "message", None) in _SESSION_GONE_MESSAGES
        and getattr(error, "code", None) in _SESSION_GONE_CODES
    )


def _transport_dead(session) -> bool:
    """Only stdio can prove a transport dead; HTTP always reads unknown, so this returns False there."""
    client = getattr(session, "client", None)
    if client is None:
        return True
    transport = getattr(client, "transport", None)
    probe = getattr(transport, "_is_session_dead", None)
    if callable(probe):
        try:
            if probe():
                return True
        except Exception:  # noqa: BLE001
            pass
    connect_task = getattr(transport, "_connect_task", None)
    if connect_task is not None:
        try:
            if connect_task.done():
                return True
        except Exception:  # noqa: BLE001
            pass
    return False


def _needs_idle_recheck(session, idle_for: float, remaining: Optional[float]) -> bool:
    """Idle HTTP sessions are re-proved since a server may drop one silently; stdio is exempt; skipped when the budget is too small to afford the probe."""
    if is_stdio(session.url):
        return False
    # Negative means this borrower connected the session itself, so the handshake it just completed is proof enough.
    if idle_for < 0.0 or idle_for < _HTTP_IDLE_RECHECK:
        return False
    return remaining is None or remaining > _SESSION_LIVENESS_TIMEOUT * 2


def _session_responsive(
    session,
    budget: Optional[float] = None,
    cancel_event = None,
    timeout_is_fatal: bool = True,
) -> bool:
    """Silence condemns a dirty session; an idle one retires only on definite failure; probe is one raw tools/list page, not ping or auto-paginating list_tools."""
    client = session.client
    if client is None:
        return False
    window = _SESSION_LIVENESS_TIMEOUT if budget is None else min(_SESSION_LIVENESS_TIMEOUT, budget)
    if window <= 0:
        # No budget left to ask in; that is not evidence either way.
        return not timeout_is_fatal
    probe = getattr(client, "list_tools_mcp", None) or client.list_tools
    try:
        # margin=0: a wedged loop must fail inside the window, not 15s past it.
        session.run(_race_tool_call(probe(), window, cancel_event), window, margin = 0.0)
    except _MCPCancelled:
        raise
    except (asyncio.TimeoutError, _SessionWedged):
        return not timeout_is_fatal
    except Exception as exc:  # noqa: BLE001
        # A JSON-RPC error means the transport works; reconnecting would lose session state.
        if _is_session_terminated(exc) or not _is_protocol_error(exc):
            return False
    session.dirty = False
    session.proved_at = time.monotonic()
    return True


class _SessionWedged(Exception):
    pass


class _SessionClosed(Exception):
    """The session was closed (server update/delete/shutdown) mid-call."""


def _abort_future(future) -> None:
    # Let the cancelled coroutine unwind before its loop is stopped.
    future.cancel()
    try:
        future.result(1.0)
    except BaseException:  # noqa: BLE001
        pass


class _McpSession:
    def __init__(
        self,
        url: str,
        headers: Optional[dict],
        use_oauth: bool = False,
    ):
        # Cached sessions carry no auth; fail loudly rather than talk to an OAuth server unauthenticated.
        if use_oauth and not is_stdio(url):
            raise ValueError("OAuth MCP servers cannot use a shared session")
        self.url = url
        self.account_id = current_account_id()
        self.headers = headers
        self.client = None
        self.closed = threading.Event()
        self.defunct = False  # discarded; close once in_flight drains (see _retire)
        self.dirty = False  # a call was abandoned on it; ping before reuse
        self.abandoned_at: Optional[float] = None
        self.abandoned = 0
        self.posts = _PostTracker()
        self._close_lock = threading.Lock()
        self.call_lock = threading.Lock()
        # stdio is one ordered byte stream; HTTP POSTs can run in parallel.
        self.serialize_calls = is_stdio(url)
        self.last_used = time.monotonic()
        # Measured from proof of life, not checkout, so a concurrent borrower still sees the idle gap.
        self.proved_at = self.last_used
        self.in_flight = 0  # guarded by _mcp_sessions_lock
        # Windows: force ProactorEventLoop; SelectorEventLoop cannot spawn subprocesses.
        if sys.platform == "win32":
            self.loop = asyncio.ProactorEventLoop()
        else:
            self.loop = asyncio.new_event_loop()
        self._thread = account_thread(target = self._run_loop, name = "mcp-session", daemon = True)
        self._thread.start()

    def note_abandoned(self, slot: _PostSlot) -> None:
        """Record a call abandoned mid-flight on an HTTP transport (stdio has no reply socket to leak)."""
        if is_stdio(self.url):
            return
        if self.posts.installed:
            self.posts.settle(slot, abandoned = True)
            return
        if self.abandoned_at is None:
            self.abandoned_at = time.monotonic()
        self.abandoned += 1

    def abandoned_overdue(self, now: Optional[float] = None) -> bool:
        """Whether still-open abandoned replies require closing the session rather than probing it."""
        now = time.monotonic() if now is None else now
        if self.posts.installed:
            pending = self.posts.pending()
            if pending is None:
                return False
            oldest, count = pending
        elif self.abandoned_at is None:
            return False
        else:
            oldest, count = self.abandoned_at, self.abandoned
        return count >= _MAX_ABANDONED_REPLIES or now - oldest >= _ABANDONED_REPLY_TIMEOUT

    def _run_loop(self) -> None:
        asyncio.set_event_loop(self.loop)
        try:
            self.loop.run_forever()
        finally:
            self.loop.close()

    def connect(self, timeout: Optional[float], cancel_event) -> None:
        async def _open():
            _SESSION_POSTS.set(self.posts)
            client = _client(self.url, self.headers)
            await client.__aenter__()
            # No await between: close() must see the client after a racing abort.
            self.client = client
            return client

        future = asyncio.run_coroutine_threadsafe(_open(), self.loop)
        # timeout=None is no connect deadline; else _connect_window() caps stdio at its cold-start limit.
        window = _connect_window(self.url, timeout)
        deadline = None if window is None else time.monotonic() + window
        while True:
            if cancel_event is not None and cancel_event.is_set():
                _abort_future(future)
                raise _MCPCancelled
            try:
                future.result(0.05)
                return
            except (concurrent.futures.TimeoutError, asyncio.TimeoutError):
                if future.done():
                    raise  # the connect itself failed fast; don't wait out the window
                if deadline is not None and time.monotonic() >= deadline:
                    _abort_future(future)
                    raise _ConnectTimeout(window)

    def is_connected(self) -> bool:
        client = self.client
        if client is None:
            return False
        probe = getattr(client, "is_connected", None)
        try:
            return bool(probe()) if callable(probe) else True
        except Exception:
            return False

    def run(
        self,
        coro,
        timeout: Optional[float],
        margin: float = _SESSION_WEDGE_MARGIN,
    ):
        self.last_used = time.monotonic()
        future = asyncio.run_coroutine_threadsafe(coro, self.loop)
        # Margin only catches a wedged loop; poll so a closed session can't hang forever.
        deadline = None if timeout is None else time.monotonic() + timeout + margin
        try:
            while True:
                try:
                    return future.result(0.25)
                except concurrent.futures.CancelledError:
                    # Only close() cancels in-flight tasks (in _shutdown).
                    raise _SessionClosed
                except (concurrent.futures.TimeoutError, asyncio.TimeoutError):
                    if future.done():
                        raise  # the call's own timeout; the session stays usable
                    if self.closed.is_set():
                        future.cancel()
                        raise _SessionClosed
                    if deadline is not None and time.monotonic() >= deadline:
                        future.cancel()
                        raise _SessionWedged
        finally:
            self.last_used = time.monotonic()

    def close(self) -> None:
        # Setting `closed` first also unblocks run() waiters (they poll it).
        with self._close_lock:
            if self.closed.is_set():
                return
            self.closed.set()
        loop = getattr(self, "loop", None)
        loop_alive = loop is not None and not loop.is_closed()
        if loop_alive:

            async def _shutdown() -> None:
                # On the loop thread, it serializes with an aborted connect() that finished.
                client, self.client = self.client, None
                if client is not None:
                    await client.__aexit__(None, None, None)
                # Cancel in-flight calls so they unwind before loop.stop; closed has already released run() waiters.
                for task in asyncio.all_tasks():
                    if task is not asyncio.current_task():
                        task.cancel()

            try:
                asyncio.run_coroutine_threadsafe(_shutdown(), loop).result(_SESSION_CLOSE_TIMEOUT)
            except Exception as exc:  # noqa: BLE001
                logger.warning(
                    "MCP session close failed for %s: %s",
                    _session_log_id(getattr(self, "url", "")),
                    exc,
                )
            try:
                loop.call_soon_threadsafe(loop.stop)
            except RuntimeError:
                pass
        else:
            self.client = None
        thread = getattr(self, "_thread", None)
        if thread is not None:
            thread.join(timeout = 5.0)


_mcp_sessions: dict[tuple, _McpSession] = {}


# Per-key locks so a slow connect/close never blocks unrelated servers; the global lock only guards the dicts.
class _McpKeyLock:
    """A per-key lock that can be removed once nobody references it."""

    def __init__(self) -> None:
        self.lock = threading.Lock()
        self.users = 0  # guarded by _mcp_sessions_lock


_mcp_key_locks: dict[tuple, _McpKeyLock] = {}
_mcp_sessions_lock = threading.Lock()
_mcp_reaper_started = False
# Sessions discarded while somebody else was mid-call, closed by one worker off the request path. See _close_detached.
_mcp_cleanup_lock = threading.Lock()
_mcp_cleanup_queue: list = []
# Depth past which an evicting caller closes the overflow itself. See _close_detached.
_MAX_PENDING_CLOSES = 8
# How wide close_mcp_sessions fans out. See _close_all.
_MAX_CLOSE_THREADS = 16
_mcp_cleanup_worker: Optional[threading.Thread] = None
# Bumped on every close so an in-flight connect discards its session instead of publishing it.
_mcp_close_all_gen = 0
_mcp_account_close_gen: dict[str, int] = {}
_mcp_url_close_gen: dict[str | tuple[str, str], int] = {}
_mcp_cfg_close_gen: dict[str | tuple[str, str], int] = {}
_mcp_connects_in_flight = 0

_ANY_HEADERS = object()


def _headers_key(headers: Optional[dict]) -> tuple:
    return tuple(sorted((headers or {}).items()))


def _url_close_key(url: str) -> str | tuple[str, str]:
    # Key by digest: commands/URLs/env may hold secrets and these maps are never pruned.
    return _account_key(hashlib.sha256(url.encode()).hexdigest())


def _cfg_close_key(url: str, headers: Optional[dict]) -> str | tuple[str, str]:
    return _account_key(hashlib.sha256(repr((url, _headers_key(headers))).encode()).hexdigest())


def _mcp_close_generation(url: str, headers: Optional[dict]) -> tuple[tuple[int, int], int, int]:
    return (
        (_mcp_close_all_gen, _mcp_account_close_gen.get(current_account_id(), 0)),
        _mcp_url_close_gen.get(_url_close_key(url), 0),
        _mcp_cfg_close_gen.get(_cfg_close_key(url, headers), 0),
    )


def _session_key(url: str, headers: Optional[dict], scope: Optional[str]) -> tuple:
    return (url, _headers_key(headers), scope or "", current_account_id())


def _checkout_session(key: tuple) -> tuple[Optional[_McpSession], float]:
    """Returns the idle gap, not stored on the session, since concurrent borrowers would overwrite it."""
    session = _mcp_sessions.get(key)
    if session is not None and session.is_connected():
        now = time.monotonic()
        idle_for = now - session.proved_at
        session.last_used = now
        session.in_flight += 1
        return session, idle_for
    return None, -1.0


def _borrow_key_lock(key: tuple) -> _McpKeyLock:
    """Return a stable per-key lock while a caller waits for/connects it."""
    key_lock = _mcp_key_locks.setdefault(key, _McpKeyLock())
    key_lock.users += 1
    return key_lock


def _discard_key_lock(key: tuple) -> None:
    key_lock = _mcp_key_locks.get(key)
    if key_lock is not None and key_lock.users == 0 and key not in _mcp_sessions:
        _mcp_key_locks.pop(key, None)


def _return_key_lock(key: tuple, key_lock: _McpKeyLock) -> None:
    with _mcp_sessions_lock:
        key_lock.users -= 1
        _discard_key_lock(key)


@contextmanager
def _connect_slot(url: str, headers: Optional[dict]):
    global _mcp_connects_in_flight
    with _mcp_sessions_lock:
        generation = _mcp_close_generation(url, headers)
        _mcp_connects_in_flight += 1
    try:
        yield generation
    finally:
        with _mcp_sessions_lock:
            _mcp_connects_in_flight -= 1


def _get_session(
    url: str,
    headers: Optional[dict],
    scope: Optional[str],
    deadline,
    cancel_event,
    config_check,
    use_oauth: bool = False,
) -> tuple[_McpSession, float]:
    """Key-lock wait and connect share one absolute deadline so slow startups cannot stack timeouts; only the borrower may act on its idle gap."""
    global _mcp_reaper_started
    key = _session_key(url, headers, scope)
    with _mcp_sessions_lock:
        session, idle_for = _checkout_session(key)
        if session is not None:
            return session, idle_for
        key_lock = _borrow_key_lock(key)
    try:
        # Poll so a same-scope call can be cancelled while queued behind a slow startup.
        remaining = None if deadline is None else max(0.0, deadline - time.monotonic())
        # Key-lock wait is bounded like the connect behind it, so HTTP is not cut off at the stdio cap.
        window = _connect_window(url, remaining)
        lock_deadline = None if window is None else time.monotonic() + window
        while not key_lock.lock.acquire(timeout = 0.05):
            if cancel_event is not None and cancel_event.is_set():
                raise _MCPCancelled
            if lock_deadline is not None and time.monotonic() >= lock_deadline:
                raise _ConnectTimeout(window)
        try:
            stale = None
            with _mcp_sessions_lock:
                session, idle_for = _checkout_session(key)
                if session is not None:
                    return session, idle_for
                if key in _mcp_sessions:
                    stale = _mcp_sessions.pop(key)
            if stale is not None:
                _retire_session(stale)
            with _connect_slot(url, headers) as generation:
                session = _McpSession(url, headers, use_oauth)
                try:
                    session.connect(
                        None if deadline is None else max(0.0, deadline - time.monotonic()),
                        cancel_event,
                    )
                except Exception:
                    session.close()
                    raise
                if config_check is not None:
                    try:
                        current = bool(config_check())
                    except Exception:  # noqa: BLE001
                        current = False
                    if not current:
                        session.close()
                        raise RuntimeError("MCP server was updated or removed while connecting")
                evicted: list = []
                with _mcp_sessions_lock:
                    closed_while_connecting = _mcp_close_generation(url, headers) != generation
                    if not closed_while_connecting:
                        session.in_flight = 1
                        evicted = _evict_lru_locked()  # bound the cache (LRU idle)
                        _mcp_sessions[key] = session
                        if not _mcp_reaper_started:
                            _mcp_reaper_started = True
                            threading.Thread(
                                target = _session_reaper, name = "mcp-session-reaper", daemon = True
                            ).start()
                            atexit.register(close_mcp_sessions, all_accounts = True)
                for victim in evicted:
                    logger.info("Evicting LRU idle MCP session: %s", _session_log_id(victim.url))
                if evicted:
                    # Detached: an unresponsive close would eat this caller's tool-call deadline.
                    _close_detached(evicted)
                if closed_while_connecting:
                    session.close()
                    raise RuntimeError("MCP server was updated or removed while connecting")
                return session, -1.0
        finally:
            key_lock.lock.release()
    finally:
        _return_key_lock(key, key_lock)


def _release_session(session: _McpSession, defer_close: bool = False) -> None:
    victims: list = []
    with _mcp_sessions_lock:
        session.in_flight = max(0, session.in_flight - 1)
        session.last_used = time.monotonic()
        close_now = session.defunct and session.in_flight == 0
        # Re-enforce the cap once a burst idles; never evict the session just used; the cap is per account, so a call never closes sessions of another account.
        account_id = getattr(session, "account_id", None) or current_account_id()
        mine = {
            k: s
            for k, s in _mcp_sessions.items()
            if (k[3] if len(k) > 3 else OWNER_ACCOUNT_ID) == account_id
        }
        while len(mine) > _MAX_SESSIONS:
            idle = [
                (s.last_used, k) for k, s in mine.items() if s.in_flight == 0 and s is not session
            ]
            if not idle:
                break
            _, oldest = min(idle, key = lambda item: item[0])
            victims.append(_mcp_sessions.pop(oldest))
            mine.pop(oldest)
            _discard_key_lock(oldest)
    if close_now and defer_close:
        # Close off the request path: a discarded transport's close runs long.
        victims.append(session)
    elif close_now:
        session.close()
    if victims:
        _close_detached(victims)


def _retire_session(session: _McpSession) -> None:
    """Close a discarded session, but only once no other borrower is mid-call on it: overlapping
    same-scope calls share one client, and one call's timeout must not kill another's in-flight
    request. The last borrower's _release_session() performs the deferred close."""
    with _mcp_sessions_lock:
        session.defunct = True
        busy = session.in_flight > 0
    if not busy:
        session.close()


def _drop_session(key: tuple, session: _McpSession) -> None:
    with _mcp_sessions_lock:
        if _mcp_sessions.get(key) is session:
            _mcp_sessions.pop(key)
        _discard_key_lock(key)
    _retire_session(session)


def _evict_lru_locked() -> list:
    """Caller holds _mcp_sessions_lock; returns idle LRU victims to close outside it; if every
    session is busy the cache may overshoot the cap rather than kill an in-flight call"""
    victims: list = []
    if len(_mcp_sessions) < _MAX_SESSIONS:
        return victims
    account_id = current_account_id()
    candidates = {
        key: session
        for key, session in _mcp_sessions.items()
        if (key[3] if len(key) > 3 else OWNER_ACCOUNT_ID) == account_id
    }
    while len(candidates) >= _MAX_SESSIONS:
        idle = [(s.last_used, k) for k, s in candidates.items() if s.in_flight == 0]
        if not idle:
            break
        _, oldest = min(idle, key = lambda item: item[0])
        victims.append(_mcp_sessions.pop(oldest))
        candidates.pop(oldest)
        _discard_key_lock(oldest)
    return victims


def close_mcp_sessions(
    url: Optional[str] = None,
    headers = _ANY_HEADERS,
    *,
    all_accounts: bool = False,
) -> None:
    global _mcp_close_all_gen
    hk = None if headers is _ANY_HEADERS else _headers_key(headers)
    account_id = current_account_id()
    with _mcp_sessions_lock:
        keys = [
            k
            for k in _mcp_sessions
            if (url is None or k[0] == url)
            and (hk is None or k[1] == hk)
            and (all_accounts or (k[3] if len(k) > 3 else OWNER_ACCOUNT_ID) == account_id)
        ]
        sessions = [_mcp_sessions.pop(k) for k in keys]
        for key in keys:
            _discard_key_lock(key)
        if sessions or _mcp_connects_in_flight:
            if url is None:
                if all_accounts:
                    _mcp_close_all_gen += 1
                else:
                    _mcp_account_close_gen[account_id] = (
                        _mcp_account_close_gen.get(account_id, 0) + 1
                    )
            elif hk is None:
                uk = _url_close_key(url)
                _mcp_url_close_gen[uk] = _mcp_url_close_gen.get(uk, 0) + 1
            else:
                cfg = _cfg_close_key(url, headers)
                _mcp_cfg_close_gen[cfg] = _mcp_cfg_close_gen.get(cfg, 0) + 1
    pending, worker = _drain_cleanup_queue()
    _close_all(sessions + pending)
    if worker is not None and worker is not threading.current_thread():
        # Draining does not recall a popped session, so the join waits for that one close and no longer.
        worker.join(_SESSION_CLOSE_TIMEOUT + 5.0)


def _close_all(sessions: list) -> None:
    """Closes at most _MAX_CLOSE_THREADS at once; serial closes could stall a request for minutes."""
    if not sessions:
        return
    if len(sessions) == 1:
        sessions[0].close()
        return

    pending = list(sessions)
    pending_lock = threading.Lock()

    def _drain() -> None:
        while True:
            with pending_lock:
                if not pending:
                    return
                session = pending.pop()
            _close_quietly(session)

    # Bare threads: executors are shut down before atexit callbacks, so submitting there raises.
    width = min(len(pending), _MAX_CLOSE_THREADS)
    threads = [threading.Thread(target = _drain, name = "mcp-close", daemon = True) for _ in range(width)]
    for thread in threads:
        thread.start()
    # Each worker closes several sessions in turn, so the join budget scales with the rounds.
    rounds = -(-len(sessions) // width)
    for thread in threads:
        thread.join(rounds * (_SESSION_CLOSE_TIMEOUT + 5.0))


def _close_detached(sessions: list) -> None:
    """One worker, not a thread per session, so closes cannot spawn unbounded threads; past _MAX_PENDING_CLOSES the caller closes the overflow as backpressure."""
    global _mcp_cleanup_worker
    if not sessions:
        return
    with _mcp_cleanup_lock:
        room = max(0, _MAX_PENDING_CLOSES - len(_mcp_cleanup_queue))
        _mcp_cleanup_queue.extend(sessions[:room])
        overflow = sessions[room:]
        if _mcp_cleanup_queue and _mcp_cleanup_worker is None:
            _mcp_cleanup_worker = threading.Thread(
                target = _cleanup_worker, name = "mcp-cleanup", daemon = True
            )
            _mcp_cleanup_worker.start()
    _close_all(overflow)


def _cleanup_worker() -> None:
    global _mcp_cleanup_worker
    while True:
        with _mcp_cleanup_lock:
            if not _mcp_cleanup_queue:
                _mcp_cleanup_worker = None  # _close_detached starts the next one
                return
            session = _mcp_cleanup_queue.pop(0)
        _close_quietly(session)


def _drain_cleanup_queue() -> tuple[list, Optional[threading.Thread]]:
    """Takes back unstarted cleanups and the worker so a caller can wait out the active close."""
    with _mcp_cleanup_lock:
        pending = list(_mcp_cleanup_queue)
        _mcp_cleanup_queue.clear()
        return pending, _mcp_cleanup_worker


def _close_quietly(session) -> None:
    try:
        session.close()
    except Exception:  # noqa: BLE001
        logger.exception("Closing a discarded MCP session failed")


# Legacy alias kept for callers of the old name.
close_stdio_sessions = close_mcp_sessions


def _reset_after_fork() -> None:
    """Only the forking thread survives a fork, so inherited session loops are dead; close nothing."""
    global _mcp_reaper_started, _mcp_connects_in_flight, _mcp_sessions_lock
    global _mcp_cleanup_lock, _mcp_cleanup_worker
    # Replaced: a lock held at fork belongs to a thread that does not exist in the child.
    _mcp_sessions_lock = threading.Lock()
    _mcp_sessions.clear()
    _mcp_key_locks.clear()
    _mcp_connects_in_flight = 0
    _mcp_reaper_started = False
    # The cleanup worker did not survive the fork either, and its queue holds the parent's sessions.
    _mcp_cleanup_lock = threading.Lock()
    _mcp_cleanup_queue.clear()
    _mcp_cleanup_worker = None


if hasattr(os, "register_at_fork"):
    os.register_at_fork(after_in_child = _reset_after_fork)


def _reap_idle_sessions(now: Optional[float] = None) -> None:
    now = time.monotonic() if now is None else now
    with _mcp_sessions_lock:
        expired = [
            key
            for key, session in _mcp_sessions.items()
            if session.in_flight == 0
            and (now - session.last_used >= _SESSION_IDLE_TTL or session.abandoned_overdue(now))
        ]
        sessions = [_mcp_sessions.pop(key) for key in expired]
        for key in expired:
            _discard_key_lock(key)
    for session in sessions:
        logger.info("Closing idle MCP session: %s", _session_log_id(session.url))
        session.close()


def _session_reaper() -> None:
    while True:
        time.sleep(_SESSION_REAP_INTERVAL)
        try:
            _reap_idle_sessions()
        except Exception as exc:  # noqa: BLE001
            logger.debug("MCP session reaper iteration failed: %s", exc)


MCP_RESOURCE_TOOL = "read_resource"
MAX_MCP_RESOURCES = 200


class McpToolList(list):
    """Tools plus the resources listed on the same connection."""

    resources: Optional[list[dict]] = None


def _capabilities(client) -> Any:
    # initialize_result stays None on a modern connection, which has no initialize handshake.
    return getattr(client, "server_capabilities", None)


async def _list_resources(client) -> Optional[list[dict]]:
    capabilities = _capabilities(client)
    if capabilities is not None and getattr(capabilities, "resources", None) is None:
        return None
    listed, cursors = [], set()
    cursor = None
    try:
        while len(listed) < MAX_MCP_RESOURCES:
            page = await client.list_resources_mcp(cursor = cursor)
            listed.extend(getattr(page, "resources", None) or ())
            cursor = getattr(page, "next_cursor", None)
            # A repeated cursor would loop forever.
            if not cursor or cursor in cursors:
                break
            cursors.add(cursor)
    except Exception as exc:  # noqa: BLE001 - resources are optional, the tools still load
        logger.debug("MCP resources/list failed: %s", exc)
        if not listed:
            return None
    resources = []
    for resource in listed:
        uri = str(getattr(resource, "uri", "") or "")
        # MCP Apps templates are for the host's widgets, not the model.
        if not uri or uri.startswith(UI_RESOURCE_SCHEME):
            continue
        audience = getattr(getattr(resource, "annotations", None), "audience", None)
        if audience and "assistant" not in audience:
            continue
        fields = {
            "name": getattr(resource, "name", None),
            "description": getattr(resource, "description", None),
            "mimeType": _resource_mime(resource),
        }
        resources.append(
            {"uri": uri, **{k: v for k, v in fields.items() if isinstance(v, str) and v}}
        )
    return resources[:MAX_MCP_RESOURCES] or None


async def list_tools_async(
    url: str,
    headers: Optional[dict] = None,
    timeout: float = 5.0,
    use_oauth: bool = False,
    **oauth,
) -> list[dict]:
    listed: list = []

    async def _fetch() -> list[dict]:
        async with _client(url, headers, use_oauth, **oauth) as client:
            try:
                raw_tools = await client.list_tools()
            except Exception:
                # A resource-only server need not answer tools/list.
                capabilities = _capabilities(client)
                if (
                    capabilities is None
                    or getattr(capabilities, "tools", None) is not None
                    or getattr(capabilities, "resources", None) is None
                ):
                    raise
                raw_tools = []
            tools = McpToolList(t.model_dump(exclude_none = True) for t in raw_tools)
            listed.append(tools)
            tools.resources = await _list_resources(client)
        return tools

    try:
        return await asyncio.wait_for(_fetch(), timeout = timeout)
    except asyncio.TimeoutError:
        # A slow resources/list must not cost the server its tools.
        if listed:
            return listed[0]
        raise


# Probe only on cache miss, off the chat send's critical path. Successful probes cached forever.
_tool_cache: dict[str | tuple[str, str], list[dict]] = {}

# Failed server's re-probe cooloff (monotonic time); cleared on a good probe or eviction.
_probe_cooloff_until: dict[str | tuple[str, str], float] = {}

# Coordinate off-loop token-count snapshots with row and schema-cache mutations.
_mcp_server_snapshot_locks: WeakKeyDictionary[asyncio.AbstractEventLoop, asyncio.Lock] = (
    WeakKeyDictionary()
)


def mcp_server_snapshot_guard() -> asyncio.Lock:
    loop = asyncio.get_running_loop()
    return _mcp_server_snapshot_locks.setdefault(loop, asyncio.Lock())


def serialize_mcp_server_mutation(handler):
    """Run an MCP mutation from validation through row/cache commit as one snapshot."""

    @wraps(handler)
    async def _serialized(*args, **kwargs):
        async with mcp_server_snapshot_guard():
            return await handler(*args, **kwargs)

    return _serialized


# Shared by the update route's eviction and the mid-probe guard so they can't drift.
TOOL_CACHE_INVALIDATING_FIELDS = frozenset(
    {"url", "headers_json", "use_oauth", "oauth_client_id", "oauth_client_secret", "is_enabled"}
)


def get_cached_tools(server_id: str) -> Optional[list[dict]]:
    return _tool_cache.get(_account_key(server_id))


def get_cached_resources(server_id: str) -> Optional[list[dict]]:
    return getattr(_tool_cache.get(_account_key(server_id)), "resources", None)


def cache_tools(server_id: str, tools: list[dict]) -> None:
    _tool_cache[_account_key(server_id)] = tools
    _probe_cooloff_until.pop(_account_key(server_id), None)


def record_probe_failure(server_id: str, use_oauth: bool = False) -> None:
    cooloff = OAUTH_FAILED_PROBE_COOLOFF_SECONDS if use_oauth else FAILED_PROBE_COOLOFF_SECONDS
    _probe_cooloff_until[_account_key(server_id)] = time.monotonic() + cooloff


def in_failure_cooloff(server_id: str) -> bool:
    return _probe_cooloff_until.get(_account_key(server_id), 0.0) > time.monotonic()


def invalidate_tool_cache(server_id: Optional[str] = None) -> None:
    """Evict one server's cached tools, or every entry when server_id is None."""
    if server_id is None:
        account_id = current_account_id()
        for cache in (_tool_cache, _probe_cooloff_until):
            for key in list(cache):
                owner = key[0] if isinstance(key, tuple) else OWNER_ACCOUNT_ID
                if owner == account_id:
                    cache.pop(key, None)
    else:
        _tool_cache.pop(_account_key(server_id), None)
        _probe_cooloff_until.pop(_account_key(server_id), None)


UI_RESOURCE_SCHEME = "ui://"
MAX_UI_RESOURCE_CHARS = 5_000_000


def _ui_meta_field(tool: Any, field: str):
    """`ui.<field>`, else the flat `ui/<field>`, from the SDK's `meta` or the wire `_meta`."""
    metas = [tool.get(k) for k in ("meta", "_meta")] if isinstance(tool, dict) else []
    metas = [m for m in metas if isinstance(m, dict)]
    for ui in (m.get("ui") for m in metas):
        if isinstance(ui, dict) and ui.get(field) is not None:
            return ui[field]
    return next((m[f"ui/{field}"] for m in metas if m.get(f"ui/{field}") is not None), None)


def tool_ui_resource_uri(tool: Any) -> Optional[str]:
    """Only ui:// is honoured: the host fetches this URI."""
    uri = _ui_meta_field(tool, "resourceUri")
    uri = uri.strip() if isinstance(uri, str) else ""
    return (
        uri if uri.startswith(UI_RESOURCE_SCHEME) and len(uri) > len(UI_RESOURCE_SCHEME) else None
    )


def tool_visible_to(tool: Any, audience: str) -> bool:
    """`audience` is "model" or "app"; an undeclared visibility means both."""
    visibility = _ui_meta_field(tool, "visibility")
    return audience in visibility if isinstance(visibility, (list, tuple)) else True


MCP_IMAGES_SENTINEL = mcp_images.SENTINEL
MAX_IMAGE_PAYLOAD_CHARS = 12_000_000

# Emitted BEFORE the image envelope, whose parse reads to end of string.
MCP_UI_SENTINEL = "__MCP_UI__:"
MAX_UI_STRUCTURED_CHARS = 1_000_000


def _json_within(value: Any, limit: int) -> Optional[str]:
    try:
        line = json.dumps(value)
    except (TypeError, ValueError, RecursionError):
        return None
    return line if len(line) <= limit else None


def _ui_envelope(result: Any, ui_resource_uri: str, seed: list) -> str:
    payload: dict = {"resourceUri": ui_resource_uri}
    meta = getattr(result, "meta", None)
    if isinstance(meta, dict) and meta:
        payload["_meta"] = meta
    structured = getattr(result, "structured_content", None)
    if structured is not None:
        payload["structuredContent"] = structured
    if seed:
        payload["content"] = [
            _seeded_image_block(b, m) if m else _content_block_json(b) for b, m in seed
        ]
    line = _json_within(payload, MAX_UI_STRUCTURED_CHARS)
    if line is None:
        # Shed structuredContent, then content, then _meta: the view still gets its template.
        reduced = {"resourceUri": ui_resource_uri, "structuredContentOmitted": True}
        keys = [k for k in ("content", "_meta") if k in payload]
        for kept in (keys, keys[:1], keys[1:]):
            line = _json_within(
                {**reduced, **{k: payload[k] for k in kept}}, MAX_UI_STRUCTURED_CHARS
            )
            if line:
                break
        else:
            line = json.dumps(reduced)
    return "\n" + MCP_UI_SENTINEL + line


def _is_ui_envelope_line(line: str) -> bool:
    if not line.startswith(MCP_UI_SENTINEL):
        return False
    try:
        payload = json.loads(line[len(MCP_UI_SENTINEL) :])
    except (ValueError, RecursionError):
        return False
    return isinstance(payload, dict) and isinstance(payload.get("resourceUri"), str)


def _drop_forged_ui_sentinels(body: str) -> str:
    """Readers take the last marker, so a tool-written one could summon a widget with forged seed text."""
    if MCP_UI_SENTINEL not in body:
        return body
    return "\n".join(line for line in body.split("\n") if not _is_ui_envelope_line(line))


def _block_text(block: Any) -> Optional[str]:
    text = getattr(block, "text", None)
    if text:
        return str(text)
    resource = getattr(block, "resource", None)
    if resource is not None:
        text = getattr(resource, "text", None)
        return str(text) if text else None
    return None


def _block_link(block: Any) -> Optional[str]:
    # keep host-generated link text from suppressing structured_content
    uri = getattr(block, "uri", None)
    if uri and getattr(block, "type", None) == "resource_link":
        name = getattr(block, "name", None)
        return f"[resource: {name} <{uri}>]" if name else f"[resource: <{uri}>]"
    return None


# fastmcp File(data=..., format=...) labels payloads as application/<format>
_IMAGE_SUBTYPES = {
    "apng": "image/apng",
    "png": "image/png",
    "jpeg": "image/jpeg",
    "jpg": "image/jpeg",
    "gif": "image/gif",
    "webp": "image/webp",
    "bmp": "image/bmp",
    "avif": "image/avif",
    "tif": "image/tiff",
    "tiff": "image/tiff",
    "ico": "image/vnd.microsoft.icon",
    "svg": "image/svg+xml",
    "svg+xml": "image/svg+xml",
}


# Interpolated into data: URLs by tool-fallback.tsx; RFC 9110 token subtype, minus '*'.
_MEDIA_TYPE = re.compile(r"^image/[a-z0-9][a-z0-9!#$%&'^_`|~.+-]*$")


def _uri_mime(uri: Any) -> Optional[str]:
    """Drops query and fragment so every Python guesses the same type; the scheme stays for data: URIs."""
    split = urlsplit(str(uri))
    cleaned = urlunsplit((split.scheme, split.netloc if split.path else "", split.path, "", ""))
    return mimetypes.guess_type(cleaned, strict = False)[0]


def _image_mime(mime: Any) -> Optional[str]:
    if not isinstance(mime, str):
        return None
    # media type names are case-insensitive; data urls need only the essence
    essence = mime.partition(";")[0].strip().lower()
    if essence.startswith("image/"):
        resolved = essence
    else:
        subtype = essence[len("application/") :] if essence.startswith("application/") else ""
        resolved = _IMAGE_SUBTYPES.get(subtype) or _uri_mime(f"file:///image.{subtype}")
    # Windows registry returns image/JXL, so lowercase again.
    resolved = resolved.lower() if resolved else ""
    return resolved if _MEDIA_TYPE.match(resolved) else None


def _resource_mime(obj: Any) -> Any:
    # mcp 2.x exposes mime_type; mimeType is only a constructor alias there
    return obj.mime_type if hasattr(obj, "mime_type") else getattr(obj, "mimeType", None)


def _block_image(block: Any) -> Optional[tuple[str, str]]:
    # embedded resources keep binary data on resource.blob
    data = getattr(block, "data", None)
    mime = _resource_mime(block)
    if not data:
        resource = getattr(block, "resource", None)
        if resource is None:
            return None
        data = getattr(resource, "blob", None)
        mime = _resource_mime(resource)
        if not mime:
            uri = getattr(resource, "uri", None)
            mime = _uri_mime(uri) if uri else None
    mime = _image_mime(mime)
    if data and mime:
        return str(data), mime
    return None


def _block_attachment(block: Any) -> Optional[tuple[str, str]]:
    # presence, not truthiness: a zero-byte file arrives as ""
    data = getattr(block, "data", None)
    if data is not None:
        kind = getattr(block, "type", "binary")
        mime = _resource_mime(block)
        uri = None
    else:
        resource = getattr(block, "resource", None)
        data = getattr(resource, "blob", None) if resource is not None else None
        if data is None:
            return None
        kind = "file"
        mime = _resource_mime(resource)
        uri = getattr(resource, "uri", None)
    label = f"{kind} attachment"
    if mime:
        label += f" ({mime})"
    if uri and not str(uri).lower().startswith("data:"):
        label += f" <{uri}>"
    return f"{label} not shown to the model", str(data)


_MIRRORED = object()
# fields MCP defines on image/audio and embedded resource blocks; anything else is the tool's own
_MEDIA_FIELDS = frozenset({"type", "data", "mimeType", "mime_type", "annotations", "_meta"})
_RESOURCE_BLOCK_FIELDS = frozenset({"type", "resource", "annotations", "_meta"})
_RESOURCE_FIELDS = frozenset({"uri", "blob", "mimeType", "mime_type", "_meta"})


def _is_payload(value: Any, payloads: set[str]) -> bool:
    return isinstance(value, str) and value in payloads


def _mirrored_extras(value: dict, payloads: set[str]) -> Optional[dict]:
    # the tool's own fields on a content block copied from result.content; None if it is not one
    kind = value.get("type")
    if kind in ("image", "audio") and _is_payload(value.get("data"), payloads):
        return {k: v for k, v in value.items() if k not in _MEDIA_FIELDS}
    resource = value.get("resource")
    if (
        kind == "resource"
        and isinstance(resource, dict)
        and _is_payload(resource.get("blob"), payloads)
    ):
        extras = {k: v for k, v in value.items() if k not in _RESOURCE_BLOCK_FIELDS}
        inner = {k: v for k, v in resource.items() if k not in _RESOURCE_FIELDS}
        if inner:
            extras["resource"] = inner
        return extras
    return None


def _strip_payloads(value: Any, payloads: set[str]) -> Any:
    # drop mirrored payloads and the MCP fields of the blocks carrying them, then containers left empty
    if isinstance(value, str):
        return _MIRRORED if value in payloads else value
    if isinstance(value, dict):
        extras = _mirrored_extras(value, payloads)
        if extras is not None:
            if not extras:
                return _MIRRORED
            value = extras
        kept = {}
        for key, item in value.items():
            item = _strip_payloads(item, payloads)
            if item is not _MIRRORED:
                kept[key] = item
    elif isinstance(value, (list, tuple)):
        kept = [
            s for s in (_strip_payloads(item, payloads) for item in value) if s is not _MIRRORED
        ]
    else:
        return value
    return _MIRRORED if value and not kept else kept


# The frontend refills bytes positionally: `data` on an image block, `resource.blob` on an embedded one.
def _seeded_image_block(block: Any, mime: str) -> dict:
    out = {k: v for k, v in _content_block_json(block).items() if k != "data"}
    if isinstance(out.get("resource"), dict):
        out["resource"] = {k: v for k, v in out["resource"].items() if k != "blob"}
        return out
    return {**out, "type": "image", "mimeType": mime}


def _flatten_result(result: Any, ui_resource_uri: Optional[str] = None) -> str:
    parts = []
    images = []
    seed = []
    unshown = []
    payloads = set()
    omitted = 0
    has_text = False
    budget = MAX_IMAGE_PAYLOAD_CHARS
    for block in getattr(result, "content", None) or []:
        text = _block_text(block)
        if text:
            parts.append(text)
            has_text = True
            seed.append((block, None))
            continue
        link = _block_link(block)
        if link:
            parts.append(link)
            seed.append((block, None))
            continue
        image = _block_image(block)
        if image is not None:
            data, mime = image
            payloads.add(data)
            if len(data) > budget:
                omitted += 1
                continue
            budget -= len(data)
            images.append({"data": data, "mimeType": mime})
            seed.append((block, mime))
            continue
        seed.append((block, None))
        attachment = _block_attachment(block)
        if attachment is not None:
            note, data = attachment
            unshown.append(note)
            if data:
                payloads.add(data)
    body = "\n".join(parts)
    # the filesystem server mirrors binary blocks in structured_content; keep everything else
    structured = None if has_text else getattr(result, "structured_content", None)
    if structured is not None and payloads:
        structured = _strip_payloads(structured, payloads)
    if structured is not None and structured is not _MIRRORED:
        body = f"{structured}\n{body}" if body else str(structured)
    if images or omitted or unshown:
        notes = []
        if images:
            n = len(images)
            notes.append(f"{n} image{'s' if n > 1 else ''} returned")
        if omitted:
            notes.append(f"{omitted} image{'s' if omitted > 1 else ''} omitted (too large)")
        notes.extend(unshown)
        note = f"[{'; '.join(notes)}]"
        body = f"{body}\n{note}" if body else note

    if getattr(result, "is_error", False):
        # "Error: " prefix triggers tool_call_parser's TOOL_ERROR_PREFIXES nudge.
        body = f"Error: {body}" if body else "Error: tool returned no content"
    body = _drop_forged_ui_sentinels(body)
    if ui_resource_uri and not getattr(result, "is_error", False):
        body += _ui_envelope(result, ui_resource_uri, seed)
    if images:
        body += "\n" + MCP_IMAGES_SENTINEL + json.dumps(images)
    return body


def _unwind_budget(unwind_timeout: float, timeout: Optional[float], elapsed: float) -> float:
    """A cancelled call's unwind wait is the caller's leftover window, never past a deadline."""
    if not unwind_timeout:
        return 0.0
    if timeout is None:
        return unwind_timeout
    return min(unwind_timeout, max(0.0, timeout - elapsed))


async def _race_tool_call(
    call_coro,
    timeout: Optional[float],
    cancel_event,
    unwind_timeout: float = 0.0,
) -> Any:
    """Polls cancel_event alongside the call, so a /cancel interrupts a read already in flight."""

    async def _watch_cancel() -> None:
        while cancel_event is not None and not cancel_event.is_set():
            await asyncio.sleep(0.05)

    if cancel_event is not None and cancel_event.is_set():
        call_coro.close()
        raise _MCPCancelled
    started = time.monotonic()
    call_task = asyncio.create_task(call_coro)
    if cancel_event is None:
        return await asyncio.wait_for(call_task, timeout = timeout)
    watch_task = asyncio.create_task(_watch_cancel())
    try:
        done, pending = await asyncio.wait(
            {call_task, watch_task},
            timeout = timeout,
            return_when = asyncio.FIRST_COMPLETED,
        )
    finally:
        for t in (call_task, watch_task):
            if not t.done():
                t.cancel()
        # Cancelled calls unwind within the caller's remaining budget, or the session is left dirty.
        left = _unwind_budget(unwind_timeout, timeout, time.monotonic() - started)
        if left:
            await asyncio.wait({call_task, watch_task}, timeout = left)
    if not done:
        raise asyncio.TimeoutError
    if call_task in done:
        return call_task.result()
    raise _MCPCancelled


async def _enqueued(tracker: _PostTracker, slot: _PostSlot, call) -> Any:
    tracker.enqueue(slot)
    return await call


def _call_session_tool(
    url: str,
    headers: Optional[dict],
    name: str,
    args: dict,
    timeout,
    cancel_event,
    scope: Optional[str],
    config_check,
    use_oauth: bool = False,
    dispatch = None,
    rpc: Optional[tuple] = None,
) -> Any:
    if cancel_event is not None and cancel_event.is_set():
        raise _MCPCancelled
    if dispatch is None:
        rpc = ("tools/call", name)
    # One deadline covers the key-lock wait, connect, call-lock wait, and the call itself, matching the one-shot path
    # where the caller's timeout wrapped connect plus call in a single window.
    deadline = None if timeout is None else time.monotonic() + timeout

    def _remaining() -> Optional[float]:
        return None if deadline is None else max(0.0, deadline - time.monotonic())

    # No session id: use an ephemeral key so no state leaks across requests.
    def _config_ok() -> bool:
        if config_check is None:
            return True
        try:
            return bool(config_check())
        except Exception:  # noqa: BLE001
            return False

    ephemeral = not scope
    if ephemeral:
        scope = f"request-{uuid.uuid4().hex}"
    key = _session_key(url, headers, scope)
    # Attempt 0 may reconnect once if the cached session died before dispatch; attempt 1 is fresh.
    for attempt in (0, 1):
        session, idle_for = _get_session(
            url, headers, scope, deadline, cancel_event, config_check, use_oauth
        )
        locked = False
        try:
            # Serialize stdio (stateful byte stream); HTTP multiplexes by request id.
            if session.serialize_calls:
                while not session.call_lock.acquire(timeout = 0.05):
                    if cancel_event is not None and cancel_event.is_set():
                        raise _MCPCancelled
                    rem = _remaining()
                    if rem is not None and rem <= 0:
                        raise asyncio.TimeoutError
                locked = True
        except BaseException:
            # Never touched the transport: keep the session for its borrower.
            _release_session(session)
            if ephemeral:
                _drop_session(key, session)
            raise
        discard_session = ephemeral
        slot = None
        retry = False
        try:
            # Re-check after waiting on the call lock: session may be retired, invalidated or dead.
            if session.closed.is_set():
                # Intentional close (server update/delete/shutdown): don't retry on stale config.
                discard_session = True
                raise RuntimeError("MCP server was updated or removed during the call")
            elif session.defunct:
                # A same-scope timeout retired this session; switch to a fresh one rather than reuse it.
                discard_session = True
                if attempt == 0:
                    retry = True
                else:
                    raise RuntimeError("MCP server session was retired during the call")
            elif not _config_ok():
                discard_session = True
                raise RuntimeError("MCP server was updated or removed during the call")
            elif _transport_dead(session):
                # Dead BEFORE dispatch: no request was sent, so reconnect + retry.
                discard_session = True
                if attempt == 0:
                    retry = True
                else:
                    raise RuntimeError("MCP server connection is not available")
            elif session.abandoned_overdue():
                # A probe would prove the server is up, not that the abandoned POSTs closed.
                discard_session = True
                if attempt == 0:
                    retry = True
                else:
                    raise RuntimeError("MCP server session was retired during the call")
            elif (
                session.dirty or _needs_idle_recheck(session, idle_for, _remaining())
            ) and not _session_responsive(
                session, _remaining(), cancel_event, timeout_is_fatal = session.dirty
            ):
                # Dirty or idle-HTTP sessions may be dead; reconnect BEFORE dispatch.
                discard_session = True
                if attempt == 0:
                    retry = True
                else:
                    raise RuntimeError("MCP server is not responding")
            else:
                rem = _remaining()
                slot = _PostSlot(rpc)
                # raise_on_error=False for the same reason as the one-shot path.
                coro = _race_tool_call(
                    _enqueued(
                        session.posts,
                        slot,
                        dispatch(session.client)
                        if dispatch is not None
                        else session.client.call_tool(name, args, raise_on_error = False),
                    ),
                    rem,
                    cancel_event,
                    # Only a cached session is worth waiting on.
                    0.0 if ephemeral else _CANCEL_UNWIND_TIMEOUT,
                )
                out = session.run(coro, rem)
                # A completed round trip proves the transport better than a probe, so it resets the idle clock.
                session.proved_at = time.monotonic()
                return out
        except (_MCPCancelled, asyncio.TimeoutError):
            # Keep the session so Stop doesn't destroy server state; reuse is gated on a live probe.
            session.dirty = True
            if not ephemeral and slot is not None:
                session.note_abandoned(slot)
            raise
        except _SessionWedged:
            discard_session = True
            raise asyncio.TimeoutError
        except _SessionClosed:
            # close_mcp_sessions() shut this session mid-call, so do not retry against the stale config.
            discard_session = True
            raise RuntimeError("MCP server was updated or removed during the call")
        except Exception as exc:
            if session.closed.is_set():
                # Intentional close may look like a transport error or AttributeError; do not treat as crash
                discard_session = True
                raise RuntimeError("MCP server was updated or removed during the call")
            if _is_session_terminated(exc):
                # A 404 means the server never processed the request, so reconnect and replay once.
                discard_session = True
                retry = attempt == 0
            # Protocol error = server alive, keep session. Transport error: evict but DO NOT replay.
            elif _is_protocol_error(exc):
                # A protocol error means the server replied, so keep the session but probe it before the next call.
                session.dirty = True
            elif not _is_tool_error(exc):
                discard_session = True
            if not retry:
                raise
        finally:
            if slot is not None:
                session.posts.settle(slot, abandoned = False)
            # Drop the broken session from the cache before its borrow is released, so no caller
            # reuses it.
            if discard_session:
                _drop_session(key, session)
            _release_session(session, defer_close = not ephemeral)
            if locked:
                session.call_lock.release()
        if not retry:
            break
    raise RuntimeError("unreachable")


def call_tool_sync(
    url: str,
    headers: Optional[dict],
    name: str,
    args: dict,
    timeout: Optional[float] = 300.0,
    use_oauth: bool = False,
    cancel_event = None,
    scope: Optional[str] = None,
    config_check = None,
    ui_resource_uri: Optional[str] = None,
    **oauth,
) -> str:
    """Never raises: failures return as Error strings; OAuth or scope-less HTTP connects once per call."""

    if is_studio_tools(url):
        if config_check is not None and not config_check():
            return f"Error: MCP tool '{name}' failed: MCP server was updated or removed"
        from core.inference import studio_tools_mcp
        return studio_tools_mcp.call(
            name,
            args,
            timeout = timeout,
            cancel_event = cancel_event,
            ui_resource_uri = ui_resource_uri,
            config_check = config_check,
        )

    async def _one_shot() -> Any:
        async with _client(url, headers, use_oauth, **oauth) as client:
            # Connecting (OAuth included) can outlast an edit or delete of the server row.
            if config_check is not None and not config_check():
                raise RuntimeError("MCP server was updated or removed while connecting")
            # raise_on_error=False so an is_error result keeps its image content.
            return await client.call_tool(name, args, raise_on_error = False)

    try:
        if is_stdio(url) or (scope and not use_oauth):
            result = _call_session_tool(
                url, headers, name, args, timeout, cancel_event, scope, config_check, use_oauth
            )
        else:
            result = asyncio.run(_race_tool_call(_one_shot(), timeout, cancel_event))
    except _MCPCancelled:
        return f"Error: MCP tool '{name}' cancelled"
    except _ConnectTimeout as exc:
        # Report the window that expired: for stdio the cold-start cap, not the larger caller timeout.
        suffix = f" after {round(exc.window, 1):g}s" if exc.window is not None else ""
        return f"Error: MCP tool '{name}' timed out connecting{suffix}"
    except asyncio.TimeoutError:
        suffix = f" after {timeout:g}s" if timeout is not None else ""
        return f"Error: MCP tool '{name}' timed out{suffix}"
    except Exception as exc:
        logger.exception("MCP call_tool failed for %s: %s", name, exc)
        return f"Error: MCP tool '{name}' failed: {exc}"

    return _flatten_result(result, ui_resource_uri)


MAX_UI_TOOL_RESULT_CHARS = 4_000_000


def _content_block_json(block: Any) -> dict:
    dump = getattr(block, "model_dump", None)
    if callable(dump):
        try:
            # by_alias, or the SDK's `meta` reaches the widget instead of `_meta`.
            return dump(mode = "json", exclude_none = True, by_alias = True)
        except Exception:  # noqa: BLE001
            pass
    out = {"type": getattr(block, "type", "text")}
    for field in ("text", "data", "mimeType", "uri", "name"):
        value = getattr(block, field, None)
        if value is not None:
            out[field] = value if isinstance(value, (str, int, float, bool)) else str(value)
    return out


def _structured_result(result: Any) -> dict:
    out: dict = {
        "content": [_content_block_json(b) for b in getattr(result, "content", None) or []],
        "is_error": bool(getattr(result, "is_error", False)),
    }
    if getattr(result, "structured_content", None) is not None:
        out["structured_content"] = result.structured_content
    meta = getattr(result, "meta", None)
    if isinstance(meta, dict) and meta:
        out["meta"] = meta
    if _json_within(out, MAX_UI_TOOL_RESULT_CHARS) is None:
        raise ValueError(
            f"tool result is not JSON-serialisable or over {MAX_UI_TOOL_RESULT_CHARS} chars"
        )
    return out


def _ui_request_sync(
    url,
    headers,
    label,
    dispatch,
    *,
    timeout,
    use_oauth = False,
    cancel_event = None,
    scope = None,
    config_check = None,
    rpc = None,
    **oauth,
) -> Any:
    """``dispatch(client)`` on the transport call_tool_sync picks for this scope; ``rpc`` = (method, name or URI)."""

    async def _one_shot() -> Any:
        # As the session branch: an edit during discovery must not reach the old endpoint.
        if config_check is not None and not config_check():
            raise RuntimeError("MCP server was updated or removed during the call")
        async with _client(url, headers, use_oauth, **oauth) as client:
            # Connecting (OAuth included) can outlast an edit, as in call_tool_sync.
            if config_check is not None and not config_check():
                raise RuntimeError("MCP server was updated or removed while connecting")
            return await dispatch(client)

    session_args = (url, headers, label, {}, timeout, cancel_event, scope, config_check, use_oauth)
    try:
        if is_stdio(url) or (scope and not use_oauth):
            return _call_session_tool(*session_args, dispatch = dispatch, rpc = rpc)
        return asyncio.run(_race_tool_call(_one_shot(), timeout, cancel_event))
    except _MCPCancelled as exc:
        raise TimeoutError(f"{label} was cancelled") from exc


def call_tool_structured_sync(
    url: str, headers: Optional[dict], name: str, args: dict, **kw
) -> dict:
    dispatch = lambda client: client.call_tool(name, args, raise_on_error = False)  # noqa: E731
    label = f"MCP tool '{name}'"
    return _structured_result(
        _ui_request_sync(url, headers, label, dispatch, rpc = ("tools/call", name), **kw)
    )


def read_resource_sync(url: str, headers: Optional[dict], uri: str, **kw) -> dict:
    dispatch = lambda client: client.read_resource(uri)  # noqa: E731
    return _resource_contents(
        _ui_request_sync(
            url, headers, f"MCP resource '{uri}'", dispatch, rpc = ("resources/read", uri), **kw
        ),
        uri,
    )


def _resource_contents(blocks: Any, uri: str) -> dict:
    """Keyed as McpUiResourceResponse. Of several contents the one matching ``uri`` wins, else the first."""
    import base64

    items = list(blocks or [])
    if not items:
        raise ValueError("resource is empty")
    chosen = next((b for b in items if str(getattr(b, "uri", "")) == uri), items[0])
    text, blob = getattr(chosen, "text", None), None
    if text is None:
        if getattr(chosen, "blob", None) is None:
            raise ValueError("resource carries neither text nor blob content")
        blob = str(chosen.blob)
        try:
            raw = base64.b64decode(blob, validate = True)
        except Exception as exc:  # noqa: BLE001
            raise ValueError(f"resource blob is not base64: {exc}") from exc
        try:
            # Decoded for the host to render a template; the widget still gets the server's blob.
            text = raw.decode("utf-8")
        except UnicodeDecodeError:
            text = ""
    text = str(text)
    # Every block for a widget's own multi-block read; a single block is the fields above.
    contents = []
    for item in items if len(items) > 1 else ():
        entry = {"uri": str(getattr(item, "uri", "") or uri)}
        if _resource_mime(item):
            entry["mimeType"] = str(_resource_mime(item))
        if getattr(item, "text", None) is not None:
            entry["text"] = str(item.text)
        elif getattr(item, "blob", None) is not None:
            entry["blob"] = str(item.blob)
        else:
            continue
        contents.append(entry)
    size = (
        len(text)
        + len(blob or "")
        + sum(len(c.get("text") or c.get("blob") or "") for c in contents)
    )
    if size > MAX_UI_RESOURCE_CHARS:
        raise ValueError(f"resource is {size} chars, over the {MAX_UI_RESOURCE_CHARS} limit")
    # _meta.ui on the contents, not the tool: the template's CSP declaration.
    metas = (getattr(chosen, "meta", None), getattr(chosen, "_meta", None))
    ui = next((m["ui"] for m in metas if isinstance(m, dict) and isinstance(m.get("ui"), dict)), {})
    mime = str(_resource_mime(chosen) or "")
    return {
        "uri": uri,
        "mime_type": mime,
        "text": text,
        "blob": blob,
        "ui": ui,
        "contents": contents,
    }


class _MCPCancelled(Exception):
    """Internal sentinel raised when cancel_event fires before the tool returns."""