ha-mcp-dev 8.5.0.dev2732__tar.gz → 8.5.0.dev2737__tar.gz

{ha_mcp_dev-8.5.0.dev2732/src/ha_mcp_dev.egg-info → ha_mcp_dev-8.5.0.dev2737}/PKG-INFO

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

{ha_mcp_dev-8.5.0.dev2732 → ha_mcp_dev-8.5.0.dev2737}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.5.0.dev2732"
+version = "8.5.0.dev2737"
 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-8.5.0.dev2732 → ha_mcp_dev-8.5.0.dev2737}/src/ha_mcp/client/rest_client.py

@@ -239,6 +239,91 @@ _NO_ANSWER_ERRORS = (
     WebSocketException,
 )
 
+RENDER_NO_VERDICT_WITHOUT_REPORT_ERRORS = (
+    "No template result from Home Assistant. With report_errors=false Home "
+    "Assistant does not report a failed render (it only writes the error to "
+    "its own log), so the template most likely failed. Retry with "
+    "report_errors=true to get the error."
+)
+
+
+def _is_typed_template_error(error: str) -> bool:
+    """True for ``"UndefinedError: ..."``-style messages that name the class."""
+    name = error.partition(": ")[0]
+    return name.isidentifier() and name.endswith(("Error", "Exception"))
+
+
+def _pick_render_error(first: str, queue: asyncio.Queue[dict[str, Any]]) -> str:
+    """Choose the clearest of the ERROR events already queued after ``first``.
+
+    One failure can arrive as several events: an undefined attribute is
+    reported once bare (``'dict object' has no attribute 'split'``) and once
+    with its class (``UndefinedError: ...``). The class-named one is kept.
+    """
+    candidates = [first]
+    while True:
+        try:
+            event = queue.get_nowait().get("event") or {}
+        except (asyncio.QueueEmpty, asyncio.QueueShutDown):
+            break
+        error = event.get("error")
+        if event.get("level") == "ERROR" and isinstance(error, str):
+            candidates.append(error)
+    return next((e for e in candidates if _is_typed_template_error(e)), first)
+
+
+async def _read_render_verdict(
+    queue: asyncio.Queue[dict[str, Any]],
+    template: Any,
+    wait: float,
+    report_errors: bool,
+) -> dict[str, Any]:
+    """Read ``render_template`` events up to the render's verdict."""
+    warnings: list[str] = []
+    try:
+        async with asyncio.timeout(wait):
+            while True:
+                event = (await queue.get()).get("event") or {}
+                if "result" in event:
+                    response: dict[str, Any] = {
+                        "success": True,
+                        "result": event["result"],
+                        "template": template,
+                        "listeners": event.get("listeners", {}),
+                    }
+                    break
+                error = event.get("error")
+                if not isinstance(error, str):
+                    logger.debug("render_template: unrecognised event %r", event)
+                    continue
+                if event.get("level") == "ERROR":
+                    response = {
+                        "success": False,
+                        "error": _pick_render_error(error, queue),
+                        "template": template,
+                    }
+                    break
+                if error not in warnings:
+                    warnings.append(error)
+    except TimeoutError:
+        response = {
+            "success": False,
+            "error": (
+                "Event timeout - template result not received"
+                if report_errors
+                else RENDER_NO_VERDICT_WITHOUT_REPORT_ERRORS
+            ),
+            "no_verdict": True,
+            "template": template,
+        }
+    except asyncio.QueueShutDown as e:
+        raise HomeAssistantConnectionError(
+            "WebSocket connection to Home Assistant closed while rendering the template"
+        ) from e
+    if warnings:
+        response["warnings"] = warnings
+    return response
+
 
 class HomeAssistantClient:
     """Authenticated HTTP client for Home Assistant API."""
@@ -1768,7 +1853,7 @@ class HomeAssistantClient:
                 )
                 acquiring = False
 
-                # Special handling for render_template which returns an event with the actual result
+                # render_template is a subscription; see _handle_render_template.
                 if message.get("type") == "render_template":
                     return await self._handle_render_template(ws_client, message)
 
@@ -1868,37 +1953,46 @@ class HomeAssistantClient:
     async def _handle_render_template(
         self, ws_client: Any, message: dict[str, Any]
     ) -> dict[str, Any]:
-        """Handle render_template WebSocket command with event-based response."""
+        """Render a template, keeping the errors and warnings HA reports.
+
+        ``render_template`` opens a subscription. With ``report_errors`` HA sends
+        each template error or warning as an ``{"error", "level"}`` event,
+        possibly before the result frame (#2522). The first ERROR event or
+        ``{"result", "listeners"}`` event is the render's verdict; WARNING
+        events seen before it are returned in ``warnings`` whatever the
+        outcome. Without ``report_errors`` HA only logs a failed render and
+        never sends a verdict, so the wait runs out (``no_verdict``). The
+        subscription is released in every case, or HA keeps re-rendering the
+        template on every relevant state change for the life of the socket.
+        """
+        template = message.get("template")
         template_timeout = message.get("timeout", 3)
+        report_errors = message.get("report_errors", True)
+        params: dict[str, Any] = {
+            "template": template,
+            "timeout": template_timeout,
+            "report_errors": report_errors,
+        }
+        if message.get("strict"):
+            params["strict"] = True
+        if message.get("variables") is not None:
+            params["variables"] = message["variables"]
 
         try:
-            _, event_response = await ws_client.send_command_with_event(
-                "render_template",
-                wait_timeout=template_timeout + 2,
-                template=message.get("template"),
-                timeout=template_timeout,
-                report_errors=message.get("report_errors", True),
+            sub_id, queue = await ws_client.subscribe_command(
+                "render_template", wait_timeout=template_timeout + 2, **params
             )
-            logger.debug(f"WebSocket render_template event: {event_response}")
-
-            # Extract template result from event
-            if "event" in event_response and "result" in event_response["event"]:
-                template_result = event_response["event"]["result"]
-                listeners_info = event_response["event"].get("listeners", {})
-
-                return {
-                    "success": True,
-                    "result": template_result,
-                    "template": message.get("template"),
-                    "listeners": listeners_info,
-                }
-            else:
-                return {
-                    "success": False,
-                    "error": "Invalid event response format",
-                    "template": message.get("template"),
-                }
-
+        except HomeAssistantCommandError as e:
+            # A rejection of the command itself: the render exceeded its
+            # timeout, or the template/variables failed HA's schema.
+            return {
+                "success": False,
+                "error": str(e).removeprefix(
+                    "subscribe_command('render_template') failed: "
+                ),
+                "error_code": e.code,
+                "template": template,
+            }
         except TimeoutError:
             # Template-level, not transport-level: the wait budget here is the
             # caller's own ``timeout`` (default 3s) plus two seconds, and a
@@ -1908,7 +2002,8 @@ class HomeAssistantClient:
             return {
                 "success": False,
                 "error": "Event timeout - template result not received",
-                "template": message.get("template"),
+                "no_verdict": True,
+                "template": template,
             }
         except Exception as e:
             if isinstance(e, _NO_ANSWER_ERRORS):
@@ -1917,12 +2012,24 @@ class HomeAssistantClient:
                 # in ``send_websocket_message`` — the very swallow this branch
                 # used to hide (#1947).
                 raise
+            # Neither Home Assistant's answer nor a dead transport: a fault on
+            # this side. Flagged so the tool does not present it as an error
+            # in the caller's template.
+            logger.exception("render_template failed on the client side")
             return {
                 "success": False,
                 "error": str(e),
-                "template": message.get("template"),
+                "client_error": True,
+                "template": template,
             }
 
+        try:
+            return await _read_render_verdict(
+                queue, template, template_timeout + 2, report_errors
+            )
+        finally:
+            await ws_client.release_subscription(sub_id)
+
     async def _resolve_script_id(self, identifier: str) -> str:
         """
         Resolve a script identifier to its storage key via the entity registry.

{ha_mcp_dev-8.5.0.dev2732 → ha_mcp_dev-8.5.0.dev2737}/src/ha_mcp/client/websocket_client.py

@@ -155,6 +155,9 @@ class WebSocketConnectionState:
         # registered for a given id, every event with that id is pushed
         # into it instead of going to ``event_type``-keyed handlers.
         self._subscription_queues: dict[int, asyncio.Queue[dict[str, Any]]] = {}
+        # Ids of subscribe commands whose caller gave up before Home Assistant
+        # acknowledged them. See ``take_abandoned_subscription``.
+        self._abandoned_subscriptions: set[int] = set()
 
     def next_message_id(self) -> int:
         """Reserve the next available WebSocket message identifier."""
@@ -213,6 +216,24 @@ class WebSocketConnectionState:
             # Same GC guard as cancel_pending_request above.
             future.exception()
 
+    def mark_abandoned_subscription(self, message_id: int) -> None:
+        """Record a subscribe command whose acknowledgement nobody awaits."""
+        self._abandoned_subscriptions.add(message_id)
+
+    def take_abandoned_subscription(self, message_id: int) -> bool:
+        """Forget an abandoned subscribe command; True if it was one.
+
+        Home Assistant may register a subscription only after the caller has
+        given up and the immediate release answered ``not_found`` — a
+        ``render_template`` setup waits out the template's own timeout first.
+        Its late acknowledgement then arrives with no pending request, and
+        this is how the dispatch recognises that it still has to release it.
+        """
+        if message_id in self._abandoned_subscriptions:
+            self._abandoned_subscriptions.discard(message_id)
+            return True
+        return False
+
     def store_auth_message(self, message_type: str, data: dict[str, Any]) -> None:
         """Store an authentication handshake message."""
         self._auth_messages[message_type] = data
@@ -267,6 +288,8 @@ class WebSocketConnectionState:
         for queue in self._subscription_queues.values():
             queue.shutdown(immediate=True)
         self._subscription_queues.clear()
+        # Subscriptions die with the socket, and ids restart on the next one.
+        self._abandoned_subscriptions.clear()
 
         self._auth_messages.clear()
 
@@ -370,6 +393,9 @@ class HomeAssistantWebSocketClient:
         self._send_lock: asyncio.Lock | None = None
         self._lock_loop: asyncio.AbstractEventLoop | None = None
         self._state = WebSocketConnectionState()
+        # Releases of subscriptions acknowledged after their caller gave up,
+        # held here so the tasks are not garbage-collected mid-flight.
+        self._late_releases: set[asyncio.Task[None]] = set()
         # Reason the most recent connect() attempt failed (exception text),
         # or None. Surfaced by callers so the agent sees *why* a WebSocket
         # connection failed instead of an opaque "Failed to connect" string.
@@ -594,13 +620,24 @@ class HomeAssistantWebSocketClient:
             self._state.store_auth_message(message_type, data)
             return
 
-        # Handle command responses
-        if message_id is not None:
+        # Handle command responses. An event frame is never the reply to a
+        # command, even when it shares the command's id and arrives first:
+        # render_template reports template errors as events before its result
+        # frame (#2522).
+        if message_id is not None and message_type != "event":
             future = self._state.resolve_pending_request(message_id)
             if future:
                 if not future.cancelled():
                     future.set_result(data)
                 return
+            if self._state.take_abandoned_subscription(message_id):
+                if message_type == "result" and data.get("success"):
+                    task = asyncio.ensure_future(
+                        self._release_abandoned_subscription(message_id)
+                    )
+                    self._late_releases.add(task)
+                    task.add_done_callback(self._late_release_done)
+                return
 
         # Handle events
         if message_type == "event":
@@ -818,9 +855,9 @@ class HomeAssistantWebSocketClient:
     ) -> tuple[dict[str, Any], dict[str, Any]]:
         """Send a command that returns a result followed by an event response.
 
-        Some HA WebSocket commands (e.g. system_health/info, render_template)
-        reply with an immediate result message and then deliver the actual data
-        in a subsequent event message sharing the same message ID.
+        Some HA WebSocket commands (e.g. system_health/info) reply with an
+        immediate result message and then deliver the actual data in a
+        subsequent event message sharing the same message ID.
 
         Args:
             command_type: Type of command to send.
@@ -945,6 +982,7 @@ class HomeAssistantWebSocketClient:
             # something that was never registered answers not_found, which
             # the release treats as its ordinary outcome.
             self.cancel_pending_response(message_id)
+            self._state.mark_abandoned_subscription(message_id)
             await self._run_cleanup(
                 self._release_abandoned_subscription(message_id),
                 f"abandoned subscribe_events({message_id})",
@@ -964,6 +1002,7 @@ class HomeAssistantWebSocketClient:
             # it is this operation's job, not the caller's, because the id it
             # needs is the one the caller never receives.
             self.cancel_pending_response(message_id)
+            self._state.mark_abandoned_subscription(message_id)
             await self._run_cleanup(
                 self._release_abandoned_subscription(message_id),
                 f"abandoned subscribe_events({message_id})",
@@ -1019,9 +1058,11 @@ class HomeAssistantWebSocketClient:
                 e,
             )
 
-    async def _run_cleanup(self, coro: Coroutine[Any, Any, None], what: str) -> None:
+    async def _run_cleanup(self, coro: Coroutine[Any, Any, None], what: str) -> bool:
         """Run ``coro`` to completion or to a deadline, from a cancelled path.
 
+        Returns whether it finished; False means the deadline stopped it.
+
         Cleanup scheduled while a cancellation is propagating cannot simply
         be awaited: the await is cancelled in turn, and under a cancel scope
         again at every suspension, so the tidying never happens. It also
@@ -1083,9 +1124,11 @@ class HomeAssistantWebSocketClient:
                 # stop it, then collect the outcome so a late failure does
                 # not surface as an orphaned "exception was never
                 # retrieved".
-                if not task.done():
+                finished = task.done()
+                if not finished:
                     task.cancel()
                 await asyncio.gather(task, return_exceptions=True)
+        return finished
 
     async def _release_abandoned_subscription(self, message_id: int) -> None:
         """Ask Home Assistant to drop a subscription we can no longer name.
@@ -1145,7 +1188,7 @@ class HomeAssistantWebSocketClient:
         self,
         command_type: str,
         *,
-        timeout: float = 30.0,
+        wait_timeout: float = 30.0,
         **kwargs: Any,
     ) -> tuple[int, asyncio.Queue[dict[str, Any]]]:
         """Send a subscribe-style command and return (subscription_id, queue).
@@ -1158,10 +1201,15 @@ class HomeAssistantWebSocketClient:
         event-type handler registry; use this method for everything
         else.
 
+        ``wait_timeout`` is named apart from ``**kwargs`` because those become
+        fields of the command, and some commands (``render_template``) carry a
+        ``timeout`` field of their own.
+
         Returns:
             (subscription_id, queue) — ``await queue.get()`` yields each
             incoming ``{"id": N, "type": "event", "event": ...}`` payload.
-            Cancel the subscription via :meth:`unsubscribe_command`.
+            Cancel the subscription via :meth:`unsubscribe_command`, or
+            :meth:`release_subscription` from a ``finally``.
         """
         if not self._state.is_ready:
             raise HomeAssistantConnectionError("WebSocket not authenticated")
@@ -1183,20 +1231,34 @@ class HomeAssistantWebSocketClient:
         except BaseException:
             # Cancellation mid-send: skips the clause above and would leave BOTH
             # the queue and the pending future registered — the queue never
-            # drains and buffers every later event for this id forever.
+            # drains and buffers every later event for this id forever. The
+            # frame may already be on the wire, so release it on Home
+            # Assistant's side too, as subscribe_events does.
             self._state.unregister_subscription_queue(message_id)
             self.cancel_pending_response(message_id)
+            self._state.mark_abandoned_subscription(message_id)
+            await self._run_cleanup(
+                self._release_abandoned_subscription(message_id),
+                f"abandoned {command_type}({message_id})",
+            )
             raise
 
         try:
-            response = await asyncio.wait_for(result_future, timeout=timeout)
+            response = await asyncio.wait_for(result_future, timeout=wait_timeout)
         except BaseException:
             # A cancelled caller leaks the pending future AND the subscription
             # queue, which keeps accumulating events with no reader. The
-            # cleanup is exception-type-independent and the original exception
-            # re-raises unchanged.
+            # command is on the wire, so Home Assistant may have registered
+            # the subscription: the caller never receives its id, so releasing
+            # it is this method's job. The original exception re-raises
+            # unchanged.
             self._state.unregister_subscription_queue(message_id)
             self.cancel_pending_response(message_id)
+            self._state.mark_abandoned_subscription(message_id)
+            await self._run_cleanup(
+                self._release_abandoned_subscription(message_id),
+                f"abandoned {command_type}({message_id})",
+            )
             raise
 
         if response.get("type") == "result" and response.get("success"):
@@ -1208,6 +1270,65 @@ class HomeAssistantWebSocketClient:
             f"subscribe_command({command_type!r}) failed: {error_msg}", error_code
         )
 
+    async def release_subscription(self, subscription_id: int) -> None:
+        """Release a :meth:`subscribe_command` subscription from a ``finally``.
+
+        Unlike :meth:`unsubscribe_command` this never raises and survives the
+        caller's cancellation: a failed or timed-out release must not replace
+        the result the caller already has, and a cancelled caller must still
+        release, or Home Assistant keeps the subscription for the life of the
+        socket.
+        """
+        self._state.unregister_subscription_queue(subscription_id)
+        socket = self.websocket
+        if await self._run_cleanup(
+            self._release_abandoned_subscription(subscription_id),
+            f"subscription {subscription_id}",
+        ):
+            return
+        # The deadline stopped the release before ``unsubscribe_events`` went
+        # out (the send lock was held throughout), and the subscription's ack
+        # has already been consumed, so nothing else will release it.
+        task = asyncio.ensure_future(self._finish_release(subscription_id, socket))
+        self._late_releases.add(task)
+        task.add_done_callback(self._late_release_done)
+
+    def _late_release_done(self, task: asyncio.Task[None]) -> None:
+        """Collect cleanup outcomes while keeping unexpected failures visible."""
+        self._late_releases.discard(task)
+        if task.cancelled():
+            return
+        error = task.exception()
+        if isinstance(error, HomeAssistantCommandTimeout) and self._state.is_ready:
+            logger.warning(
+                "Background subscription release timed out; could not confirm "
+                "subscription cleanup in Home Assistant"
+            )
+        elif isinstance(
+            error,
+            (
+                HomeAssistantConnectionError,
+                HomeAssistantCommandTimeout,
+                websockets.exceptions.ConnectionClosed,
+            ),
+        ):
+            logger.debug("Background subscription release failed: %s", error)
+        elif error is not None:
+            logger.error(
+                "Unexpected background subscription release failure",
+                exc_info=(type(error), error, error.__traceback__),
+            )
+
+    async def _finish_release(self, subscription_id: int, socket: Any) -> None:
+        """Complete a release the cleanup deadline cut short, on the same socket.
+
+        A reconnect drops the subscription with the old socket and restarts
+        message ids, so on a new socket the id could name an unrelated one.
+        """
+        if self.websocket is not socket:
+            return
+        await self._release_abandoned_subscription(subscription_id)
+
     async def unsubscribe_command(
         self,
         subscription_id: int,

{ha_mcp_dev-8.5.0.dev2732 → ha_mcp_dev-8.5.0.dev2737}/src/ha_mcp/server.py

@@ -900,8 +900,8 @@ class HomeAssistantSmartMCPServer:
         # which measures both sides at test time.
         #
         # It was the largest full description in the GATEWAY catalog this was
-        # measured against, not in the repo: ha_eval_template (5834) and
-        # ha_get_system_health (5811) are both larger and both unmapped.
+        # measured against, not in the repo: ha_get_system_health (5811) is
+        # larger and unmapped.
         # The reduction is smaller than pure compression would give because
         # the safety content below is kept inline. The routing matrix STAYS —
         # the `action` parameter's own Field description says "Valid (scope,

{ha_mcp_dev-8.5.0.dev2732 → ha_mcp_dev-8.5.0.dev2737}/src/ha_mcp/tools/config_entry_reload_watch.py

@@ -84,7 +84,7 @@ async def _subscribe_entry_changes(client: Any) -> tuple[Any, Any] | None:
             verify_ssl=getattr(client, "verify_ssl", None),
         )
         sub_id, queue = await ws.subscribe_command(
-            WS_CONFIG_ENTRIES_SUBSCRIBE, timeout=_ENTRY_SUBSCRIBE_TIMEOUT
+            WS_CONFIG_ENTRIES_SUBSCRIBE, wait_timeout=_ENTRY_SUBSCRIBE_TIMEOUT
         )
     except Exception as exc:
         # Degrade to polling rather than failing the reconfigure; the caller

{ha_mcp_dev-8.5.0.dev2732 → ha_mcp_dev-8.5.0.dev2737}/src/ha_mcp/tools/hacs_registration.py

@@ -343,7 +343,7 @@ async def wait_for_repo_registration(
     try:
         sub_id, queue = await ws_client.subscribe_command(
             "hacs/subscribe",
-            timeout=HACS_SUBSCRIBE_TIMEOUT,
+            wait_timeout=HACS_SUBSCRIBE_TIMEOUT,
             signal=HACS_REPOSITORY_SIGNAL,
         )
     except (