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

{ha_mcp_dev-8.4.3.dev2648/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.dev2648
+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.dev2648 → 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.dev2648"
+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
@@ -258,36 +258,117 @@ ignore = [
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
-python_files = ["test_*.py", "*_test.py"]
+python_files = ["test_*.py"]
 python_classes = ["Test*"]
 python_functions = ["test_*"]
-# See tests/pytest.ini: an empty parametrize list is a guard that stopped
-# running, and the default mark hides it as a skip the summary ignores.
+# A parametrize list that resolves to nothing is a guard that silently stopped
+# running: pytest reports "got empty parameter set", and the summary counts it
+# as neither a failure nor a real skip. Make it a collection error instead.
 empty_parameter_set_mark = "fail_at_collect"
+
+# Command line options
 addopts = [
     "--strict-markers",
     "--strict-config",
     "--verbose",
     "--tb=short",
+    "--maxfail=3",
+    "-ra",
+    "--durations=10",
 ]
+
+# Test markers
 markers = [
-    "slow: marks tests as slow (deselect with '-m \"not slow\"')",
-    "integration: marks tests as integration tests",
-    "unit: marks tests as unit tests",
+    # Test speed
+    "slow: marks tests as slow (use -m 'not slow' to skip)",
+    "addon_disruptive: restarts the server-under-test's own process (addon self-restart); must never run concurrently with other tests on lanes where the MCP server is out-of-process - the lane workflow runs these in a single-worker phase AFTER the parallel run",
+
+    # Test types
+    "unit: unit tests (isolated, fast)",
+    "integration: integration tests requiring external services",
+    "e2e: end-to-end tests with full system",
+    "performance: performance and load tests",
+
+    # E2E test categories
     "automation: automation lifecycle tests",
+    "blueprint: blueprint management tests",
     "calendar: calendar event management tests",
     "device: device control tests",
     "script: script orchestration tests",
     "helper: helper integration tests",
+    "integrations: integration management tests (config entries)",
+    "labels: label management tests",
+    "registry: entity and device registry tests",
+    "services: service discovery tests",
+    "todo: todo/shopping list management tests",
     "convenience: convenience tools tests (scene, weather, energy, docs)",
+    "updates: update management tools tests",
+    "system: system management tests (restart, reload, health)",
+    "themes: frontend theme management tests",
     "error_handling: error handling and edge case tests",
     "cleanup: tests that create entities needing cleanup",
-    "performance: performance measurement and regression tests",
-    "external_only: in-process-server tiers only; skips inaddon, stdio, container-embedded, and HAOS-embedded servers",
-    "inaddon_only: only runs on HAOS inaddon tier",
+    "area: area management tests",
+    "floor: floor management tests",
+    "zone: zone management tests",
+    "group: entity group management tests",
+    "hacs: HACS (Home Assistant Community Store) tests",
+    "update_path: component (stable tag + working tree) x new-server in-process update-path e2e (dedicated lane; runs only with E2E_UPDATE_PATH=1; #1783/#1785)",
+    "core: core tool tests (state, service, bulk control, history, templates)",
+    "config: configuration management tests (helpers, labels)",
+    "filesystem: filesystem access tools tests",
+    "haos_only: skip unless HAOS_TEST_IMAGE_PATH is set (HAOS-QEMU backend required; #1281)",
     "beta_haos_only: beta HAOS image lanes with Supervisor/Core version expectations configured",
+    "container_only: skip when HAOS backend is active (testcontainer-specific behavior; #1281)",
+    "embedded_only: only the embedded testcontainer backend (E2E_BACKEND=embedded), the one lane that installs ha-mcp into the HA image (#2245)",
+    "external_only: in-process-server tiers only - skip for inaddon, stdio, container-embedded, and HAOS-embedded servers; #1349, #1527, #2233",
+    "inaddon_only: HAOS inaddon mode only - exercises is_running_in_addon()=True paths; #1349",
+    "haos_stdio_only: HAOS stdio mode only - exercises the installed ha-mcp command over a real stdio subprocess transport; #2233",
+    "haos_tls: final HAOS embedded scenario that restarts Core with HTTPS in the existing worker VM, then restores HTTP; #2241",
+    "haos_embedded_only: HAOS embedded mode only (HAOS_TEST_MODE=embedded) - the server shares Home Assistant's process and event loop; #2357",
+    "not_on_embedded: skip on the embedded backend (E2E_BACKEND=embedded) - provably redundant with the lane's own in-process ha_mcp_server session backend; #1527",
+    "not_on_haos_embedded: skip on the haos_embedded backend (HAOS_TEST_MODE=embedded) - provably redundant with the lane's own session backend, which enables the entry once and drives the in-process server for the whole suite; #1527",
+    "requires_tools_entry: needs the File & YAML Tools config entry - skipped on E2E_NO_TOOLS_ENTRY=1 lanes (#2292)",
+    "no_tools_only: runs only on E2E_NO_TOOLS_ENTRY=1 lanes (#2292)",
 ]
+
+# Async support - session-scoped loop lets session-scoped fixtures
+# (mcp_server, mcp_client, ha_client) share one event loop with tests.
+# Without this, each test gets a new loop and session-scoped httpx
+# clients fail with "Event loop is closed".
 asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "session"
+asyncio_default_test_loop_scope = "session"
+
+# Per-test timeout (pytest-timeout). A stuck server-side await otherwise
+# stalls the run silently until the JOB timeout - observed as a 22-minute
+# hang in test_zone_search_discovery on the HAOS in-addon backend. 300s is
+# ~10x the slowest legitimate test (~30s deliberate-timeout tests). The signal
+# method interrupts only the hung test and raises inside the running coroutine,
+# so the failure traceback names the exact stuck await.
+timeout = 300
+timeout_method = "signal"
+# Bill the timeout to the TEST FUNCTION only. Session fixtures (container
+# boot, the embedded backend's server bring-up, HAOS staging) legitimately
+# exceed 300s and were being killed mid-setup on the first test per worker,
+# preempting their own diagnostics. Runaway fixtures are still bounded by
+# the CI job timeouts.
+timeout_func_only = true
+
+# Log capture
+log_cli = true
+log_cli_level = "INFO"
+log_cli_format = "%(asctime)s [%(levelname)8s] %(name)s: %(message)s"
+log_cli_date_format = "%Y-%m-%d %H:%M:%S"
+
+# Treat warnings as errors to enforce clean tests
+filterwarnings = [
+    "error",
+    # Allow specific non-critical warnings that don't affect functionality
+    "ignore::DeprecationWarning",
+    "ignore::PendingDeprecationWarning",
+    # Allow all ResourceWarnings, including those emitted during test cleanup
+    "ignore::ResourceWarning",
+]
 
 [dependency-groups]
 dev = [

{ha_mcp_dev-8.4.3.dev2648 → 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.dev2648 → 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