ha-mcp-dev 7.13.0.dev1973__tar.gz → 7.13.0.dev1975__tar.gz

{ha_mcp_dev-7.13.0.dev1973/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.13.0.dev1975}/PKG-INFO

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.13.0.dev1973"
+version = "7.13.0.dev1975"
 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-7.13.0.dev1973 → ha_mcp_dev-7.13.0.dev1975}/src/ha_mcp/backup_manager.py

@@ -1296,14 +1296,18 @@ async def _restore_scene(client: Any, entity_id: str, config: Any) -> Any:
 async def _fetch_dashboard(client: Any, entity_id: str) -> Any:
     """Fetch a dashboard config via the same helper the get tool uses.
 
-    Delegates to ``tools_config_dashboards._get_dashboard_config_internal``
-    which handles the WS envelope, force-cache-bypass, and structured
-    error wrapping consistently with how the rest of the dashboard surface
-    fetches state. Imported lazily to avoid an import cycle.
+    The identifier is pre-resolved to its canonical url_path via the shared
+    ``_resolve_dashboard`` (component ``list`` when available), then the config is
+    read through the component ``get`` (one in-process frame) with a fall back to
+    the legacy ``lovelace/config`` read (``_get_dashboard_config_internal``, which
+    handles the WS envelope, force-cache-bypass, and structured error wrapping).
+    The component refuses YAML bodies, so those capture through legacy unchanged.
+    Imported lazily to avoid an import cycle.
     """
     from fastmcp.exceptions import ToolError
 
     from .tools.tools_config_dashboards import (
+        _component_dashboard_config,
         _get_dashboard_config_internal,
         _resolve_dashboard,
     )
@@ -1329,6 +1333,12 @@ async def _fetch_dashboard(client: Any, entity_id: str) -> Any:
             err,
         )
 
+    # Component fast path (freshness-safe in-memory read); None ⇒ legacy below,
+    # which also covers YAML dashboards and not-found (nothing to back up).
+    component_config = await _component_dashboard_config(client, fetch_path)
+    if component_config is not None:
+        return component_config
+
     try:
         config, _config_hash = await _get_dashboard_config_internal(client, fetch_path)
     except ToolError as err:
@@ -1442,10 +1452,21 @@ def _strip_readonly(config: dict[str, Any], *extra: str) -> dict[str, Any]:
 
 
 async def _fetch_label(client: Any, entity_id: str) -> Any:
-    items = _require_list(
-        await _ws_send(client, {"type": "config/label_registry/list"}),
-        "config/label_registry/list",
-    )
+    # Route the capture through the component's ``registries`` capability when
+    # available (one in-process read of the label registry) instead of dumping
+    # the whole registry via WS. Lazy import to avoid the backup_manager →
+    # tools → backup_manager cycle (same pattern as ``_fetch_device``). ``None``
+    # from the helper means "component unavailable"; fall back to the full list.
+    from .tools.component_registries import fetch_registries_via_component
+
+    component_result = await fetch_registries_via_component(client, ["label"])
+    if component_result is not None:
+        items = component_result.get("labels") or []
+    else:
+        items = _require_list(
+            await _ws_send(client, {"type": "config/label_registry/list"}),
+            "config/label_registry/list",
+        )
     for item in items:
         if item.get("label_id") == entity_id:
             return item
@@ -1466,12 +1487,22 @@ async def _fetch_category(client: Any, entity_id: str) -> Any:
     scope, _, cat_id = entity_id.partition(":")
     if not cat_id:
         return None
-    items = _require_list(
-        await _ws_send(
-            client, {"type": "config/category_registry/list", "scope": scope}
-        ),
-        "config/category_registry/list",
+    # Same component-first routing as ``_fetch_label``; categories are scoped,
+    # so the requested scope rides ``category_scopes``.
+    from .tools.component_registries import fetch_registries_via_component
+
+    component_result = await fetch_registries_via_component(
+        client, ["category"], category_scopes=[scope]
     )
+    if component_result is not None:
+        items = (component_result.get("categories") or {}).get(scope, [])
+    else:
+        items = _require_list(
+            await _ws_send(
+                client, {"type": "config/category_registry/list", "scope": scope}
+            ),
+            "config/category_registry/list",
+        )
     for item in items:
         if item.get("category_id") == cat_id:
             return {"scope": scope, **item}
@@ -1607,19 +1638,30 @@ async def _fetch_area_or_floor(client: Any, entity_id: str) -> Any:
     kind, _, real_id = entity_id.partition(":")
     if not real_id:
         return None
+    # Same component-first routing as ``_fetch_label`` / ``_fetch_category``.
+    from .tools.component_registries import fetch_registries_via_component
+
     if kind == "area":
-        items = _require_list(
-            await _ws_send(client, {"type": "config/area_registry/list"}),
-            "config/area_registry/list",
-        )
+        component_result = await fetch_registries_via_component(client, ["area"])
+        if component_result is not None:
+            items = component_result.get("areas") or []
+        else:
+            items = _require_list(
+                await _ws_send(client, {"type": "config/area_registry/list"}),
+                "config/area_registry/list",
+            )
         for item in items:
             if item.get("area_id") == real_id:
                 return {"kind": "area", **item}
     elif kind == "floor":
-        items = _require_list(
-            await _ws_send(client, {"type": "config/floor_registry/list"}),
-            "config/floor_registry/list",
-        )
+        component_result = await fetch_registries_via_component(client, ["floor"])
+        if component_result is not None:
+            items = component_result.get("floors") or []
+        else:
+            items = _require_list(
+                await _ws_send(client, {"type": "config/floor_registry/list"}),
+                "config/floor_registry/list",
+            )
         for item in items:
             if item.get("floor_id") == real_id:
                 return {"kind": "floor", **item}

{ha_mcp_dev-7.13.0.dev1973 → ha_mcp_dev-7.13.0.dev1975}/src/ha_mcp/tools/backup.py

@@ -30,10 +30,21 @@ from ..backup_manager import (
     MandatoryBackupError,
     get_backup_manager,
 )
-from ..client.rest_client import HomeAssistantClient, HomeAssistantError
-from ..client.websocket_client import HomeAssistantWebSocketClient
+from ..client.rest_client import (
+    HomeAssistantClient,
+    HomeAssistantCommandError,
+    HomeAssistantCommandTimeout,
+    HomeAssistantError,
+)
+from ..client.websocket_client import HomeAssistantWebSocketClient, get_websocket_client
 from ..config import get_global_settings
 from ..errors import ErrorCode, create_error_response
+from .component_api import (
+    component_supports,
+    get_component_caps,
+    invalidate_caps,
+    is_unknown_command,
+)
 from .helpers import (
     exception_to_structured_error,
     get_connected_ws_client,
@@ -89,6 +100,9 @@ _BACKUP_PROGRESS_INTERVAL_S = 10
 # _wait_timeout) can be too tight for a slow or rate-limited remote agent —
 # same class of false-timeout problem this file already fixes for creation.
 _BACKUP_DELETE_WAIT_S = 60.0
+# WS command name is a module-local constant per the component-routing seam
+# pattern (see component_api.py / component_devices.py).
+WS_BACKUP_PREP = "ha_mcp_tools/backup_prep"
 
 
 def _get_backup_hint_text() -> str:
@@ -217,6 +231,91 @@ async def _get_backup_password(
     return cast(str, default_password)
 
 
+async def _backup_prep_via_component(
+    client: HomeAssistantClient,
+) -> dict[str, Any] | None:
+    """One ``ha_mcp_tools/backup_prep`` read; ``None`` ⇒ run the legacy two-call path.
+
+    Returns the component's ``{agent_ids, local_agent_id, default_password}``
+    payload, replacing the sequential ``backup/agents/info`` (local-agent
+    discovery, :func:`_get_local_backup_agent_id`) + ``backup/config/info``
+    (default password, :func:`_get_backup_password`) WS round-trips with one
+    in-process read. ``None`` on capability miss, downgrade (``unknown_command``
+    → invalidate the cached caps), or command error/timeout (logged) — the
+    caller falls back to the legacy sequential calls. A
+    ``HomeAssistantConnectionError`` (pooled-WS drop) or the plain ``Exception``
+    ``get_websocket_client()`` raises on a failed (re)connect is caught here and
+    mapped to ``None``: the legacy probes (``_get_local_backup_agent_id`` /
+    ``_get_backup_password``) run on a DEDICATED ``get_connected_ws_client`` socket
+    already connected before this read, NOT this pooled one — so a wedged pooled
+    socket must fall back to the legacy calls rather than fail create/restore.
+    Same caps-gate discipline as ``component_devices.fetch_device_via_component``.
+    """
+    caps = await get_component_caps(client)
+    if not component_supports(caps, "backup_prep"):
+        return None
+    try:
+        ws = await get_websocket_client(url=client.base_url, token=client.token)
+        raw = await ws.send_command(WS_BACKUP_PREP)
+    except (HomeAssistantCommandError, HomeAssistantCommandTimeout) as exc:
+        if is_unknown_command(exc):
+            invalidate_caps(client)
+        else:
+            logger.warning("%s failed; fell back to legacy: %r", WS_BACKUP_PREP, exc)
+        return None
+    except Exception as exc:
+        # HomeAssistantConnectionError (pooled-WS drop) OR the plain Exception
+        # get_websocket_client() raises on a failed (re)connect. The legacy probes
+        # ride a dedicated already-connected socket, so fall back rather than fail
+        # create/restore on a wedged pooled socket.
+        logger.warning(
+            "%s connection error; falling back to legacy: %r", WS_BACKUP_PREP, exc
+        )
+        return None
+    result = raw.get("result")
+    if not isinstance(result, dict) or "local_agent_id" not in result:
+        logger.debug(
+            "%s returned a malformed result (missing 'local_agent_id' key); "
+            "falling back to legacy",
+            WS_BACKUP_PREP,
+        )
+        return None
+    return result
+
+
+def _raise_no_local_backup_agent_error(agent_ids: list[Any] | None) -> NoReturn:
+    """Same "no local agent" error ``_get_local_backup_agent_id`` raises.
+
+    Used when the ``backup_prep`` component read comes back with
+    ``local_agent_id: None`` — the SAME outcome as the legacy probe finding no
+    agent named ``"local"``, so both paths fail identically.
+    """
+    raise_tool_error(
+        create_error_response(
+            ErrorCode.SERVICE_CALL_FAILED,
+            "No local backup agent found",
+            context={"available_agents": [a for a in (agent_ids or []) if a]},
+            suggestions=[
+                "Backup creation requires a local agent (hassio.local on "
+                "Supervised, backup.local on Core); none is registered",
+            ],
+        )
+    )
+
+
+def _raise_no_default_password_error() -> NoReturn:
+    """Same error ``_get_backup_password`` raises when no default password is configured."""
+    raise_tool_error(
+        create_error_response(
+            ErrorCode.SERVICE_CALL_FAILED,
+            "No default backup password configured in Home Assistant",
+            suggestions=[
+                "Configure automatic backups in Home Assistant settings to set a default password"
+            ],
+        )
+    )
+
+
 def _parse_backup_date(raw: Any) -> datetime | None:
     """Parse an HA backup `date` (ISO-8601, may use `Z` suffix) to a tz-aware
     datetime, returning None on missing/malformed input. Naive timestamps are
@@ -530,13 +629,24 @@ async def create_backup(
             )
         ws_client = cast(HomeAssistantWebSocketClient, ws_client)
 
-        # Get backup password (raises ToolError on failure)
-        password = await _get_backup_password(ws_client)
+        # One component read replaces the sequential password + local-agent
+        # probes when the ha_mcp_tools component supports backup_prep.
+        prep = await _backup_prep_via_component(client)
+        if prep is not None:
+            password = prep.get("default_password")
+            if not password:
+                _raise_no_default_password_error()
+            local_agent = prep.get("local_agent_id")
+            if not local_agent:
+                _raise_no_local_backup_agent_error(prep.get("agent_ids"))
+        else:
+            # Get backup password (raises ToolError on failure)
+            password = await _get_backup_password(ws_client)
 
-        # Discover the local backup agent at call time. HA Core registers
-        # `backup.local`; HA Supervised registers `hassio.local`. Hardcoding
-        # either breaks the other deployment.
-        local_agent = await _get_local_backup_agent_id(ws_client)
+            # Discover the local backup agent at call time. HA Core registers
+            # `backup.local`; HA Supervised registers `hassio.local`. Hardcoding
+            # either breaks the other deployment.
+            local_agent = await _get_local_backup_agent_id(ws_client)
 
         # Generate backup name if not provided
         if not name:
@@ -768,19 +878,38 @@ async def restore_backup(
                 )
             )
 
-        # Discover the local backup agent (Supervisor's hassio.local on
-        # Supervised, backup.local on Core). Used for both the safety backup
-        # and the restore call below.
-        local_agent = await _get_local_backup_agent_id(ws_client)
+        # One component read replaces the sequential local-agent + password
+        # probes when the ha_mcp_tools component supports backup_prep.
+        prep = await _backup_prep_via_component(client)
+        if prep is not None:
+            # Local backup agent (Supervisor's hassio.local on Supervised,
+            # backup.local on Core). Used for both the safety backup and the
+            # restore call below.
+            local_agent = prep.get("local_agent_id")
+            if not local_agent:
+                _raise_no_local_backup_agent_error(prep.get("agent_ids"))
+
+            # Create safety backup BEFORE restoring
+            logger.info("Creating safety backup before restore...")
+            password = prep.get("default_password")
+            if not password:
+                # No default password - log warning but continue (restore might still work)
+                logger.warning("No default password - proceeding without safety backup")
+                password = None
+        else:
+            # Discover the local backup agent (Supervisor's hassio.local on
+            # Supervised, backup.local on Core). Used for both the safety backup
+            # and the restore call below.
+            local_agent = await _get_local_backup_agent_id(ws_client)
 
-        # Create safety backup BEFORE restoring
-        logger.info("Creating safety backup before restore...")
-        try:
-            password = await _get_backup_password(ws_client)
-        except ToolError:
-            # Password error - log warning but continue (restore might still work)
-            logger.warning("No default password - proceeding without safety backup")
-            password = None
+            # Create safety backup BEFORE restoring
+            logger.info("Creating safety backup before restore...")
+            try:
+                password = await _get_backup_password(ws_client)
+            except ToolError:
+                # Password error - log warning but continue (restore might still work)
+                logger.warning("No default password - proceeding without safety backup")
+                password = None
 
         safety_backup_id, safety_warnings = await _create_safety_backup(
             ws_client, password, local_agent, ctx=ctx

{ha_mcp_dev-7.13.0.dev1973 → ha_mcp_dev-7.13.0.dev1975}/src/ha_mcp/tools/component_api.py

@@ -62,9 +62,20 @@ SUPPORTED_SCHEMA_VERSION = 1
 # (the cache key is the process-lifetime REST client — see ``_CAPS_CACHE``).
 # Positive entries never expire on this timer; they are dropped only by
 # ``invalidate_caps`` (a supposedly-supported command coming back
-# ``unknown_command``).
+# ``unknown_command``). This ABSENT-negative window covers a definitive
+# "component responded, no usable surface" verdict (``unknown_command`` /
+# malformed / unsupported schema_version).
 _NEGATIVE_CACHE_TTL_S = 300.0
 
+# A separate, much SHORTER window for a TRANSIENT negative: the probe couldn't
+# reach the component at all (WS down / connect failure), which is not a verdict
+# about the component, only about the transport. Caching it briefly stops a
+# WS-broken install from re-paying the slow connect attempt on every tool call
+# (issue #1813 Phase 2, review-5 M8) while still self-healing quickly once the
+# socket recovers. Kept short precisely because the transport may come back at
+# any moment — unlike the absent-negative, which reflects a stable answer.
+_TRANSIENT_NEGATIVE_CACHE_TTL_S = 30.0
+
 
 def _monotonic() -> float:
     """Monotonic clock read, isolated so tests can advance it deterministically."""
@@ -79,13 +90,18 @@ class ComponentCaps:
     commands the component actually registered. ``schema_version`` guards the
     wire-format generation of those commands (a consumer needing a reshaped
     payload checks ``schema_version >= N``). ``component_version`` and
-    ``limits`` are advisory (display / body-size caps).
+    ``limits`` are advisory (display / body-size caps). ``timezone`` is the
+    instance's ``hass.config.time_zone`` (an additive ``info`` field — ``None``
+    on a component too old to report it, or when unset); it is cached here for
+    the consumers that localize timestamps (issue #1813 Phase 2), but nothing
+    routes on it — capability negotiation, not a timezone floor.
     """
 
     schema_version: int
     component_version: str
     capabilities: frozenset[str]
     limits: dict[str, Any]
+    timezone: str | None = None
 
 
 # Weak-keyed by client so the negotiated caps self-evict when the client is
@@ -94,14 +110,23 @@ class ComponentCaps:
 # so a positive entry persists for the whole process (dropped only by
 # ``invalidate_caps`` on an ``unknown_command``). A ``None`` value is a cached
 # *negative* ("probed, no usable WS surface"); absence means "not yet probed".
-# Negatives carry an expiry in ``_NEGATIVE_CACHE_TS`` so a component installed /
-# upgraded mid-session is eventually re-probed instead of pinned absent forever.
+# A negative carries an expiry in EXACTLY ONE of the two timestamp maps below —
+# ``_NEGATIVE_CACHE_TS`` (definitive absent, long) or ``_TRANSIENT_NEGATIVE_TS``
+# (transport-only, short) — so a component installed/upgraded mid-session, or one
+# that just became reachable again, is eventually re-probed instead of pinned.
 _CAPS_CACHE: weakref.WeakKeyDictionary[Any, ComponentCaps | None] = (
     weakref.WeakKeyDictionary()
 )
-# Monotonic timestamp a negative entry was stored, keyed by the same client.
-# Only populated for ``None`` values; positive entries never appear here.
+# Monotonic timestamp a definitive ABSENT-negative was stored, keyed by the same
+# client. Only populated for ``None`` values; positive entries never appear here.
 _NEGATIVE_CACHE_TS: weakref.WeakKeyDictionary[Any, float] = weakref.WeakKeyDictionary()
+# Monotonic timestamp a TRANSIENT (transport-failure) negative was stored. Kept
+# separate from ``_NEGATIVE_CACHE_TS`` so the two negative kinds carry different
+# TTLs; a client is stamped in at most one of the two at a time (the store helpers
+# clear the other).
+_TRANSIENT_NEGATIVE_TS: weakref.WeakKeyDictionary[Any, float] = (
+    weakref.WeakKeyDictionary()
+)
 _CAPS_LOCKS: weakref.WeakKeyDictionary[Any, asyncio.Lock] = weakref.WeakKeyDictionary()
 
 
@@ -118,30 +143,60 @@ def _live_cache_entry(client: Any) -> tuple[bool, ComponentCaps | None]:
     """Return ``(hit, caps)`` for a still-valid cache entry, else ``(False, None)``.
 
     A positive entry is a hit for the process lifetime. A negative (``None``)
-    entry is a hit only within ``_NEGATIVE_CACHE_TTL_S`` of when it was stored
-    (monotonic clock); once that window lapses it reports a miss so the caller
-    re-probes and can adopt a component that appeared mid-session.
+    entry is a hit only within its window of when it was stored (monotonic clock):
+    ``_NEGATIVE_CACHE_TTL_S`` for a definitive absent-negative, the shorter
+    ``_TRANSIENT_NEGATIVE_CACHE_TTL_S`` for a transport-failure negative. Once the
+    relevant window lapses it reports a miss so the caller re-probes and can adopt a
+    component that appeared — or became reachable — mid-session.
     """
     if client not in _CAPS_CACHE:
         return False, None
     cached = _CAPS_CACHE[client]
     if cached is not None:
         return True, cached
+    now = _monotonic()
     stored_at = _NEGATIVE_CACHE_TS.get(client)
-    if stored_at is not None and (_monotonic() - stored_at) < _NEGATIVE_CACHE_TTL_S:
+    if stored_at is not None and (now - stored_at) < _NEGATIVE_CACHE_TTL_S:
+        return True, None
+    transient_at = _TRANSIENT_NEGATIVE_TS.get(client)
+    if (
+        transient_at is not None
+        and (now - transient_at) < _TRANSIENT_NEGATIVE_CACHE_TTL_S
+    ):
         return True, None
     return False, None
 
 
 def _store_caps(client: Any, caps: ComponentCaps | None) -> None:
-    """Cache ``caps`` for ``client``, stamping a negative with the current clock."""
+    """Cache a positive result or a definitive ABSENT-negative for ``client``.
+
+    A ``None`` here is the long-window absent-negative (``info`` responded
+    ``unknown_command`` / malformed / unsupported schema). Clears any prior
+    transient-negative stamp so a client never carries both negative kinds.
+    """
     _CAPS_CACHE[client] = caps
+    _TRANSIENT_NEGATIVE_TS.pop(client, None)
     if caps is None:
         _NEGATIVE_CACHE_TS[client] = _monotonic()
     else:
         _NEGATIVE_CACHE_TS.pop(client, None)
 
 
+def _store_transient_negative(client: Any) -> None:
+    """Cache a SHORT transient negative after a transport-failure probe.
+
+    The probe could not reach the component (WS down / connect failure), so cache
+    ``None`` with the short ``_TRANSIENT_NEGATIVE_CACHE_TTL_S`` window: repeated
+    calls inside it skip re-paying the slow connect and go straight to legacy
+    (issue #1813 Phase 2, review-5 M8), then the next call past the window re-probes
+    and adopts a now-reachable component (self-healing). Clears any prior
+    absent-negative stamp so a client never carries both negative kinds.
+    """
+    _CAPS_CACHE[client] = None
+    _NEGATIVE_CACHE_TS.pop(client, None)
+    _TRANSIENT_NEGATIVE_TS[client] = _monotonic()
+
+
 def _parse_caps(response: Any) -> ComponentCaps | None:
     """Map an ``ha_mcp_tools/info`` response into ``ComponentCaps``.
 
@@ -162,11 +217,15 @@ def _parse_caps(response: Any) -> ComponentCaps | None:
         schema_version = int(result.get("schema_version", 0) or 0)
     except (TypeError, ValueError):
         schema_version = 0
+    raw_timezone = result.get("timezone")
     return ComponentCaps(
         schema_version=schema_version,
         component_version=str(result.get("component_version", "")),
         capabilities=capabilities,
         limits=raw_limits if isinstance(raw_limits, dict) else {},
+        # Additive info field: a component too old to report it (or an unset
+        # time_zone) leaves this None; a non-string value is ignored likewise.
+        timezone=raw_timezone if isinstance(raw_timezone, str) else None,
     )
 
 
@@ -184,13 +243,17 @@ async def get_component_caps(client: Any) -> ComponentCaps | None:
       installed / upgraded mid-session (the REST client — the cache key — is not
       recreated on an HA restart) is eventually adopted instead of pinned absent.
     - ``HomeAssistantConnectionError`` / ``HomeAssistantCommandTimeout`` (WS
-      down or slow): do **not** cache — re-probe on the next call once the
-      connection recovers. The consuming tool's legacy path will surface the
-      transport failure on its own.
+      down or slow) — and the plain ``Exception`` ``get_websocket_client()`` raises
+      when ``WebSocketManager`` can't build the socket: cache a SHORT transient
+      negative (``_TRANSIENT_NEGATIVE_CACHE_TTL_S``) so repeated calls on a
+      WS-broken install skip the slow connect and go straight to legacy, then
+      re-probe once the window lapses (self-healing). The consuming tool's legacy
+      path serves the request meanwhile.
     - No credentials on the client (a bare test double with no ``base_url`` /
       ``token``): nothing to probe; return ``None`` without caching.
-    - Any other unexpected exception: logged at debug, returns ``None`` without
-      caching (a transient runtime fault re-probes on the next call).
+    - Any other unexpected exception: logged at debug, cached as the same short
+      transient negative (dominated by the connect-establishment failure above; a
+      genuine runtime fault re-probes after the window).
 
     A probe whose ``schema_version`` is not ``SUPPORTED_SCHEMA_VERSION`` is
     treated as no-caps (cached negative, logged once): the server can't trust
@@ -223,9 +286,14 @@ async def get_component_caps(client: Any) -> ComponentCaps | None:
             logger.debug(
                 "%s probe skipped: WS unavailable", INFO_COMMAND, exc_info=True
             )
+            _store_transient_negative(client)
             return None
         except Exception:
+            # Includes the plain Exception get_websocket_client() raises when
+            # WebSocketManager can't build the socket — the connect-establishment
+            # failure review-5 M8 targets. Short transient cache, self-healing.
             logger.debug("%s probe failed unexpectedly", INFO_COMMAND, exc_info=True)
+            _store_transient_negative(client)
             return None
 
         caps = _parse_caps(response)
@@ -265,3 +333,4 @@ def invalidate_caps(client: Any) -> None:
     """
     _CAPS_CACHE.pop(client, None)
     _NEGATIVE_CACHE_TS.pop(client, None)
+    _TRANSIENT_NEGATIVE_TS.pop(client, None)