ha-mcp-dev 9.1.0.dev3255__tar.gz → 9.1.0.dev3258__tar.gz

{ha_mcp_dev-9.1.0.dev3255 → ha_mcp_dev-9.1.0.dev3258}/PKG-INFO

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

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "9.1.0.dev3255"
+version = "9.1.0.dev3258"
 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.dev3255 → ha_mcp_dev-9.1.0.dev3258}/pyproject.toml.orig

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

@@ -18,6 +18,7 @@ from typing import Any, NoReturn
 from ._vendor.fastmcp.exceptions import ToolError
 from .backup_entities import current_entity_id
 from .backup_entity_ids import _manager
+from .backup_todo import safety_target as todo_safety_target
 
 
 async def _stored_items(client: Any, helper_type: str) -> list[Any]:
@@ -83,8 +84,11 @@ async def safety_target(
     another item. For a storage item the registry entry whose unique_id is the
     stored id follows it. An item can outlive its registry entry, so only its
     absence from the stored items means it is gone: the restore recreates it or
-    fails, and overwrites nothing that needs a backup.
+    fails, and overwrites nothing that needs a backup. A todo item is followed
+    by its uid (``backup_todo.safety_target``).
     """
+    if domain == "todo_item":
+        return await todo_safety_target(client, entity_id, config)
     bm = _manager()
     if domain == "entity":
         return await current_entity_id(client, entity_id, config)
@@ -172,8 +176,9 @@ def note_no_safety_backup(
 ) -> None:
     """Say why a restore goes ahead without a safety backup."""
     if target is None:  # safety_target: the stored item no longer exists
-        # An entity snapshot's "id" is its registry entry id, not a name to show.
-        key = "entity_id" if domain == "entity" else "id"
+        # An entity snapshot's "id" is its registry entry id, not a name to show;
+        # a todo snapshot has none.
+        key = {"entity": "entity_id", "todo_item": "summary"}.get(domain, "id")
         stored = config.get(key) if isinstance(config, dict) else None
         outcome["warnings"] = [
             f"No safety backup was taken: {domain.removeprefix('helper_')} "

{ha_mcp_dev-9.1.0.dev3255 → ha_mcp_dev-9.1.0.dev3258}/src/ha_mcp/backup_manager.py

@@ -103,12 +103,16 @@ from .backup_helper_target import require_holds as _require_holds
 from .backup_helper_target import safety_target as _safety_target
 from .backup_integrations import fetch_integration, restore_integration
 from .backup_tags import restore_tag, tag_snapshot
+from .backup_todo import current_key as todo_current_key
+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 (
     HomeAssistantCommandError,
     HomeAssistantConnectionError,
     HomeAssistantError,
 )
+from .errors import ErrorCode
 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
@@ -197,6 +201,19 @@ class BackupRestoreError(HomeAssistantError):
         }
 
 
+def restore_error_code(err: BackupRestoreError) -> ErrorCode:
+    """The error code a refused or failed restore is reported with."""
+    return {
+        "snapshot_not_found": ErrorCode.RESOURCE_NOT_FOUND,
+        "invalid_snapshot": ErrorCode.VALIDATION_INVALID_PARAMETER,
+        "unsupported_domain": ErrorCode.VALIDATION_INVALID_PARAMETER,
+        "backup_capture_failed": ErrorCode.BACKUP_CAPTURE_FAILED,
+        "entry_deleted": ErrorCode.RESOURCE_NOT_FOUND,
+        "entity_unavailable": ErrorCode.ENTITY_UNAVAILABLE,
+        "entity_not_found": ErrorCode.ENTITY_NOT_FOUND,
+    }.get(err.outcome.get("reason") or "", ErrorCode.SERVICE_CALL_FAILED)
+
+
 class InvalidBackupSnapshotError(ValueError):
     """Persisted snapshot data is invalid, independently of live HA access."""
 
@@ -1659,6 +1676,15 @@ class BackupManager:
 
     # ----- diff ----------------------------------------------------------
 
+    async def _comparison_target(self, domain: str, data: dict[str, Any]) -> str | None:
+        """The id the item a snapshot holds has now."""
+        target: str = data["entity_id"]
+        if domain == "entity":
+            return await current_entity_id(self._client, target, data["config"])
+        if domain == "todo_item":
+            return todo_current_key(target, data["config"])
+        return target
+
     async def snapshot_comparison(self, name: str) -> tuple[dict[str, Any], Any]:
         """Read a snapshot and the live config for its stable target identity."""
         data = await asyncio.to_thread(self.read_snapshot, name)
@@ -1672,9 +1698,7 @@ class BackupManager:
         handler = self.handler_for(domain)
         if handler is None:
             raise LookupError(f"No diff handler registered for domain {domain!r}")
-        target = data["entity_id"]
-        if domain == "entity":
-            target = await current_entity_id(self._client, target, data["config"])
+        target = await self._comparison_target(domain, data)
         current = await handler.fetch(self._client, target) if target else None
         if domain == "dashboard":
             _stored, legacy = dashboard_snapshot(data)
@@ -1693,6 +1717,11 @@ class BackupManager:
             # A snapshot from before registry icons were recorded: its restore
             # leaves the registry alone, so the icon is no difference.
             current.pop("registry_icon", None)
+        if domain == "todo_item" and isinstance(data["config"], dict):
+            current = todo_snapshot_item(data["config"], current)
+            # Older snapshots carry the list's completion time, which the
+            # fetch now leaves out.
+            data["config"].pop("completed", None)
         if _is_flow_helper_domain(domain) and current is not None:
             # Both MCP and Settings preview this comparison. Registry metadata
             # is recreation-only; an existing-entry restore applies options.
@@ -2024,8 +2053,8 @@ async def _ws_send(client: Any, message: dict[str, Any]) -> Any:
             )
     # ``send_command`` returns ``{"success": True, "result": <inner>}``
     # — unwrap so fetch / restore handlers downstream see the inner
-    # shape directly (list for ``<type>/list`` calls, dict for
-    # ``execute_script`` calls, etc.). Without the unwrap the
+    # shape directly (a list for the registry ``<type>/list`` calls, a dict
+    # for others such as ``todo/item/list``). Without the unwrap the
     # ``_require_list`` checks in every fetch handler would see the
     # envelope as a non-list and raise a spurious degraded-fetch error.
     if isinstance(envelope, dict) and "result" in envelope:
@@ -2119,15 +2148,12 @@ def _require_list(value: Any, endpoint: str) -> list[Any]:
 def _require_dict(value: Any, endpoint: str) -> dict[str, Any]:
     """Return ``value`` if it's a dict, else raise.
 
-    Dict-shaped counterpart to :func:`_require_list` for the
-    ``execute_script``-backed fetchers (calendar / todo). Their service
-    response is a dict envelope; a non-dict body is a degraded/malformed
-    200 (auth-scope change, API drift), not a genuine miss. Raising
-    funnels it through the diff tool's ``exception_to_structured_error``
-    and the capture pipeline's ``_CAPTURE_TRANSIENT_ERRORS`` warning,
-    instead of collapsing to ``None`` — which callers read as
-    ``entity_missing``. The genuine-miss signal stays the nested ``uid``
-    lookup returning ``None``.
+    Dict-shaped counterpart to :func:`_require_list` for replies and rows
+    that are dicts. A non-dict body is a degraded/malformed reply
+    (auth-scope change, API drift), not a genuine miss. Raising funnels it
+    through the diff tool's ``exception_to_structured_error`` and the
+    capture pipeline's ``_CAPTURE_TRANSIENT_ERRORS`` warning, instead of
+    collapsing to ``None`` — which callers read as ``entity_missing``.
     """
     if not isinstance(value, dict):
         raise HomeAssistantError(
@@ -2623,59 +2649,6 @@ async def _restore_area_or_floor(client: Any, entity_id: str, config: Any) -> An
         return await _ws_send(client, payload)
 
 
-# Todo items — entity_id is "<todo.entity>::<item_uid>"
-
-
-async def _fetch_todo_item(client: Any, entity_id: str) -> Any:
-    # The second segment is whatever the tool's ``item`` param carried.
-    # ha_set_todo_item / ha_remove_todo_item accept EITHER the item uid OR
-    # its exact summary/name, so this can be either form.
-    cal, _, item_ref = entity_id.partition("::")
-    if not cal or not item_ref:
-        return None
-    payload = {
-        "type": "execute_script",
-        "sequence": [
-            {
-                "service": "todo.get_items",
-                "target": {"entity_id": cal},
-                "response_variable": "items",
-            },
-            {"stop": "", "response_variable": "items"},
-        ],
-    }
-    try:
-        result = await _ws_send(client, payload)
-    except HomeAssistantError as err:
-        # Same narrow-to-404 rule as the calendar fetcher: only treat
-        # "todo entity not present" as a clean skip; let auth/transport
-        # errors propagate to the WARNING log via the manager's outer
-        # _CAPTURE_TRANSIENT_ERRORS catch.
-        if getattr(err, "status_code", None) == 404:
-            return None
-        raise
-    result = _require_dict(result, "execute_script")
-    items = result.get("response", {}).get("items", {}).get(cal, {}).get("items", [])
-    for item in items:
-        # Match either form. Matching only on uid silently skipped the
-        # snapshot whenever the caller passed the human-readable summary
-        # (the documented/common case, e.g. ha_remove_todo_item(list, "Buy
-        # milk")) — uid != summary, so the loop found nothing -> None.
-        if item.get("uid") == item_ref or item.get("summary") == item_ref:
-            return {"todo_entity_id": cal, **item}
-    return None
-
-
-async def _restore_todo_item(client: Any, entity_id: str, config: Any) -> Any:
-    cal = config.get("todo_entity_id") or entity_id.split("::", 1)[0]
-    data = {k: v for k, v in config.items() if k != "todo_entity_id"}
-    return await _rest_post(
-        client,
-        "services/todo/add_item",
-        {"entity_id": cal, **data},
-    )
-
-
 # Devices — config/device_registry/{list,update}. ``ha_set_device`` mutates
 # the user-editable registry fields (name_by_user / area_id / disabled_by /
 # labels); restore re-applies exactly those. A device deleted by
@@ -3907,7 +3880,7 @@ def register_default_handlers(mgr: BackupManager, _client: Any) -> None:
     mgr.register(
         DomainHandler("area_or_floor", _fetch_area_or_floor, _restore_area_or_floor)
     )
-    mgr.register(DomainHandler("todo_item", _fetch_todo_item, _restore_todo_item))
+    mgr.register(DomainHandler("todo_item", fetch_todo_item, restore_todo_item))
     mgr.register(DomainHandler("entity", fetch_entity, restore_entity))
     mgr.register(DomainHandler("device", _fetch_device, _restore_device))
     mgr.register(DomainHandler("integration", fetch_integration, restore_integration))

ha_mcp_dev-9.1.0.dev3258/src/ha_mcp/backup_todo.py

@@ -0,0 +1,379 @@
+"""Todo item backups: an item as Core's ``todo/item/list`` reports it.
+
+The backup key is ``<todo entity>::<item>``, where ``item`` is the item's
+uid (its summary when it has none); a backup from an earlier ha-mcp version
+keys it by what the tool was given, which may be its summary. A key finds the
+item with that uid, else the one Core's todo services act on for that value.
+The snapshot is Core's item row (uid, summary, status, and description and due
+where set) plus ``todo_entity_id``; it leaves out ``completed``, the time the
+list sets when an item is completed, which follows the restored status. A
+restore's safety backup and the diff follow the item by the snapshot's uid, so
+a rename since the backup does not lose it.
+
+An item still on the list under its uid gets its summary, status,
+description and due back through ``todo.update_item``; a description or due
+date the snapshot has none of is cleared. A removed item is added again with
+``todo.add_item`` and then given its status. When the component serves
+``todo_item``, both go through its bridge, which updates by uid and picks the
+due field with Core's own date validator. A restore to a list Home Assistant
+has not loaded, or to an unavailable one, is refused before anything is
+written. The snapshot holds no position and Core's services cannot set a uid,
+so a re-added item gets a new uid and goes where the list adds new items.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from .backup_entities import fetch_entity
+from .backup_entity_ids import _manager
+from .client.rest_client import HomeAssistantCommandError, HomeAssistantError
+from .config import get_global_settings
+from .tools.component_todo import todo_item
+
+_LIST = "todo/item/list"
+
+logger = logging.getLogger(__name__)
+
+
+class TodoListNotLoaded(HomeAssistantError):
+    """Home Assistant holds no loaded todo list under the entity id, so
+    whether the item is on it is unknown."""
+
+    def __init__(self, todo_entity: str) -> None:
+        super().__init__(f"Home Assistant has not loaded the todo list {todo_entity}")
+
+
+def find_item(items: list[dict[str, Any]], ref: str) -> dict[str, Any] | None:
+    """The first item whose uid or summary is ``ref``, the one Core's todo
+    services act on for the same value."""
+    return next((i for i in items if ref in (i.get("uid"), i.get("summary"))), None)
+
+
+async def list_items(client: Any, todo_entity: str) -> list[dict[str, Any]] | None:
+    """The list's items, or None when Core holds no such todo list."""
+    bm = _manager()
+    try:
+        result = await bm._ws_send(client, {"type": _LIST, "entity_id": todo_entity})
+    except HomeAssistantCommandError as err:
+        if err.code == "not_found":
+            return None
+        raise
+    items: list[dict[str, Any]] = bm._require_list(
+        bm._require_dict(result, _LIST).get("items"), _LIST
+    )
+    return items
+
+
+async def _find(
+    client: Any, todo_entity: str, items: list[dict[str, Any]], ref: str
+) -> dict[str, Any] | None:
+    """The item with uid ``ref``, else the one Core resolves ``ref`` to."""
+    exact = next((i for i in items if i.get("uid") == ref), None)
+    if exact is not None:
+        return exact
+    reply = await todo_item(client, todo_entity, "resolve", refs=[ref])
+    if reply is None:
+        return find_item(items, ref)
+    if not reply.get("success"):
+        raise TodoListNotLoaded(todo_entity)
+    found: dict[str, Any] | None = reply["items"][0]
+    return found
+
+
+async def fetch_todo_item(client: Any, entity_id: str) -> dict[str, Any] | None:
+    todo_entity, _, ref = entity_id.partition("::")
+    if not todo_entity or not ref:
+        return None
+    items = await list_items(client, todo_entity)
+    if items is None:
+        if await _list_gone(client, todo_entity):
+            return None
+        raise TodoListNotLoaded(todo_entity)
+    item = await _find(client, todo_entity, items, ref)
+    if not item:
+        return None
+    return {"todo_entity_id": todo_entity} | {
+        k: v for k, v in item.items() if k != "completed"
+    }
+
+
+async def back_up_items(
+    client: Any, todo_entity: str, items: list[dict[str, Any] | None], tool_name: str
+) -> list[str]:
+    """Back up the given items, each under its uid (its summary when it has
+    none); returns why a backup that was due was not taken."""
+    settings = get_global_settings()
+    if not getattr(settings, "enable_auto_backup", False):
+        return []
+    refs = dict.fromkeys(
+        ref
+        for item in items
+        if item and (ref := item.get("uid") or item.get("summary"))
+    )
+    skipped: list[str] = []
+    bm = _manager()
+    try:
+        mgr = bm.get_backup_manager(client, settings)
+        for ref in refs:
+            await mgr.maybe_snapshot(
+                "todo_item",
+                f"{todo_entity}::{ref}",
+                tool_name=tool_name,
+                skip_reasons=skipped,
+            )
+    except bm._CAPTURE_TRANSIENT_ERRORS as err:
+        logger.warning("Todo item backup failed: %s", err)
+        skipped.append(f"No pre-write backup was taken: {type(err).__name__}")
+    return skipped
+
+
+def unbacked_removals(
+    before: list[dict[str, Any]], after: list[dict[str, Any]] | None
+) -> list[str]:
+    """Why an item gone after ``remove_completed_items`` has no backup: Core
+    picks the completed items when it runs the service, so one completed
+    after the list was read and backed up is removed without a backup. An
+    item another client deleted meanwhile is named the same way."""
+    settings = get_global_settings()
+    if after is None or not getattr(settings, "enable_auto_backup", False):
+        return []
+    kept = {i.get("uid") for i in after}
+    return [
+        f"'{i.get('summary')}' is gone from the list, but it was not completed "
+        "when the list was read, so no backup of it was taken"
+        for i in before
+        if i.get("status") != "completed" and i.get("uid") not in kept
+    ]
+
+
+def current_key(entity_id: str, config: Any) -> str:
+    """The key that finds the snapshot's item now: its uid where it has one."""
+    uid = config.get("uid") if isinstance(config, dict) else None
+    return f"{entity_id.partition('::')[0]}::{uid}" if uid else entity_id
+
+
+async def safety_target(client: Any, entity_id: str, config: Any) -> str | None:
+    """The key a restore's safety backup is taken under; None when the item
+    is gone, since the restore then adds it again and overwrites nothing."""
+    key = current_key(entity_id, config)
+    bm = _manager()
+    try:
+        item = await fetch_todo_item(client, key)
+    except TodoListNotLoaded as err:
+        raise _unavailable(f"{err}; nothing was restored") from err
+    except bm._CAPTURE_TRANSIENT_ERRORS as err:
+        raise bm.MandatoryBackupError(
+            f"the todo list could not be read: {type(err).__name__}",
+            safe_detail="the todo list could not be read",
+        ) from err
+    return key if snapshot_item(config, item) else None
+
+
+def snapshot_item(config: Any, item: dict[str, Any] | None) -> dict[str, Any] | None:
+    """``item`` when it is the snapshot's item: once the item with the
+    snapshot's uid is gone, a row named after that uid is another item."""
+    uid = config.get("uid") if isinstance(config, dict) else None
+    if item is None or (uid and item.get("uid") != uid):
+        return None
+    return item
+
+
+def _due_field(due: str) -> str:
+    # Core lists a due datetime as an ISO datetime with a 'T', a due date
+    # without one.
+    return "due_datetime" if "T" in due else "due_date"
+
+
+def _description(snapshot: dict[str, Any], current: dict[str, Any]) -> dict[str, Any]:
+    """The description as the snapshot had it. One only the current item has
+    is sent as None, which Core takes as a clear; one neither has is left
+    out, since Core refuses a field the list does not support."""
+    if snapshot.get("description") is not None:
+        return {"description": snapshot["description"]}
+    if current.get("description") is not None:
+        return {"description": None}
+    return {}
+
+
+def _field_values(snapshot: dict[str, Any], current: dict[str, Any]) -> dict[str, Any]:
+    """Description and due as the snapshot had them, for Core's services."""
+    fields = _description(snapshot, current)
+    if (due := snapshot.get("due")) is not None:
+        fields[_due_field(due)] = due
+    elif (current_due := current.get("due")) is not None:
+        fields[_due_field(current_due)] = None
+    return fields
+
+
+def service_message(
+    service: str, todo_entity: str, data: dict[str, Any]
+) -> dict[str, Any]:
+    """A WebSocket ``call_service`` of todo.<service> on one list."""
+    return {
+        "type": "call_service",
+        "domain": "todo",
+        "service": service,
+        "target": {"entity_id": todo_entity},
+        "service_data": data,
+    }
+
+
+async def _call(
+    client: Any, todo_entity: str, service: str, data: dict[str, Any]
+) -> Any:
+    return await _manager()._ws_send(
+        client, service_message(service, todo_entity, data)
+    )
+
+
+def _not_applied(message: str, **outcome: Any) -> HomeAssistantError:
+    error: HomeAssistantError = _manager().BackupRestoreError(
+        message, apply_status="not_applied", **outcome
+    )
+    return error
+
+
+def _unavailable(message: str) -> HomeAssistantError:
+    return _not_applied(message, reason="entity_unavailable")
+
+
+async def _list_gone(client: Any, todo_entity: str) -> bool:
+    """Whether Home Assistant no longer has the list. Core answers a deleted
+    list as one it has not loaded. A deleted list has neither a state nor a
+    registry entry; a disabled one keeps its entry. So does a list without a
+    unique id that Home Assistant has not loaded, which is taken as deleted."""
+    state = await _manager()._rest_get_or_none(client, f"states/{todo_entity}")
+    return state is None and await fetch_entity(client, todo_entity) is None
+
+
+async def _require_available(client: Any, todo_entity: str) -> None:
+    # Core skips an unavailable list: a write changes nothing and succeeds.
+    state = await _manager()._rest_get_or_none(client, f"states/{todo_entity}")
+    if state is None and await fetch_entity(client, todo_entity) is None:
+        raise _not_applied(
+            f"Todo list {todo_entity} no longer exists", reason="entity_not_found"
+        )
+    if state is not None and state.get("state") == "unavailable":
+        raise _unavailable(
+            f"Todo list {todo_entity} is unavailable, so nothing would be restored"
+        )
+
+
+async def _completed_again(todo_entity: str, summary: Any, mark: Any) -> Any:
+    """Mark a re-added item completed. The add is applied by then, so any
+    failure says so, since restoring again would add the item twice."""
+    try:
+        return await mark()
+    except Exception as err:
+        raise HomeAssistantError(
+            f"Re-added {summary!r} to {todo_entity}, but marking it completed "
+            f"failed or got no answer ({err}); check its status before restoring "
+            "again, which would add it a second time"
+        ) from err
+
+
+async def _restore_by_bridge(
+    client: Any, todo_entity: str, config: Any, current: dict[str, Any] | None
+) -> Any:
+    """The restore through the component, an update going by uid; None when
+    the component does not serve it."""
+    summary = config.get("summary")
+    status = config.get("status")
+    if current is not None:
+        action = "update"
+        data = {"rename": summary, "status": status} | _description(config, current)
+        fields = {"uid": current["uid"], "data": data}
+    else:
+        action = "add"
+        fields = {"data": {"item": summary} | _description(config, {})}
+    reply = await todo_item(
+        client, todo_entity, action, due=config.get("due"), **fields
+    )
+    if reply is None:
+        return None
+    if not reply.get("success"):
+        message = (reply.get("error") or {}).get("message", "Unknown error")
+        raise _not_applied(f"{message}; nothing was restored")
+    if current is not None or status != "completed":
+        return reply
+
+    async def mark() -> Any:
+        if reply["item"] is None:
+            raise HomeAssistantError("the re-added item could not be told apart")
+        marked = await todo_item(
+            client,
+            todo_entity,
+            "update",
+            uid=reply["item"]["uid"],
+            data={"status": status},
+        )
+        if not marked or not marked.get("success"):
+            error = (marked or {}).get("error") or {}
+            raise HomeAssistantError(
+                error.get("message", "the component did not run it")
+            )
+        return marked
+
+    return await _completed_again(todo_entity, summary, mark)
+
+
+async def restore_todo_item(client: Any, entity_id: str, config: Any) -> Any:
+    # The list comes from the backup key, which the safety backup also uses.
+    todo_entity = entity_id.partition("::")[0]
+    uid = config.get("uid")
+    summary = config.get("summary")
+    status = config.get("status")
+    await _require_available(client, todo_entity)
+    items = await list_items(client, todo_entity)
+    if items is None:
+        raise _unavailable(f"{TodoListNotLoaded(todo_entity)}; nothing was restored")
+    current = (
+        next((i for i in items if i.get("uid") == uid), None)
+        if uid
+        else find_item(items, summary)
+    )
+    if current is None or current.get("uid"):
+        result = await _restore_by_bridge(client, todo_entity, config, current)
+        if result is not None:
+            return result
+    if current is not None:
+        if uid and find_item(items, uid) is not current:
+            raise _not_applied(
+                f"Another item on {todo_entity} is named {uid!r}, so Home "
+                "Assistant would update that one; nothing was restored"
+            )
+        return await _call(
+            client,
+            todo_entity,
+            "update_item",
+            {"item": uid or summary, "rename": summary, "status": status}
+            | _field_values(config, current),
+        )
+
+    result = await _call(
+        client, todo_entity, "add_item", {"item": summary} | _field_values(config, {})
+    )
+    if status != "completed":
+        return result
+    known = {i.get("uid") for i in items}
+
+    async def mark() -> Any:
+        after = await list_items(client, todo_entity) or []
+        added = [i for i in after if i.get("uid") not in known]
+        if (
+            len(added) != 1
+            or not added[0].get("uid")
+            or added[0].get("summary") != summary
+            or find_item(after, added[0]["uid"]) is not added[0]
+        ):
+            raise HomeAssistantError("the re-added item could not be told apart")
+        return await _call(
+            client,
+            todo_entity,
+            "update_item",
+            {"item": added[0]["uid"], "status": status},
+        )
+
+    return await _completed_again(todo_entity, summary, mark)

{ha_mcp_dev-9.1.0.dev3255 → ha_mcp_dev-9.1.0.dev3258}/src/ha_mcp/settings_ui/_handlers_backups.py

@@ -33,7 +33,9 @@ from ..backup_manager import (
     _FlowHelperReadError,
     _snapshot_validation_message,
     get_backup_manager,
+    restore_error_code,
 )
+from ..backup_todo import TodoListNotLoaded
 from ..config import (
     BACKUP_OVERRIDE_FIELDS,
     _reset_global_settings,
@@ -142,6 +144,8 @@ async def _diff_backup(
         return _bad_request(_snapshot_validation_message(err))
     except LookupError as err:
         return _bad_request(str(err), code=ErrorCode.RESOURCE_NOT_FOUND, status=404)
+    except TodoListNotLoaded as err:
+        return _bad_request(str(err), code=ErrorCode.ENTITY_UNAVAILABLE, status=409)
     except _FlowHelperReadError as err:
         return JSONResponse(
             create_error_response(
@@ -204,13 +208,7 @@ async def _restore_backup(
     except (ValueError, LookupError) as err:
         return _bad_request(str(err))
     except BackupRestoreError as err:
-        code = {
-            "snapshot_not_found": ErrorCode.RESOURCE_NOT_FOUND,
-            "invalid_snapshot": ErrorCode.VALIDATION_INVALID_PARAMETER,
-            "unsupported_domain": ErrorCode.VALIDATION_INVALID_PARAMETER,
-            "backup_capture_failed": ErrorCode.BACKUP_CAPTURE_FAILED,
-            "entry_deleted": ErrorCode.RESOURCE_NOT_FOUND,
-        }.get(err.outcome.get("reason") or "", ErrorCode.SERVICE_CALL_FAILED)
+        code = restore_error_code(err)
         return JSONResponse(
             create_error_response(
                 code,
@@ -229,6 +227,7 @@ async def _restore_backup(
             ),
             status_code={
                 ErrorCode.RESOURCE_NOT_FOUND: 404,
+                ErrorCode.ENTITY_NOT_FOUND: 404,
                 ErrorCode.VALIDATION_INVALID_PARAMETER: 400,
             }.get(code, 409),
         )