ha-mcp-dev 7.8.0.dev701__tar.gz → 7.8.0.dev703__tar.gz

{ha_mcp_dev-7.8.0.dev701/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.8.0.dev703}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.8.0.dev701
+Version: 7.8.0.dev703
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT
@@ -275,8 +275,8 @@ Some tools require a companion custom component installed in Home Assistant. Sta
 | Tool | Description |
 |------|-------------|
 | `ha_config_set_yaml` *(beta)* | Safely add, replace, or remove top-level YAML keys in `configuration.yaml` and package files (automatic backup, validation, and config check) |
-| `ha_list_files` *(beta)* | List files in allowed directories (www/, themes/, custom_templates/) |
-| `ha_read_file` *(beta)* | Read files from allowed paths (config YAML, logs, www/, themes/, custom_templates/, custom_components/) |
+| `ha_list_files` *(beta)* | List files in allowed directories |
+| `ha_read_file` *(beta)* | Read files from allowed paths (config YAML, logs, and allowed directories) |
 | `ha_write_file` *(beta)* | Write files to allowed directories |
 | `ha_delete_file` *(beta)* | Delete files from allowed directories |
 

{ha_mcp_dev-7.8.0.dev701 → ha_mcp_dev-7.8.0.dev703}/README.md

@@ -245,8 +245,8 @@ Some tools require a companion custom component installed in Home Assistant. Sta
 | Tool | Description |
 |------|-------------|
 | `ha_config_set_yaml` *(beta)* | Safely add, replace, or remove top-level YAML keys in `configuration.yaml` and package files (automatic backup, validation, and config check) |
-| `ha_list_files` *(beta)* | List files in allowed directories (www/, themes/, custom_templates/) |
-| `ha_read_file` *(beta)* | Read files from allowed paths (config YAML, logs, www/, themes/, custom_templates/, custom_components/) |
+| `ha_list_files` *(beta)* | List files in allowed directories |
+| `ha_read_file` *(beta)* | Read files from allowed paths (config YAML, logs, and allowed directories) |
 | `ha_write_file` *(beta)* | Write files to allowed directories |
 | `ha_delete_file` *(beta)* | Delete files from allowed directories |
 

{ha_mcp_dev-7.8.0.dev701 → ha_mcp_dev-7.8.0.dev703}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.8.0.dev701"
+version = "7.8.0.dev703"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 requires-python = ">=3.13,<3.14"
@@ -85,6 +85,8 @@ ignore_missing_imports = true
 [[tool.mypy.overrides]]
 module = [
     "homeassistant.*",
+    "aiohasupervisor",
+    "aiohasupervisor.*",
     "aiohttp",
     "voluptuous",
     "jsonschema",

{ha_mcp_dev-7.8.0.dev701 → ha_mcp_dev-7.8.0.dev703}/src/ha_mcp/read_only.py

@@ -66,8 +66,12 @@ class ReadOnlyExemption(NamedTuple):
 def _backup_write(args: dict[str, Any]) -> str | None:
     scope = args.get("scope")
     action = args.get("action")
+    # Read-only-safe: per-edit backup listing/viewing, and snapshot listing
+    # (issue #1586 — pure ``backup/info`` read, no tarball mutation).
     if scope == "edits" and action in ("list", "view"):
         return None
+    if scope == "snapshot" and action == "list":
+        return None
     return f"scope={scope!r}, action={action!r}"
 
 
@@ -144,7 +148,8 @@ def _custom_tool_write(args: dict[str, Any]) -> str | None:
 READ_ONLY_EXEMPT_TOOLS: dict[str, ReadOnlyExemption] = {
     "ha_manage_backup": ReadOnlyExemption(
         _backup_write,
-        "listing and viewing per-edit backups (scope='edits', action='list' or 'view')",
+        "listing and viewing per-edit backups (scope='edits', action='list' or "
+        "'view') and listing snapshots (scope='snapshot', action='list')",
     ),
     "ha_manage_addon": ReadOnlyExemption(
         _addon_write,

{ha_mcp_dev-7.8.0.dev701 → ha_mcp_dev-7.8.0.dev703}/src/ha_mcp/settings.css

@@ -415,6 +415,13 @@
   fieldset.a11y-options { border: 0; padding: 0; margin: 0; min-inline-size: auto; }
   .visually-hidden { position: absolute; width: 1px; height: 1px; padding: 0;
     margin: -1px; overflow: hidden; clip-path: inset(50%); white-space: nowrap; border: 0; }
+  /* Skip-to-content link: visually hidden until focused, then pinned to the
+     top-left so keyboard users can bypass the header. */
+  .skip-link { position: absolute; left: 8px; top: -56px; z-index: 100;
+    padding: 8px 16px; border-radius: 8px; font-size: 0.875rem; font-weight: 600;
+    background: var(--surface); color: var(--text); border: 1px solid var(--border);
+    transition: top 0.15s ease; }
+  .skip-link:focus { top: 8px; outline: 2px solid var(--accent); outline-offset: 2px; }
   .a11y-option { display: inline-flex; align-items: center; gap: 6px; padding: 6px 12px;
     border: 1px solid var(--border); border-radius: 8px; cursor: pointer; font-size: 0.85rem;
     background: var(--bg); user-select: none; }

{ha_mcp_dev-7.8.0.dev701 → ha_mcp_dev-7.8.0.dev703}/src/ha_mcp/settings.js

@@ -9,11 +9,13 @@ window.addEventListener('error', (e) => {
   const el = document.getElementById('status');
   if (!el) return;
   const where = e.filename ? `${e.filename}:${e.lineno}:${e.colno}` : 'inline';
+  setStatusAlert(el, true);
   el.textContent = `JS error: ${e.message} @ ${where}`;
 });
 window.addEventListener('unhandledrejection', (e) => {
   const el = document.getElementById('status');
   if (!el) return;
+  setStatusAlert(el, true);
   el.textContent = `Async error: ${e.reason && e.reason.message ? e.reason.message : String(e.reason)}`;
 });
 
@@ -135,18 +137,18 @@ async function loadTools() {
   try {
     resp = await fetch('./api/settings/tools');
   } catch (e) {
-    updateStatus('Network error reaching /api/settings/tools: ' + e.message);
+    updateStatus('Network error reaching /api/settings/tools: ' + e.message, false, true);
     return;
   }
   if (!resp.ok) {
-    updateStatus(`/api/settings/tools returned HTTP ${resp.status} ${resp.statusText}`);
+    updateStatus(`/api/settings/tools returned HTTP ${resp.status} ${resp.statusText}`, false, true);
     return;
   }
   let data;
   try {
     data = await resp.json();
   } catch (e) {
-    updateStatus('Failed to parse /api/settings/tools response as JSON: ' + e.message);
+    updateStatus('Failed to parse /api/settings/tools response as JSON: ' + e.message, false, true);
     return;
   }
   toolData = data.tools || [];
@@ -169,14 +171,15 @@ async function loadTools() {
     // the user where to look instead of leaving them on "Loading".
     updateStatus(
       'No tools found. The sidecar reads ~/.ha-mcp/tool_metadata.json — ' +
-      'if missing/empty, restart your MCP client. See ~/.ha-mcp/sidecar.log for details.'
+      'if missing/empty, restart your MCP client. See ~/.ha-mcp/sidecar.log for details.',
+      false, true
     );
     return;
   }
   try {
     render();
   } catch (e) {
-    updateStatus('Render failed: ' + e.message + ' (open browser devtools for the stack)');
+    updateStatus('Render failed: ' + e.message + ' (open browser devtools for the stack)', false, true);
     throw e;
   }
   updateStatus('Loaded');
@@ -765,14 +768,24 @@ async function saveConfig() {
     // are on.
     if (restartChannel) restartChannel.postMessage({type: 'restart-required'});
   } else {
-    updateStatus('Save failed!');
+    updateStatus('Save failed!', false, true);
   }
 }
 
-function updateStatus(text, saved) {
+// Reflect success/error semantics on a status span for assistive tech:
+// failures switch to role=alert/assertive so screen readers interrupt; all
+// other updates stay role=status/polite (matching the static markup). (#1596)
+function setStatusAlert(el, isError) {
+  if (!el) return;
+  el.setAttribute('role', isError ? 'alert' : 'status');
+  el.setAttribute('aria-live', isError ? 'assertive' : 'polite');
+}
+
+function updateStatus(text, saved, isError) {
   const el = document.getElementById('status');
-  el.textContent = text;
+  setStatusAlert(el, isError);
   el.className = saved ? 'status saved' : 'status';
+  el.textContent = text;
 }
 
 function applyToolSearch() {
@@ -916,6 +929,7 @@ async function saveBackupConfig() {
     return;
   }
   btn.disabled = true;
+  setStatusAlert(statusEl, false);
   statusEl.textContent = 'Saving…';
   try {
     const resp = await fetch('./api/settings/backup-config', {
@@ -931,6 +945,7 @@ async function saveBackupConfig() {
         if (typeof data.error === 'string') msg = data.error;
         else if (data.error.message) msg = data.error.message;
       }
+      setStatusAlert(statusEl, true);
       statusEl.textContent = msg;
       return;
     }
@@ -958,6 +973,7 @@ async function saveBackupConfig() {
     }
   } catch (err) {
     btn.disabled = false;
+    setStatusAlert(statusEl, true);
     statusEl.textContent = 'Network error: ' + String(err);
   }
 }
@@ -1014,8 +1030,8 @@ function renderFsCustomPathsSubForm(parentEl, masterOn, fsOn) {
       : '.storage, secrets.yaml';
   info.innerHTML =
     `<div class="feature-name">Custom filesystem directories (advanced)</div>` +
-    `<div class="feature-help">Extra directories (one per line, relative to your config dir) that the file tools may READ and WRITE — e.g. <code>pyscript</code>, <code>python_scripts</code>. Each entry grants both read and write. Applies immediately; no restart needed.</div>` +
-    `<div class="feature-help">Always blocked (cannot be added): <code>${escapeHtml(denyList)}</code>, path traversal (<code>..</code>), and absolute paths.</div>`;
+    `<div class="feature-help">Extra directories (one per line) that the file tools may READ and WRITE — either relative to your config dir (e.g. <code>pyscript</code>, <code>python_scripts</code>) or an absolute HAOS sibling volume <code>/share</code>, <code>/media</code>, <code>/ssl</code>, <code>/backup</code> (or a subdirectory of one). Each entry grants both read and write. Applies immediately; no restart needed.</div>` +
+    `<div class="feature-help">Always blocked (cannot be added): <code>${escapeHtml(denyList)}</code>, path traversal (<code>..</code>), and any absolute path outside the HAOS sibling volumes.</div>`;
 
   const control = document.createElement('div');
   control.className = 'feature-control';
@@ -1050,6 +1066,8 @@ function renderFsCustomPathsSubForm(parentEl, masterOn, fsOn) {
     const status = document.createElement('div');
     status.id = 'fsCustomPathsStatus';
     status.className = 'feature-help';
+    status.setAttribute('role', 'status');
+    status.setAttribute('aria-live', 'polite');
     control.appendChild(ta);
     control.appendChild(btn);
     control.appendChild(status);
@@ -1070,6 +1088,7 @@ async function saveFsCustomPaths() {
     .map(s => s.trim())
     .filter(s => s.length);
   btn.disabled = true;
+  setStatusAlert(statusEl, false);
   statusEl.textContent = 'Saving…';
   try {
     const resp = await fetch('./api/settings/fs-custom-paths', {
@@ -1085,6 +1104,7 @@ async function saveFsCustomPaths() {
         if (typeof data.error === 'string') msg = data.error;
         else if (data.error.message) msg = data.error.message;
       }
+      setStatusAlert(statusEl, true);
       statusEl.textContent = msg;
       return;
     }
@@ -1101,6 +1121,7 @@ async function saveFsCustomPaths() {
       : 'Saved.';
   } catch (err) {
     btn.disabled = false;
+    setStatusAlert(statusEl, true);
     statusEl.textContent = 'Network error: ' + String(err);
   }
 }
@@ -2453,15 +2474,18 @@ async function removePolicyRule(toolName) {
 
 async function saveGlobalSettings() {
   const statusEl = document.getElementById('policy-global-save-status');
+  setStatusAlert(statusEl, false);
   statusEl.textContent = 'Saving...';
   let resp;
   try {
     resp = await fetch('./api/policy/config');
   } catch (e) {
+    setStatusAlert(statusEl, true);
     statusEl.textContent = 'Network error: ' + e.message;
     return;
   }
   if (!resp.ok) {
+    setStatusAlert(statusEl, true);
     statusEl.textContent = 'Load failed: ' + resp.status;
     return;
   }
@@ -2472,6 +2496,7 @@ async function saveGlobalSettings() {
     await policyPut(policy, 'Save global settings');
     statusEl.textContent = 'Saved.';
   } catch (e) {
+    setStatusAlert(statusEl, true);
     statusEl.textContent = e.message;
   }
 }
@@ -2629,10 +2654,18 @@ setInterval(() => {
 // Generic dispatcher — every .tab button names its target panel via
 // data-panel, every .panel has matching id="panel-<name>". Adding a
 // new tab is one button + one panel div; no JS change needed.
-function activateTab(target) {
-  document.querySelectorAll('.tab').forEach(t =>
-    t.classList.toggle('active', t.dataset.panel === target)
-  );
+function activateTab(target, opts) {
+  const focusTab = opts && opts.focusTab;
+  document.querySelectorAll('.tab').forEach(t => {
+    const selected = t.dataset.panel === target;
+    t.classList.toggle('active', selected);
+    // Expose tab state + roving tabindex to assistive tech (WAI-ARIA APG
+    // tabs pattern). Only the selected tab stays in the Tab sequence;
+    // arrow keys move between the rest. (#1596)
+    t.setAttribute('aria-selected', selected ? 'true' : 'false');
+    t.tabIndex = selected ? 0 : -1;
+    if (selected && focusTab) t.focus();
+  });
   document.querySelectorAll('.panel').forEach(p =>
     p.classList.toggle('active', p.id === 'panel-' + target)
   );
@@ -2649,6 +2682,27 @@ document.querySelectorAll('.tab').forEach(tab => {
   tab.addEventListener('click', () => activateTab(tab.dataset.panel));
 });
 
+// Keyboard navigation for the tablist (WAI-ARIA APG tabs pattern): Left/Right
+// move + activate the adjacent tab, Home/End jump to the ends. (#1596)
+{
+  const tablist = document.querySelector('.tabs[role="tablist"]');
+  if (tablist) {
+    tablist.addEventListener('keydown', (e) => {
+      const tabs = Array.from(tablist.querySelectorAll('.tab'));
+      const currentIndex = tabs.indexOf(document.activeElement);
+      if (currentIndex === -1) return;
+      let nextIndex = null;
+      if (e.key === 'ArrowRight') nextIndex = (currentIndex + 1) % tabs.length;
+      else if (e.key === 'ArrowLeft') nextIndex = (currentIndex - 1 + tabs.length) % tabs.length;
+      else if (e.key === 'Home') nextIndex = 0;
+      else if (e.key === 'End') nextIndex = tabs.length - 1;
+      if (nextIndex === null) return;
+      e.preventDefault();
+      activateTab(tabs[nextIndex].dataset.panel, { focusTab: true });
+    });
+  }
+}
+
 // Cross-tab links — any <a data-panel-link="<name>"> switches tabs
 // in-page rather than following the href (used by the "no gated
 // tools" empty state to point users at the Tools tab).
@@ -2858,8 +2912,8 @@ function _advSaveStatusEls() {
     document.getElementById('advSaveStatusTop'),
   ].filter(Boolean);
 }
-function _setAdvSaveStatus(text) {
-  _advSaveStatusEls().forEach(el => { el.textContent = text; });
+function _setAdvSaveStatus(text, isError) {
+  _advSaveStatusEls().forEach(el => { setStatusAlert(el, isError); el.textContent = text; });
 }
 function _setAdvSaveDisabled(disabled) {
   _advSaveBtns().forEach(b => { b.disabled = disabled; });
@@ -2934,7 +2988,7 @@ async function saveAdvancedSettings() {
           data = {restart_required: true};
         } else {
           _setAdvSaveDisabled(false);
-          _setAdvSaveStatus(`Save failed (HTTP ${resp.status}, non-JSON body)`);
+          _setAdvSaveStatus(`Save failed (HTTP ${resp.status}, non-JSON body)`, true);
           return;
         }
       }
@@ -2945,7 +2999,7 @@ async function saveAdvancedSettings() {
           if (typeof data.error === 'string') msg = data.error;
           else if (data.error.message) msg = data.error.message;
         }
-        _setAdvSaveStatus(msg);
+        _setAdvSaveStatus(msg, true);
         return;
       }
     }
@@ -2973,7 +3027,7 @@ async function saveAdvancedSettings() {
     }
   } catch (err) {
     _setAdvSaveDisabled(false);
-    _setAdvSaveStatus('Network error: ' + String(err));
+    _setAdvSaveStatus('Network error: ' + String(err), true);
   }
 }
 

{ha_mcp_dev-7.8.0.dev701 → ha_mcp_dev-7.8.0.dev703}/src/ha_mcp/settings_ui.py

@@ -787,6 +787,7 @@ _SETTINGS_HTML = (
     + """</style>
 </head>
 <body>
+<a href="#main-content" class="skip-link">Skip to content</a>
 <div class="header">
   <h1>HA-MCP Settings</h1>
   <div style="display:flex;align-items:center;gap:8px">
@@ -798,15 +799,16 @@ _SETTINGS_HTML = (
         <option value="dark">Dark</option>
       </select>
     </label>
-    <span id="status" class="status">Loading...</span>
+    <span id="status" class="status" role="status" aria-live="polite">Loading...</span>
   </div>
 </div>
-<div class="tabs">
-  <button class="tab active" data-panel="tools">Tools</button>
-  <button class="tab" data-panel="server">Server Settings</button>
-  <button class="tab" data-panel="backups">Backups</button>
-  <button class="tab" data-panel="tool-security-policies">Tool Security Policies</button>
-  <button class="tab" data-panel="accessibility">Accessibility</button>
+<main id="main-content" tabindex="-1" style="outline:none">
+<div class="tabs" role="tablist" aria-label="Settings sections">
+  <button class="tab active" data-panel="tools" role="tab" id="tab-tools" aria-controls="panel-tools" aria-selected="true">Tools</button>
+  <button class="tab" data-panel="server" role="tab" id="tab-server" aria-controls="panel-server" aria-selected="false" tabindex="-1">Server Settings</button>
+  <button class="tab" data-panel="backups" role="tab" id="tab-backups" aria-controls="panel-backups" aria-selected="false" tabindex="-1">Backups</button>
+  <button class="tab" data-panel="tool-security-policies" role="tab" id="tab-tool-security-policies" aria-controls="panel-tool-security-policies" aria-selected="false" tabindex="-1">Tool Security Policies</button>
+  <button class="tab" data-panel="accessibility" role="tab" id="tab-accessibility" aria-controls="panel-accessibility" aria-selected="false" tabindex="-1">Accessibility</button>
 </div>
 <div class="restart-notice" id="restartNotice">
   <span class="restart-notice-text" id="restartNoticeText">
@@ -819,7 +821,7 @@ _SETTINGS_HTML = (
   </span>
   <button class="restart-btn" id="restartBtn" style="display:none">Restart Add-on</button>
 </div>
-<div class="panel active" id="panel-tools">
+<div class="panel active" id="panel-tools" role="tabpanel" aria-labelledby="tab-tools" tabindex="0">
   <div class="readonly-notice">
     Server-wide features (Tool Search, YAML config editing, filesystem
     tools, etc.) appear in both the <strong>Server Settings</strong>
@@ -859,7 +861,7 @@ _SETTINGS_HTML = (
   <input type="text" class="search" id="search" placeholder="Search tools...">
   <div id="groups"></div>
 </div>
-<div class="panel" id="panel-server">
+<div class="panel" id="panel-server" role="tabpanel" aria-labelledby="tab-server" tabindex="0">
   <div class="features-sub">
     Tool Search, advanced settings. Changes take effect only after you
     restart the add-on (applies the change server-side) AND reconnect or
@@ -880,7 +882,7 @@ _SETTINGS_HTML = (
   </div>
   <div id="advSaveRowTop" class="adv-save-row" style="display:none;">
     <button id="advSaveBtnTop" class="adv-save-btn">💾 Save advanced settings</button>
-    <span id="advSaveStatusTop" class="status"></span>
+    <span id="advSaveStatusTop" class="status" role="status" aria-live="polite"></span>
   </div>
   <div id="featuresBody"></div>
 
@@ -917,7 +919,7 @@ _SETTINGS_HTML = (
   </div>
   <div id="advSaveRow" class="adv-save-row" style="display:none;">
     <button id="advSaveBtn" class="adv-save-btn">💾 Save advanced settings</button>
-    <span id="advSaveStatus" class="status"></span>
+    <span id="advSaveStatus" class="status" role="status" aria-live="polite"></span>
   </div>
 
   <div id="sidecarStopRow" style="display:none; margin: 16px 0; text-align: right;">
@@ -926,13 +928,13 @@ _SETTINGS_HTML = (
     >Permanently disable settings server</button>
   </div>
 </div>
-<div class="panel" id="panel-backups">
+<div class="panel" id="panel-backups" role="tabpanel" aria-labelledby="tab-backups" tabindex="0">
   <div class="backup-state" id="backupState">Loading backup state…</div>
   <div class="backup-config" id="backupConfig">
     <div class="backup-config-form" id="backupConfigForm"></div>
     <div class="backup-config-actions" id="backupConfigActions" style="display:none">
       <button id="backupConfigSave">Save settings</button>
-      <span id="backupConfigStatus" class="status"></span>
+      <span id="backupConfigStatus" class="status" role="status" aria-live="polite"></span>
     </div>
   </div>
   <div class="backup-filters">
@@ -943,7 +945,7 @@ _SETTINGS_HTML = (
   </div>
   <div id="backupList"></div>
 </div>
-<div class="panel" id="panel-tool-security-policies">
+<div class="panel" id="panel-tool-security-policies" role="tabpanel" aria-labelledby="tab-tool-security-policies" tabindex="0">
   <h2>Tool Security Policies</h2>
   <p class="features-sub">
     Per-tool approval gating for high-stakes calls. Use the
@@ -991,7 +993,7 @@ _SETTINGS_HTML = (
     </div>
     <div style="margin-top:10px; display:flex; align-items:center; gap:12px">
       <button id="policy-save-global-btn" class="restart-btn">Save global settings</button>
-      <span id="policy-global-save-status" class="status"></span>
+      <span id="policy-global-save-status" class="status" role="status" aria-live="polite"></span>
     </div>
   </section>
 
@@ -1010,7 +1012,7 @@ _SETTINGS_HTML = (
     <div id="policy-rules-list"></div>
   </section>
 </div>
-<div class="panel" id="panel-accessibility">
+<div class="panel" id="panel-accessibility" role="tabpanel" aria-labelledby="tab-accessibility" tabindex="0">
   <p class="tool-desc" style="margin-bottom:16px">
     These settings apply immediately and are saved in this browser and on the
     server, so they survive restarts in every mode (including stdio, where the
@@ -1064,6 +1066,7 @@ _SETTINGS_HTML = (
     <button id="a11y-reset" class="restart-btn" type="button">Reset to defaults</button>
   </section>
 </div>
+</main>
 <div class="modal-backdrop" id="modalBackdrop">
   <div class="modal">
     <div class="modal-header">

{ha_mcp_dev-7.8.0.dev701 → ha_mcp_dev-7.8.0.dev703}/src/ha_mcp/tools/backup.py

@@ -731,10 +731,126 @@ async def restore_backup(
     return None  # py/mixed-returns: explicit terminal; error handlers above always raise (NoReturn), unreachable
 
 
+def _summarize_backup(entry: dict[str, Any]) -> dict[str, Any]:
+    """Project one HA ``backup/info`` entry to the fields a caller needs to
+    identify and choose a snapshot (issue #1586).
+
+    Size is reported per backup agent; we surface the largest reported size
+    across agents. Every field is ``.get`` so a schema the running HA version
+    doesn't populate yields ``None`` rather than raising.
+    """
+    agents = entry.get("agents") or {}
+    size_bytes: int | None = None
+    if isinstance(agents, dict):
+        sizes: list[int] = []
+        for a in agents.values():
+            if isinstance(a, dict):
+                size = a.get("size")
+                # Accept int or float (some agents report byte counts as float);
+                # bool is an int subclass but never a real size, so exclude it.
+                if isinstance(size, (int, float)) and not isinstance(size, bool):
+                    sizes.append(int(size))
+        if sizes:
+            size_bytes = max(sizes)
+    return {
+        "backup_id": entry.get("backup_id"),
+        "name": entry.get("name"),
+        "date": entry.get("date"),
+        "size_bytes": size_bytes,
+        "protected": entry.get("protected"),
+        "database_included": entry.get("database_included"),
+        "homeassistant_included": entry.get("homeassistant_included"),
+        "homeassistant_version": entry.get("homeassistant_version"),
+        "with_automatic_settings": entry.get("with_automatic_settings"),
+        "agent_ids": list(agents.keys()) if isinstance(agents, dict) else [],
+    }
+
+
+async def list_backups(client: HomeAssistantClient, limit: int = 200) -> dict[str, Any]:
+    """List the full HA snapshot tarballs known to Home Assistant (issue #1586).
+
+    Surfaces the inventory HA already returns from its WebSocket ``backup/info``
+    command — the same data ``restore_backup`` uses internally to verify a
+    ``backup_id`` exists. Before this, the snapshot scope exposed only
+    ``create`` and ``restore``, so a caller had no way to discover backup IDs or
+    confirm a specific backup landed; they had to already know the ID. Newest
+    first. Read-only: no safety backup, no restart.
+    """
+    ws_client = None
+    try:
+        ws_client, error = await get_connected_ws_client(
+            client.base_url, client.token, verify_ssl=client.verify_ssl
+        )
+        if error:
+            raise_tool_error(
+                error
+                or create_error_response(
+                    ErrorCode.CONNECTION_FAILED,
+                    "Failed to connect to Home Assistant WebSocket to list backups",
+                )
+            )
+        ws_client = cast(HomeAssistantWebSocketClient, ws_client)
+
+        info = await ws_client.send_command("backup/info")
+        if not info.get("success"):
+            raise_tool_error(
+                create_error_response(
+                    ErrorCode.SERVICE_CALL_FAILED,
+                    info.get("error", "Failed to retrieve backup information"),
+                )
+            )
+
+        result_block = info.get("result") or {}
+        raw_backups = result_block.get("backups") or []
+        summarized = [_summarize_backup(b) for b in raw_backups]
+        # Newest first so "did my backup land?" is answered by the top entry.
+        # Parse via _parse_backup_date (handles `Z`/naive) rather than sorting
+        # the raw strings lexicographically — `'Z'` > `'+'` would misorder a mix
+        # of `...Z` and `...+00:00`. Undated entries sink to the bottom.
+        _date_floor = datetime.min.replace(tzinfo=UTC)
+        summarized.sort(
+            key=lambda b: _parse_backup_date(b.get("date")) or _date_floor,
+            reverse=True,
+        )
+        total = len(summarized)
+        if limit and total > limit:
+            summarized = summarized[:limit]
+        return {
+            "success": True,
+            "count": len(summarized),
+            "total": total,
+            "backups": summarized,
+        }
+
+    except ToolError:
+        raise
+    except Exception as e:
+        logger.error(f"Error listing backups: {e}")
+        exception_to_structured_error(
+            e,
+            context={"tool": "list_backups"},
+            suggestions=["Check Home Assistant connection and the backup integration"],
+        )
+        return None  # unreachable: exception_to_structured_error always raises
+    finally:
+        # Always disconnect WebSocket — narrow to transport errors; a
+        # programming error during cleanup should still surface.
+        if ws_client:
+            try:
+                await ws_client.disconnect()
+            except (TimeoutError, OSError, ConnectionError) as err:
+                logger.debug(
+                    "ws disconnect (cleanup) transport error: %s: %s",
+                    type(err).__name__,
+                    err,
+                )
+
+
 # Valid (scope, action) combinations. Anything outside this set is
 # rejected with a structured VALIDATION_INVALID_PARAMETER error.
 _VALID_COMBOS: set[tuple[str, str]] = {
     ("snapshot", "create"),
+    ("snapshot", "list"),
     ("snapshot", "restore"),
     ("edits", "create"),
     ("edits", "list"),
@@ -799,6 +915,7 @@ def register_backup_tools(
 | scope | action | What it does |
 |---|---|---|
 | `snapshot` | `create` | Create a full HA tarball (config + addons, no DB by default). Heavy, seconds-long. |
+| `snapshot` | `list` | List full HA tarball snapshots (id, name, date, size). Read-only — use to discover a `backup_id` or confirm a backup landed. |
 | `snapshot` | `restore` | Restore a full HA tarball. **Restarts HA.** Last-resort recovery. |
 | `edits` | `create` | On-demand snapshot of one entity (`domain` + `entity_id` required). Use before the user manually edits in the HA UI. Same handler path the decorator takes on writes; bypasses the `enable_auto_backup` toggle. |
 | `edits` | `list` | List per-entity auto-backups (lightweight). Filter by `domain` and/or `entity_id`. |
@@ -817,6 +934,7 @@ def register_backup_tools(
 
 **Examples:**
 - Snapshot before risky op: `ha_manage_backup(scope="snapshot", action="create", name="Before_Big_Change")`
+- List snapshots (to discover a backup_id or confirm one landed): `ha_manage_backup(scope="snapshot", action="list")`
 - Restore full snapshot: `ha_manage_backup(scope="snapshot", action="restore", backup_id="dd7550ed")`
 - On-demand entity snapshot before a manual UI edit: `ha_manage_backup(scope="edits", action="create", domain="helper_input_boolean", entity_id="kitchen_lights_active")`
 - List recent auto-backups for one automation: `ha_manage_backup(scope="edits", action="list", domain="automation", entity_id="kitchen_lights")`
@@ -906,7 +1024,7 @@ def register_backup_tools(
                 default=200,
                 ge=1,
                 le=10_000,
-                description="(edits.list) Maximum number of entries to return.",
+                description="(edits.list / snapshot.list) Maximum number of entries to return.",
             ),
         ] = 200,
     ) -> dict[str, Any]:
@@ -916,6 +1034,8 @@ def register_backup_tools(
         if scope == "snapshot":
             if action == "create":
                 return await create_backup(client, name)
+            if action == "list":
+                return await list_backups(client, limit)
             # action == "restore"
             bid = _require("backup_id", backup_id, scope, action)
             return await restore_backup(client, bid, restore_database)