iCode-TUI 0.29.1__py3-none-any.whl

chrys/service/llm/sdk_headers.py

@@ -0,0 +1,47 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Static request headers for the provider SDK client subclasses.
+
+It imports no provider SDK, so each SDK's subclass module loads only its own.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import TYPE_CHECKING, Any, Protocol
+
+if TYPE_CHECKING:
+
+    class _HeadersBase(Protocol):
+        _custom_headers: Mapping[str, str]
+
+        @property
+        def auth_headers(self) -> dict[str, str]: ...
+
+        @property
+        def default_headers(self) -> dict[str, Any]: ...
+
+else:
+    _HeadersBase = object
+
+
+class CaseFoldedDefaultHeaders(_HeadersBase):
+    """Send each static header name once, whatever case a profile spells it in.
+
+    The pinned SDKs merge their own headers, Chrys's and the profile's as
+    dictionaries, case-sensitively, so a profile's ``user-agent`` or
+    ``openai-organization`` would go out beside, or be dropped for, the
+    ``User-Agent`` or ``OpenAI-Organization`` the SDK or Chrys sets. Names
+    are folded under their first spelling, or the auth header's, and the
+    client's custom headers (Chrys's and the profile's, the SDK's
+    ``_custom_headers``) are laid over last, as they are when spelled alike.
+    """
+
+    @property
+    def default_headers(self) -> dict[str, Any]:
+        spellings = {name.casefold(): name for name in self.auth_headers}
+        folded: dict[str, Any] = {}
+        for headers in (super().default_headers, self._custom_headers):
+            for name, value in headers.items():
+                folded[spellings.setdefault(name.casefold(), name)] = value
+        return folded

chrys/service/llm/sdk_openai.py

@@ -0,0 +1,18 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""The ``AsyncOpenAI`` client Chrys builds for every OpenAI-SDK provider.
+
+Importing this module loads the OpenAI SDK; the client factory imports it only
+while it builds such a client.
+"""
+
+from __future__ import annotations
+
+from openai import AsyncOpenAI
+
+from chrys.service.llm.sdk_headers import CaseFoldedDefaultHeaders
+from chrys.service.llm.sdk_retry import DeterministicConnectionSleepGuard
+
+
+class RetryGuardedAsyncOpenAI(DeterministicConnectionSleepGuard, CaseFoldedDefaultHeaders, AsyncOpenAI):
+    """``AsyncOpenAI`` that does not retry a connection error that cannot self-heal, and sends each header name once."""

chrys/service/llm/sdk_retry.py

@@ -0,0 +1,59 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Retry policy for the provider SDK client subclasses.
+
+It imports no provider SDK, so each SDK's subclass module loads only its own.
+The two pinned SDKs expose different retry hooks, so each has its own guard.
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import TYPE_CHECKING, Any, Protocol
+
+from chrys.foundation.errors import is_deterministic_connection_error
+
+if TYPE_CHECKING:
+    import httpx
+
+    class _RetrySleepBase(Protocol):
+        async def _sleep_for_retry(self, **kwargs: Any) -> None: ...
+
+    class _RetryDecisionBase(Protocol):
+        def _should_retry_exception(self, err: BaseException) -> tuple[bool, httpx.Response | None]: ...
+
+else:
+    _RetrySleepBase = object
+    _RetryDecisionBase = object
+
+
+class DeterministicConnectionSleepGuard(_RetrySleepBase):
+    """Stop OpenAI SDK retries when the active request error cannot self-heal.
+
+    The pinned OpenAI SDK calls its async ``_sleep_for_retry`` hook from the
+    ``except`` block that caught the request exception. Python preserves that
+    handled exception across the awaited call, so :func:`sys.exception`
+    exposes its transport cause chain.
+    """
+
+    async def _sleep_for_retry(self, **kwargs: Any) -> None:
+        active_exception = sys.exception()
+        if active_exception is not None and is_deterministic_connection_error(active_exception):
+            raise active_exception
+        await super()._sleep_for_retry(**kwargs)
+
+
+class DeterministicConnectionDecisionGuard(_RetryDecisionBase):
+    """Stop Anthropic SDK retries when a request attempt's error cannot self-heal.
+
+    The pinned Anthropic SDK passes every exception a request attempt raised to
+    ``_should_retry_exception``; a status response it retries never reaches it,
+    so an exception the caller is handling cannot veto that retry. Declining
+    here makes the SDK re-raise its own error, an ``APIConnectionError`` whose
+    ``__cause__`` is the transport failure.
+    """
+
+    def _should_retry_exception(self, err: BaseException) -> tuple[bool, httpx.Response | None]:
+        if is_deterministic_connection_error(err):
+            return False, None
+        return super()._should_retry_exception(err)

chrys/service/llm/wire_client.py

@@ -0,0 +1,246 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""The base class every provider wire client derives from.
+
+A wire client encodes one request, sends it over its provider SDK and decodes
+the response or stream; the tool loop and chat middleware wrap it. The client
+factory composes the production stack::
+
+    ToolLoopLayer(              # chrys-owned tool loop
+      ChatMiddlewareLayer(      # chrys-owned per-call chat middleware
+        <WireClient subclass>)) # telemetry + observer + protocol codec
+
+:class:`WireClient` implements the kernel's ``_inner_get_response`` hook once
+for every protocol: it drops the loop's trajectory handle from the call
+keywords, lets its :class:`~chrys.service.llm.observer.WireCallObserver`
+report the request, and dispatches to the protocol's ``_send`` or
+``_open_stream``. :class:`RequestHeaders` holds the Chrys metadata each
+protocol stamps on the request it builds.
+"""
+
+from __future__ import annotations
+
+from abc import abstractmethod
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Self, final, override
+
+from chrys.foundation.trajectory.context import TRAJECTORY_EXCHANGE_KWARG
+from chrys.foundation.util.chrys_headers import (
+    MODEL_ID_HEADER,
+    PARENT_SESSION_ID_HEADER,
+    SESSION_ID_HEADER,
+    X_PARENT_SESSION_ID_HEADER,
+    X_SESSION_ID_HEADER,
+    is_chrys_managed_header_name,
+)
+from chrys.foundation.util.header_charset import (
+    header_name_charset_error,
+    header_value_charset_error,
+    model_id_charset_error,
+)
+from chrys.kernel import BaseChatClient, ChatTelemetryLayer
+from chrys.service.llm.route_sessions import llm_parent_session_id, llm_route_session_id
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Sequence
+
+    from chrys.kernel.compaction import CompactionStrategy, TokenizerProtocol
+    from chrys.kernel.types import ChatResponse, ChatResponseUpdate, Message, ResponseStream
+    from chrys.service.llm.observer import WireCallObserver
+
+
+def _reject_wire_unsafe_request_values(model_id: Any, headers: Mapping[Any, Any] | None) -> None:
+    """Reject per-request option values httpx cannot encode into HTTP headers.
+
+    Final wire boundary for values ``create_client`` never sees: resolved
+    ``chat_options.extra_headers`` (env templates resolve per run, after
+    the client is built) and a per-request ``model`` override, which
+    becomes the ``Chrys-Model-Id`` header.  Raising here replaces the
+    opaque ``UnicodeEncodeError``/``LocalProtocolError`` the transport
+    would otherwise produce with an error naming the offending field —
+    without echoing secret header values.
+    """
+    problems: list[str] = []
+    if model_id:
+        model_error = model_id_charset_error(str(model_id))
+        if model_error:
+            problems.append(model_error)
+    if isinstance(headers, Mapping):
+        for index, (name, value) in enumerate(headers.items(), start=1):
+            if not isinstance(name, str):
+                problems.append(f"Header name at position {index} must be a string.")
+                continue
+            name_error = header_name_charset_error(name)
+            if name_error:
+                problems.append(name_error)
+            if not isinstance(value, str):
+                problems.append(f"Header {name!r} value must be a string.")
+                continue
+            value_error = header_value_charset_error(name, value)
+            if value_error:
+                problems.append(value_error)
+    if problems:
+        raise ValueError("Chat request options contain values that cannot be sent over HTTP: " + " ".join(problems))
+
+
+@dataclass(frozen=True, slots=True)
+class RequestHeaders:
+    """The Chrys metadata headers one client stamps on every request it builds.
+
+    *use_route_session_context* makes the per-invocation route-session
+    ContextVars win over the client's own session ids, for clients that
+    several sub-agent invocations share.
+    """
+
+    session_id: str | None = None
+    parent_session_id: str | None = None
+    use_route_session_context: bool = False
+
+    def route_session_id(self) -> str | None:
+        """The session the request being built belongs to, as the session headers name it."""
+        if self.use_route_session_context:
+            return llm_route_session_id.get() or self.session_id
+        return self.session_id
+
+    def stamp(self, request: dict[str, Any]) -> None:
+        """Set the metadata headers on a built request, including the ``X-Session-ID`` alias.
+
+        The request's final ``model`` becomes ``Chrys-Model-Id``. Caller
+        headers that collide with a Chrys-managed name are dropped, and the
+        remaining ones must be sendable over HTTP.
+        """
+        model_id = request.get("model")
+        session_id = self.route_session_id()
+        if self.use_route_session_context:
+            parent_session_id = llm_parent_session_id.get() or self.parent_session_id
+        else:
+            parent_session_id = self.parent_session_id
+        if not model_id and not session_id and not parent_session_id:
+            # No Chrys metadata to merge — any caller-supplied extra headers
+            # still go to the wire as-is, so they still need the charset gate.
+            _reject_wire_unsafe_request_values(None, request.get("extra_headers"))
+            return
+
+        raw_headers = request.get("extra_headers")
+        headers = (
+            {k: v for k, v in raw_headers.items() if not is_chrys_managed_header_name(str(k))}
+            if isinstance(raw_headers, Mapping)
+            else {}
+        )
+        # Validate after the managed-name filter (a dropped header never
+        # reaches the wire) and before Chrys' own metadata joins the dict.
+        _reject_wire_unsafe_request_values(model_id, headers)
+        if model_id:
+            headers[MODEL_ID_HEADER] = str(model_id)
+        if session_id:
+            headers[X_SESSION_ID_HEADER] = session_id
+            headers[SESSION_ID_HEADER] = session_id
+        if parent_session_id:
+            headers[X_PARENT_SESSION_ID_HEADER] = parent_session_id
+            headers[PARENT_SESSION_ID_HEADER] = parent_session_id
+        request["extra_headers"] = headers
+
+
+class WireClient(ChatTelemetryLayer, BaseChatClient):
+    """A provider wire client: OTel spans, request reporting and one protocol codec.
+
+    Subclasses implement ``_send`` and ``_open_stream``. Both are plain, not
+    async, methods: whatever they check before returning fails the call
+    itself, after the observer reported the request as started.
+    ``_open_stream`` returns its stream without consuming any of it. Every
+    protocol builds its request through one method that ends with
+    :meth:`_stamp_request_headers`.
+
+    The observer and request headers are optional: a client built without
+    them is the bare codec, which the codec tests drive directly.
+    """
+
+    def __init__(
+        self,
+        *,
+        observer: WireCallObserver | None = None,
+        request_headers: RequestHeaders | None = None,
+        compaction_strategy: CompactionStrategy | None = None,
+        tokenizer: TokenizerProtocol | None = None,
+        additional_properties: dict[str, Any] | None = None,
+    ) -> None:
+        self._observer = observer
+        self._request_headers = request_headers
+        super().__init__(
+            compaction_strategy=compaction_strategy,
+            tokenizer=tokenizer,
+            additional_properties=additional_properties,
+        )
+
+    @classmethod
+    def from_sdk_client(
+        cls,
+        sdk_client: Any,
+        *,
+        model: str,
+        observer: WireCallObserver | None = None,
+        request_headers: RequestHeaders | None = None,
+    ) -> Self:
+        """Build this client over a configured provider SDK client."""
+        raise NotImplementedError(f"{cls.__name__} does not take a provider SDK client")
+
+    @final
+    @override
+    def _inner_get_response(
+        self,
+        *,
+        messages: Sequence[Message],
+        stream: bool = False,
+        options: Mapping[str, Any],
+        **kwargs: Any,
+    ) -> Awaitable[ChatResponse[Any]] | ResponseStream[ChatResponseUpdate, ChatResponse[Any]]:
+        # The trajectory exchange trace is a loop-to-client handle, never a
+        # provider request parameter: drop it before any kwargs are forwarded.
+        forwarded_trace = kwargs.pop(TRAJECTORY_EXCHANGE_KWARG, None)
+        if self._observer is None:
+            return self._dispatch(messages, options, stream=stream, kwargs=kwargs)
+        call = self._observer.begin(messages, options, stream=stream, forwarded_trace=forwarded_trace)
+        try:
+            result = self._dispatch(messages, options, stream=stream, kwargs=kwargs)
+        except BaseException as exc:
+            call.failed(exc)
+            raise
+        return call.observe(result)
+
+    def _dispatch(
+        self,
+        messages: Sequence[Message],
+        options: Mapping[str, Any],
+        *,
+        stream: bool,
+        kwargs: dict[str, Any],
+    ) -> Awaitable[ChatResponse[Any]] | ResponseStream[ChatResponseUpdate, ChatResponse[Any]]:
+        if stream:
+            return self._open_stream(messages=messages, options=options, **kwargs)
+        return self._send(messages=messages, options=options, **kwargs)
+
+    @abstractmethod
+    def _send(
+        self,
+        *,
+        messages: Sequence[Message],
+        options: Mapping[str, Any],
+        **kwargs: Any,
+    ) -> Awaitable[ChatResponse[Any]]:
+        """Send one request and return the pending response."""
+
+    @abstractmethod
+    def _open_stream(
+        self,
+        *,
+        messages: Sequence[Message],
+        options: Mapping[str, Any],
+        **kwargs: Any,
+    ) -> ResponseStream[ChatResponseUpdate, ChatResponse[Any]]:
+        """Return the stream of one request; nothing is sent until it is consumed."""
+
+    def _stamp_request_headers(self, request: dict[str, Any]) -> None:
+        """Last step of building a request: add this client's Chrys metadata headers."""
+        if self._request_headers is not None:
+            self._request_headers.stamp(request)

chrys/service/mcp/__init__.py

@@ -0,0 +1,3 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""MCP (Model Context Protocol) integration."""

chrys/service/mcp/_connection.py

@@ -0,0 +1,235 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""MCP tool validation and connection factory."""
+
+from __future__ import annotations
+
+import asyncio
+import dataclasses
+from typing import TYPE_CHECKING, Any
+
+from chrys.foundation.util.env_templates import resolve_env_template_mapping
+from chrys.service.mcp._http_transport import _HTTP_HEADERS_OVERRIDE, _HTTPMCPTool
+from chrys.service.mcp._stdio_transport import (
+    _STDIO_CWD_OVERRIDE,
+    _STDIO_ENV_IS_COMPLETE,
+    _STDIO_ENV_OVERRIDE,
+    _SafeStdioTool,
+    _StdioFailureDiagnostics,
+)
+from chrys.service.mcp.errors import MCPToolNameValidationError
+from chrys.service.mcp.validation import (
+    MCP_PROGRESSIVE_CONTROL_TOOL_NAMES,
+    validate_mcp_tool_loading_policy,
+    validate_mcp_tool_name_prefix,
+)
+
+if TYPE_CHECKING:
+    from chrys.service.mcp.owned import MCPTool
+    from chrys.service.profiles.agents.schema import MCPServerConfig
+
+
+# Hard timeouts that bound how long a misbehaving MCP server can hold up the
+# UI / agent build.  The MCP SDK's per-request timeout
+# (``read_timeout_seconds``) defaults to ``None`` (wait forever), and a
+# server that emits welcome banner text instead of a valid ``initialize``
+# response will leave the client blocked indefinitely on
+# ``response_stream_reader.receive()``.  These floors are injected into
+# the MCP tool's ``request_timeout`` when the user didn't set one, so the
+# SDK's own timeout fires from *inside* MCPTool's lifecycle-owner
+# task.  We intentionally do **not** wrap ``__aenter__`` in
+# ``asyncio.wait_for`` from the outside: the lifecycle owner is a
+# separate ``asyncio.Task`` (see ``MCPTool._run_lifecycle_owner``) which
+# ``wait_for`` cannot cancel safely (anyio cancel scopes are scoped per
+# task and cross-task cancellation raises "Attempted to exit cancel scope
+# in a different task").  ``MCPServerConfig.request_timeout`` (when set)
+# always takes precedence — these are only the defaults applied when no
+# per-server timeout is configured.
+DEFAULT_CONNECT_TIMEOUT_SECONDS = 30
+
+
+def _validate_config(config: MCPServerConfig) -> None:
+    """Reject malformed configs before constructing an owned MCPTool."""
+    if not config.name:
+        raise ValueError("MCP server config requires a non-empty 'name'")
+    if not isinstance(config.use_progressive_disclosure, bool):
+        raise ValueError(f"MCP server {config.name!r}: 'use_progressive_disclosure' must be a boolean")
+    if not isinstance(config.expose_instructions, bool):
+        raise ValueError(f"MCP server {config.name!r}: 'expose_instructions' must be a boolean")
+    cap = config.max_tool_result_tokens
+    if not (cap is None or (type(cap) is int and (cap == 0 or cap >= 100))):
+        raise ValueError(
+            f"MCP server {config.name!r}: 'max_tool_result_tokens' must be null, 0, or an integer of at least 100"
+        )
+    if config.allowed_tools is not None and (
+        not isinstance(config.allowed_tools, list) or not all(isinstance(name, str) for name in config.allowed_tools)
+    ):
+        raise ValueError(f"MCP server {config.name!r}: 'allowed_tools' must be a list of strings or null")
+    if not isinstance(config.always_load, list) or not all(isinstance(name, str) for name in config.always_load):
+        raise ValueError(f"MCP server {config.name!r}: 'always_load' must be a list of strings")
+    if policy_errors := validate_mcp_tool_loading_policy(
+        allowed_tools=config.allowed_tools,
+        use_progressive_disclosure=config.use_progressive_disclosure,
+        always_load=config.always_load,
+    ):
+        raise ValueError(f"MCP server {config.name!r}: {' '.join(policy_errors)}")
+    prefix_error = validate_mcp_tool_name_prefix(
+        config.tool_name_prefix,
+        generated_suffixes=MCP_PROGRESSIVE_CONTROL_TOOL_NAMES if config.use_progressive_disclosure else (),
+    )
+    if prefix_error is not None:
+        raise MCPToolNameValidationError(
+            config.name,
+            config.transport,
+            violations={prefix_error},
+        )
+    if config.transport == "stdio":
+        if not config.command:
+            raise ValueError(f"MCP server {config.name!r} (stdio) requires 'command'")
+    elif config.transport == "http":
+        if not config.url:
+            raise ValueError(f"MCP server {config.name!r} (http) requires 'url'")
+    else:
+        raise ValueError(f"Unknown MCP transport: {config.transport!r}")
+
+
+def _build_common_kwargs(config: MCPServerConfig) -> dict[str, Any]:
+    """Kwargs shared by every MCPTool subclass."""
+    kwargs: dict[str, Any] = {
+        "name": config.name,
+        "load_prompts": config.load_prompts,
+    }
+    if config.description:
+        kwargs["description"] = config.description
+    if config.tool_name_prefix:
+        kwargs["tool_name_prefix"] = config.tool_name_prefix
+    if config.allowed_tools is not None:
+        kwargs["allowed_tools"] = config.allowed_tools
+    if config.request_timeout is not None:
+        kwargs["request_timeout"] = config.request_timeout
+    return kwargs
+
+
+def _create_mcp_tool(config: MCPServerConfig) -> MCPTool:
+    """Create the appropriate MCPTool subclass from a profile config."""
+    _validate_config(config)
+    common = _build_common_kwargs(config)
+
+    if config.transport == "stdio":
+        env = _STDIO_ENV_OVERRIDE.get()
+        env_is_complete = _STDIO_ENV_IS_COMPLETE.get()
+        if env is None:
+            env = resolve_env_template_mapping(config.env, location=f"MCP server {config.name!r} env")
+            env_is_complete = False
+        kwargs: dict[str, Any] = {
+            **common,
+            "command": config.command,
+            "args": config.args or None,
+            "env": env if env_is_complete else env or None,
+            "encoding": config.encoding,
+            "env_is_complete": env_is_complete,
+        }
+        cwd = _STDIO_CWD_OVERRIDE.get()
+        if cwd is not None:
+            kwargs["cwd"] = cwd
+        return _SafeStdioTool(**kwargs)
+
+    # transport == "http" (validated above).  Static headers are attached by
+    # ``_HTTPMCPTool``'s same-origin request hook, so they reach every request,
+    # ``initialize`` and ``list_tools`` included.
+    headers = _HTTP_HEADERS_OVERRIDE.get()
+    if headers is None:
+        headers = (
+            resolve_env_template_mapping(config.headers, location=f"MCP server {config.name!r} headers")
+            if config.resolve_header_templates
+            else dict(config.headers)
+        )
+    return _HTTPMCPTool(
+        **common,
+        url=config.url,
+        terminate_on_close=config.terminate_on_close,
+        verify_ssl=config.verify_ssl,
+        bypass_proxy=config.bypass_proxy,
+        headers=headers or None,
+    )
+
+
+def _create_tool_with_timeout_floor(
+    config: MCPServerConfig,
+    default_timeout: int,
+    *,
+    resolved_stdio_env: dict[str, str] | None = None,
+    stdio_cwd: str | None = None,
+    resolved_http_headers: dict[str, str] | None = None,
+) -> Any:
+    """Build the MCP tool, injecting the timeout floor when none is configured.
+
+    We bound a hung connect/initialize by setting the MCP tool's
+    ``request_timeout`` (used as ``ClientSession.read_timeout_seconds``)
+    — the SDK's own ``anyio.fail_after`` then fires from inside the
+    owned MCPTool's lifecycle-owner task, where ``_safe_close_exit_stack``
+    runs cleanup safely.  A user-configured ``request_timeout`` always
+    wins; we only inject when ``config.request_timeout is None``.
+
+    Why not ``asyncio.wait_for(__aenter__, ...)`` from outside?  The
+    lifecycle owner runs in a separate task started by
+    ``MCPTool._run_lifecycle_owner`` and uses anyio cancel scopes
+    which are pinned to the owning task.  Cross-task cancellation
+    raises ``RuntimeError("Attempted to exit cancel scope in a
+    different task than it was entered in")`` and leaves the inner
+    coroutine still running — defeating both the timeout and cleanup.
+    """
+    effective_config = (
+        dataclasses.replace(config, request_timeout=default_timeout) if config.request_timeout is None else config
+    )
+    env_token = _STDIO_ENV_OVERRIDE.set(resolved_stdio_env)
+    cwd_token = _STDIO_CWD_OVERRIDE.set(stdio_cwd)
+    headers_token = _HTTP_HEADERS_OVERRIDE.set(resolved_http_headers)
+    complete_token = _STDIO_ENV_IS_COMPLETE.set(resolved_stdio_env is not None)
+    try:
+        return _create_mcp_tool(effective_config)
+    finally:
+        _STDIO_ENV_IS_COMPLETE.reset(complete_token)
+        _HTTP_HEADERS_OVERRIDE.reset(headers_token)
+        _STDIO_CWD_OVERRIDE.reset(cwd_token)
+        _STDIO_ENV_OVERRIDE.reset(env_token)
+
+
+def _banner_lines_from(tool: Any) -> list[str]:
+    """Extract banner diagnostics from a stdio tool, empty list otherwise."""
+    return list(getattr(tool, "dropped_banner_lines", []) or [])
+
+
+def _stdio_failure_diagnostics_from(tool: Any) -> _StdioFailureDiagnostics:
+    """Snapshot bounded process diagnostics from Chrys's stdio tool."""
+    if not isinstance(tool, _SafeStdioTool):
+        return _StdioFailureDiagnostics()
+    diagnostics = tool._process_diagnostics
+    return _StdioFailureDiagnostics(
+        stderr_tail=diagnostics.stderr_tail,
+        stderr_dropped_bytes=diagnostics.stderr_dropped_bytes,
+        process_exit_code=diagnostics.exit_code,
+        resolved_executable=diagnostics.resolved_executable,
+        effective_cwd=diagnostics.effective_cwd,
+    )
+
+
+def _is_timeout_cause(exc: BaseException) -> bool:
+    """True if the exception chain contains an MCP/anyio read-timeout signal.
+
+    The MCP SDK's ``ClientSession.send_request`` translates an
+    ``anyio.fail_after`` timeout into ``McpError(ErrorData(code=408, ...))``.
+    For other paths (e.g. cancelled transport) we also accept plain
+    ``TimeoutError`` / ``asyncio.TimeoutError``.
+    """
+    seen: set[int] = set()
+    cur: BaseException | None = exc
+    while cur is not None and id(cur) not in seen:
+        if isinstance(cur, (TimeoutError, asyncio.TimeoutError)):
+            return True
+        data = getattr(cur, "error", None)
+        if getattr(data, "code", None) == 408:
+            return True
+        seen.add(id(cur))
+        cur = cur.__cause__ or cur.__context__
+    return False