ha-mcp-dev 8.4.3.dev2650__tar.gz → 8.4.3.dev2652__tar.gz

{ha_mcp_dev-8.4.3.dev2650/src/ha_mcp_dev.egg-info → ha_mcp_dev-8.4.3.dev2652}/PKG-INFO

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.4.3.dev2650"
+version = "8.4.3.dev2652"
 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.4.3.dev2650 → ha_mcp_dev-8.4.3.dev2652}/src/ha_mcp/tools/component_config_reads.py

@@ -3,19 +3,14 @@
 Two consumers in the automation/script/scene family pay for a whole-collection
 fetch to answer a single question:
 
-- The set/remove/post-write resolvers (``_resolve_scene_entity_id`` /
-  ``_resolve_automation_entity_id``) map a storage id (a scene's ``unique_id``,
-  an automation's config id) to its live ``entity_id`` — the scene resolver by
-  dumping the ENTIRE ``config/entity_registry/list`` (with a 0.2 s sleep + retry
-  to absorb post-upsert registration lag), the automation resolver by scanning
-  the WHOLE ``get_states()`` state machine. When the component advertises
-  ``entity_lookup``, a single ``ha_mcp_tools/entity_lookup(unique_id=, domain=)``
-  frame returns just the matching registry entries — a hit is authoritative the
-  instant it returns (no settle). An in-process read removes the network latency
-  but NOT HA's async entity-registration lag, so the scene resolver still
-  rechecks an EMPTY result ONCE after the same short delay before its naive
-  fallback (the automation resolver has no post-upsert lag exposure — its only
-  routed call site resolves an already-registered entity before a delete).
+- Entity resolution maps storage keys to live registry entity IDs.
+  ``entity_registration.resolve_entity_id_after_write`` polls after scene/script
+  writes against one deadline. ``_resolve_scene_entity_id`` uses a single retry
+  before scene removal; ``_resolve_automation_entity_id`` resolves an existing
+  entity before deletion. The component's ``entity_lookup`` returns only matching
+  rows instead of a full registry/state listing. A hit is authoritative at once,
+  but an empty read can precede HA's asynchronous entity registration even when
+  performed in-process, so post-write callers must continue polling.
 - The reference validator (``validate_config_references``) fetches BOTH
   ``client.get_services()`` and ``client.get_states()`` on every automation/script
   write purely to build a name index. When the component advertises
@@ -40,16 +35,11 @@ path runs, NEVER propagated out of the read. Neither consumer's legacy path dies
 identically on a pooled-WS drop, so propagating would abort work the legacy path
 still completes:
 
-- ``fetch_entity_lookup_via_component``'s consumers degrade gracefully. The scene
-  resolver's ``config/entity_registry/list`` dump rides
-  ``client.send_websocket_message``, which answers a command HA rejected with
-  ``{"success": False}``, so the resolver walks its retry loop to the naive
-  ``scene.{id}`` fallback (a dead transport raises there instead, #1947) - and
-  the automation resolver scans REST
-  ``get_states()`` and additionally catches broadly → ``None``. Its only routed
-  call sites run AFTER a scene/automation upsert commits or BEFORE a REST delete,
-  so an escaping transport error would report a landed write as failed / abort a
-  delete the REST path would have finished.
+- ``fetch_entity_lookup_via_component`` consumers fall back to the legacy
+  WebSocket registry bridge or REST state reads. The post-write resolver catches
+  known API/transport failures and retains a best-effort entity ID; later wait
+  and category operations report any verification or assignment failure. Removal
+  resolvers retain their own error policies.
 - ``fetch_reference_data_via_component``'s legacy path is the REST
   ``get_services()`` / ``get_states()`` pair; an escaping transport error would
   make ``validate_config_references`` hit its swallow-all fetch guard and skip
@@ -58,9 +48,9 @@ still completes:
 **GET-path invariant:** the automation/script/scene *config-get* tools must never
 route through the component — their in-process ``raw_config`` freshness lags the
 config file between a write and the next completed reload. The resolvers gate the
-whole component branch (caps probe included) behind an explicit ``allow_component``
-flag that only the set/remove/post-write call sites pass, so a get never even
-probes caps. ``TestConfigGetSeam`` pins this.
+whole component branch (caps probe included) behind ``allow_component`` for
+removals. The dedicated post-write resolver is never called from a config-get.
+``TestConfigGetSeam`` pins this.
 """
 
 from __future__ import annotations

ha_mcp_dev-8.4.3.dev2652/src/ha_mcp/tools/entity_registration.py

@@ -0,0 +1,133 @@
+"""Resolve storage keys after writes while Home Assistant registers entities."""
+
+import asyncio
+import logging
+import time
+from typing import Any, Literal
+
+from ..client.rest_client import (
+    HomeAssistantAPIError,
+    HomeAssistantAuthError,
+    HomeAssistantConnectionError,
+)
+from .component_config_reads import fetch_entity_lookup_via_component
+
+logger = logging.getLogger(__name__)
+
+# A bounded registration budget, not a fixed delay: existing entries return on
+# the first lookup. Keep this separate from the subsequent state-availability
+# wait, which cannot discover a name-derived or registry-renamed entity ID.
+RESOLVE_TIMEOUT = 5.0
+
+
+def _matching_entity_id(
+    entries: list[dict[str, Any]], storage_key: str, domain: Literal["scene", "script"]
+) -> str | None:
+    """UI scenes belong to platform homeassistant; scripts belong to script."""
+    platform = "homeassistant" if domain == "scene" else "script"
+    for entry in entries:
+        entity_id = entry.get("entity_id") or ""
+        if (
+            entry.get("unique_id") == storage_key
+            and entry.get("platform") == platform
+            and entity_id.startswith(f"{domain}.")
+        ):
+            return str(entity_id)
+    return None
+
+
+async def _lookup_entity_id(
+    client: Any, storage_key: str, domain: Literal["scene", "script"]
+) -> str | None:
+    """Read once; an unavailable component falls back to the legacy registry."""
+    matches = await fetch_entity_lookup_via_component(
+        client, storage_key, domain=domain
+    )
+    if matches is None:
+        if domain == "script":
+            direct = await client.send_websocket_message(
+                {
+                    "type": "config/entity_registry/get",
+                    "entity_id": f"script.{storage_key}",
+                }
+            )
+            row = direct.get("result")
+            if direct.get("success") and isinstance(row, dict):
+                entity_id = _matching_entity_id([row], storage_key, domain)
+                if entity_id is not None:
+                    return entity_id
+        listing = await client.send_websocket_message(
+            {"type": "config/entity_registry/list"}
+        )
+        if listing.get("success") is False:
+            raise HomeAssistantAPIError(
+                f"Entity registry lookup failed: {listing.get('error')} "
+                f"(code={listing.get('error_code')})"
+            )
+        matches = listing.get("result") or []
+    return _matching_entity_id(matches, storage_key, domain)
+
+
+async def resolve_entity_id_after_write(
+    client: Any,
+    storage_key: str,
+    domain: Literal["scene", "script"],
+    *,
+    timeout: float | None = None,
+    poll_interval: float = 0.2,
+    fallback_entity_id: str | None = None,
+) -> str:
+    """Poll for the actual entity ID before a post-write wait/category update.
+
+    An empty registry read can precede asynchronous registration even inside
+    the component. Retry against one deadline, checking component availability
+    on every attempt. A positive budget includes in-flight lookups and sleeps;
+    zero requests one lookup without a time limit, for test fixtures. Known
+    API failures retain the best-effort fallback. Errors escaping the component
+    adapter propagate unless listed below; cancellation always propagates.
+    ``fallback_entity_id`` overrides the constructed ID on failure; registry
+    matching always uses the storage key.
+
+    Config reads and removals must use their existing resolution paths. Bulk
+    writes with neither a state wait nor a category update should skip this
+    helper entirely. The optional budget and interval support deterministic
+    tests without extending production waits.
+    """
+    storage_key = storage_key.removeprefix(f"{domain}.")
+    fallback = fallback_entity_id or f"{domain}.{storage_key}"
+    budget = RESOLVE_TIMEOUT if timeout is None else timeout
+    deadline = time.monotonic() + budget
+    try:
+        async with asyncio.timeout(budget if budget > 0 else None):
+            while True:
+                entity_id = await _lookup_entity_id(client, storage_key, domain)
+                if entity_id is not None:
+                    return entity_id
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    break
+                await asyncio.sleep(min(poll_interval, remaining))
+                if time.monotonic() >= deadline:
+                    break
+    except (
+        TimeoutError,
+        HomeAssistantAPIError,
+        HomeAssistantAuthError,
+        HomeAssistantConnectionError,
+    ) as exc:
+        logger.warning(
+            "Post-write registry resolve failed for %s.%s (%s: %s); using %s",
+            domain,
+            storage_key,
+            type(exc).__name__,
+            exc,
+            fallback,
+        )
+    else:
+        logger.debug(
+            "Post-write registry budget exhausted for %s.%s; using %s",
+            domain,
+            storage_key,
+            fallback,
+        )
+    return fallback

{ha_mcp_dev-8.4.3.dev2650 → ha_mcp_dev-8.4.3.dev2652}/src/ha_mcp/tools/tools_config_scenes.py

@@ -32,6 +32,7 @@ from ..utils.python_sandbox import (
 )
 from .auto_backup import with_auto_backup
 from .component_config_reads import fetch_entity_lookup_via_component
+from .entity_registration import resolve_entity_id_after_write
 from .helpers import (
     exception_to_structured_error,
     log_tool_usage,
@@ -115,10 +116,8 @@ class ConfigSceneTools:
     def __init__(self, client: Any) -> None:
         self._client = client
 
-    # Time to wait between the first and second registry-list query when the
-    # scene was just upserted but hasn't yet been indexed. Exposed as a class
-    # attribute so tests can patch it down to ``0`` instead of waiting 200 ms
-    # in suite runs.
+    # Short retry retained for config reads and removals; post-write polling
+    # has its own deadline in entity_registration.
     _RESOLVE_RETRY_DELAY = 0.2
 
     @staticmethod
@@ -133,53 +132,19 @@ class ConfigSceneTools:
     async def _resolve_scene_entity_id(
         self, scene_id: str, *, allow_component: bool = False
     ) -> str:
-        """Resolve a scene's actual entity_id via the entity registry.
-
-        Unlike scripts (where ``entity_id == 'script.<storage_key>'``), HA
-        derives a scene's entity_id from the ``name`` field. So a scene
-        upserted with ``scene_id='night_light_led_desk_strip'`` and
-        ``name='LED Desk Strip Night Light'`` lands at entity_id
-        ``scene.led_desk_strip_night_light`` while the storage key (and the
-        unique_id) stays ``night_light_led_desk_strip``.
-
-        Naively assuming ``f"scene.{scene_id}"`` for the wait/category
-        callsites surfaces a false-negative warning ("not yet queryable")
-        whenever a name is supplied. This helper finds the actual entity_id
-        by matching the scene_id to ``unique_id`` in the entity registry.
-
-        On a freshly-upserted scene the registry can lag the storage write
-        by tens to ~200 ms — the first query returns no match and the naive
-        ``scene.{scene_id}`` fallback is then chased by
-        ``wait_for_entity_registered`` to its phantom-404 timeout. Retry
-        the registry list once after a short delay so the post-upsert
-        callsites see the real entity_id instead of trailing the lookup
-        with a phantom (issue #1168 R3 blocker 1).
-
-        When ``allow_component`` (set/remove/post-write call sites only — a
-        config-get must never route through the component, see
-        ``component_config_reads`` and ``TestConfigGetSeam``) AND the component
-        advertises ``entity_lookup``, one in-process
-        ``entity_lookup(unique_id=scene_id, domain="scene")`` frame replaces the
-        whole-registry dump. A hit returns immediately — the in-process read
-        needs no settle. But an EMPTY result right after an upsert can be HA's
-        async entity-registration lag (#1168) rather than a true absence: the
-        in-process read removes the network latency, not the registration lag
-        (the upsert and this resolve are separate round-trips). So an empty
-        result is rechecked ONCE after ``_RESOLVE_RETRY_DELAY`` — the same delay
-        the legacy path uses — before the naive ``scene.{scene_id}`` fallback. If the recheck answers
-        AUTHORITATIVELY (component still available) its verdict is final: a hit is
-        returned, a genuine empty falls to the naive guess. But if the recheck
-        itself returns ``None`` (component went unavailable / errored / downgraded
-        mid-retry) the first empty read is NOT authoritative, so resolution drops
-        to the legacy list+retry path below (its own retry absorbs the same lag)
-        rather than trusting the empty and guessing.
-        The component unavailable / errored ⇒ the legacy list+retry path below
-        runs unchanged; that is the FIRST-read case (issue #1813 Phase 2).
-
-        Accepts a bare ``scene_id`` ("movie_night") or a fully-qualified
-        ``entity_id`` ("scene.movie_night") — the leading ``scene.`` is
-        stripped so callers don't accidentally produce ``scene.scene.movie_night``
-        on fallback. Mirrors ``rest_client.resolve_scene_id`` ergonomics.
+        """Resolve the entity ID for config reads and removals, with one retry.
+
+        HA derives scene entity IDs from the name; the storage key remains
+        the registry unique_id. Match that key instead of assuming the slug.
+        Accept either a bare key or a key prefixed with ``scene.``.
+
+        Only removals enable ``allow_component``. Config reads use the legacy
+        registry path to preserve the GET-path invariant documented in
+        ``component_config_reads``. An empty component result is rechecked
+        once; component unavailability falls through to the legacy path.
+
+        Post-write waits and categories use ``resolve_entity_id_after_write``:
+        their registration window requires deadline-based polling (#2426).
         """
         scene_id = scene_id.removeprefix("scene.")
         if allow_component:
@@ -197,8 +162,7 @@ class ConfigSceneTools:
         non-authoritative (capability miss, or the recheck went
         unavailable/errored mid-retry), so the caller falls through to the
         legacy registry list+retry path. ``scene_id`` must already have its
-        ``scene.`` prefix stripped; see ``_resolve_scene_entity_id`` for the
-        full lag-vs-absence reasoning.
+        ``scene.`` prefix stripped.
         """
         matches = await fetch_entity_lookup_via_component(
             self._client, scene_id, domain="scene"
@@ -871,8 +835,10 @@ class ConfigSceneTools:
         # post-upsert finalisation the full-config branch runs. Without
         # these, ``wait`` and ``category`` are silently dropped on
         # python_transform calls.
-        entity_id = await self._resolve_scene_entity_id(
-            resolved_id, allow_component=True
+        entity_id = (
+            await resolve_entity_id_after_write(self._client, resolved_id, "scene")
+            if wait or category
+            else f"scene.{resolved_id}"
         )
         if wait:
             try:
@@ -1152,8 +1118,10 @@ class ConfigSceneTools:
         # Resolve actual entity_id via registry — HA derives scene
         # entity_ids from the 'name' slug, not the scene_id storage key,
         # so f"scene.{scene_id}" is wrong whenever a name is supplied.
-        entity_id = await self._resolve_scene_entity_id(
-            resolved_id, allow_component=True
+        entity_id = (
+            await resolve_entity_id_after_write(self._client, resolved_id, "scene")
+            if wait or effective_category
+            else f"scene.{resolved_id}"
         )
 
         # Wait for scene to be queryable

{ha_mcp_dev-8.4.3.dev2650 → ha_mcp_dev-8.4.3.dev2652}/src/ha_mcp/tools/tools_config_scripts.py

@@ -38,7 +38,7 @@ from .blueprint_substitute import (
     take_control_config,
     validate_write_modes,
 )
-from .component_config_reads import fetch_entity_lookup_via_component
+from .entity_registration import resolve_entity_id_after_write
 from .helpers import (
     exception_to_structured_error,
     log_tool_usage,
@@ -793,6 +793,7 @@ class ConfigScriptTools:
                     python_transform,
                     bp_warnings,
                     MandatoryBPS,
+                    wait,
                     effective_category,
                 )
 
@@ -951,46 +952,44 @@ class ConfigScriptTools:
             )
         return transformed_config, resolved_id
 
-    async def _resolve_script_entity_id(self, storage_key: str) -> str:
-        """Resolve a script storage key to its current entity_id.
+    async def _finalize_script_write(
+        self,
+        result: dict[str, Any],
+        script_id: str,
+        resolved_key: str | None,
+        wait: bool,
+        category: str | None,
+    ) -> None:
+        """Resolve, wait, and apply a category for either script write mode.
 
-        Normally ``script.<storage_key>``, but a registry rename decouples
-        the entity_id from the storage key while the registry entry keeps
-        ``unique_id == storage_key``. Component lookup first, then a
-        registry-get fast path, then a registry-list scan; the constructed id
-        is the last resort (fresh creates resolve here before registration).
+        Match the upsert's storage key, which can differ from the caller's
+        entity ID after a registry rename. Keep the caller's ID as fallback.
         """
-        constructed = f"script.{storage_key}"
-        try:
-            matches = await fetch_entity_lookup_via_component(
-                self._client, storage_key, domain="script"
-            )
-            if matches is not None:
-                for match in matches:
-                    entity_id = match.get("entity_id") or ""
-                    if entity_id.startswith("script."):
-                        return str(entity_id)
-                return constructed
-            result = await self._client.send_websocket_message(
-                {"type": "config/entity_registry/get", "entity_id": constructed}
-            )
-            if isinstance(result, dict) and result.get("success"):
-                return constructed
-            listing = await self._client.send_websocket_message(
-                {"type": "config/entity_registry/list"}
+        if not wait and not category:
+            return
+        storage_key = result.get("script_id") or resolved_key or script_id
+        entity_id = await resolve_entity_id_after_write(
+            self._client,
+            storage_key,
+            "script",
+            fallback_entity_id=f"script.{script_id.removeprefix('script.')}",
+        )
+        if wait:
+            try:
+                registered = await wait_for_entity_registered(self._client, entity_id)
+                if not registered:
+                    result.setdefault("warnings", []).append(
+                        f"Script saved but {entity_id} not yet queryable. "
+                        "It may take a moment to become available."
+                    )
+            except (HomeAssistantConnectionError, HomeAssistantAuthError) as e:
+                result.setdefault("warnings", []).append(
+                    f"Script saved but verification failed: {e}"
+                )
+        if category:
+            await apply_entity_category(
+                self._client, entity_id, category, "script", result, "script"
             )
-            entries = (listing.get("result") or []) if isinstance(listing, dict) else []
-            for entry in entries:
-                if (
-                    isinstance(entry, dict)
-                    and entry.get("platform") == "script"
-                    and entry.get("unique_id") == storage_key
-                    and str(entry.get("entity_id", "")).startswith("script.")
-                ):
-                    return str(entry["entity_id"])
-        except Exception as e:
-            logger.debug(f"Failed to resolve entity_id for script {storage_key}: {e}")
-        return constructed
 
     async def _commit_script_transform(
         self,
@@ -1000,13 +999,10 @@ class ConfigScriptTools:
         python_transform: str,
         bp_warnings: BestPracticeCheckResult,
         MandatoryBPS: bool,
+        wait: bool,
         effective_category: str | None = None,
     ) -> dict[str, Any]:
-        """Upsert a transformed script config and build the tool response.
-
-        Extracted verbatim from ``ha_config_set_script``'s python_transform
-        branch (the post-``_check_best_practices`` tail).
-        """
+        """Upsert, refresh the hash, finalize wait/category, and build the response."""
         # Save transformed config. ``_fetch_and_verify_hash`` already
         # resolved the storage key; pass it as the write target so the
         # upsert skips the redundant re-resolve (issue #1813 Phase 0).
@@ -1020,18 +1016,9 @@ class ConfigScriptTools:
         # Re-fetch to get authoritative hash (HA may normalize after save)
         _, new_config_hash, _ = await self._get_script_config_internal(script_id)
 
-        # Apply category to entity registry if provided (parity with the
-        # full-config branch — issue #2159). Resolve the storage key first: a
-        # registry-renamed script no longer lives at script.<storage_key>.
-        if effective_category:
-            await apply_entity_category(
-                self._client,
-                await self._resolve_script_entity_id(script_id),
-                effective_category,
-                "script",
-                result,
-                "script",
-            )
+        await self._finalize_script_write(
+            result, script_id, resolved_id, wait, effective_category
+        )
 
         response: dict[str, Any] = {
             "success": True,
@@ -1081,11 +1068,7 @@ class ConfigScriptTools:
         MandatoryBPS: bool,
         detached_blueprint: str | None = None,
     ) -> dict[str, Any]:
-        """Validate references, upsert, wait, and build the tool response.
-
-        Extracted verbatim from ``ha_config_set_script``'s full-config branch
-        (the post-``_check_best_practices`` tail).
-        """
+        """Validate references, upsert, finalize wait/category, and build the response."""
         # Cross-check literal service and entity references against
         # the live registries. Soft warnings only — the write still
         # happens, even when references don't resolve (#940).
@@ -1093,38 +1076,9 @@ class ConfigScriptTools:
 
         result = await self._upsert_script(config_dict, script_id, resolved_key)
 
-        # Resolve the storage key only when the entity_id is consumed (the
-        # wait poll or the category write): with wait=False and no category —
-        # the documented bulk path — the resolution round-trips would be pure
-        # cost. A registry-renamed script no longer lives at
-        # script.<storage_key>; fresh creates fall back to the constructed id.
-        if wait or effective_category:
-            entity_id = await self._resolve_script_entity_id(script_id)
-        else:
-            entity_id = f"script.{script_id}"
-        if wait:
-            try:
-                registered = await wait_for_entity_registered(self._client, entity_id)
-                if not registered:
-                    result.setdefault("warnings", []).append(
-                        f"Script saved but {entity_id} not yet queryable. "
-                        "It may take a moment to become available."
-                    )
-            except (HomeAssistantConnectionError, HomeAssistantAuthError) as e:
-                result.setdefault("warnings", []).append(
-                    f"Script saved but verification failed: {e}"
-                )
-
-        # Apply category to entity registry if provided
-        if effective_category and entity_id:
-            await apply_entity_category(
-                self._client,
-                entity_id,
-                effective_category,
-                "script",
-                result,
-                "script",
-            )
+        await self._finalize_script_write(
+            result, script_id, resolved_key, wait, effective_category
+        )
 
         if bp_warnings:
             result["best_practice_warnings"] = list(bp_warnings)

{ha_mcp_dev-8.4.3.dev2650 → ha_mcp_dev-8.4.3.dev2652/src/ha_mcp_dev.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 8.4.3.dev2650
+Version: 8.4.3.dev2652
 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.4.3.dev2650 → ha_mcp_dev-8.4.3.dev2652}/src/ha_mcp_dev.egg-info/SOURCES.txt

@@ -618,6 +618,7 @@ src/ha_mcp/tools/config_entry_reconfigure.py
 src/ha_mcp/tools/config_entry_reload_watch.py
 src/ha_mcp/tools/dashboard_edit_errors.py
 src/ha_mcp/tools/device_control.py
+src/ha_mcp/tools/entity_registration.py
 src/ha_mcp/tools/error_log_parsing.py
 src/ha_mcp/tools/hacs_registration.py
 src/ha_mcp/tools/helpers.py