homeassistant-ai
diff --git a/‎custom_components/ha_mcp_tools/const.py‎
Lines changed: 1 addition & 1 deletion b/‎custom_components/ha_mcp_tools/const.py‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎custom_components/ha_mcp_tools/manifest.json‎
Lines changed: 5 additions & 3 deletions b/‎custom_components/ha_mcp_tools/manifest.json‎
Lines changed: 5 additions & 3 deletions
diff --git a/‎custom_components/ha_mcp_tools/websocket_api.py‎
Lines changed: 2362 additions & 52 deletions b/‎custom_components/ha_mcp_tools/websocket_api.py‎
Lines changed: 2362 additions & 52 deletions
diff --git a/‎src/ha_mcp/backup_manager.py‎
Lines changed: 63 additions & 21 deletions b/‎src/ha_mcp/backup_manager.py‎
Lines changed: 63 additions & 21 deletions
diff --git a/‎src/ha_mcp/tools/backup.py‎
Lines changed: 149 additions & 20 deletions b/‎src/ha_mcp/tools/backup.py‎
Lines changed: 149 additions & 20 deletions
@@ -24,7 +24,7 @@
 # manifest bump that forgets this constant (or vice-versa) fails in CI. The
 # capability negotiation — not this version — gates each WS command (see
 # ``websocket_api.CAPABILITIES``).
-COMPONENT_VERSION = "1.1.1"
+COMPONENT_VERSION = "1.2.0"
 
 # Config-entry discriminator (``entry.data[CONF_ENTRY_TYPE]``). A missing value
 # means "tools" so the pre-existing services entry keeps working across the
 
@@ -2,9 +2,11 @@
     "domain": "ha_mcp_tools",
     "name": "HA-MCP Custom Component",
     "after_dependencies": [
-        "http",
+        "backup",
         "cloud",
-        "frontend"
+        "frontend",
+        "http",
+        "lovelace"
     ],
     "codeowners": [
         "@homeassistant-ai"
@@ -19,5 +21,5 @@
     "requirements": [
         "ruamel.yaml>=0.18.0"
     ],
-    "version": "1.1.1"
+    "version": "1.2.0"
 }
@@ -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}
 
@@ -30,10 +30,21 @@
     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 @@
 # _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