ha-mcp-dev 7.5.0.dev571__tar.gz → 7.5.0.dev573__tar.gz

{ha_mcp_dev-7.5.0.dev571/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.5.0.dev573}/PKG-INFO

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.5.0.dev571"
+version = "7.5.0.dev573"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 requires-python = ">=3.13,<3.14"

{ha_mcp_dev-7.5.0.dev571 → ha_mcp_dev-7.5.0.dev573}/src/ha_mcp/client/rest_client.py

@@ -895,8 +895,6 @@ class HomeAssistantClient:
         Raises:
             HomeAssistantAPIError: If configuration invalid or API error
         """
-        import time
-
         # Generate unique_id for new automation if not provided
         if identifier is None:
             unique_id = str(int(time.time() * 1000))
@@ -964,51 +962,51 @@ class HomeAssistantClient:
                 ) from e
             raise
 
-    # 3-attempt × 6s upper-bound budget; first poll 0.025s is a 5×
-    # cushion above the ~4ms HA-Core entity-registration latency
-    # measured by ``test_poll_cadence_measurement.py`` (#1389 — p50
-    # 104.1-104.8 ms on the prior 0.1s first-poll, all from the sleep
-    # itself with ~4 ms of real registration work).
-    _POLL_CADENCE: tuple[float, ...] = (0.025, 1.0, 4.975)
+    # Upper-bound budget for the WS-driven discovery wait (and its REST
+    # fallback). Preserves the 6s ceiling PR #1384 tuned for the legacy
+    # cadence loop; the WS path resolves in <1s on the happy path because
+    # ``state_changed`` fires as soon as HA hydrates the new entity. The
+    # cadence tuple itself is gone — uniform polling at ``poll_interval``
+    # is fine when the WS happy path is the primary route. #1389's
+    # cadence-measurement instrumentation also retired with the loop;
+    # the WS waiter logs `time.monotonic()` elapsed via its own debug
+    # line at ``util_helpers._ws_wait_for_condition``.
+    _POLL_BUDGET_S: float = 6.0
 
     async def _poll_for_automation_entity(self, unique_id: str) -> str | None:
-        """Poll HA state to find the entity_id assigned to a newly created automation."""
-        # Measure cumulative elapsed from function entry to first successful match.
-        # Feeds the #1389 p50/p99 validation of `_POLL_CADENCE`.
-        start_monotonic = time.monotonic()
+        """Discover the entity_id assigned to a newly created automation.
+
+        Delegates to ``wait_for_automation_entity_by_unique_id`` which uses
+        a ``state_changed`` WebSocket subscription filtered on
+        ``new_state.attributes.id == unique_id`` and falls back to REST
+        polling of ``get_states()`` when the WebSocket is unavailable.
+        See #1152 / #1395 for context.
+        """
+        # Local import: ``util_helpers`` imports from ``rest_client`` for
+        # the typed-error classes, so a module-level import here would be
+        # circular. Mirrors the same pattern in ``_get_waiter_ws_client``.
+        from ..tools.util_helpers import wait_for_automation_entity_by_unique_id
+
         try:
-            for sleep_time in self._POLL_CADENCE:
-                await asyncio.sleep(sleep_time)
-                states = await self.get_states()
-                for state in states:
-                    if not state.get("entity_id", "").startswith("automation."):
-                        continue
-                    if state.get("attributes", {}).get("id") == unique_id:
-                        entity_id = state.get("entity_id")
-                        elapsed_ms = (time.monotonic() - start_monotonic) * 1000.0
-                        logger.debug(
-                            "entity-registration-elapsed: %.1fms "
-                            "(unique_id=%s, entity_id=%s)",
-                            elapsed_ms,
-                            unique_id,
-                            entity_id,
-                        )
-                        return entity_id
+            entity_id = await wait_for_automation_entity_by_unique_id(
+                self, unique_id, timeout=self._POLL_BUDGET_S
+            )
         except HomeAssistantError as e:
             # Narrow catch: programming bugs (TypeError/KeyError/etc.) propagate.
             # Mirrors test-side _POLLING_TRANSIENT_ERRORS in
             # tests/src/e2e/utilities/wait_helpers.py and styleguide §
             # "Exception Handling in Test Polling Loops".
             logger.warning(
-                f"Failed to query actual entity_id for unique_id {unique_id}: {e}",
+                f"Failed to discover entity_id for unique_id {unique_id}: {e}",
                 exc_info=True,
             )
             return None
 
-        logger.warning(
-            f"Automation with unique_id {unique_id} was not found in HA state after creation"
-        )
-        return None
+        if entity_id is not None:
+            logger.debug(
+                f"Found actual entity_id for unique_id {unique_id}: {entity_id}"
+            )
+        return entity_id
 
     async def delete_automation_config(self, identifier: str) -> dict[str, Any]:
         """

{ha_mcp_dev-7.5.0.dev571 → ha_mcp_dev-7.5.0.dev573}/src/ha_mcp/client/websocket_client.py

@@ -400,7 +400,18 @@ class HomeAssistantWebSocketClient:
                 try:
                     await handler(data["event"])
                 except Exception as e:
-                    logger.error(f"Error in event handler: {e}")
+                    # ``exc_info=True`` so handler bugs (AttributeError /
+                    # KeyError / TypeError from schema-drift on the
+                    # incoming event payload) leave a traceback rather
+                    # than a one-line obscured error. Without this the
+                    # dispatch loop keeps a single buggy handler from
+                    # killing the WS, but the bug itself becomes
+                    # invisible — handlers wired to ``asyncio.Event``
+                    # nudges (see ``util_helpers._ws_wait_for_condition``)
+                    # silently stop nudging and the calling waiter times
+                    # out reporting "not found." #1395 silent-failure
+                    # audit.
+                    logger.error("Error in event handler: %s", e, exc_info=True)
 
     def _ensure_send_lock(self) -> None:
         """Ensure the send lock belongs to the current event loop."""

{ha_mcp_dev-7.5.0.dev571 → ha_mcp_dev-7.5.0.dev573}/src/ha_mcp/tools/tools_config_automations.py

@@ -56,11 +56,10 @@ logger = logging.getLogger(__name__)
 
 # Distinctive prefix of the soft-failure warning emitted by
 # ``ha_config_set_automation`` when ``_poll_for_automation_entity``
-# exhausts ``_POLL_CADENCE`` without matching the new automation.
-# Exported so tests (e.g. ``test_poll_cadence_measurement.py``) can
-# detect a missed registration without hard-coding the literal —
-# rewording the warning becomes a compile-time coupling rather than
-# a silent test drift.
+# exhausts its budget (``_POLL_BUDGET_S``) without resolving the new
+# automation's entity_id. Exported so future tests can detect a missed
+# registration without hard-coding the literal — rewording the warning
+# becomes a compile-time coupling rather than a silent test drift.
 NOT_VERIFIED_WARNING_PREFIX = (
     "Automation was submitted to Home Assistant but the entity was not found"
 )

{ha_mcp_dev-7.5.0.dev571 → ha_mcp_dev-7.5.0.dev573}/src/ha_mcp/tools/util_helpers.py

@@ -614,7 +614,7 @@ costs at most ~6 REST calls per wait (one post-subscribe sample plus
 
 
 async def _legacy_poll_until(
-    entity_id: str,
+    identifier: str,
     sample: Callable[[], Awaitable[Any]],
     *,
     timeout: float,
@@ -627,7 +627,10 @@ async def _legacy_poll_until(
     backstop tick — it returns a truthy value when the wait should
     succeed, ``None`` otherwise. Connection / auth errors propagate
     (callers care about those); other transient errors raised inside
-    ``sample`` are swallowed there.
+    ``sample`` are swallowed there. ``identifier`` is the human-readable
+    name used in log lines — usually an entity_id but may be a
+    descriptor like ``automation[unique_id=...]`` for discovery waits
+    that don't know the entity_id up front.
     """
     start = time.monotonic()
     while time.monotonic() - start < timeout:
@@ -635,7 +638,7 @@ async def _legacy_poll_until(
             result = await sample()
             if result is not None:
                 logger.debug(
-                    f"REST waiter: {description} for {entity_id} resolved "
+                    f"REST waiter: {description} for {identifier} resolved "
                     f"after {time.monotonic() - start:.2f}s"
                 )
                 return result
@@ -643,7 +646,7 @@ async def _legacy_poll_until(
             raise
         await asyncio.sleep(poll_interval)
     logger.warning(
-        f"REST fallback: {description} for {entity_id} timed out after {timeout}s"
+        f"REST fallback: {description} for {identifier} timed out after {timeout}s"
     )
     return None
 
@@ -690,22 +693,23 @@ async def _get_waiter_ws_client(client: Any) -> Any:
 
 async def _ws_wait_for_condition(
     client: Any,
-    entity_id: str,
+    identifier: str,
     sample: Callable[[], Awaitable[Any]],
     *,
     event_types: tuple[str, ...],
     timeout: float,
     poll_interval: float,
     description: str,
+    event_filter: Callable[[dict[str, Any]], bool] | None = None,
 ) -> Any:
     """Subscribe to ``event_types``, sample after subscribe, wait on event.
 
     Implements the standard "subscribe → sample → wait" pattern from #1152:
 
     - The handler nudges a single ``asyncio.Event`` whenever HA pushes an
-      event for our ``entity_id``. The main loop wakes on that nudge or on
-      the polling-backstop timeout, then re-runs ``sample`` (the REST
-      source-of-truth check) to decide whether the wait succeeded.
+      event matching ``event_filter``. The main loop wakes on that nudge
+      or on the polling-backstop timeout, then re-runs ``sample`` (the
+      REST source-of-truth check) to decide whether the wait succeeded.
     - Sample-after-subscribe (not before) closes the gap between the
       caller's write returning and our subscription landing on the HA
       side. The event for the write may have already fired by the time we
@@ -714,12 +718,22 @@ async def _ws_wait_for_condition(
       we fall back to ``_legacy_poll_until``. The helpers' contract is
       identical to the pre-#1152 REST loop in that case.
 
+    ``identifier`` is used only for log lines — usually an entity_id but
+    may be a descriptor like ``automation[unique_id=...]`` for discovery
+    waits (#1395) that don't know the entity_id up front. When
+    ``event_filter`` is None the default predicate matches events whose
+    ``data["entity_id"]`` equals ``identifier`` — i.e. the standard
+    "watch this entity_id" shape used by ``wait_for_entity_*`` /
+    ``wait_for_state_change``. Callers that need a different match shape
+    (e.g. "any automation with attributes.id == unique_id") pass a custom
+    ``event_filter``.
+
     Returns ``sample``'s truthy return value, or ``None`` on timeout.
     """
     ws_client = await _get_waiter_ws_client(client)
     if ws_client is None:
         return await _legacy_poll_until(
-            entity_id,
+            identifier,
             sample,
             timeout=timeout,
             poll_interval=poll_interval,
@@ -728,14 +742,19 @@ async def _ws_wait_for_condition(
 
     nudge = asyncio.Event()
 
-    async def handler(event: dict[str, Any]) -> None:
+    def _default_filter(event: dict[str, Any]) -> bool:
         # HA nests ``entity_id`` under ``event["data"]`` for both
         # state_changed and entity_registry_updated. The top-level fallback
         # is defensive only — it lets a future schema drift degrade to a
         # missed nudge rather than an AttributeError.
         data = event.get("data") or {}
         evt_entity = data.get("entity_id") or event.get("entity_id")
-        if evt_entity == entity_id:
+        return bool(evt_entity == identifier)
+
+    filter_fn = event_filter if event_filter is not None else _default_filter
+
+    async def handler(event: dict[str, Any]) -> None:
+        if filter_fn(event):
             nudge.set()
 
     # Track which handlers / subscriptions we actually attached so cleanup
@@ -763,11 +782,11 @@ async def _ws_wait_for_condition(
                     "falling back to REST polling",
                     et,
                     description,
-                    entity_id,
+                    identifier,
                     e,
                 )
                 return await _legacy_poll_until(
-                    entity_id,
+                    identifier,
                     sample,
                     timeout=timeout,
                     poll_interval=poll_interval,
@@ -782,7 +801,7 @@ async def _ws_wait_for_condition(
             result = await sample()
             if result is not None:
                 logger.debug(
-                    f"WS waiter: {description} for {entity_id} resolved by "
+                    f"WS waiter: {description} for {identifier} resolved by "
                     f"post-subscribe sample after {time.monotonic() - start:.2f}s"
                 )
                 return result
@@ -798,13 +817,13 @@ async def _ws_wait_for_condition(
                 "WS connection dropped before wait loop for %s on %s — "
                 "completing via REST polling",
                 description,
-                entity_id,
+                identifier,
             )
             remaining = timeout - (time.monotonic() - start)
             if remaining <= 0:
                 return None
             return await _legacy_poll_until(
-                entity_id,
+                identifier,
                 sample,
                 timeout=remaining,
                 poll_interval=poll_interval,
@@ -834,13 +853,13 @@ async def _ws_wait_for_condition(
                     "WS connection dropped during %s for %s — completing "
                     "wait via REST polling",
                     description,
-                    entity_id,
+                    identifier,
                 )
                 remaining = timeout - (time.monotonic() - start)
                 if remaining <= 0:
                     return None
                 return await _legacy_poll_until(
-                    entity_id,
+                    identifier,
                     sample,
                     timeout=remaining,
                     poll_interval=poll_interval,
@@ -851,7 +870,7 @@ async def _ws_wait_for_condition(
                 result = await sample()
                 if result is not None:
                     logger.debug(
-                        f"WS waiter: {description} for {entity_id} resolved "
+                        f"WS waiter: {description} for {identifier} resolved "
                         f"after {time.monotonic() - start:.2f}s"
                     )
                     return result
@@ -859,7 +878,7 @@ async def _ws_wait_for_condition(
                 raise
 
         logger.warning(
-            f"WS waiter: {description} for {entity_id} timed out after {timeout}s"
+            f"WS waiter: {description} for {identifier} timed out after {timeout}s"
         )
         return None
     finally:
@@ -1084,6 +1103,132 @@ async def wait_for_state_change(
     return None
 
 
+async def wait_for_automation_entity_by_unique_id(
+    client: Any,
+    unique_id: str,
+    timeout: float = 6.0,
+    poll_interval: float = 0.3,
+) -> str | None:
+    """
+    Discover the entity_id assigned to a newly-created automation by unique_id.
+
+    Used after ``POST /config/automation/config/{unique_id}`` to resolve the
+    ``automation.<slug>`` entity_id Home Assistant assigned. Listens to
+    ``state_changed`` events filtered to ``automation.*`` entities whose
+    ``new_state.attributes.id`` equals ``unique_id`` — HA's
+    ``BaseAutomationEntity.capability_attributes`` exposes ``unique_id`` as
+    ``CONF_ID`` on every emit, so the first state event for a fresh
+    automation carries the match. Falls back to REST polling of
+    ``get_states()`` when the WebSocket is unavailable. See #1152 / #1395.
+
+    Args:
+        client: HomeAssistantClient instance
+        unique_id: The unique_id passed to ``POST /config/automation/config/{unique_id}``
+        timeout: Maximum time to wait in seconds (preserves the legacy 6s budget)
+        poll_interval: REST poll interval used for the WS-unavailable fallback
+
+    Returns:
+        The discovered entity_id (e.g. ``"automation.morning_routine"``)
+        or ``None`` on timeout.
+    """
+    # Mutable closure cells: ``entity_id`` stashes the discovered
+    # entity_id when the filter sees a matching event (sample() then
+    # short-circuits the full get_states() scan). ``last_api_error``
+    # tracks the most recent transient API failure during sampling so
+    # the final timeout warning can distinguish "automation truly not
+    # found" from "REST channel wedged the whole budget."
+    captured: dict[str, str | None] = {"entity_id": None, "last_api_error": None}
+
+    async def sample() -> str | None:
+        if captured["entity_id"] is not None:
+            return captured["entity_id"]
+        try:
+            states = await client.get_states()
+        except HomeAssistantAPIError as e:
+            # Debug-level here is intentional — the waiter retries on
+            # transient errors. The wedged-channel signal goes in the
+            # final timeout warning via ``captured["last_api_error"]``.
+            logger.debug(
+                f"API error sampling get_states() for unique_id {unique_id}: {e}"
+            )
+            captured["last_api_error"] = str(e)
+            return None
+        for state in states:
+            entity_id = state.get("entity_id")
+            if not isinstance(entity_id, str) or not entity_id.startswith(
+                "automation."
+            ):
+                continue
+            if state.get("attributes", {}).get("id") == unique_id:
+                return entity_id
+        return None
+
+    def event_filter(event: dict[str, Any]) -> bool:
+        # state_changed payload shape:
+        #   event["data"] = {"entity_id": ..., "new_state": {"attributes": {...}}}
+        # capability_attributes on BaseAutomationEntity guarantees attributes.id
+        # carries the unique_id on the first state emission (the caller has
+        # always just POSTed /config/automation/config/{unique_id}, so
+        # unique_id is non-None by construction).
+        #
+        # Defensive ``isinstance`` guards mirror the ``sample()`` callback
+        # above — the WS dispatcher swallows handler exceptions broadly
+        # (``websocket_client.py``'s ``except Exception`` in the dispatch
+        # loop), so a malformed payload reaching ``.startswith`` here would
+        # silently fail to nudge and the wait would time out reporting
+        # "not found" when the real cause was schema drift. Same shape-
+        # hardening pattern as ``sample()``.
+        data = event.get("data") or {}
+        evt_entity = data.get("entity_id")
+        if not isinstance(evt_entity, str) or not evt_entity.startswith("automation."):
+            return False
+        new_state = data.get("new_state") or {}
+        attrs = new_state.get("attributes") if isinstance(new_state, dict) else None
+        if not isinstance(attrs, dict) or attrs.get("id") != unique_id:
+            return False
+        # Guard against last-writer-wins: if two events for matching
+        # automations arrived (HA storage forbids duplicate unique_id, but
+        # don't coin-flip silently if it ever happens), keep the first
+        # observed entity_id and log the collision.
+        if captured["entity_id"] is None:
+            captured["entity_id"] = evt_entity
+        elif captured["entity_id"] != evt_entity:
+            logger.warning(
+                "Duplicate automation match for unique_id %s: %s already "
+                "captured, ignoring %s",
+                unique_id,
+                captured["entity_id"],
+                evt_entity,
+            )
+        return True
+
+    result = await _ws_wait_for_condition(
+        client,
+        identifier=f"automation[unique_id={unique_id}]",
+        sample=sample,
+        event_types=("state_changed",),
+        timeout=timeout,
+        poll_interval=poll_interval,
+        description="automation entity discovery",
+        event_filter=event_filter,
+    )
+    if isinstance(result, str):
+        return result
+    # `_ws_wait_for_condition` / `_legacy_poll_until` already logged the
+    # generic "timed out" warning before returning None; just surface the
+    # discovery-specific signal when REST sampling was wedged the whole
+    # budget so operators can distinguish "automation never published"
+    # from "REST channel down."
+    if captured["last_api_error"] is not None:
+        logger.warning(
+            "Automation discovery for unique_id %s timed out with every "
+            "REST sample failing; last error: %s",
+            unique_id,
+            captured["last_api_error"],
+        )
+    return None
+
+
 async def fetch_entity_category(client: Any, entity_id: str, scope: str) -> str | None:
     """Fetch a category ID for an entity from the entity registry.
 

{ha_mcp_dev-7.5.0.dev571 → ha_mcp_dev-7.5.0.dev573/src/ha_mcp_dev.egg-info}/PKG-INFO

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