ha-mcp-dev 8.5.0.dev2725__tar.gz → 8.5.0.dev2729__tar.gz

{ha_mcp_dev-8.5.0.dev2725/src/ha_mcp_dev.egg-info → ha_mcp_dev-8.5.0.dev2729}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 8.5.0.dev2725
+Version: 8.5.0.dev2729
 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.dev2725 → ha_mcp_dev-8.5.0.dev2729}/pyproject.toml

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

@@ -15,10 +15,12 @@ import logging
 import ssl
 import time
 from collections import defaultdict
-from collections.abc import Awaitable, Callable
+from collections.abc import Awaitable, Callable, Coroutine
 from typing import Any
 from urllib.parse import urlparse
 
+import anyio
+
 # The vendored copy, NEVER the shared site-packages one: inside Home
 # Assistant that copy is unowned — ~20 integration libraries drag it in with
 # conflicting version demands and any of their installs can replace or tear
@@ -46,6 +48,28 @@ logger = logging.getLogger(__name__)
 # overflowed the previous 20MB cap (#1721).
 MAX_WS_MESSAGE_BYTES = 64 * 1024 * 1024
 
+
+# How long a cancellation path waits for its own cleanup. Bounded because
+# the caller is already being torn down and must not be held indefinitely;
+# awaited rather than abandoned because a cleanup that outlives its call
+# acts on whatever the client looks like later, not on what it was cleaning
+# up. Matches the theme-guard session close, which solves the same problem.
+CLEANUP_TIMEOUT_SECONDS = 2.0
+
+# Structured error codes that mean the subscription is already gone, which
+# is the ordinary outcome when releasing one that was abandoned before Home
+# Assistant registered it. Everything else is a refusal of the release, and
+# leaves the subscription open.
+#
+# An absent code counts as gone rather than as a refusal. Home Assistant's
+# unsubscribe handler answers either success or not_found and nothing else,
+# so for THIS command an error without a structured code is still that same
+# answer from a build that did not send one. The codes worth distinguishing
+# -- unauthorised, malformed, unknown command -- come from the layer above
+# the handler and do carry one. Treating a missing code as a refusal would
+# put a warning on the routine path, which fires on every cancelled
+# subscribe.
+_SUBSCRIPTION_GONE_CODES = frozenset({"not_found"})
 # How long :meth:`HomeAssistantWebSocketClient.send_command` waits for a reply
 # when the caller names no ``_wait_timeout``. Named rather than inlined because
 # callers that schedule retries have to budget around it: a caller whose retry
@@ -53,6 +77,49 @@ MAX_WS_MESSAGE_BYTES = 64 * 1024 * 1024
 # later than it planned when the command hangs instead.
 DEFAULT_COMMAND_WAIT_TIMEOUT = 30.0
 
+# Field names whose value must never reach the log, matched case-insensitively
+# wherever they appear in a received frame. The approval-response event carries
+# the user's approval PIN in ``event.data.pin`` (issue #2502), and the debug
+# line below prints whole decoded frames -- so without this, turning on debug
+# logging would write that PIN into Home Assistant's log in clear text.
+_REDACTED_LOG_FIELDS = frozenset({"pin"})
+_REDACTED_PLACEHOLDER = "<redacted>"
+
+
+def _redacted_for_log(value: Any) -> Any:
+    """A copy of ``value`` with ``_REDACTED_LOG_FIELDS`` masked.
+
+    Only for logging: the caller keeps handling the original, so redaction
+    cannot change what the client does with a frame -- verification still
+    sees the real PIN. Containers are rebuilt rather than mutated for the
+    same reason. Anything that is not a dict or a list is returned as it
+    is, which is why this stays cheap enough to run per frame; the caller
+    runs it only when DEBUG is actually enabled.
+    """
+    if isinstance(value, dict):
+        return {
+            key: (
+                _REDACTED_PLACEHOLDER
+                if isinstance(key, str) and key.lower() in _REDACTED_LOG_FIELDS
+                else _redacted_for_log(item)
+            )
+            for key, item in value.items()
+        }
+    if isinstance(value, list):
+        return [_redacted_for_log(item) for item in value]
+    return value
+
+
+def _log_received_frame(data: Any) -> None:
+    """Debug-log one received frame, with secret fields masked.
+
+    Its own function so the redaction cannot cost the message loop a
+    branch it does not need: the guard keeps the copy from being built at
+    all when DEBUG is off, which is every production deployment.
+    """
+    if logger.isEnabledFor(logging.DEBUG):
+        logger.debug("WebSocket received: %s", _redacted_for_log(data))
+
 
 def _extract_ws_error(error: Any) -> tuple[str, str | None]:
     """Split an HA WebSocket ``error`` payload into ``(message, code)``.
@@ -419,6 +486,19 @@ class HomeAssistantWebSocketClient:
             await self.disconnect()
             return False
 
+        except BaseException:
+            # Everything that is not an ``Exception`` -- a cancellation above
+            # all -- used to skip the clause above entirely, leaving the
+            # reader task started earlier and the open socket behind with
+            # nothing tracking them: the pool only takes the client once
+            # connect has returned True, so nothing else would ever close
+            # them. Ordered after the ``Exception`` handler so the ordinary
+            # failure path is unchanged, and it re-raises unconditionally --
+            # only the tidying happens here, and it is bounded because
+            # awaiting it plainly would be cancelled in turn.
+            await self._run_cleanup(self.disconnect(), "cancelled connect")
+            raise
+
     async def disconnect(self) -> None:
         """Disconnect from WebSocket."""
         if self.background_task:
@@ -473,7 +553,7 @@ class HomeAssistantWebSocketClient:
             async for message in self.websocket:
                 try:
                     data = json.loads(message)
-                    logger.debug(f"WebSocket received: {data}")
+                    _log_received_frame(data)
                     await self._process_message(data)
                 except json.JSONDecodeError as e:
                     logger.error(f"Invalid JSON received: {e}")
@@ -854,7 +934,21 @@ class HomeAssistantWebSocketClient:
         except BaseException:
             # Cancellation mid-send: skips the clause above and would leave the
             # pending future registered — drop it before propagating.
+            #
+            # And a cancelled send is not proof that Home Assistant received
+            # nothing. The vendored implementation writes the frame before it
+            # awaits flow-control drainage, so a cancellation landing in that
+            # wait can leave the subscription registered on a socket this
+            # process keeps using -- the same orphan the acknowledgment path
+            # below releases, reached one await earlier. The id is allocated
+            # before the send, so it is still known here; an unsubscribe for
+            # something that was never registered answers not_found, which
+            # the release treats as its ordinary outcome.
             self.cancel_pending_response(message_id)
+            await self._run_cleanup(
+                self._release_abandoned_subscription(message_id),
+                f"abandoned subscribe_events({message_id})",
+            )
             raise
 
         try:
@@ -864,7 +958,16 @@ class HomeAssistantWebSocketClient:
             # resolves once the caller is gone. The cleanup is
             # exception-type-independent and the original exception re-raises
             # unchanged.
+            #
+            # The command is already on the wire by this point, so Home
+            # Assistant may well have registered the subscription: releasing
+            # 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)
+            await self._run_cleanup(
+                self._release_abandoned_subscription(message_id),
+                f"abandoned subscribe_events({message_id})",
+            )
             raise
 
         if response.get("type") == "result" and response.get("success"):
@@ -916,6 +1019,128 @@ class HomeAssistantWebSocketClient:
                 e,
             )
 
+    async def _run_cleanup(self, coro: Coroutine[Any, Any, None], what: str) -> None:
+        """Run ``coro`` to completion or to a deadline, from a cancelled path.
+
+        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
+        must not merely be detached. A detached task reads the client's
+        state when it eventually runs, not when it was scheduled, so a
+        second ``connect()`` on the same object races it -- measured, the
+        stale task closed the NEW socket and left the old one open, the
+        exact failure this cleanup exists to prevent.
+
+        So the work is owned by a task, which makes it survive the
+        cancellation, and awaited through a shield with a deadline, which
+        makes it finish before control returns to anyone. The same shape as
+        the theme-guard session cleanup, for the same reason.
+
+        The shield holds against an anyio cancel scope, which is the shape
+        this is reached under. A plain ``asyncio.Task.cancel()`` -- what
+        ``asyncio.timeout`` issues -- goes through it: measured, the wait
+        below then ends at the caller's deadline with the cleanup untouched.
+        """
+        task = asyncio.ensure_future(coro)
+        # Shielded with anyio's scope rather than asyncio's, and around the
+        # WAIT as much as around the drain: a cancel scope re-delivers its
+        # cancellation to the HOST TASK on every tick while that task is
+        # still inside it, and ``asyncio.shield`` only governs propagation
+        # from one awaited future -- it does not stop a second ``cancel()``
+        # landing on the task at its next await. Such a scope is how this
+        # method is reached in the first place: the approval listener opens
+        # its subscription inside a ``move_on_after`` setup budget, and a
+        # cancelled ``subscribe_events`` is what calls this. Shielding only
+        # the drain leaves the wait below cancelled on its first tick, and
+        # the ``finally`` then stops the work before it ever had its own
+        # budget -- collecting a task is not the same as letting it finish,
+        # and cleanup that has to suspend (an unsubscribe waiting for the
+        # shared send lock) never reaches its release.
+        #
+        # What this does NOT do is re-deliver the cancellation it shielded:
+        # measured, an enclosing ``move_on_after`` ends with
+        # ``cancelled_caught`` False when this returns normally. Each call
+        # site raises on its way out, and that raise is what delivers the
+        # caller's cancellation -- after the cleanup rather than instead of
+        # it. A caller added on a non-raising path would swallow its own
+        # deadline here.
+        with anyio.CancelScope(shield=True):
+            try:
+                await asyncio.wait_for(
+                    asyncio.shield(task), timeout=CLEANUP_TIMEOUT_SECONDS
+                )
+            except (Exception, TimeoutError) as e:
+                logger.debug("%s: cleanup did not finish cleanly: %s", what, e)
+            except asyncio.CancelledError:
+                logger.debug("%s: cleanup cancelled before it finished", what)
+                raise
+            finally:
+                # The inner ``asyncio.shield`` is what lets the deadline
+                # expire without killing the work -- and it is equally what
+                # would let the work outlive this call, which is the failure
+                # being fixed. A task still running here reads the client's
+                # state whenever it gets there, so it must not get there:
+                # stop it, then collect the outcome so a late failure does
+                # not surface as an orphaned "exception was never
+                # retrieved".
+                if not task.done():
+                    task.cancel()
+                await asyncio.gather(task, return_exceptions=True)
+
+    async def _release_abandoned_subscription(self, message_id: int) -> None:
+        """Ask Home Assistant to drop a subscription we can no longer name.
+
+        ``subscribe_events`` allocates the message id before sending, so a
+        cancelled call still knows the id Home Assistant would have used --
+        the id is only lost to the *caller*, which never gets its return
+        value. Without this the subscription stays open on a socket this
+        process keeps using, the next attempt opens a second one, and every
+        event is then delivered once per orphan.
+
+        "Subscription not found" is the ordinary outcome here rather than a
+        surprise: the command may never have reached Home Assistant, which
+        is exactly the case that needs no cleanup. It is logged at debug for
+        that reason, where ``unsubscribe_events`` logs a warning -- there,
+        a rejection means a subscription that was known to exist.
+        """
+        if not self._state.is_ready:
+            logger.debug(
+                "abandoned subscribe_events(%s): socket not ready, nothing to release",
+                message_id,
+            )
+            return
+        try:
+            await self.send_command("unsubscribe_events", subscription=message_id)
+        except OSError as e:
+            logger.debug(
+                "abandoned subscribe_events(%s): transport lost before cleanup: %s",
+                message_id,
+                e,
+            )
+        except HomeAssistantCommandError as e:
+            if e.code is None or e.code in _SUBSCRIPTION_GONE_CODES:
+                logger.debug(
+                    "abandoned subscribe_events(%s): Home Assistant has no such "
+                    "subscription, so the command did not reach it: %s",
+                    message_id,
+                    e,
+                )
+            else:
+                # Anything else is a rejection of the unsubscribe itself --
+                # not authorised, malformed, a command this build does not
+                # know. The subscription is then still open on a socket this
+                # process keeps using, which is the leak this method exists
+                # to prevent, so it must not disappear at debug level with
+                # the routine case.
+                logger.warning(
+                    "abandoned subscribe_events(%s): Home Assistant refused "
+                    "the release (code %s); the subscription may still be "
+                    "open: %s",
+                    message_id,
+                    e.code,
+                    e,
+                )
+
     async def subscribe_command(
         self,
         command_type: str,

{ha_mcp_dev-8.5.0.dev2725 → ha_mcp_dev-8.5.0.dev2729}/src/ha_mcp/policy/approval_queue.py

@@ -8,6 +8,7 @@ import logging
 import secrets
 from dataclasses import dataclass, field
 from datetime import UTC, datetime, timedelta
+from enum import StrEnum
 from typing import Any, Literal
 
 import anyio
@@ -34,6 +35,7 @@ class PendingApproval:
     _decision: Decision = "pending"
     _event: anyio.Event = field(default_factory=anyio.Event)
     _claimed: bool = False
+    _notified: bool = False
 
     @property
     def decision(self) -> Decision:
@@ -72,11 +74,38 @@ class PendingApproval:
         self._claimed = True
         return True
 
+    def mark_notified(self) -> bool:
+        """Take ownership of announcing this entry. False if already taken.
+
+        Concurrent identical calls share one entry (``find_or_create``), and
+        a caller that joins an existing row must not fire a second Home
+        Assistant event for the request the user has already been told
+        about. Same one-shot shape as ``claim()``: there is no ``await``
+        here, so the check-and-set cannot interleave with another task.
+        """
+        if self._notified:
+            return False
+        self._notified = True
+        return True
+
     def __post_init__(self) -> None:
         if self.expires_at <= self.created_at:
             raise ValueError("expires_at must be after created_at")
 
 
+# What a decision did, for a caller that has to report it rather than just
+# branch on it. ``approve``/``deny`` keep returning a bool because that is
+# all their callers in the settings UI and the developer tool ever needed;
+# a decision arriving over the event bus has to say WHY it did not apply,
+# and the queue is the only place that knows. The values are part of the
+# event payload, so they are a stable vocabulary rather than prose.
+class DecisionOutcome(StrEnum):
+    APPLIED = "applied"
+    EXPIRED = "expired"
+    UNKNOWN_TOKEN = "unknown_token"
+    ALREADY_DECIDED = "already_decided"
+
+
 class ApprovalQueue:
     """In-memory per-process approval queue with args-hash binding.
 
@@ -202,40 +231,80 @@ class ApprovalQueue:
         self._sweep_expired()
         return [e for e in self._by_token.values() if e.decision == "pending"]
 
-    def approve(self, token: str) -> bool:
-        """Mark the entry approved. Returns False if unknown or already decided."""
+    def decide_with_outcome(
+        self, token: str, decision: Literal["approve", "deny"]
+    ) -> DecisionOutcome:
+        """Decide ``token`` and say what happened, not merely whether it worked.
+
+        Same work as ``approve``/``deny`` -- those delegate here -- with the
+        distinction the logs already draw kept in the return value: a TTL
+        that ran out while a phone notification sat unread is a different
+        thing from a token nobody ever issued, and a caller that has to
+        tell the user which one it was cannot get that from a bool.
+        """
+        action = "approve" if decision == "approve" else "deny"
+        if self._expire(token, action):
+            return DecisionOutcome.EXPIRED
         entry = self._by_token.get(token)
         if entry is None:
             # WARNING because on a security-gating endpoint this means
             # either a UI bug, a stale tab racing the sweeper, or an
-            # attacker probing tokens — operator should see it.
-            logger.warning("approval_queue.approve: unknown token %s", token)
-            return False
-        ok = entry.decide("approved")
-        if not ok:
-            # INFO — could be a legitimate race (two approvers, or
-            # quick double-click) rather than a security signal.
-            logger.info(
-                "approval_queue.approve: token %s already decided as %s",
-                token,
-                entry.decision,
-            )
-        return ok
+            # attacker probing tokens -- operator should see it. An entry
+            # that merely ran out of TTL is handled above, at INFO, so a
+            # late click on a phone notification does not read as a probe.
+            logger.warning("approval_queue.%s: unknown token %s", action, token)
+            return DecisionOutcome.UNKNOWN_TOKEN
+        if entry.decide("approved" if decision == "approve" else "denied"):
+            return DecisionOutcome.APPLIED
+        # INFO -- could be a legitimate race (two approvers, or a quick
+        # double-click) rather than a security signal.
+        logger.info(
+            "approval_queue.%s: token %s already decided as %s",
+            action,
+            token,
+            entry.decision,
+        )
+        return DecisionOutcome.ALREADY_DECIDED
+
+    def approve(self, token: str) -> bool:
+        """Mark the entry approved. False if unknown, expired or already decided.
+
+        The sweep is what makes the TTL binding for every decider, not only
+        for the ones that happen to read the queue first. The settings UI
+        calls ``get`` before approving and so expires the entry on the way
+        in; a decision arriving on the event bus does not, and without this
+        an entry whose TTL elapsed while its caller was retrying could still
+        be approved -- waking a retry that is holding the same row and
+        dispatching the tool long after the window closed.
+        """
+        return self.decide_with_outcome(token, "approve") is DecisionOutcome.APPLIED
 
     def deny(self, token: str) -> bool:
-        """Mark the entry denied. Returns False if unknown or already decided."""
-        entry = self._by_token.get(token)
-        if entry is None:
-            logger.warning("approval_queue.deny: unknown token %s", token)
-            return False
-        ok = entry.decide("denied")
-        if not ok:
+        """Mark the entry denied. False if unknown, expired or already decided.
+
+        Expires first, for the reason ``approve`` gives: the TTL has to mean
+        the same thing to a decision from the bus as to one from the tab.
+        """
+        return self.decide_with_outcome(token, "deny") is DecisionOutcome.APPLIED
+
+    def _expire(self, token: str, action: str) -> bool:
+        """Sweep, and report whether ``token`` is gone because its TTL ran out.
+
+        The sweep is what makes the TTL binding for a decision, and the
+        return value is what keeps an ordinary expiry distinguishable from
+        an unknown token: both leave the queue without the entry, but only
+        one of them is worth an operator's attention.
+        """
+        known_before = token in self._by_token
+        self._sweep_expired()
+        if known_before and token not in self._by_token:
             logger.info(
-                "approval_queue.deny: token %s already decided as %s",
+                "approval_queue.%s: token %s expired before the decision reached it",
+                action,
                 token,
-                entry.decision,
             )
-        return ok
+            return True
+        return False
 
     def remove(self, token: str) -> None:
         self._by_token.pop(token, None)