ha-mcp-dev 9.1.0.dev3282__tar.gz → 9.1.0.dev3289__tar.gz

{ha_mcp_dev-9.1.0.dev3282 → ha_mcp_dev-9.1.0.dev3289}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 9.1.0.dev3282
+Version: 9.1.0.dev3289
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Keywords: mcp,home-assistant,ai,automation,smart-home
 Author: Julien

{ha_mcp_dev-9.1.0.dev3282 → ha_mcp_dev-9.1.0.dev3289}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "9.1.0.dev3282"
+version = "9.1.0.dev3289"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 requires-python = ">=3.13,<3.15"

{ha_mcp_dev-9.1.0.dev3282 → ha_mcp_dev-9.1.0.dev3289}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "9.1.0.dev3282"
+version = "9.1.0.dev3289"
 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-9.1.0.dev3282 → ha_mcp_dev-9.1.0.dev3289}/src/ha_mcp/backup_manager.py

@@ -108,11 +108,12 @@ from .backup_todo import fetch_todo_item, restore_todo_item
 from .backup_todo import snapshot_item as todo_snapshot_item
 from .backup_zones import fetch_zone, restore_zone
 from .client.rest_client import (
+    HomeAssistantAuthError,
     HomeAssistantCommandError,
     HomeAssistantConnectionError,
     HomeAssistantError,
 )
-from .errors import ErrorCode
+from .errors import ErrorCode, get_error_code
 from .storage_helper_types import SIMPLE_HELPER_TYPES
 from .utils.data_paths import get_data_dir
 from .utils.registry_update_lock import registry_update_lock
@@ -2021,9 +2022,8 @@ async def _ws_send(client: Any, message: dict[str, Any]) -> Any:
         client.base_url, client.token, verify_ssl=client.verify_ssl
     )
     if error or ws_client is None:
-        # ``error`` is a structured-error envelope; the message can live
-        # under either error.error.message (nested) or error.message
-        # (flat, as ``create_error_response`` actually produces).
+        # ``error`` is get_connected_ws_client's nested envelope; the flat
+        # ``error["message"]`` read is a defensive fallback.
         if isinstance(error, dict):
             err_obj = error.get("error", error)
             msg = (
@@ -2031,11 +2031,10 @@ async def _ws_send(client: Any, message: dict[str, Any]) -> Any:
             ) or error.get("message", "WS connect failed")
         else:
             msg = "WS connect failed"
-        # Typed connection error so the outer ``_CAPTURE_TRANSIENT_ERRORS``
-        # tuple catches it; a bare ``RuntimeError`` would propagate past
-        # ``maybe_snapshot``'s catch and break the wrapped write — exactly
-        # what the best-effort contract on the decorator forbids.
-        raise HomeAssistantConnectionError(msg)
+        # Typed so ``_CAPTURE_TRANSIENT_ERRORS`` catches it (a bare ``RuntimeError``
+        # would break the best-effort write); a rejected token reports AUTH_*.
+        auth = str(get_error_code(error or {})).startswith("AUTH_")
+        raise (HomeAssistantAuthError if auth else HomeAssistantConnectionError)(msg)
     try:
         cmd_type = message.pop("type")
         envelope = await ws_client.send_command(cmd_type, **message)
@@ -2071,25 +2070,13 @@ async def _ws_send(client: Any, message: dict[str, Any]) -> Any:
 
 
 async def _fetch_automation(client: Any, entity_id: str) -> Any:
-    """Fetch an automation through the same path the get tool uses.
-
-    Applies ``_normalize_config_for_roundtrip`` so the snapshot matches
-    what ``ha_config_get_automation`` returns and round-trips cleanly
-    back through ``ha_config_set_automation`` on restore. Imported lazily
-    to keep the manager import-cycle-free.
-    """
-    # Lazy import to avoid backup_manager → tools → backup_manager cycle.
-    from .tools.tools_config_automations import _normalize_config_for_roundtrip
-
+    """Fetch the stored body verbatim."""
     try:
-        raw = await client.get_automation_config(entity_id)
+        return await client.get_automation_config(entity_id)
     except HomeAssistantError as err:
         if getattr(err, "status_code", None) == 404:
             return None
         raise
-    if not isinstance(raw, dict):
-        return raw
-    return _normalize_config_for_roundtrip(raw)
 
 
 async def _restore_automation(client: Any, entity_id: str, config: Any) -> Any:

{ha_mcp_dev-9.1.0.dev3282 → ha_mcp_dev-9.1.0.dev3289}/src/ha_mcp/client/rest_client.py

@@ -90,16 +90,17 @@ class HomeAssistantConnectionError(HomeAssistantError):
 class HomeAssistantCommandNotSent(HomeAssistantConnectionError):
     """A WS command that provably never left the process.
 
-    Raised by ``HomeAssistantWebSocketClient.send_command`` ONLY at its single
-    provably-never-sent site: the entry-guard reject (socket not authenticated), where
-    nothing is transmitted. Subclass of ``HomeAssistantConnectionError`` so every
-    existing broad handler is unaffected, yet a write consumer can catch this type
-    FIRST to fall back to the legacy path safely — the write provably never happened,
-    so a legacy first fire cannot double-apply. A ``send_json_message`` failure is NOT
-    this type: ``websocket.send()`` raising does not prove the frame was untransmitted
-    (bytes may already be on the socket when the close surfaces), so send_command
-    re-raises the original exception and the consumer treats it as ambiguous. A
-    post-send socket close (mid-await) likewise raises a plain
+    Raised by ``HomeAssistantWebSocketClient.send_command``'s entry guard (socket not
+    authenticated) and by ``send_websocket_message`` when no attempt obtained a client
+    (raised from the acquisition error, so a rejected token survives as ``__cause__``).
+    A subclass of ``HomeAssistantConnectionError``, so broad handlers are unaffected,
+    yet a write consumer can catch it FIRST: the write provably never happened, so a
+    legacy first fire cannot double-apply. Check ``__cause__`` before such a fallback:
+    resending a rejected token over REST adds a 401 toward Home Assistant's IP ban. A
+    ``send_json_message`` failure is NOT this type: ``websocket.send()`` raising does
+    not prove the frame was untransmitted (bytes may already be on the socket when the
+    close surfaces), so send_command re-raises the original exception and the consumer
+    treats it as ambiguous. A post-send socket close (mid-await) likewise raises a plain
     ``HomeAssistantConnectionError`` (the close handler sets it on the pending future),
     so type alone distinguishes never-sent from sent-then-dropped/ambiguous.
     """
@@ -1376,40 +1377,44 @@ class HomeAssistantClient:
     # Automation Configuration Management
 
     async def _resolve_automation_id(self, identifier: str) -> str:
-        """Convert entity_id to unique_id if needed, or return unique_id as-is.
+        """Return the config id of ``identifier`` (an entity_id or a config id).
 
-        Args:
-            identifier: Either entity_id (automation.xxx) or unique_id
-
-        Returns:
-            The unique_id for configuration API
+        An entity_id resolves through the entity registry first, so a disabled
+        automation (no state) resolves too; the state's ``id`` attribute is the
+        fallback when the registry does not answer with a ``unique_id``.
 
         Raises:
             HomeAssistantAPIError: 404 if not found; other read failures propagate
         """
-        if identifier.startswith("automation."):
-            try:
-                state = await self.get_entity_state(identifier)
-                unique_id = state.get("attributes", {}).get("id")
-                if not unique_id:
-                    raise HomeAssistantAPIError(
-                        f"Automation {identifier} has no unique_id attribute",
-                        status_code=404,
-                    )
-                logger.debug(
-                    f"Converted entity_id {identifier} to unique_id {unique_id}"
-                )
-                return str(unique_id)
-            except HomeAssistantAPIError as e:
-                if e.status_code != 404:  # a failed read is not a missing one
-                    raise
-                raise HomeAssistantAPIError(
-                    f"Failed to resolve automation {identifier}: {str(e)}",
-                    status_code=404,
-                ) from e
-        else:
-            # Assume it's already a unique_id
+        if not identifier.startswith("automation."):
             return identifier
+        try:
+            entry = await self.send_websocket_message(
+                {"type": "config/entity_registry/get", "entity_id": identifier}
+            )
+        except HomeAssistantConnectionError as e:
+            logger.debug(f"Registry lookup for {identifier} failed: {e}")
+            entry = {}
+        if entry.get("success"):
+            unique_id = (entry.get("result") or {}).get("unique_id")
+            if unique_id:
+                return str(unique_id)
+        try:
+            state = await self.get_entity_state(identifier)
+        except HomeAssistantAPIError as e:
+            if e.status_code != 404:  # a failed read is not a missing one
+                raise
+            raise HomeAssistantAPIError(
+                f"Failed to resolve automation {identifier}: {str(e)}",
+                status_code=404,
+            ) from e
+        unique_id = state.get("attributes", {}).get("id")
+        if not unique_id:
+            raise HomeAssistantAPIError(
+                f"Automation {identifier} has no unique_id attribute",
+                status_code=404,
+            )
+        return str(unique_id)
 
     async def get_automation_config(self, identifier: str) -> dict[str, Any]:
         """Get automation configuration by unique_id or entity_id.
@@ -1445,19 +1450,19 @@ class HomeAssistantClient:
         identifier: str | None = None,
         *,
         _resolved: bool = False,
+        wait_for_entity: bool = False,
     ) -> dict[str, Any]:
         """
         Create new automation or update existing one.
 
         Args:
-            config: Automation configuration dictionary
-            identifier: Optional automation entity_id or unique_id (None = create new)
-            _resolved: When True, ``identifier`` is already the resolved unique_id
-                (the caller ran ``_resolve_automation_id``), so the redundant
-                entity_id→unique_id lookup is skipped. Ignored on the create path
-                (``identifier is None``). The #1404 config-id mismatch guard below
-                is unaffected — it still compares ``config['id']`` to the resolved
-                unique_id.
+            config: Automation configuration dictionary, sent as given
+            identifier: Optional automation entity_id or config id (None = create new)
+            _resolved: When True, ``identifier`` is already the config id (the
+                caller resolved it), so the entity_id lookup is skipped. The
+                #1404 config-id mismatch guard below still applies.
+            wait_for_entity: Poll for the entity the write registers, as a
+                creation does, and report it as ``entity_id``.
 
         Returns:
             Result with automation unique_id and status
@@ -1465,19 +1470,14 @@ class HomeAssistantClient:
         Raises:
             HomeAssistantAPIError: If configuration invalid or API error
         """
-        # Generate unique_id for new automation if not provided
         if identifier is None:
             unique_id = str(int(time.time() * 1000))
-            operation = "created"
-            logger.debug(f"Creating new automation with unique_id: {unique_id}")
         else:
             unique_id = (
                 identifier
                 if _resolved
                 else await self._resolve_automation_id(identifier)
             )
-            operation = "updated"
-            logger.debug(f"Updating automation with unique_id: {unique_id}")
 
         # Reject mismatch between resolved storage key and inner ``config["id"]``.
         # HA stores by the inner id field even though the URL carries one too —
@@ -1490,20 +1490,20 @@ class HomeAssistantClient:
                     "Cannot create automation with explicit config['id']="
                     f"{config_id!r}: Home Assistant stores by the inner id, "
                     "which would silently overwrite an existing automation. "
-                    "Omit 'id' from config to auto-generate, or pass identifier "
+                    "Omit 'id' from config to auto-generate, or pass entity_id "
                     "to update an existing automation.",
                     status_code=400,
                 )
             raise HomeAssistantAPIError(
-                f"Mismatched automation id: identifier={identifier!r} resolves "
-                f"to unique_id={unique_id!r}, but config['id']={config_id!r}. "
+                f"Mismatched automation id: the target's config id is "
+                f"{unique_id!r}, but config['id']={config_id!r}. "
                 "Refusing to write to prevent overwriting the wrong automation. "
-                f"Remove 'id' from config or set it to the resolved unique_id "
+                f"Remove 'id' from config or set it to the target's config id "
                 f"({unique_id!r}).",
                 status_code=400,
             )
 
-        # Add unique_id to config for updates
+        # Core stores by the body's id, so it carries the target's.
         if unique_id and "id" not in config:
             config = {**config, "id": unique_id}
 
@@ -1512,10 +1512,9 @@ class HomeAssistantClient:
                 "POST", f"/config/automation/config/{unique_id}", json=config
             )
 
-            # For new automations, query Home Assistant to get the actual entity_id that was assigned
             actual_entity_id = None
             entity_not_verified = False
-            if operation == "created":
+            if wait_for_entity:
                 actual_entity_id = await self._poll_for_automation_entity(unique_id)
                 if not actual_entity_id:
                     entity_not_verified = True
@@ -1524,7 +1523,6 @@ class HomeAssistantClient:
                 "unique_id": unique_id,
                 "entity_id": actual_entity_id,
                 "result": response.get("result", "ok"),
-                "operation": operation,
             }
             if entity_not_verified:
                 result["entity_not_verified"] = True
@@ -1532,7 +1530,9 @@ class HomeAssistantClient:
         except HomeAssistantAPIError as e:
             if e.status_code == 400:
                 raise HomeAssistantAPIError(
-                    f"Invalid automation configuration: {str(e)}", status_code=400
+                    f"Invalid automation configuration: {str(e)}",
+                    status_code=400,
+                    response_data=e.response_data,
                 ) from e
             raise
 
@@ -1609,27 +1609,11 @@ class HomeAssistantClient:
                 "operation": "deleted",
             }
         except HomeAssistantAPIError as e:
-            if e.status_code == 404:
-                raise HomeAssistantAPIError(
-                    f"Automation not found: {identifier} (unique_id: {unique_id})",
-                    status_code=404,
-                ) from e
-            elif e.status_code == 405:
-                raise HomeAssistantAPIError(
-                    f"Cannot delete automation '{identifier}': The HTTP DELETE method is blocked. "
-                    f"This typically occurs when running ha-mcp as a Home Assistant add-on, because "
-                    f"the Supervisor ingress proxy only allows GET and POST requests. "
-                    f"WORKAROUNDS: "
-                    f"(1) Use ha-mcp via pip, Docker, or as an external MCP server instead of the add-on. "
-                    f"(2) Use a long-lived access token to connect directly to Home Assistant's API. "
-                    f"(3) As a fallback, disable the automation and rename it with a 'DELETE_' prefix "
-                    f"(e.g., 'DELETE_{identifier}') so you can identify and manually delete it later "
-                    f"via the Home Assistant UI (Settings > Automations & Scenes).",
-                    status_code=405,
-                ) from e
-            raise
-        except Exception as e:
-            if "404" in str(e):
+            # Core's DELETE answers a missing id with 400, not 404.
+            if (
+                e.status_code == 400
+                and (e.response_data or {}).get("message") == "Resource not found"
+            ):
                 raise HomeAssistantAPIError(
                     f"Automation not found: {identifier} (unique_id: {unique_id})",
                     status_code=404,
@@ -1955,12 +1939,11 @@ class HomeAssistantClient:
 
         max_retries = 2
         retry_delay = 0.5  # seconds
+        # Whether an earlier attempt got past acquisition, so may have sent.
+        sent_before = False
 
         for attempt in range(max_retries):
             # Whether the failure happened before a usable connection existed.
-            # Failing to obtain one is transport death whatever class the
-            # manager raises; an auth failure or the pool-lock guard's bare
-            # ``Exception`` is not a connection error; type cannot decide this.
             acquiring = True
             try:
                 # Use per-client WebSocket keyed to this client's credentials
@@ -1996,34 +1979,33 @@ class HomeAssistantClient:
                         f"retrying after {retry_delay}s: {error_str}"
                     )
                     await asyncio.sleep(retry_delay)
+                    sent_before = sent_before or not acquiring
                     continue
 
                 # Phase first, type second. Failing before a client exists is
-                # evidence about the transport whatever class was raised; an
-                # auth failure or the pool-lock guard's bare ``Exception`` is not
-                # a no-answer class, so that case cannot be decided by type.
-                # Past acquisition only the no-answer classes count:
-                # ``send_command`` deliberately re-raises the original
-                # ``ConnectionClosed`` / ``ConnectionResetError`` from the send
-                # rather than wrapping it, to keep at-most-once semantics for
-                # write callers, so those arrive here untranslated. Anything
-                # else (a ``ValueError`` from building the message, say) is a
-                # bug rather than evidence about the connection.
+                # transport evidence whatever was raised: an auth failure or the
+                # pool-lock guard's bare ``Exception`` is no no-answer class.
+                # Past acquisition only those classes count (``send_command``
+                # re-raises the original ``ConnectionClosed`` /
+                # ``ConnectionResetError`` to keep writes at-most-once); anything
+                # else is Home Assistant's own answer or a local bug.
                 if acquiring or isinstance(e, _NO_ANSWER_ERRORS):
                     # One error channel for "no answer came back" (#1947): the
-                    # caller decides the policy, rather than every consumer
-                    # having to notice a marker on an otherwise ordinary
-                    # failure envelope. Callers that legitimately continue on a
-                    # missing answer catch this and say in ``warnings`` what
-                    # they skipped; callers whose output would read as a
-                    # negative finding let it propagate.
+                    # caller decides the policy. Callers that legitimately continue
+                    # on a missing answer catch this and say in ``warnings`` what
+                    # they skipped; callers whose output would read as a negative
+                    # finding let it propagate.
                     logger.error(
                         f"WebSocket transport failed ({message.get('type')}): {e}"
                     )
-                    if isinstance(e, HomeAssistantConnectionError):
-                        # Already the right class — re-raise unchanged so
-                        # subtypes (``HomeAssistantCommandNotSent``) and the
-                        # original traceback survive.
+                    if acquiring and not sent_before:
+                        # No attempt obtained a client, so nothing was sent.
+                        raise HomeAssistantCommandNotSent(error_str) from e
+                    if isinstance(e, HomeAssistantConnectionError) and not (
+                        sent_before and isinstance(e, HomeAssistantCommandNotSent)
+                    ):
+                        # Re-raised unchanged so subtypes and the traceback
+                        # survive; not "never sent" once an attempt may have sent.
                         raise
                     raise HomeAssistantConnectionError(error_str) from e
 

{ha_mcp_dev-9.1.0.dev3282 → ha_mcp_dev-9.1.0.dev3289}/src/ha_mcp/client/websocket_client.py

@@ -764,8 +764,8 @@ class HomeAssistantWebSocketClient:
             Response from Home Assistant
         """
         if not self._state.is_ready:
-            # PRE-SEND and the ONLY provably-never-sent site: nothing is transmitted at
-            # this entry guard. Raise the never-sent subtype so an at-most-once write
+            # PRE-SEND and send_command's only provably-never-sent site: nothing is
+            # transmitted here. Raise the never-sent subtype so an at-most-once write
             # consumer can fall back to legacy safely (a subclass of
             # HomeAssistantConnectionError, so every existing broad handler is
             # unaffected). A later send() failure is NOT never-sent (see below).

{ha_mcp_dev-9.1.0.dev3282 → ha_mcp_dev-9.1.0.dev3289}/src/ha_mcp/server_tool_text.py

@@ -213,10 +213,10 @@ SEARCH_KEYWORDS: dict[str, str] = {
 LITE_DOCSTRINGS: dict[str, str] = {
     "ha_config_get_automation": (
         "Get a Home Assistant automation configuration by "
-        "entity_id or unique_id. Returns the full config "
-        "(trigger, condition, action, mode) plus a stable "
-        "config_hash for use with python_transform on "
-        "ha_config_set_automation.\n\n"
+        "entity_id or config id. Returns the stored config "
+        "plus a stable config_hash for use with python_transform on "
+        "ha_config_set_automation, the registry entry, and Home "
+        "Assistant's validation status.\n\n"
         "For schema and field-level details, see "
         "ha_get_skill_guide."
     ),
@@ -224,14 +224,14 @@ LITE_DOCSTRINGS: dict[str, str] = {
         "Create or update a Home Assistant automation.\n\n"
         "Supports three modes: full `config` replacement, surgical "
         "`python_transform` on an existing automation (requires "
-        "`identifier` and `config_hash` from "
+        "`entity_id` and `config_hash` from "
         "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. Reusing an identifier targets "
+        "`entity_id` to create a new automation. Reusing an entity_id targets "
         "the same automation; changing its alias requires config_hash from a prior read. "
         "`enabled` turns it on or off and `run_actions` runs it now, with a "
-        "write or alone with `identifier`.\n\n"
+        "write or alone with `entity_id`.\n\n"
         "For schema details, examples, and native-vs-template "
         "guidance, see ha_get_skill_guide or your locally "
         "installed skills."

{ha_mcp_dev-9.1.0.dev3282 → ha_mcp_dev-9.1.0.dev3289}/src/ha_mcp/tools/addon_connection_hints.py

@@ -1,7 +1,29 @@
-"""Connection-failure guidance shared by app HTTP and WebSocket proxies."""
+"""Failure guidance for Supervisor calls and the app HTTP and WebSocket proxies."""
+
+from typing import Any
 
 from .._version import is_running_in_addon
 from ..client.rest_client import HomeAssistantClient
+from ..errors import ErrorCode
+
+_SUPERVISOR_AVAILABILITY_SUGGESTION = (
+    "Check Home Assistant connection and Supervisor availability"
+)
+_APP_SUPPORT_SUGGESTION = "Check that this installation supports apps (add-ons)."
+
+
+def add_supervisor_error_suggestions(error_details: dict[str, Any]) -> None:
+    """Add Supervisor guidance to a failed call's error; a refused token says
+    nothing about app support, so it gets none."""
+    code = str(error_details.get("code", ""))
+    if code == ErrorCode.RESOURCE_NOT_FOUND.value:
+        error_details["suggestion"] = _SUPERVISOR_AVAILABILITY_SUGGESTION
+        error_details["suggestions"] = [_SUPERVISOR_AVAILABILITY_SUGGESTION]
+    if not code.startswith("AUTH_"):
+        error_details["suggestions"] = [
+            *error_details.get("suggestions", []),
+            _APP_SUPPORT_SUGGESTION,
+        ]
 
 
 def addon_connection_failure_suggestions(

{ha_mcp_dev-9.1.0.dev3282 → ha_mcp_dev-9.1.0.dev3289}/src/ha_mcp/tools/auto_backup.py

@@ -108,13 +108,13 @@ def automation_backup_target(kw: dict[str, Any]) -> str:
     """Resolve the actual storage target for an automation write.
 
     HA's automation storage uses the body's ``id`` field as the primary
-    key (#1404). When the caller passes both ``identifier`` and a
+    key (#1404). When the caller passes both ``entity_id`` and a
     ``config.id`` that differ, HA writes to ``config.id`` — the
     snapshot must capture *that* entity, not the user-provided
-    ``identifier`` whose target is left untouched.
+    ``entity_id`` whose target is left untouched.
 
     Returns ``str(config["id"])`` when present, else
-    ``str(identifier or "")``. Empty string skips capture (matches the
+    ``str(entity_id or "")``. Empty string skips capture (matches the
     create path where there's nothing to back up yet).
 
     ``config`` accepts dict or JSON-string per the tool signature; both
@@ -130,7 +130,7 @@ def automation_backup_target(kw: dict[str, Any]) -> str:
         config_id = config.get("id")
         if config_id:
             return str(config_id)
-    # Return the identifier UNCHANGED — do NOT strip the ``automation.``
+    # Return the entity_id UNCHANGED — do NOT strip the ``automation.``
     # prefix. Capture and restore resolve the target through
     # ``client.get_automation_config`` -> ``_resolve_automation_id``, which
     # converts an entity_id ("automation.<slug>") to the real numeric
@@ -142,8 +142,8 @@ def automation_backup_target(kw: dict[str, Any]) -> str:
     # would POST to the wrong key and create a stray automation). The
     # doubled domain segment in the snapshot filename
     # ("automation.automation.<slug>.<ts>.yaml") is purely cosmetic and is
-    # exactly what the remove path (id_param="identifier") already produces.
-    return _resolve_str(kw.get("identifier"))
+    # exactly what the remove path (id_param="entity_id") already produces.
+    return _resolve_str(kw.get("entity_id"))
 
 
 def with_auto_backup(