ha-mcp-dev 7.12.3.dev1888__tar.gz → 7.12.3.dev1894__tar.gz

{ha_mcp_dev-7.12.3.dev1888/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.12.3.dev1894}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.12.3.dev1888
+Version: 7.12.3.dev1894
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT

{ha_mcp_dev-7.12.3.dev1888 → ha_mcp_dev-7.12.3.dev1894}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.12.3.dev1888"
+version = "7.12.3.dev1894"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 # Upper bound widened to <3.15 so the package installs on Home Assistant's

{ha_mcp_dev-7.12.3.dev1888 → ha_mcp_dev-7.12.3.dev1894}/src/ha_mcp/client/rest_client.py

@@ -1388,8 +1388,12 @@ class HomeAssistantClient:
         for attempt in range(max_retries):
             try:
                 # Use per-client WebSocket keyed to this client's credentials
+                # (verify_ssl included so a verify_ssl=False client never
+                # shares a default-verification pooled connection).
                 ws_client = await get_websocket_client(
-                    url=self.base_url, token=self.token
+                    url=self.base_url,
+                    token=self.token,
+                    verify_ssl=self.verify_ssl,
                 )
 
                 # Special handling for render_template which returns an event with the actual result
@@ -1642,9 +1646,17 @@ class HomeAssistantClient:
             )
         return bare_id
 
-    async def get_scene_config(self, scene_id: str) -> dict[str, Any]:
-        """Get Home Assistant scene configuration by scene_id."""
-        resolved_id = await self.resolve_scene_id(scene_id)
+    async def get_scene_config(
+        self, scene_id: str, *, _resolved: bool = False
+    ) -> dict[str, Any]:
+        """Get Home Assistant scene configuration by scene_id.
+
+        ``_resolved=True`` signals ``scene_id`` is already the resolved storage
+        key (the caller ran :meth:`resolve_scene_id`), skipping the redundant
+        registry lookup. ``resolve_scene_id`` is idempotent, so the result is
+        identical either way.
+        """
+        resolved_id = scene_id if _resolved else await self.resolve_scene_id(scene_id)
         try:
             endpoint = f"config/scene/config/{resolved_id}"
             response = await self._request("GET", endpoint)
@@ -1662,10 +1674,15 @@ class HomeAssistantClient:
             raise
 
     async def upsert_scene_config(
-        self, config: dict[str, Any], scene_id: str
+        self, config: dict[str, Any], scene_id: str, *, _resolved: bool = False
     ) -> dict[str, Any]:
-        """Create or update Home Assistant scene configuration."""
-        resolved_id = await self.resolve_scene_id(scene_id)
+        """Create or update Home Assistant scene configuration.
+
+        ``_resolved=True`` signals ``scene_id`` is already the resolved storage
+        key, skipping the redundant registry lookup (``resolve_scene_id`` is
+        idempotent, so the endpoint id is unchanged).
+        """
+        resolved_id = scene_id if _resolved else await self.resolve_scene_id(scene_id)
         try:
             endpoint = f"config/scene/config/{resolved_id}"
 
@@ -1699,9 +1716,16 @@ class HomeAssistantClient:
             logger.error(f"Failed to upsert scene config for {scene_id}: {e}")
             raise
 
-    async def delete_scene_config(self, scene_id: str) -> dict[str, Any]:
-        """Delete Home Assistant scene configuration."""
-        resolved_id = await self.resolve_scene_id(scene_id)
+    async def delete_scene_config(
+        self, scene_id: str, *, _resolved: bool = False
+    ) -> dict[str, Any]:
+        """Delete Home Assistant scene configuration.
+
+        ``_resolved=True`` signals ``scene_id`` is already the resolved storage
+        key, skipping the redundant registry lookup (``resolve_scene_id`` is
+        idempotent, so the endpoint id is unchanged).
+        """
+        resolved_id = scene_id if _resolved else await self.resolve_scene_id(scene_id)
         try:
             endpoint = f"config/scene/config/{resolved_id}"
             response = await self._request("DELETE", endpoint)

{ha_mcp_dev-7.12.3.dev1888 → ha_mcp_dev-7.12.3.dev1894}/src/ha_mcp/client/websocket_client.py

@@ -1037,7 +1037,7 @@ class WebSocketManager:
     _current_loop: asyncio.AbstractEventLoop | None = None
     _lock: asyncio.Lock | None = None
     _lock_loop: asyncio.AbstractEventLoop | None = None
-    _client_factory: Callable[[str, str], HomeAssistantWebSocketClient] | None = None
+    _client_factory: Callable[..., HomeAssistantWebSocketClient] | None = None
 
     def __new__(cls) -> "WebSocketManager":
         if cls._instance is None:
@@ -1052,8 +1052,7 @@ class WebSocketManager:
     def configure(
         self,
         *,
-        client_factory: Callable[[str, str], HomeAssistantWebSocketClient]
-        | None = None,
+        client_factory: Callable[..., HomeAssistantWebSocketClient] | None = None,
     ) -> None:
         """Configure the manager with injectable dependencies."""
         if client_factory is not None:
@@ -1084,10 +1083,28 @@ class WebSocketManager:
         """Create a cache key from credentials."""
         return hashlib.sha256(f"{url.rstrip('/')}:{token}".encode()).hexdigest()
 
+    @staticmethod
+    def _effective_verify_ssl(verify_ssl: bool | None) -> bool:
+        """Resolve the effective TLS-verification mode for the pool key."""
+        if verify_ssl is not None:
+            return verify_ssl
+        try:
+            return bool(get_global_settings().verify_ssl)
+        except Exception as e:
+            # Mirror HomeAssistantWebSocketClient.__init__: a bad env var
+            # elsewhere should not crash pooling or silently flip TLS off.
+            logger.warning(
+                "Could not load settings while resolving the pool verify_ssl "
+                "key (%s); falling back to verify_ssl=True.",
+                e,
+            )
+            return True
+
     async def get_client(
         self,
         url: str | None = None,
         token: str | None = None,
+        verify_ssl: bool | None = None,
     ) -> HomeAssistantWebSocketClient:
         """Get WebSocket client, creating connection if needed.
 
@@ -1100,6 +1117,10 @@ class WebSocketManager:
                  credentials instead of global settings. This is required
                  for OAuth mode where each request has its own credentials.
             token: Optional HA token. Must be provided with url.
+            verify_ssl: TLS verification override, keyed into the pool so a
+                 ``HomeAssistantClient(verify_ssl=False)`` caller never shares
+                 a connection built with default verification. ``None`` keeps
+                 the client's own settings-based default.
         """
         current_loop = asyncio.get_event_loop()
 
@@ -1134,7 +1155,16 @@ class WebSocketManager:
                 ws_url = settings.homeassistant_url
                 ws_token = settings.homeassistant_token
 
-            key = self._client_key(ws_url, ws_token)
+            # Key on the EFFECTIVE verification mode: a caller passing the
+            # resolved settings default (send_websocket_message) must share
+            # the pooled connection with callers that omit the argument
+            # (listener, HACS, installer) — only a genuine override such as
+            # verify_ssl=False gets its own isolated connection.
+            effective_verify_ssl = self._effective_verify_ssl(verify_ssl)
+            key = (
+                f"{self._client_key(ws_url, ws_token)}"
+                f"|verify_ssl={effective_verify_ssl}"
+            )
 
             # Return existing connected client for these credentials
             existing = self._clients.get(key)
@@ -1148,7 +1178,11 @@ class WebSocketManager:
                 self._last_used.pop(key, None)
 
             factory = self._client_factory or HomeAssistantWebSocketClient
-            client = factory(ws_url, ws_token)
+            client = (
+                factory(ws_url, ws_token)
+                if verify_ssl is None
+                else factory(ws_url, ws_token, verify_ssl=verify_ssl)
+            )
 
             connected = await client.connect()
             if not connected:
@@ -1210,11 +1244,16 @@ websocket_manager = WebSocketManager()
 async def get_websocket_client(
     url: str | None = None,
     token: str | None = None,
+    verify_ssl: bool | None = None,
 ) -> HomeAssistantWebSocketClient:
     """Get the global WebSocket client instance.
 
     Args:
         url: Optional HA URL for per-client credentials (OAuth mode).
         token: Optional HA token for per-client credentials (OAuth mode).
+        verify_ssl: Optional TLS-verification override propagated into the
+            pool key and client construction (None = settings default).
     """
-    return await websocket_manager.get_client(url=url, token=token)
+    return await websocket_manager.get_client(
+        url=url, token=token, verify_ssl=verify_ssl
+    )

{ha_mcp_dev-7.12.3.dev1888 → ha_mcp_dev-7.12.3.dev1894}/src/ha_mcp/smoke_test.py

@@ -8,8 +8,8 @@ from typing import Any
 
 # Force UTF-8 encoding on Windows for Unicode output
 if sys.platform == "win32":
-    sys.stdout.reconfigure(encoding="utf-8", errors="replace")
-    sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+    sys.stdout.reconfigure(encoding="utf-8", errors="replace")  # type: ignore[union-attr,unused-ignore]
+    sys.stderr.reconfigure(encoding="utf-8", errors="replace")  # type: ignore[union-attr,unused-ignore]
 
 # Set dummy credentials before any imports try to use them
 os.environ.setdefault("HOMEASSISTANT_URL", "http://smoke-test:8123")

{ha_mcp_dev-7.12.3.dev1888 → ha_mcp_dev-7.12.3.dev1894}/src/ha_mcp/stdio_settings_sidecar.py

@@ -125,7 +125,7 @@ def _pid_alive(pid: int) -> bool:
         # ctypes.windll.kernel32 (no external deps).
         import ctypes
 
-        kernel32 = ctypes.windll.kernel32  # type: ignore[attr-defined]
+        kernel32 = ctypes.windll.kernel32  # type: ignore[attr-defined,unused-ignore]
         SYNCHRONIZE = 0x00100000
         handle = kernel32.OpenProcess(SYNCHRONIZE, False, pid)
         if not handle:
@@ -394,13 +394,13 @@ def _do_spawn() -> None:
         # mode the user saw.
         pythonw = Path(sys.executable).with_name("pythonw.exe")
         cmd_python = str(pythonw) if pythonw.exists() else sys.executable
-        startupinfo = subprocess.STARTUPINFO()  # type: ignore[attr-defined]
-        startupinfo.dwFlags |= subprocess.STARTF_USESHOWWINDOW  # type: ignore[attr-defined]
-        startupinfo.wShowWindow = subprocess.SW_HIDE  # type: ignore[attr-defined]
+        startupinfo = subprocess.STARTUPINFO()  # type: ignore[attr-defined,unused-ignore]
+        startupinfo.dwFlags |= subprocess.STARTF_USESHOWWINDOW  # type: ignore[attr-defined,unused-ignore]
+        startupinfo.wShowWindow = subprocess.SW_HIDE  # type: ignore[attr-defined,unused-ignore]
         popen_kwargs["startupinfo"] = startupinfo
         popen_kwargs["creationflags"] = (
-            subprocess.CREATE_NEW_PROCESS_GROUP  # type: ignore[attr-defined]
-            | subprocess.CREATE_NO_WINDOW  # type: ignore[attr-defined]
+            subprocess.CREATE_NEW_PROCESS_GROUP  # type: ignore[attr-defined,unused-ignore]
+            | subprocess.CREATE_NO_WINDOW  # type: ignore[attr-defined,unused-ignore]
         )
         cmd = [cmd_python, "-m", "ha_mcp.stdio_settings_sidecar"]
     else:

{ha_mcp_dev-7.12.3.dev1888 → ha_mcp_dev-7.12.3.dev1894}/src/ha_mcp/tools/backup.py

@@ -899,22 +899,15 @@ async def list_backups(client: HomeAssistantClient, limit: int = 200) -> dict[st
     confirm a specific backup landed; they had to already know the ID. Newest
     first. Read-only: no safety backup, no restart.
     """
-    ws_client = None
     try:
-        ws_client, error = await get_connected_ws_client(
-            client.base_url, client.token, verify_ssl=client.verify_ssl
-        )
-        if error:
-            raise_tool_error(
-                error
-                or create_error_response(
-                    ErrorCode.CONNECTION_FAILED,
-                    "Failed to connect to Home Assistant WebSocket to list backups",
-                )
-            )
-        ws_client = cast(HomeAssistantWebSocketClient, ws_client)
-
-        info = await ws_client.send_command("backup/info")
+        # Route through the shared pooled WebSocket (issue #1813) rather than a
+        # dedicated connect/auth handshake per call. ``list_backups`` issues a
+        # single request/response ``backup/info`` command; the pooled client
+        # owns the connection lifecycle, so there is no per-call connect or
+        # disconnect. A failed command surfaces as ``success=False`` and is
+        # handled by the guard below (send_websocket_message never raises for
+        # WS command failures).
+        info = await client.send_websocket_message({"type": "backup/info"})
         if not info.get("success"):
             raise_tool_error(
                 create_error_response(
@@ -955,18 +948,6 @@ async def list_backups(client: HomeAssistantClient, limit: int = 200) -> dict[st
             suggestions=["Check Home Assistant connection and the backup integration"],
         )
         return None  # unreachable: exception_to_structured_error always raises
-    finally:
-        # Always disconnect WebSocket — narrow to transport errors; a
-        # programming error during cleanup should still surface.
-        if ws_client:
-            try:
-                await ws_client.disconnect()
-            except (TimeoutError, OSError, ConnectionError) as err:
-                logger.debug(
-                    "ws disconnect (cleanup) transport error: %s: %s",
-                    type(err).__name__,
-                    err,
-                )
 
 
 # Valid (scope, action) combinations. Anything outside this set is

{ha_mcp_dev-7.12.3.dev1888 → ha_mcp_dev-7.12.3.dev1894}/src/ha_mcp/tools/tools_addons.py

@@ -22,10 +22,9 @@ from pydantic import Field
 from websockets.asyncio.client import ClientConnection
 
 from .._version import is_running_in_addon
-from ..client.rest_client import HomeAssistantClient
+from ..client.rest_client import HomeAssistantClient, HomeAssistantCommandError
 from ..errors import (
     ErrorCode,
-    create_connection_error,
     create_error_response,
     create_validation_error,
 )
@@ -36,7 +35,6 @@ from ..utils.python_sandbox import (
 )
 from .helpers import (
     exception_to_structured_error,
-    get_connected_ws_client,
     log_tool_usage,
     raise_tool_error,
     validate_identifier_not_empty,
@@ -233,16 +231,7 @@ async def _supervisor_api_call(
     Returns:
         The "result" field from a successful response, or an error dict.
     """
-    ws_client = None
     try:
-        ws_client, error = await get_connected_ws_client(
-            client.base_url, client.token, verify_ssl=client.verify_ssl
-        )
-        if error or ws_client is None:
-            return error or create_connection_error(
-                "Failed to establish WebSocket connection",
-            )
-
         kwargs: dict[str, Any] = {"endpoint": endpoint, "method": method}
         if data is not None:
             kwargs["data"] = data
@@ -256,29 +245,20 @@ async def _supervisor_api_call(
             kwargs["timeout"] = timeout
             wait_timeout = float(timeout) + 15.0
 
-        result = await ws_client.send_command(
-            "supervisor/api", _wait_timeout=wait_timeout, **kwargs
+        # Route through the shared pooled WebSocket (issue #1813) rather than
+        # opening a dedicated connect/auth handshake per call. ``_wait_timeout``
+        # is consumed by send_command (it never reaches Home Assistant). The
+        # pooled path collapses a failed WS command into
+        # ``{"success": False, "error": ...}``; re-raise it as the same
+        # ``HomeAssistantCommandError`` the dedicated send_command used to raise
+        # so the classifier below maps schema/not-found/etc. identically.
+        result = await client.send_websocket_message(
+            {"type": "supervisor/api", "_wait_timeout": wait_timeout, **kwargs}
         )
 
         if not result.get("success"):
-            error_msg = str(result.get("error", ""))
-            if "not_found" in error_msg.lower() or "unknown" in error_msg.lower():
-                raise_tool_error(
-                    create_error_response(
-                        ErrorCode.RESOURCE_NOT_FOUND,
-                        "Supervisor API not available",
-                        details=str(result),
-                        suggestions=[
-                            "This feature requires Home Assistant OS or Supervised installation",
-                        ],
-                    )
-                )
-            raise_tool_error(
-                create_error_response(
-                    ErrorCode.SERVICE_CALL_FAILED,
-                    f"Supervisor API call failed: {endpoint}",
-                    details=str(result),
-                )
+            raise HomeAssistantCommandError(
+                str(result.get("error", f"Supervisor API call failed: {endpoint}"))
             )
 
         return {"success": True, "result": result.get("result", {})}
@@ -293,14 +273,6 @@ async def _supervisor_api_call(
             suggestions=["Check Home Assistant connection and Supervisor availability"],
         )
         return None  # unreachable: exception_to_structured_error always raises
-    finally:
-        if ws_client:
-            try:
-                await ws_client.disconnect()
-            except Exception:
-                # Best-effort cleanup: the WS connection is being torn down, so a
-                # disconnect failure is non-fatal and must not mask the real result.
-                pass
 
 
 def _addon_connection_failure_suggestions(

{ha_mcp_dev-7.12.3.dev1888 → ha_mcp_dev-7.12.3.dev1894}/src/ha_mcp/tools/tools_bug_report.py

@@ -32,6 +32,7 @@ from ..utils.usage_logger import (
     get_recent_logs,
     get_startup_logs,
 )
+from .component_api import get_component_caps
 from .helpers import log_tool_usage, register_tool_methods
 from .util_helpers import ANSI_ESCAPE_RE
 
@@ -613,11 +614,21 @@ class BugReportTools:
     async def _detect_component_version(self) -> str | None:
         """Read the ha_mcp_tools custom component's version, best-effort.
 
-        Uses the component's ``get_caller_token`` bootstrap service, whose
-        response carries the manifest version (the same field the filesystem
-        tools' version gate reads). Returns None when the component is not
-        installed or the call fails — the report path must never break on it.
+        Prefers the shared cached capability probe (``get_component_caps`` — one
+        ``ha_mcp_tools/info`` round-trip per client): a component new enough to
+        answer it (1.1.0+) reports its version there, so the report reuses that
+        cached probe instead of a bespoke round-trip. A component in the
+        0.11.0-1.1.0 band has services but no ``info`` command (caps is None),
+        so it falls back to the ``get_caller_token`` bootstrap service, whose
+        response also carries the manifest version. Returns None when the
+        component is not installed or the call fails — the report path must
+        never break on it.
         """
+        # get_component_caps never raises (it caches/returns None on every
+        # failure mode), so no guard is needed around it.
+        caps = await get_component_caps(self._client)
+        if caps is not None:
+            return caps.component_version or None
         try:
             resp = await self._client.call_service(
                 "ha_mcp_tools", "get_caller_token", {}, return_response=True

{ha_mcp_dev-7.12.3.dev1888 → ha_mcp_dev-7.12.3.dev1894}/src/ha_mcp/tools/tools_calendar.py

@@ -15,16 +15,20 @@ from fastmcp.exceptions import ToolError
 from fastmcp.tools import tool
 from pydantic import Field
 
+from ..client.rest_client import (
+    HomeAssistantCommandError,
+    HomeAssistantConnectionError,
+)
 from ..errors import ErrorCode, create_error_response
 from .auto_backup import with_auto_backup
 from .helpers import (
     exception_to_structured_error,
-    get_connected_ws_client,
     log_tool_usage,
     raise_tool_error,
     register_tool_methods,
     validate_identifier_not_empty,
 )
+from .util_helpers import is_connection_error_message
 
 logger = logging.getLogger(__name__)
 
@@ -199,35 +203,23 @@ class CalendarTools:
         if location is not None:
             event["location"] = location
 
-        ws_client, conn_error = await get_connected_ws_client(
-            self._client.base_url,
-            self._client.token,
-            verify_ssl=self._client.verify_ssl,
+        # Route through the shared pooled WebSocket (issue #1813) instead of a
+        # dedicated connect/auth handshake per call. The pooled path collapses a
+        # failed WS command into ``{"success": False, "error": ...}``; a
+        # transport-shaped failure re-raises as ``HomeAssistantConnectionError``
+        # (the classifier type-matches it to connectivity guidance), anything
+        # else as the same ``HomeAssistantCommandError`` the dedicated
+        # send_command used to raise so the caller's error handler still
+        # attaches the rrule-specific suggestions.
+        result = await self._client.send_websocket_message(
+            {"type": "calendar/event/create", "entity_id": entity_id, "event": event}
         )
-        if conn_error or ws_client is None:
-            raise_tool_error(
-                conn_error
-                or create_error_response(
-                    ErrorCode.CONNECTION_FAILED,
-                    "Failed to connect to Home Assistant WebSocket",
-                    context={"entity_id": entity_id},
-                )
-            )
-
-        try:
-            return await ws_client.send_command(
-                "calendar/event/create", entity_id=entity_id, event=event
-            )
-        finally:
-            # Guard disconnect: a transport-teardown error here would
-            # otherwise replace the original send_command exception.
-            try:
-                await ws_client.disconnect()
-            except Exception as disconnect_error:
-                logger.debug(
-                    f"WebSocket disconnect after create_event for "
-                    f"{entity_id}: {disconnect_error}"
-                )
+        if not result.get("success"):
+            error = str(result.get("error", "calendar/event/create failed"))
+            if is_connection_error_message(error):
+                raise HomeAssistantConnectionError(error)
+            raise HomeAssistantCommandError(error)
+        return result
 
     async def _create_simple_calendar_event(
         self,
@@ -257,6 +249,13 @@ class CalendarTools:
         self, entity_id: str, rrule: str | None, error: Exception
     ) -> list[str]:
         """Build suggestions for a failed ha_config_set_calendar_event call."""
+        if isinstance(error, HomeAssistantConnectionError):
+            # A transport drop is not a calendar problem — domain hints would
+            # send the agent chasing a non-issue during an HA restart.
+            return [
+                "Home Assistant may be restarting or unreachable — retry shortly",
+                "Check the connection to Home Assistant",
+            ]
         suggestions = [
             f"Verify calendar entity '{entity_id}' exists and supports event creation",
             "Check datetime format (ISO 8601)",
@@ -541,35 +540,21 @@ class CalendarTools:
             if recurrence_range:
                 ws_kwargs["recurrence_range"] = recurrence_range
 
-            ws_client, conn_error = await get_connected_ws_client(
-                self._client.base_url,
-                self._client.token,
-                verify_ssl=self._client.verify_ssl,
+            # Route through the shared pooled WebSocket (issue #1813) instead of a
+            # dedicated connect/auth handshake per call. Transport-shaped
+            # failures raise ``HomeAssistantConnectionError`` (connectivity
+            # guidance); anything else re-raises as the same
+            # ``HomeAssistantCommandError`` the dedicated send_command used to
+            # raise so the outer handler builds the delete-specific
+            # suggestions (404 / not-supported).
+            result = await self._client.send_websocket_message(
+                {"type": "calendar/event/delete", **ws_kwargs}
             )
-            if conn_error or ws_client is None:
-                raise_tool_error(
-                    conn_error
-                    or create_error_response(
-                        ErrorCode.CONNECTION_FAILED,
-                        "Failed to connect to Home Assistant WebSocket",
-                        context={"entity_id": entity_id, "uid": uid},
-                    )
-                )
-
-            try:
-                result = await ws_client.send_command(
-                    "calendar/event/delete", **ws_kwargs
-                )
-            finally:
-                # Guard disconnect: a transport-teardown error here would
-                # otherwise replace the original send_command exception.
-                try:
-                    await ws_client.disconnect()
-                except Exception as disconnect_error:
-                    logger.debug(
-                        f"WebSocket disconnect after delete_event for "
-                        f"{entity_id} uid={uid}: {disconnect_error}"
-                    )
+            if not result.get("success"):
+                error = str(result.get("error", "calendar/event/delete failed"))
+                if is_connection_error_message(error):
+                    raise HomeAssistantConnectionError(error)
+                raise HomeAssistantCommandError(error)
 
             return {
                 "success": True,
@@ -586,28 +571,41 @@ class CalendarTools:
         except Exception as error:
             logger.error(f"Failed to delete calendar event from {entity_id}: {error}")
 
-            suggestions = [
-                f"Verify calendar entity '{entity_id}' exists",
-                f"Verify event with UID '{uid}' exists in the calendar",
-                "Use ha_config_get_calendar_events() to find the correct event UID",
-                "Some calendar integrations may not support event deletion",
-            ]
-
-            error_str = str(error)
-            if "404" in error_str or "not found" in error_str.lower():
-                suggestions.insert(
-                    0, f"Calendar entity '{entity_id}' or event '{uid}' not found"
-                )
-            if "not supported" in error_str.lower():
-                suggestions.insert(0, "This calendar does not support event deletion")
-
             exception_to_structured_error(
                 error,
                 context={"entity_id": entity_id, "uid": uid},
-                suggestions=suggestions,
+                suggestions=self._build_remove_calendar_event_error_suggestions(
+                    entity_id, uid, error
+                ),
             )
             return None  # unreachable: exception_to_structured_error always raises
 
+    def _build_remove_calendar_event_error_suggestions(
+        self, entity_id: str, uid: str, error: Exception
+    ) -> list[str]:
+        """Build suggestions for a failed ha_config_remove_calendar_event call."""
+        if isinstance(error, HomeAssistantConnectionError):
+            # A transport drop is not a calendar problem — domain hints would
+            # send the agent chasing a non-issue during an HA restart.
+            return [
+                "Home Assistant may be restarting or unreachable — retry shortly",
+                "Check the connection to Home Assistant",
+            ]
+        suggestions = [
+            f"Verify calendar entity '{entity_id}' exists",
+            f"Verify event with UID '{uid}' exists in the calendar",
+            "Use ha_config_get_calendar_events() to find the correct event UID",
+            "Some calendar integrations may not support event deletion",
+        ]
+        error_str = str(error)
+        if "404" in error_str or "not found" in error_str.lower():
+            suggestions.insert(
+                0, f"Calendar entity '{entity_id}' or event '{uid}' not found"
+            )
+        if "not supported" in error_str.lower():
+            suggestions.insert(0, "This calendar does not support event deletion")
+        return suggestions
+
 
 def register_calendar_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
     """Register calendar management tools with the MCP server."""