ha-mcp-dev 8.4.3.dev2602__tar.gz → 8.4.3.dev2608__tar.gz

{ha_mcp_dev-8.4.3.dev2602/src/ha_mcp_dev.egg-info → ha_mcp_dev-8.4.3.dev2608}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 8.4.3.dev2602
+Version: 8.4.3.dev2608
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT
@@ -239,7 +239,7 @@ Spend less time configuring, more time enjoying your smart home.
 |----------|--------------|
 | **🔍 Search** | Fuzzy entity search, deep config search, system overview |
 | **🏠 Control** | Any service, bulk device control, real-time states |
-| **🔧 Manage** | Automations, scripts, helpers, dashboards, areas, zones, groups, calendars, blueprints |
+| **🔧 Manage** | Automations, scripts, helpers, [dashboards](docs/dashboard-edits.md), areas, zones, groups, calendars, blueprints |
 | **📊 Monitor** | History, statistics, camera snapshots, automation traces, ZHA devices |
 | **💾 System** | Backup/restore, updates, apps, device registry |
 | **🔒 Safety** | Read Only Mode toggle, per-tool enable/disable, tool security policies (user approval), automatic edit backups |

{ha_mcp_dev-8.4.3.dev2602 → ha_mcp_dev-8.4.3.dev2608}/README.md

@@ -207,7 +207,7 @@ Spend less time configuring, more time enjoying your smart home.
 |----------|--------------|
 | **🔍 Search** | Fuzzy entity search, deep config search, system overview |
 | **🏠 Control** | Any service, bulk device control, real-time states |
-| **🔧 Manage** | Automations, scripts, helpers, dashboards, areas, zones, groups, calendars, blueprints |
+| **🔧 Manage** | Automations, scripts, helpers, [dashboards](docs/dashboard-edits.md), areas, zones, groups, calendars, blueprints |
 | **📊 Monitor** | History, statistics, camera snapshots, automation traces, ZHA devices |
 | **💾 System** | Backup/restore, updates, apps, device registry |
 | **🔒 Safety** | Read Only Mode toggle, per-tool enable/disable, tool security policies (user approval), automatic edit backups |

{ha_mcp_dev-8.4.3.dev2602 → ha_mcp_dev-8.4.3.dev2608}/pyproject.toml

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

@@ -727,7 +727,8 @@ class HomeAssistantSmartMCPServer:
             "ha_config_get_automation), or `take_control_of_blueprint` "
             "to convert a blueprint-backed automation into an editable "
             "standalone one (the UI's Take control action). Omit "
-            "`identifier` to create a new automation.\n\n"
+            "`identifier` to create a new automation. Reusing an identifier targets "
+            "the same automation; changing its alias requires config_hash from a prior read.\n\n"
             "For schema details, examples, and native-vs-template "
             "guidance, see ha_get_skill_guide or your locally "
             "installed skills."
@@ -806,18 +807,22 @@ class HomeAssistantSmartMCPServer:
             "matched cards surgically. (3) get — no search params "
             "returns the full Lovelace config plus a stable "
             "`config_hash`. Use `url_path='default'` for the main "
-            "dashboard.\n\n"
+            "dashboard. For known JSON Pointer paths, use "
+            "ha_config_set_dashboard(patch=..., config_hash=...).\n\n"
             "For card-type taxonomy and search workflow examples, see "
             "ha_get_skill_guide."
         ),
         "ha_config_set_dashboard": (
             "Create or update a Home Assistant dashboard.\n\n"
-            "Supports two modes: full `config` replacement (new "
-            "dashboards or full restructures), or surgical "
-            "`python_transform` on an existing dashboard (requires "
-            "`config_hash` from ha_config_get_dashboard; recommended "
-            "for edits). Use `url_path` of 'default' or 'lovelace' "
-            "to target the built-in dashboard.\n\n"
+            "Three modes: full `config` replacement for new dashboards or "
+            "restructures; `patch` for known JSON Pointer paths with literal "
+            "values (add/remove/replace/test, up to 100 operations; use `-` "
+            "to append to arrays); `python_transform` for loops and pattern-based "
+            "edits. Both edit modes require `config_hash` from "
+            "ha_config_get_dashboard. Choose one mode for content changes; "
+            "omit all three for metadata-only calls. With patch, change "
+            "sidebar metadata in a separate call. Use `url_path` of 'default' "
+            "or 'lovelace' for the built-in dashboard.\n\n"
             "For card types, layout patterns, and python_transform "
             "security rules, see "
             "ha_get_skill_guide or your locally installed skills."

{ha_mcp_dev-8.4.3.dev2602 → ha_mcp_dev-8.4.3.dev2608}/src/ha_mcp/tools/component_api.py

@@ -67,20 +67,18 @@ DEVICE_REGISTRY_CHILD_SEMANTICS = "device_registry_child_semantics"
 # time, so a component installed / upgraded mid-session is re-probed and
 # adopted instead of being pinned to "absent" for the whole process lifetime
 # (the cache key is the process-lifetime REST client — see ``_CAPS_CACHE``).
-# Positive entries never expire on this timer; they are dropped only by
+# Valid positive entries never expire on this timer; they are dropped only by
 # ``invalidate_caps`` (a supposedly-supported command coming back
 # ``unknown_command``). This ABSENT-negative window covers a definitive
 # "component responded, no usable surface" verdict (``unknown_command`` /
-# malformed / unsupported schema_version).
+# unsupported schema_version). Inconclusive failures use the short window below.
 _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.
+# A separate, SHORTER window for inconclusive discovery: transport failures,
+# info handler errors, unexpected faults, and malformed replies. Caching these
+# briefly avoids repeating a broken probe on every tool call (issue #1813 Phase 2,
+# review-5 M8), while allowing strict writers to recover promptly after discovery
+# works again. These failures do not establish that a capability is absent.
 _TRANSIENT_NEGATIVE_CACHE_TTL_S = 30.0
 
 
@@ -121,29 +119,47 @@ class ComponentCaps:
 # Weak-keyed by client so the negotiated caps self-evict when the client is
 # garbage-collected. The key is the process-lifetime REST client, NOT the WS
 # connection: an HA restart drops the socket but reuses the same pooled client,
-# so a positive entry persists for the whole process (dropped only by
+# so a valid 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".
 # 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
+# (inconclusive failure, 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 definitive ABSENT-negative was stored, keyed by the same
-# client. Only populated for ``None`` values; positive entries never appear here.
+# client. Inconclusive failures never use this window.
 _NEGATIVE_CACHE_TS: weakref.WeakKeyDictionary[Any, float] = weakref.WeakKeyDictionary()
-# Monotonic timestamp a TRANSIENT (transport-failure) negative was stored. Kept
+# Monotonic timestamp an inconclusive probe failure was stored. Also expires
+# malformed snapshots retained for permissive readers. 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()
 )
+# Preserve failed discovery separately so write callers can refuse a downgrade
+# even when a best-effort read populated the negative cache first. Store only
+# text, not exceptions whose traceback would retain clients through weak keys.
+_PROBE_FAILURES: weakref.WeakKeyDictionary[Any, str] = weakref.WeakKeyDictionary()
 _CAPS_LOCKS: weakref.WeakKeyDictionary[Any, asyncio.Lock] = weakref.WeakKeyDictionary()
 
 
+class ComponentDiscoveryError(RuntimeError):
+    """Discovery failed without establishing which component commands are usable."""
+
+
+def _checked_caps(
+    client: Any, caps: ComponentCaps | None, strict: bool
+) -> ComponentCaps | None:
+    """Keep read fallbacks while exposing failed discovery to write callers."""
+    if strict and (failure := _PROBE_FAILURES.get(client)):
+        raise ComponentDiscoveryError(failure)
+    return caps
+
+
 def _get_caps_lock(client: Any) -> asyncio.Lock:
     """Per-client lock so concurrent first-callers probe ``info`` exactly once."""
     lock = _CAPS_LOCKS.get(client)
@@ -156,28 +172,29 @@ def _get_caps_lock(client: Any) -> asyncio.Lock:
 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``)
+    A valid positive entry is a hit for the process lifetime. Malformed replies
+    retained for permissive readers expire like transient failures. A negative (``None``)
     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
+    ``_TRANSIENT_NEGATIVE_CACHE_TTL_S`` for an inconclusive failure. 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:
+    if cached is not None and client not in _PROBE_FAILURES:
         return True, cached
     now = _monotonic()
     stored_at = _NEGATIVE_CACHE_TS.get(client)
     if stored_at is not None and (now - stored_at) < _NEGATIVE_CACHE_TTL_S:
-        return True, None
+        return True, cached
     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 True, cached
     return False, None
 
 
@@ -185,9 +202,10 @@ def _store_caps(client: Any, caps: ComponentCaps | None) -> None:
     """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
+    ``unknown_command`` / unsupported schema). Clears any prior
     transient-negative stamp so a client never carries both negative kinds.
     """
+    _PROBE_FAILURES.pop(client, None)
     _CAPS_CACHE[client] = caps
     _TRANSIENT_NEGATIVE_TS.pop(client, None)
     if caps is None:
@@ -196,17 +214,16 @@ def _store_caps(client: Any, caps: ComponentCaps | None) -> None:
         _NEGATIVE_CACHE_TS.pop(client, None)
 
 
-def _store_transient_negative(client: Any) -> None:
-    """Cache a SHORT transient negative after a transport-failure probe.
+def _store_transient_negative(client: Any, caps: ComponentCaps | None = None) -> None:
+    """Cache an inconclusive probe for the short recovery window.
 
-    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.
+    Read callers retain legacy fallback or a permissively parsed snapshot.
+    Strict writers reject the accompanying probe failure until the next probe
+    succeeds. Preserve parsed capabilities from malformed replies for readers,
+    while expiring them on the same short timer as failed probes. Clear any
+    prior absent-negative stamp so a client never carries both cache windows.
     """
-    _CAPS_CACHE[client] = None
+    _CAPS_CACHE[client] = caps
     _NEGATIVE_CACHE_TS.pop(client, None)
     _TRANSIENT_NEGATIVE_TS[client] = _monotonic()
 
@@ -214,8 +231,8 @@ def _store_transient_negative(client: Any) -> None:
 def _parse_caps(response: Any) -> ComponentCaps | None:
     """Map an ``ha_mcp_tools/info`` response into ``ComponentCaps``.
 
-    Returns ``None`` for a malformed payload — the command responded, so this
-    is still a stable negative worth caching, just not a usable capability set.
+    Parse permissively for existing read callers. A missing result returns
+    ``None``; strict callers separately reject malformed discovery.
     """
     result = response.get("result") if isinstance(response, dict) else None
     if not isinstance(result, dict):
@@ -249,17 +266,25 @@ def _parse_caps(response: Any) -> ComponentCaps | None:
     )
 
 
-async def get_component_caps(client: Any) -> ComponentCaps | None:
+async def get_component_caps(
+    client: Any, *, strict: bool = False
+) -> ComponentCaps | None:
     """Return the cached (or freshly probed) capabilities of the component.
 
     One ``ha_mcp_tools/info`` probe per client, cached. ``None`` means "no
     usable component WS surface" — the caller falls back to its legacy path.
 
+    With ``strict=True``, failed or malformed discovery raises
+    ``ComponentDiscoveryError``, including failures cached by earlier read tools.
+    A definitive unknown command, unsupported schema, or valid capability list
+    without the requested command still permits legacy routing. The default
+    retains best-effort read behavior. Inconclusive failures expire after 30
+    seconds for both readers and writers.
+
     Cache-on-failure semantics follow the error taxonomy:
 
-    - ``HomeAssistantCommandError`` (``info`` is ``unknown_command`` on an old
-      component, or the handler raised): cache ``None`` with an expiry. The
-      negative is re-probed after ``_NEGATIVE_CACHE_TTL_S`` so a component
+    - ``HomeAssistantCommandError`` with ``unknown_command`` (old or absent
+      component): cache ``None`` with an expiry. The negative is re-probed after ``_NEGATIVE_CACHE_TTL_S`` so a component
       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
@@ -268,12 +293,12 @@ async def get_component_caps(client: Any) -> ComponentCaps | None:
       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.
+      path serves read requests meanwhile; strict writers refuse the edit.
     - 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, cached as the same short
-      transient negative (dominated by the connect-establishment failure above; a
-      genuine runtime fault re-probes after the window).
+    - Other command errors, malformed replies, or unexpected exceptions: cache
+      for the same short transient window. None establishes capability absence;
+      strict writers refuse the edit until a subsequent probe succeeds.
 
     A probe whose ``schema_version`` is not ``SUPPORTED_SCHEMA_VERSION`` is
     treated as no-caps (cached negative, logged once): the server can't trust
@@ -281,12 +306,12 @@ async def get_component_caps(client: Any) -> ComponentCaps | None:
     """
     hit, caps = _live_cache_entry(client)
     if hit:
-        return caps
+        return _checked_caps(client, caps, strict)
 
     async with _get_caps_lock(client):
         hit, caps = _live_cache_entry(client)
         if hit:
-            return caps
+            return _checked_caps(client, caps, strict)
 
         base_url = getattr(client, "base_url", None)
         token = getattr(client, "token", None)
@@ -305,23 +330,29 @@ async def get_component_caps(client: Any) -> ComponentCaps | None:
                 url=base_url, token=token, verify_ssl=verify_ssl
             )
             response = await ws.send_command(INFO_COMMAND)
-        except HomeAssistantCommandError:
-            # Old component (unknown_command) or an info handler bug: the
-            # component can't serve WS commands. Cache the negative.
-            _store_caps(client, None)
-            return None
+        except HomeAssistantCommandError as exc:
+            if is_unknown_command(exc):
+                _store_caps(client, None)
+            else:
+                _store_transient_negative(client)
+                _PROBE_FAILURES[client] = f"{INFO_COMMAND} failed: {exc}"
+            return _checked_caps(client, None, strict)
         except (HomeAssistantConnectionError, HomeAssistantCommandTimeout):
             logger.debug(
                 "%s probe skipped: WS unavailable", INFO_COMMAND, exc_info=True
             )
             _store_transient_negative(client)
-            return None
+            _PROBE_FAILURES[client] = (
+                f"{INFO_COMMAND} probe could not reach Home Assistant"
+            )
+            return _checked_caps(client, None, strict)
         except Exception:
-            # Broad on purpose: the probe must never promote an unexpected
-            # fault into a tool failure. Short transient cache, self-healing.
+            # Read callers retain best-effort fallback; strict write callers
+            # must not confuse an unexpected fault with capability absence.
             logger.debug("%s probe failed unexpectedly", INFO_COMMAND, exc_info=True)
             _store_transient_negative(client)
-            return None
+            _PROBE_FAILURES[client] = f"{INFO_COMMAND} probe failed unexpectedly"
+            return _checked_caps(client, None, strict)
 
         caps = _parse_caps(response)
         if caps is not None and caps.schema_version != SUPPORTED_SCHEMA_VERSION:
@@ -333,7 +364,20 @@ async def get_component_caps(client: Any) -> ComponentCaps | None:
             )
             caps = None
         _store_caps(client, caps)
-        return caps
+        result = response.get("result") if isinstance(response, dict) else None
+        if (
+            not isinstance(response, dict)
+            or response.get("success") is not True
+            or not isinstance(result, dict)
+            or type(result.get("schema_version")) is not int
+            or not isinstance(result.get("capabilities"), list)
+            or not all(isinstance(cap, str) for cap in result["capabilities"])
+        ):
+            # Keep permissive parsing for existing read callers, but expire
+            # malformed positive snapshots too so strict callers can recover.
+            _store_transient_negative(client, caps)
+            _PROBE_FAILURES[client] = f"Malformed {INFO_COMMAND} response"
+        return _checked_caps(client, caps, strict)
 
 
 def component_supports(caps: ComponentCaps | None, capability: str) -> bool:
@@ -358,6 +402,7 @@ def invalidate_caps(client: Any) -> None:
     ``unknown_command`` (e.g. the component was downgraded mid-session), so the
     stale positive doesn't keep routing to a dead command.
     """
+    _PROBE_FAILURES.pop(client, None)
     _CAPS_CACHE.pop(client, None)
     _NEGATIVE_CACHE_TS.pop(client, None)
     _TRANSIENT_NEGATIVE_TS.pop(client, None)

ha_mcp_dev-8.4.3.dev2608/src/ha_mcp/tools/component_dashboard_edit.py

@@ -0,0 +1,169 @@
+"""Capability-negotiated dashboard writes with no retry after a sent command."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any, NoReturn
+
+from ..client.rest_client import HomeAssistantCommandError, HomeAssistantCommandNotSent
+from ..client.websocket_client import get_websocket_client
+from .component_api import (
+    component_supports,
+    get_component_caps,
+    invalidate_caps,
+    is_unknown_command,
+)
+from .dashboard_edit_errors import raise_dashboard_edit_error
+
+WS_DASHBOARD_EDIT = "ha_mcp_tools/dashboard_edit"
+_LOGGER = logging.getLogger(__name__)
+
+
+def _invalid_success_fields(result: dict[str, Any]) -> list[str]:
+    """Identify invalid consumed fields without copying dashboard values into logs."""
+    verified = result.get("post_write_verified")
+    config_hash = result.get("config_hash")
+    size = result.get("previous_config_size")
+    warnings = result.get("warnings", [])
+    checks = {
+        "success": result.get("success") is True,
+        "config": isinstance(result.get("config"), dict),
+        "config_hash": "config_hash" in result
+        and (isinstance(config_hash, str) if verified else config_hash is None),
+        "post_write_verified": isinstance(verified, bool),
+        "write_committed": isinstance(result.get("write_committed"), bool),
+        "previous_config_size": isinstance(size, int)
+        and not isinstance(size, bool)
+        and size >= 0,
+        "warnings": isinstance(warnings, list)
+        and all(isinstance(warning, str) for warning in warnings),
+        "unchanged": isinstance(result.get("unchanged", False), bool),
+    }
+    return [name for name, valid in checks.items() if not valid]
+
+
+def _raise_malformed_reply(
+    url_path: str | None, action: str, fields: list[str]
+) -> NoReturn:
+    """Diagnose protocol skew without logging the config, templates, or card values."""
+    details = ", ".join(fields)
+    _LOGGER.warning("Malformed dashboard_edit response; invalid fields: %s", details)
+    raise_dashboard_edit_error(
+        url_path,
+        "write_outcome_unknown",
+        f"Malformed response fields: {details}",
+        None,
+        action,
+    )
+
+
+def _validate_edit_result(
+    raw: Any, url_path: str | None, action: str, *, hash_supplied: bool = False
+) -> dict[str, Any]:
+    """An incomplete response cannot establish whether the write happened."""
+    if not isinstance(raw, dict):
+        _raise_malformed_reply(url_path, action, ["envelope"])
+    if raw.get("success") is not True:
+        _raise_malformed_reply(url_path, action, ["envelope.success"])
+    result = raw.get("result")
+    if not isinstance(result, dict):
+        _raise_malformed_reply(url_path, action, ["result"])
+    if result.get("success") is False:
+        error = result.get("error")
+        if not isinstance(error, dict) or not isinstance(error.get("code"), str):
+            _raise_malformed_reply(url_path, action, ["error.code"])
+        committed = result.get("write_committed")
+        if committed is not False and committed is not None:
+            _raise_malformed_reply(url_path, action, ["write_committed"])
+        raise_dashboard_edit_error(
+            url_path,
+            error["code"],
+            str(error.get("message", error["code"])),
+            committed,
+            action,
+            hash_supplied=hash_supplied,
+        )
+    invalid_fields = _invalid_success_fields(result)
+    if invalid_fields:
+        _raise_malformed_reply(url_path, action, invalid_fields)
+    return result
+
+
+def _handle_command_failure(
+    exc: BaseException, client: Any, url_path: str | None, action: str
+) -> None:
+    """Only a missing command allows fallback; other failures terminate the edit."""
+    if isinstance(exc, HomeAssistantCommandNotSent):
+        raise_dashboard_edit_error(url_path, "write_not_sent", str(exc), False, action)
+    if isinstance(exc, Exception) and is_unknown_command(exc):
+        invalidate_caps(client)
+        return
+    # Core's schema/admin gates reject these before this command's prep runs.
+    # Other command errors can originate after dispatch and remain ambiguous.
+    if isinstance(exc, HomeAssistantCommandError) and exc.code in {
+        "unauthorized",
+        "invalid_format",
+    }:
+        raise_dashboard_edit_error(url_path, exc.code, str(exc), False, action)
+    _LOGGER.warning("Dashboard edit command failed after dispatch", exc_info=exc)
+    raise_dashboard_edit_error(
+        url_path,
+        "write_outcome_unknown",
+        str(exc) or "Dashboard edit interrupted before its response was received",
+        None,
+        action,
+    )
+
+
+async def edit_dashboard_via_component(
+    client: Any,
+    url_path: str | None,
+    *,
+    action: str = "set",
+    expected_hash: str | None = None,
+    config: dict[str, Any] | None = None,
+    patch: list[dict[str, Any]] | None = None,
+) -> dict[str, Any] | None:
+    """Return an authoritative edit result, or None for an unavailable command.
+
+    Legacy fallback requires confirmed absence of a compatible capability or
+    HA's definitive unknown_command. Never use the REST client's retrying
+    WebSocket bridge for a native write.
+    ``action`` labels local error responses only; it is not a command argument.
+    """
+    # Clients without connection credentials cannot probe the component.
+    if not getattr(client, "base_url", None) or not getattr(client, "token", None):
+        return None
+    try:
+        caps = await get_component_caps(client, strict=True)
+        if not component_supports(caps, "dashboard_edit"):
+            return None
+        ws = await get_websocket_client(
+            url=client.base_url,
+            token=client.token,
+            verify_ssl=getattr(client, "verify_ssl", None),
+        )
+    except Exception as exc:
+        _LOGGER.warning(
+            "Unable to prepare the dashboard edit connection", exc_info=True
+        )
+        raise_dashboard_edit_error(url_path, "load_failed", str(exc), False, action)
+
+    kwargs: dict[str, Any] = {"url_path": url_path}
+    if expected_hash is not None:
+        kwargs["expected_hash"] = expected_hash
+    if config is not None:
+        kwargs["config"] = config
+    if patch is not None:
+        kwargs["patch"] = patch
+    try:
+        raw = await ws.send_command(WS_DASHBOARD_EDIT, **kwargs)
+    except (asyncio.CancelledError, Exception) as exc:
+        # Pre-dispatch cancellation still propagates; after dispatch it cannot
+        # establish whether Core saved unless an explicit rejection says so.
+        _handle_command_failure(exc, client, url_path, action)
+        return None
+    return _validate_edit_result(
+        raw, url_path, action, hash_supplied=expected_hash is not None
+    )