ha-mcp-dev 8.3.0.dev2465__tar.gz → 8.3.0.dev2467__tar.gz

{ha_mcp_dev-8.3.0.dev2465/src/ha_mcp_dev.egg-info → ha_mcp_dev-8.3.0.dev2467}/PKG-INFO

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.3.0.dev2465"
+version = "8.3.0.dev2467"
 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
@@ -306,6 +306,7 @@ dev = [
     "ruff>=0.12.12",
     "testcontainers>=4.13.0",
     "ast-grep-cli>=0.42.0",
+    "pyyaml>=6.0",
 ]
 
 # Semantic versioning configuration

{ha_mcp_dev-8.3.0.dev2465 → ha_mcp_dev-8.3.0.dev2467}/src/ha_mcp/client/websocket_client.py

@@ -111,10 +111,15 @@ class WebSocketConnectionState:
         return self._pending_requests.pop(message_id, None)
 
     def cancel_pending_request(self, message_id: int) -> None:
-        """Cancel a pending request future if it exists."""
+        """Remove a pending request future, cancelling it or draining its exception."""
         future = self._pending_requests.pop(message_id, None)
         if future and not future.done():
             future.cancel()
+        elif future and not future.cancelled():
+            # A done future may hold the exception reset_connection set on it;
+            # retrieve it here so dropping the last reference doesn't log an
+            # ERROR-level "Future exception was never retrieved" at GC.
+            future.exception()
 
     def register_event_response(
         self, message_id: int
@@ -133,10 +138,13 @@ class WebSocketConnectionState:
         return self._event_responses.pop(message_id, None)
 
     def cancel_event_response(self, message_id: int) -> None:
-        """Cancel a stored event future."""
+        """Remove a pending event future, cancelling it or draining its exception."""
         future = self._event_responses.pop(message_id, None)
         if future and not future.done():
             future.cancel()
+        elif future and not future.cancelled():
+            # Same GC guard as cancel_pending_request above.
+            future.exception()
 
     def store_auth_message(self, message_type: str, data: dict[str, Any]) -> None:
         """Store an authentication handshake message."""
@@ -757,6 +765,12 @@ class HomeAssistantWebSocketClient:
             self.cancel_pending_response(message_id)
             self.cancel_event_response(message_id)
             raise
+        except BaseException:
+            # Cancellation mid-send: skips the clause above and would leave BOTH
+            # registrations behind — drop them before propagating.
+            self.cancel_pending_response(message_id)
+            self.cancel_event_response(message_id)
+            raise
 
         try:
             result_response = await asyncio.wait_for(
@@ -780,7 +794,12 @@ class HomeAssistantWebSocketClient:
 
         try:
             event_response = await asyncio.wait_for(event_future, timeout=wait_timeout)
-        except TimeoutError:
+        except BaseException:
+            # A cancelled caller leaves the event registration in
+            # _event_responses until an event with this id arrives, which
+            # nothing sends once the caller is gone. The cleanup is
+            # exception-type-independent and the original exception re-raises
+            # unchanged.
             self.cancel_event_response(message_id)
             raise
 
@@ -832,10 +851,19 @@ class HomeAssistantWebSocketClient:
         except Exception:
             self.cancel_pending_response(message_id)
             raise
+        except BaseException:
+            # Cancellation mid-send: skips the clause above and would leave the
+            # pending future registered — drop it before propagating.
+            self.cancel_pending_response(message_id)
+            raise
 
         try:
             response = await asyncio.wait_for(future, timeout=30.0)
-        except TimeoutError:
+        except BaseException:
+            # A cancelled caller leaks the pending future, which nothing ever
+            # resolves once the caller is gone. The cleanup is
+            # exception-type-independent and the original exception re-raises
+            # unchanged.
             self.cancel_pending_response(message_id)
             raise
 
@@ -927,10 +955,21 @@ class HomeAssistantWebSocketClient:
             self._state.unregister_subscription_queue(message_id)
             self.cancel_pending_response(message_id)
             raise
+        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.
+            self._state.unregister_subscription_queue(message_id)
+            self.cancel_pending_response(message_id)
+            raise
 
         try:
             response = await asyncio.wait_for(result_future, timeout=timeout)
-        except TimeoutError:
+        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.
             self._state.unregister_subscription_queue(message_id)
             self.cancel_pending_response(message_id)
             raise

{ha_mcp_dev-8.3.0.dev2465 → ha_mcp_dev-8.3.0.dev2467}/src/ha_mcp/tools/auto_backup.py

@@ -32,6 +32,8 @@ import logging
 from collections.abc import Awaitable, Callable
 from typing import Any
 
+from fastmcp.exceptions import ToolError
+
 from ..backup_manager import (
     _CAPTURE_TRANSIENT_ERRORS,
     MandatoryBackupError,
@@ -51,6 +53,48 @@ logger = logging.getLogger(__name__)
 _DECORATOR_TRANSIENT_ERRORS = _CAPTURE_TRANSIENT_ERRORS
 
 
+def _component_not_installed_cause(err: BaseException) -> ToolError | None:
+    """Return the ``COMPONENT_NOT_INSTALLED`` ToolError behind a capture failure.
+
+    A mandatory pre-write snapshot reads the current content through the same
+    File & YAML Tools services the wrapped write needs, so on an install
+    without that config entry the capture fails FIRST and the write would be
+    refused as ``BACKUP_CAPTURE_FAILED`` — burying the actionable "add the
+    entry" guidance one level deep (#2292). Walk the cause chain for the
+    original structured error so the caller can surface it unchanged: retrying
+    the backup cannot succeed, and the remediation is the component's, not the
+    backup pipeline's.
+    """
+    seen: set[int] = set()
+    # Worklist over BOTH chain links: an explicit ``raise ... from other``
+    # sets an unrelated ``__cause__`` while the component error stays in
+    # ``__context__`` — following only one link per node would miss it.
+    stack: list[BaseException] = [
+        link for link in (err.__cause__, err.__context__) if link is not None
+    ]
+    while stack:
+        cause = stack.pop()
+        if id(cause) in seen:
+            continue
+        seen.add(id(cause))
+        if isinstance(cause, ToolError):
+            try:
+                payload = json.loads(str(cause))
+            except (TypeError, ValueError):
+                payload = None
+            if (
+                isinstance(payload, dict)
+                and isinstance(payload.get("error"), dict)
+                and payload["error"].get("code")
+                == ErrorCode.COMPONENT_NOT_INSTALLED.value
+            ):
+                return cause
+        stack.extend(
+            link for link in (cause.__cause__, cause.__context__) if link is not None
+        )
+    return None
+
+
 def _resolve_str(value: Any) -> str:
     """Stringify a kwarg value defensively. ``None`` → empty string."""
     if value is None:
@@ -288,6 +332,27 @@ async def _capture_pre_write_snapshot(
             # wrapped write never runs, so nothing has been changed.
             # The ToolError this raises propagates rather than being
             # swallowed by the best-effort handler below.
+            component_error = _component_not_installed_cause(err)
+            if component_error is not None:
+                # The capture failed because the File & YAML Tools entry is
+                # not set up — the same reason the wrapped write itself would
+                # refuse. Surface that actionable error (add the entry), not a
+                # backup complaint (#2292). The write is still blocked. ``from
+                # None`` because this IS the underlying error being unwrapped;
+                # chaining it back onto the wrapper it came out of would only
+                # print the chain twice (and B904 wants the intent explicit).
+                # ``from None`` also drops the wrapper's own text from the
+                # traceback, so record it here or the only account of WHICH
+                # mandatory capture was re-pointed at the component error is
+                # gone.
+                logger.warning(
+                    "Auto-backup: mandatory capture for '%s' failed (%s) — "
+                    "surfacing the underlying component error instead; the "
+                    "write is blocked either way",
+                    func.__name__,
+                    err,
+                )
+                raise component_error from None
             raise_tool_error(
                 create_error_response(
                     ErrorCode.BACKUP_CAPTURE_FAILED,

{ha_mcp_dev-8.3.0.dev2465 → ha_mcp_dev-8.3.0.dev2467}/src/ha_mcp/tools/smart_search/_deep.py

@@ -238,6 +238,7 @@ class DeepSearchMixin(SceneSearchMixin):
             # search is not requested.
             scene_stats: dict[str, Any] = {
                 "failed": 0,
+                "yaml_skipped": 0,
                 "skipped": 0,
                 "timeout": 0,
                 "integration_skipped": 0,
@@ -316,6 +317,7 @@ class DeepSearchMixin(SceneSearchMixin):
                 (
                     results["scenes"],
                     scene_stats["failed"],
+                    scene_stats["yaml_skipped"],
                     scene_stats["skipped"],
                     scene_stats["integration_skipped"],
                     scene_stats["registry_failed"],
@@ -1327,6 +1329,7 @@ class DeepSearchMixin(SceneSearchMixin):
             scene_body_incomplete=bool(
                 scene_stats.get("skipped")
                 or scene_stats.get("failed")
+                or scene_stats.get("yaml_skipped")
                 or scene_stats.get("timeout")
             ),
             automation_skipped=automation_skipped,
@@ -1492,7 +1495,9 @@ class DeepSearchMixin(SceneSearchMixin):
                     "endpoint returned 404 — these are likely YAML-defined "
                     f"{noun}s that the {endpoint} REST endpoint does not "
                     "expose) — their match status is unknown; this result "
-                    "is not exhaustive."
+                    "is not exhaustive. Their definitions live outside HA "
+                    f"storage (typically {noun}s.yaml); check there if the "
+                    "match matters."
                 )
             if timeout:
                 reasons.append(

{ha_mcp_dev-8.3.0.dev2465 → ha_mcp_dev-8.3.0.dev2467}/src/ha_mcp/tools/smart_search/_scenes.py

@@ -4,6 +4,11 @@ import asyncio
 import logging
 from typing import Any
 
+from ...client.rest_client import (
+    HomeAssistantAPIError,
+    SceneResolution,
+    SceneStorageConfigNotFoundError,
+)
 from ._config import (
     ENTITY_REGISTRY_TIMEOUT,
     INDIVIDUAL_CONFIG_TIMEOUT,
@@ -212,6 +217,112 @@ class SceneSearchMixin(ConfigFetchMixin):
         )
         return scene_id
 
+    async def _fetch_one_scene_config(
+        self,
+        sid: str,
+        slug_to_storage_id: dict[str, str],
+        failed_errors: list[str],
+        *,
+        registry_failed: bool,
+    ) -> tuple[str, dict[str, Any] | None, str | None]:
+        """Fetch one scene's storage config and classify the outcome.
+
+        Extracted from ``_deep_search_scenes``'s Attempt-C fetch closure
+        (C901). Returns ``(sid, config-or-None, marker)`` where the marker is
+        the ``_individual_fetch_budgeted`` classification: ``None`` (success),
+        ``"yaml_skipped"``, ``"timeout"`` or ``"failed"``.
+        """
+        # Hand the client the resolution this scan already made instead of the
+        # bare storage key. The client's own resolver treats its input as an
+        # entity-id slug ("scene.<input>" registry/state lookups), so a bare
+        # storage key that differs from the name-derived slug misses BOTH
+        # lookups and every not-a-storage-scene 404 degrades to the bare
+        # "vanished" case — round-6 of #2302's no-component lane caught exactly
+        # that on the seeded YAML-with-id scene. Passing the resolution keeps
+        # the 404 classification working AND drops the per-scene registry
+        # round-trip the internal re-resolve used to pay.
+        #
+        # ONLY when the registry walk succeeded, though: on the failed walk the
+        # map is empty, and a synthesized (sid, registry_hit=False) resolution
+        # would suppress the client's own per-scene resolver — which may work
+        # again by fetch time on a transient list failure, and is the only way
+        # a UI-renamed storage scene (storage key != slug) can still resolve.
+        # Leaving resolution unset there restores the pre-#2302 per-scene
+        # resolve for exactly that path (Codex review on #2302).
+        resolution = (
+            None
+            if registry_failed
+            else SceneResolution(
+                storage_key=slug_to_storage_id.get(sid, sid),
+                registry_hit=sid in slug_to_storage_id,
+                platform=None,
+            )
+        )
+        try:
+            config_resp = await asyncio.wait_for(
+                # Fetch by STORAGE key (what the endpoint indexes on),
+                # return under the SLUG (what the scoring pass looks up).
+                self.client.get_scene_config(sid, resolution=resolution),
+                timeout=INDIVIDUAL_CONFIG_TIMEOUT,
+            )
+            return (sid, config_resp.get("config", {}), None)
+        except SceneStorageConfigNotFoundError as e:
+            # The entity EXISTS, it is just not an editable storage scene:
+            # a YAML-defined scene carrying an ``id:`` (which registers
+            # under platform ``homeassistant`` exactly like a storage
+            # scene, so the registry walk cannot pre-filter it), an
+            # ``id``-less YAML scene the client confirmed through the state
+            # machine, or an integration-managed (Hue/deCONZ/...) scene.
+            # The client decides that classification itself
+            # (``_raise_scene_config_404``) from the registry/state lookups
+            # it makes for the fetch, independently of the search-side
+            # registry filter — which is why this branch stays correct on
+            # the registry-failed attempt-all path, where integration-
+            # managed scenes DO reach the fetch. Every one of them is a
+            # structural gap rather than a fetch outage, so classify it the
+            # way the automation/script fetchers do (#2292).
+            logger.debug(
+                f"Scene individual config fetch ({sid}) returned 404 "
+                f"— not a storage scene: {e}"
+            )
+            return (sid, None, "yaml_skipped")
+        except HomeAssistantAPIError as e:
+            if e.status_code == 404:
+                # A bare 404 (not the subclass above) means the entity is in
+                # neither the registry nor the state machine: it vanished
+                # between get_states() and this fetch. That IS a real gap in
+                # this result, so it belongs in the failed bucket with a
+                # representative sample.
+                logger.debug(
+                    f"Scene individual config fetch ({sid}) returned 404 "
+                    "— entity no longer exists since enumeration."
+                )
+            else:
+                logger.debug(f"Scene individual config fetch ({sid}) failed: {e}")
+            record_first_failure(failed_errors, e)
+            return (sid, None, "failed")
+        except TimeoutError:
+            # Per-request timeout under batch concurrency — distinct
+            # from a real failure; see _fetch_automation_config
+            # (#1784).
+            logger.debug(
+                f"Scene individual config fetch ({sid}) timed out "
+                f"after {INDIVIDUAL_CONFIG_TIMEOUT}s."
+            )
+            return (sid, None, "timeout")
+        except Exception as e:
+            if is_timeout_error(e):
+                # Client-side HTTP timeout arrived wrapped; still a
+                # timeout. See is_timeout_error in _fetch.
+                logger.debug(
+                    f"Scene individual config fetch ({sid}) timed "
+                    f"out (client-side HTTP timeout): {e}"
+                )
+                return (sid, None, "timeout")
+            logger.debug(f"Scene individual config fetch ({sid}) failed: {e}")
+            record_first_failure(failed_errors, e)
+            return (sid, None, "failed")
+
     async def _deep_search_scenes(
         self,
         all_entities: list[dict[str, Any]],
@@ -222,19 +333,19 @@ class SceneSearchMixin(ConfigFetchMixin):
         prefetched_registry: Any = None,
         storage_ids_out: dict[str, str] | None = None,
         graph_entity_ids: set[str] | None = None,
-    ) -> tuple[list[dict[str, Any]], int, int, int, bool, int, str | None]:
+    ) -> tuple[list[dict[str, Any]], int, int, int, int, bool, int, str | None]:
         """Deep-search scenes: per-id fetch plus registry-walk augmentation.
 
         Scenes have no listing primitive, so entities are enumerated from
         get_states() and configs fetched per id. Returns the scene results plus
-        the six diagnostic signals feeding the response ``partial`` /
+        the seven diagnostic signals feeding the response ``partial`` /
         ``partial_reason``:
-        ``(results, failed_count, skipped_count, integration_skipped,
-        registry_failed, timeout_count, failed_sample)``. ``failed_sample``
-        is one representative ``summarize_fetch_error`` summary of a
-        ``failed``-class exception (``None`` when none occurred) — see the
-        automation/script mirror in ``_deep_search_automations`` (#1784
-        follow-up).
+        ``(results, failed_count, yaml_skipped_count, skipped_count,
+        integration_skipped, registry_failed, timeout_count, failed_sample)``.
+        ``failed_sample`` is one representative ``summarize_fetch_error``
+        summary of a ``failed``-class exception (``None`` when none occurred)
+        — see the automation/script mirror in ``_deep_search_automations``
+        (#1784 follow-up).
         """
         scene_entities = [
             e for e in all_entities if e.get("entity_id", "").startswith("scene.")
@@ -263,13 +374,14 @@ class SceneSearchMixin(ConfigFetchMixin):
         ) = await self._walk_scene_registry(prefetched_registry=prefetched_registry)
         # Hand the slug-to-storage-key map back to deep_search, which needs it
         # to give reference-graph scene hits their real storage key. An out
-        # parameter rather than an eighth return value: the one production
+        # parameter rather than a ninth return value: the one production
         # caller and the one test that drive this function unpack its tuple
         # positionally.
         if storage_ids_out is not None:
             storage_ids_out.update(slug_to_storage_id)
 
         failed_count = 0
+        yaml_skipped_count = 0
         skipped_count = 0
         integration_skipped = 0
         timeout_count = 0
@@ -290,45 +402,15 @@ class SceneSearchMixin(ConfigFetchMixin):
         async def _fetch_scene_config(
             sid: str,
         ) -> tuple[str, dict[str, Any] | None, str | None]:
-            try:
-                config_resp = await asyncio.wait_for(
-                    # Fetch by STORAGE key (what the endpoint indexes on),
-                    # return under the SLUG (what the scoring pass looks up).
-                    self.client.get_scene_config(slug_to_storage_id.get(sid, sid)),
-                    timeout=INDIVIDUAL_CONFIG_TIMEOUT,
-                )
-                return (sid, config_resp.get("config", {}), None)
-            except TimeoutError:
-                # Per-request timeout under batch concurrency — distinct
-                # from a real failure; see _fetch_automation_config
-                # (#1784).
-                logger.debug(
-                    f"Scene individual config fetch ({sid}) timed out "
-                    f"after {INDIVIDUAL_CONFIG_TIMEOUT}s."
-                )
-                return (sid, None, "timeout")
-            except Exception as e:
-                if is_timeout_error(e):
-                    # Client-side HTTP timeout arrived wrapped; still a
-                    # timeout. See is_timeout_error in _fetch.
-                    logger.debug(
-                        f"Scene individual config fetch ({sid}) timed "
-                        f"out (client-side HTTP timeout): {e}"
-                    )
-                    return (sid, None, "timeout")
-                logger.debug(f"Scene individual config fetch ({sid}) failed: {e}")
-                record_first_failure(failed_errors, e)
-                return (sid, None, "failed")
+            return await self._fetch_one_scene_config(
+                sid, slug_to_storage_id, failed_errors, registry_failed=registry_failed
+            )
 
         (
             fetched_configs,
             failed_count,
             skipped_count,
-            # Scene YAML/integration-managed pre-classification happens
-            # upstream via `_walk_scene_registry`; the 4th tuple slot
-            # from `_individual_fetch_budgeted` is therefore expected
-            # to stay at zero on this path.
-            _scene_yaml_skipped,
+            yaml_skipped_count,
             timeout_count,
         ) = await self._individual_fetch_budgeted(
             sids_to_fetch,
@@ -365,6 +447,7 @@ class SceneSearchMixin(ConfigFetchMixin):
         return (
             scene_results,
             failed_count,
+            yaml_skipped_count,
             skipped_count,
             integration_skipped,
             registry_failed,
@@ -392,9 +475,11 @@ class SceneSearchMixin(ConfigFetchMixin):
         failed = scene_stats["failed"]
         skipped = scene_stats["skipped"]
         # .get(): tolerate older callers/tests that build the stats dict
-        # without the timeout key (added for #1784).
+        # without the timeout key (added for #1784) or without the
+        # yaml_skipped key (added for #2292).
         timeout = scene_stats.get("timeout", 0)
-        if not (failed or skipped or timeout):
+        yaml_skipped = scene_stats.get("yaml_skipped", 0)
+        if not (failed or yaml_skipped or skipped or timeout):
             return
         response["partial"] = True
         reason_parts: list[str] = []
@@ -414,6 +499,25 @@ class SceneSearchMixin(ConfigFetchMixin):
                 f"their match status is unknown; this result is not "
                 f"exhaustive.{hint}"
             )
+        if yaml_skipped:
+            # Structural, not transient, and two kinds land here: a YAML-defined
+            # scene with an ``id:`` is indistinguishable from a storage scene in
+            # the entity registry, so it survives the integration-platform
+            # filter and then 404s on the per-id endpoint; and on the
+            # registry-failed attempt-all path integration-managed scenes reach
+            # the fetch and 404 the same way. Name both so the reader knows
+            # where the definition actually lives. Mirrors the
+            # automation/script fragment in ``_apply_per_type_partial_flag``
+            # (#2292).
+            reason_parts.append(
+                f"{yaml_skipped} scene(s) not scanned (per-id config endpoint "
+                "returned 404 — these are YAML-defined scenes, or "
+                "integration-managed scenes, which that endpoint does not "
+                "expose) — their match status is unknown; this result is not "
+                "exhaustive. Their definitions live outside HA storage "
+                "(typically scenes.yaml or the owning integration); check "
+                "there if the match matters."
+            )
         if timeout:
             reason_parts.append(
                 f"{timeout} scene(s) not scanned (per-id fetch timed out "
@@ -446,8 +550,13 @@ class SceneSearchMixin(ConfigFetchMixin):
         if scene_stats["registry_failed"]:
             # Issue #1168 R5 blocker 11: when the registry fetch errors, the
             # integration-platform filter is unavailable and Attempt C falls
-            # back to attempting all scenes -- surface that so an elevated
-            # failed_count isn't mistaken for a real config outage.
+            # back to attempting all scenes -- surface that so the elevated
+            # counts aren't mistaken for a real config outage. Since the 404
+            # taxonomy split (#2292) the bucket that swells here is
+            # ``yaml_skipped``, not ``failed``: the REST client classifies an
+            # integration-managed scene's 404 as
+            # ``SceneStorageConfigNotFoundError`` from its own registry/state
+            # lookups, which this path's failed registry walk does not affect.
             reason_parts.append(
                 "Entity-registry fetch failed; integration-platform filter "
                 "unavailable, attempted all scenes (false-positive failures "