ha-mcp-dev 8.4.3.dev2542__tar.gz → 8.4.3.dev2546__tar.gz

{ha_mcp_dev-8.4.3.dev2542/src/ha_mcp_dev.egg-info → ha_mcp_dev-8.4.3.dev2546}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 8.4.3.dev2542
+Version: 8.4.3.dev2546
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT

{ha_mcp_dev-8.4.3.dev2542 → ha_mcp_dev-8.4.3.dev2546}/pyproject.toml

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

@@ -7,7 +7,11 @@ Storage path resolution
 -----------------------
 ``Settings.auto_backup_dir`` overrides; otherwise defaults to
 ``/data/ha_mcp_backups`` in the add-on (SUPERVISOR_TOKEN set + ``/data``
-exists), else ``${XDG_DATA_HOME:-~/.local/share}/ha_mcp/backups``.
+exists), else ``<data dir>/backups`` where the data dir is what
+``utils.data_paths.get_data_dir`` resolves (``HA_MCP_CONFIG_DIR``,
+``~/.ha-mcp``, or the tmpdir fallback). Installs that still hold snapshots
+under the pre-#2372 default ``${XDG_DATA_HOME:-~/.local/share}/ha_mcp/backups``
+keep using that directory; see ``_resolve_default_dir``.
 
 File format
 -----------
@@ -55,6 +59,7 @@ import yaml  # type: ignore[import-untyped]
 from fastmcp.exceptions import ToolError
 
 from .client.rest_client import HomeAssistantConnectionError, HomeAssistantError
+from .utils.data_paths import get_data_dir
 
 logger = logging.getLogger(__name__)
 
@@ -263,17 +268,60 @@ def _now_iso() -> str:
     return datetime.now(UTC).isoformat()
 
 
-def _resolve_default_dir() -> Path:
-    """Pick a sane default backup directory for the current deployment mode."""
-    # Addon detection: Supervisor sets SUPERVISOR_TOKEN AND /data exists.
-    if os.environ.get("SUPERVISOR_TOKEN") and Path("/data").is_dir():
-        return Path("/data/ha_mcp_backups")
+# Add-on default. Named in the add-on option descriptions, so it stays put.
+_ADDON_BACKUP_DIR = Path("/data/ha_mcp_backups")
+
+
+def _legacy_default_dir() -> Path:
+    """The non-add-on default before #2372: XDG user-data, outside the data dir."""
     xdg = os.environ.get("XDG_DATA_HOME")
     if xdg:
         return Path(xdg) / "ha_mcp" / "backups"
     return (Path.home() / ".local" / "share" / "ha_mcp" / "backups").resolve()
 
 
+def _holds_files(path: Path) -> bool:
+    """Whether ``path`` is a directory with at least one entry.
+
+    An unreadable or missing directory counts as empty: nothing in it can be
+    listed or restored from, so there is nothing to keep using.
+    """
+    try:
+        return any(path.iterdir())
+    except OSError:
+        return False
+
+
+def _resolve_default_dir() -> Path:
+    """Pick a sane default backup directory for the current deployment mode.
+
+    Add-on (Supervisor sets ``SUPERVISOR_TOKEN`` and ``/data`` exists):
+    ``/data/ha_mcp_backups``. Otherwise ``backups/`` inside the data dir, the
+    directory that already holds the settings and that every documented
+    Docker recipe persists as the ``ha-mcp-data`` volume. The previous default,
+    ``${XDG_DATA_HOME:-~/.local/share}/ha_mcp/backups``, sat outside that
+    volume: under a ``read_only`` root it was EROFS, which fails the mandatory
+    pre-write snapshots closed, and on a writable root the snapshots were
+    discarded with the container (#2372).
+
+    An install that already holds snapshots under the previous default keeps
+    using it so its restore points stay listed and rotation keeps counting
+    them; only installs with nothing there move to the data dir.
+    """
+    if os.environ.get("SUPERVISOR_TOKEN") and _ADDON_BACKUP_DIR.parent.is_dir():
+        return _ADDON_BACKUP_DIR
+    legacy = _legacy_default_dir()
+    if _holds_files(legacy):
+        logger.info(
+            "Auto-backup: keeping existing backup dir %s (new installs default "
+            "to %s; set HAMCP_BACKUP_DIR to choose explicitly)",
+            legacy,
+            get_data_dir() / "backups",
+        )
+        return legacy
+    return get_data_dir() / "backups"
+
+
 # Sentinel returned by ``BackupManager._fetch_config_for_snapshot`` when there
 # is nothing to snapshot — a handled transient fetch failure (already logged),
 # or a None config for an entity that did not exist. Distinct from any real

{ha_mcp_dev-8.4.3.dev2542 → ha_mcp_dev-8.4.3.dev2546}/src/ha_mcp/config.py

@@ -400,7 +400,7 @@ class Settings(BaseSettings):
 
     # Backup directory override. Empty ("") resolves at runtime to a
     # deployment-mode default: ``/data/ha_mcp_backups`` in the add-on,
-    # otherwise ``${XDG_DATA_HOME:-~/.local/share}/ha_mcp/backups``.
+    # otherwise ``<data dir>/backups`` (see ``backup_manager._resolve_default_dir``).
     auto_backup_dir: str = Field("", alias="HAMCP_BACKUP_DIR")
 
     # Calendar event backups query an ahead-of-now window to locate the
@@ -776,8 +776,8 @@ FEATURE_FLAG_FIELDS: tuple[FeatureFlagField, ...] = (
 )
 
 # Override-file location is the same data dir that holds tool_config.json
-# (resolved via ``utils.data_paths.get_data_dir`` — addon ``/data``,
-# ``HA_MCP_CONFIG_DIR``, ``XDG_DATA_HOME``, or a tmpdir fallback).
+# (resolved via ``utils.data_paths.get_data_dir`` — ``HA_MCP_CONFIG_DIR``,
+# addon ``/data``, ``~/.ha-mcp``, or a tmpdir fallback).
 # Imported lazily inside helpers to avoid a circular import at module
 # load.
 _FEATURE_FLAG_OVERRIDE_FILENAME = "feature_flags.json"
@@ -1656,8 +1656,8 @@ BACKUP_OVERRIDE_FIELDS: tuple[BackupOverrideField, ...] = (
 )
 
 # Override-file location is the same data dir that holds tool_config.json
-# (resolved via ``utils.data_paths.get_data_dir`` — addon ``/data``,
-# ``HA_MCP_CONFIG_DIR``, ``XDG_DATA_HOME``, or a tmpdir fallback).
+# (resolved via ``utils.data_paths.get_data_dir`` — ``HA_MCP_CONFIG_DIR``,
+# addon ``/data``, ``~/.ha-mcp``, or a tmpdir fallback).
 # Imported lazily inside helpers to avoid a circular import at module
 # load (``utils.data_paths`` imports from ``_version`` which imports
 # from ``config`` transitively in some test layouts).

{ha_mcp_dev-8.4.3.dev2542 → ha_mcp_dev-8.4.3.dev2546}/src/ha_mcp/settings_ui/locales/en.json

@@ -251,7 +251,7 @@
     "backup.fields.auto_backup_retain_per_entity.label": "Retain per entity",
     "backup.fields.auto_backup_retain_per_entity.help": "Maximum snapshots kept per entity (1–10000). Older ones rotate out.",
     "backup.fields.auto_backup_dir.label": "Backup directory override",
-    "backup.fields.auto_backup_dir.help": "Leave empty to use the default directory; otherwise enter an absolute path.",
+    "backup.fields.auto_backup_dir.help": "Leave empty for the default: /data/ha_mcp_backups in the App (add-on), otherwise the backups/ subdirectory of the ha-mcp data directory; an install that already holds snapshots under the earlier default keeps using it. The directory in use is shown in the backup status. Or enter an absolute path.",
     "backup.fields.auto_backup_calendar_lookahead_days.label": "Calendar lookahead (days)",
     "backup.fields.auto_backup_calendar_lookahead_days.help": "How far ahead to query calendar events for pre-edit snapshots. Range 1–365.",
     "backup.fields.enable_snapshot_delete.label": "Allow snapshot deletion",
@@ -288,7 +288,7 @@
     "backup.bulk.confirm": "Delete all backups matching: {filters}?",
     "backup.bulk.deleted": "Deleted {count} backup(s)",
     "filesystem.custom.title": "Custom filesystem paths (advanced)",
-    "filesystem.custom.help": "Extra paths (one per line) that file tools may <strong>read and write</strong>. Config-relative paths, including exact filenames such as <code>sensor.yaml</code>, and paths under <code>/share</code>, <code>/media</code>, <code>/ssl</code>, and <code>/backup</code> are supported. Each entry allows that path and anything below it. You can also manage these paths in Home Assistant under Settings → Devices & Services → HA-MCP Custom Component → HA-MCP File & YAML Tools → Configure; both locations edit the same setting and apply changes immediately.",
+    "filesystem.custom.help": "Extra paths (one per line) that file tools may <strong>read and write</strong>. Config-relative paths, including exact filenames such as <code>sensor.yaml</code>, and paths under <code>/share</code>, <code>/media</code>, <code>/ssl</code>, and <code>/backup</code> are supported. Each entry allows that path and anything below it. Entries are matched literally; wildcards such as <code>*</code> are not supported. You can also manage these paths in Home Assistant under Settings → Devices & Services → HA-MCP Custom Component → HA-MCP File & YAML Tools → Configure; both locations edit the same setting and apply changes immediately.",
     "filesystem.custom.blocked": "Always blocked: {paths}, path traversal (<code>..</code>), and absolute paths outside allowed HAOS volumes.",
     "filesystem.custom.enable_first": "Enable beta features and filesystem tools above to edit.",
     "filesystem.custom.unavailable": "Custom paths are currently unavailable.",

{ha_mcp_dev-8.4.3.dev2542 → ha_mcp_dev-8.4.3.dev2546}/src/ha_mcp/settings_ui/settings.js

@@ -1438,7 +1438,7 @@ const BACKUP_FIELD_LABELS = {
   },
   auto_backup_dir: {
     label: 'Backup directory override',
-    help: 'Empty = default (/data/ha_mcp_backups in the App (add-on), $XDG_DATA_HOME/ha_mcp/backups otherwise). Override with an absolute path.',
+    help: 'Leave empty for the default: /data/ha_mcp_backups in the App (add-on), otherwise the backups/ subdirectory of the ha-mcp data directory; an install that already holds snapshots under the earlier default keeps using it. The directory in use is shown in the backup status. Or enter an absolute path.',
   },
   auto_backup_calendar_lookahead_days: {
     label: 'Calendar lookahead (days)',

{ha_mcp_dev-8.4.3.dev2542 → ha_mcp_dev-8.4.3.dev2546}/src/ha_mcp/tools/log_common.py

@@ -128,7 +128,7 @@ def _collect_log_warnings(
             f"ignored for source='{source}'"
         )
     if (
-        source in ("logbook", "logger", "supervisor", "system_service")
+        source in ("logbook", "logger", "supervisor", "system_service", "fault_log")
         and level is not None
     ):
         warnings.append(
@@ -140,10 +140,10 @@ def _collect_log_warnings(
             "Parameter 'slug' only applies to source='supervisor' or "
             f"'system_service'; ignored for source='{source}'"
         )
-    if source not in ("logbook", "error_log") and offset:
+    if source not in ("logbook", "error_log", "fault_log") and offset:
         warnings.append(
-            "Parameter 'offset' only applies to source='logbook' or "
-            f"'error_log'; ignored for source='{source}'"
+            "Parameter 'offset' only applies to source='logbook', 'error_log' "
+            f"or 'fault_log'; ignored for source='{source}'"
         )
     return warnings
 

ha_mcp_dev-8.4.3.dev2546/src/ha_mcp/tools/log_sources_fault.py

@@ -0,0 +1,295 @@
+"""``ha_get_logs(source='fault_log')`` — Home Assistant's native-crash dump.
+
+HA Core's ``__main__`` enables :mod:`faulthandler` on ``home-assistant.log.fault``
+in the config root. faulthandler writes only on a native fatal signal (SIGSEGV,
+SIGABRT, SIGBUS, SIGILL, SIGFPE, or a Python fatal error): the process dies
+before any logging runs, so the per-thread Python traceback it dumps reaches
+neither journald nor ``home-assistant.log``. No other ``ha_get_logs`` source can
+show it (issue #2373).
+
+The file is opened in append mode on every start, so on a healthy install it
+exists and is empty; each crash appends one block that opens with a
+``Fatal Python error: ...`` line followed by one traceback per thread. A block
+is only readable in its original line order, so unlike the line-oriented
+raw-text sources this one orders whole blocks and pages through the result
+with ``offset`` instead of reversing lines.
+
+The read goes through the File & YAML Tools entry's privileged ``read_file``
+service (the same route as ``ha_read_file``), which allows the path from
+component 2.1.4. Split out of ``log_sources`` under `.gemini/styleguide.md`
+§ Tool Consolidation and Module Size.
+"""
+
+from typing import Any, Literal, NoReturn
+
+from fastmcp.exceptions import ToolError
+
+from ..client.rest_client import (
+    HomeAssistantAPIError,
+    HomeAssistantAuthError,
+    HomeAssistantConnectionError,
+)
+from ..errors import ErrorCode, create_error_response
+from .helpers import exception_to_structured_error, raise_tool_error
+from .log_common import (
+    DEFAULT_LOG_LIMIT,
+    SUPERVISOR_SEARCH_WINDOW_LINES,
+    _coerce_limit,
+)
+from .tools_filesystem import _assert_mcp_tools_available, call_mcp_tools_service
+from .util_helpers import unwrap_service_response
+
+# Config-relative path HA Core hands to ``faulthandler.enable`` (``FAULT_LOG_FILENAME``
+# in ``homeassistant/__main__.py``).
+FAULT_LOG_PATH = "home-assistant.log.fault"
+
+# First component release whose read allowlist includes ``FAULT_LOG_PATH``. An
+# older component answers the read with "Path not allowed"; that reply is the
+# version signal, no separate probe needed.
+MIN_COMPONENT_VERSION_FAULT_LOG = "2.1.4"
+
+# Lines tailed from the file per call, independent of ``limit``. A single dump
+# lists every thread, so it routinely runs past a 100-line ``limit``; tailing
+# only ``limit`` lines would cut off the ``Fatal Python error`` header that
+# names the signal. The window is the same one the other raw-text sources use
+# for a search, and ``offset`` pages through it.
+FAULT_LOG_WINDOW_LINES = SUPERVISOR_SEARCH_WINDOW_LINES
+
+# faulthandler opens every dump with this line, so it delimits crash blocks.
+_FATAL_MARKER = "Fatal Python error:"
+
+_NO_CRASH_MESSAGE = (
+    "No native crash recorded: home-assistant.log.fault is empty. Ordinary "
+    "Python errors never land here; use source='system' or source='error_log' "
+    "for those."
+)
+
+
+def _is_missing_file_error(error: str) -> bool:
+    return "does not exist" in error or "not a file" in error
+
+
+def _no_crash(data: dict[str, Any], total_lines: int) -> dict[str, Any]:
+    data.update(
+        crash_recorded=False,
+        log="",
+        total_lines=total_lines,
+        returned_lines=0,
+        has_more=False,
+        message=_NO_CRASH_MESSAGE,
+    )
+    return data
+
+
+def _raise_read_failure(error: str) -> NoReturn:
+    """Turn a ``read_file`` refusal into the matching structured error.
+
+    "Path not allowed" is the one refusal with a known cause: a component
+    older than :data:`MIN_COMPONENT_VERSION_FAULT_LOG`, whose allowlist does
+    not yet carry the file. Anything else is reported verbatim.
+    """
+    if "Path not allowed" in error:
+        raise_tool_error(
+            create_error_response(
+                ErrorCode.COMPONENT_NOT_INSTALLED,
+                "The installed ha_mcp_tools custom component does not allow "
+                f"reading {FAULT_LOG_PATH} (requires component >= "
+                f"{MIN_COMPONENT_VERSION_FAULT_LOG}).",
+                details=error,
+                suggestions=[
+                    "HACS → Integrations → HA-MCP Custom Component → Update",
+                    "Restart Home Assistant after the update completes",
+                ],
+                context={"source": "fault_log"},
+            )
+        )
+    raise_tool_error(
+        create_error_response(
+            ErrorCode.SERVICE_CALL_FAILED,
+            f"read_file failed for {FAULT_LOG_PATH}: {error or 'unknown error'}",
+            # Parenthesised so each reads as one suggestion rather than a
+            # list entry with a missing comma (py/implicit-string-
+            # concatenation-in-list).
+            suggestions=[
+                (
+                    f"Check that {FAULT_LOG_PATH} in the Home Assistant config "
+                    "directory is readable by Home Assistant"
+                ),
+                "Check Home Assistant logs for the ha_mcp_tools read error",
+                (
+                    "Retry after the file is readable; an absent or empty file "
+                    "is reported as no crash, not as an error"
+                ),
+            ],
+            context={"source": "fault_log"},
+        )
+    )
+
+
+def _split_blocks(lines: list[str]) -> list[list[str]]:
+    """Group the window into crash blocks, each opening with the fatal marker.
+
+    Lines before the first marker are the tail of a block whose header fell
+    outside the window; they form a leading partial block so nothing is lost.
+    """
+    blocks: list[list[str]] = []
+    current: list[str] = []
+    for line in lines:
+        if line.startswith(_FATAL_MARKER) and current:
+            blocks.append(current)
+            current = []
+        current.append(line)
+    if current:
+        blocks.append(current)
+    return blocks
+
+
+def _shape_crash_page(
+    data: dict[str, Any],
+    lines: list[str],
+    *,
+    limit: int,
+    offset: int,
+    search: str | None,
+    order: Literal["newest", "oldest"],
+) -> dict[str, Any]:
+    """Order whole crash blocks, then page through the flattened text.
+
+    ``order='newest'`` puts the latest block first; every block keeps its own
+    line order so the traceback stays readable. ``search`` selects whole
+    blocks (any line matching) rather than lines, so a hit inside a traceback
+    still comes back with its ``Fatal Python error`` header and the rest of
+    the frames. ``offset``/``limit`` slice the assembled text from its start,
+    and ``has_more``/``next_offset`` continue it.
+    """
+    blocks = _split_blocks(lines)
+    fatal_blocks = sum(1 for block in blocks if block[0].startswith(_FATAL_MARKER))
+    if order == "newest":
+        blocks.reverse()
+
+    filters_applied: dict[str, str] = {}
+    if search:
+        search_lower = search.lower()
+        blocks = [b for b in blocks if any(search_lower in ln.lower() for ln in b)]
+        filters_applied["search"] = search
+    matched_blocks = len(blocks)
+    flat = [line for block in blocks for line in block]
+
+    page = flat[offset : offset + limit]
+    has_more = offset + limit < len(flat)
+    data.update(
+        crash_recorded=True,
+        log="\n".join(page),
+        returned_lines=len(page),
+        fatal_error_blocks_in_window=fatal_blocks,
+        has_more=has_more,
+    )
+    if has_more:
+        data["next_offset"] = offset + limit
+        # Carry the active filter: the next page must slice the same
+        # filtered block list, or offset lands in unrelated blocks.
+        search_arg = f", search={search!r}" if search else ""
+        data["pagination_hint"] = (
+            f"ha_get_logs(source='fault_log', offset={offset + limit}, "
+            f"limit={limit}, order='{order}'{search_arg})"
+        )
+    if filters_applied:
+        data["filters_applied"] = filters_applied
+        data["matched_blocks"] = matched_blocks
+    return data
+
+
+class FaultLogSourceMixin:
+    """``fault_log`` source, mixed into ``LogTools``."""
+
+    _client: Any
+
+    async def _read_fault_file(self) -> dict[str, Any]:
+        """One gated ``read_file`` call, unwrapped; transport errors become ToolErrors.
+
+        The live tools-entry probe runs first, as the file and YAML tools do,
+        so an entry removed after this client cached its caller token surfaces
+        the actionable "add the entry" error rather than HA's 400 for a
+        service that no longer exists. That gate and the caller-token gate
+        raise their own ToolErrors, which pass through untouched.
+        """
+        try:
+            await _assert_mcp_tools_available(self._client)
+            raw = await call_mcp_tools_service(
+                self._client,
+                "read_file",
+                {"path": FAULT_LOG_PATH, "tail_lines": FAULT_LOG_WINDOW_LINES},
+            )
+        except ToolError:
+            raise
+        except (HomeAssistantAuthError, HomeAssistantAPIError) as e:
+            exception_to_structured_error(e, context={"source": "fault_log"})
+        except (HomeAssistantConnectionError, TimeoutError, OSError) as e:
+            exception_to_structured_error(
+                e,
+                context={"source": "fault_log"},
+                suggestions=["Check Home Assistant connection"],
+            )
+        return unwrap_service_response(raw) if isinstance(raw, dict) else {}
+
+    async def _get_fault_log(
+        self,
+        limit: int | None = None,
+        search: str | None = None,
+        offset: int = 0,
+        order: Literal["newest", "oldest"] = "newest",
+    ) -> dict[str, Any]:
+        """Read ``home-assistant.log.fault`` through the component's read_file.
+
+        Always tails :data:`FAULT_LOG_WINDOW_LINES` from the file; ``order``
+        arranges whole crash blocks, ``search`` keeps the blocks that mention
+        the term, and ``offset``/``limit`` page through the assembled text. An absent or
+        empty file is the healthy state and returns success with
+        ``crash_recorded=False`` rather than an error.
+        """
+        effective_limit = _coerce_limit(
+            limit, default=DEFAULT_LOG_LIMIT, suggestion_example="100"
+        )
+        result = await self._read_fault_file()
+
+        data: dict[str, Any] = {
+            "success": True,
+            "source": "fault_log",
+            "path": FAULT_LOG_PATH,
+            "limit": effective_limit,
+            "offset": offset,
+            "order": order,
+            "window_lines": FAULT_LOG_WINDOW_LINES,
+        }
+        if not result.get("success", False):
+            error = str(result.get("error", ""))
+            if _is_missing_file_error(error):
+                # HA opens the file at every start, so a missing file means
+                # this config dir has not been started by HA's __main__ (or
+                # someone removed it). Either way: nothing to show.
+                return _no_crash(data, total_lines=0)
+            _raise_read_failure(error)
+
+        content = result.get("content")
+        lines = content.splitlines() if isinstance(content, str) else []
+        # The component reports the untailed line count; fall back to what we
+        # got when an older shape omits it.
+        total_lines = result.get("total_lines")
+        if not isinstance(total_lines, int):
+            total_lines = len(lines)
+        if isinstance(result.get("modified"), str):
+            data["modified"] = result["modified"]
+
+        if not any(line.strip() for line in lines):
+            return _no_crash(data, total_lines=total_lines)
+        data["total_lines"] = total_lines
+        # Older blocks beyond the window are unreachable by offset; say so.
+        data["window_truncated"] = bool(result.get("truncated", False))
+        return _shape_crash_page(
+            data,
+            lines,
+            limit=effective_limit,
+            offset=offset,
+            search=search,
+            order=order,
+        )

{ha_mcp_dev-8.4.3.dev2542 → ha_mcp_dev-8.4.3.dev2546}/src/ha_mcp/tools/tools_filesystem.py

@@ -712,13 +712,15 @@ class FilesystemTools:
         Reads files from allowed paths within the config directory. Some files
         have special handling:
         - `secrets.yaml`: Values are masked for security
-        - `home-assistant.log`: Limited to tail (last N lines) by default
+        - `home-assistant.log` / `home-assistant.log.fault`: Limited to tail
+          (last N lines) by default. Prefer ha_get_logs(source='error_log') and
+          ha_get_logs(source='fault_log') over reading these directly.
 
         **Allowed Read Paths:**
         - `configuration.yaml`, `automations.yaml`, `scripts.yaml`, `scenes.yaml`
         - `secrets.yaml` (values masked)
         - `packages/*.yaml`
-        - `home-assistant.log` (tail only)
+        - `home-assistant.log`, `home-assistant.log.fault` (tail only)
         - `www/**`, `themes/**`, `custom_templates/**`, `dashboards/**`, `blueprints/**`
         - `custom_components/**/*.py` (read-only)
         - Plus any custom directories OR HAOS sibling volumes (`/share`,

{ha_mcp_dev-8.4.3.dev2542 → ha_mcp_dev-8.4.3.dev2546}/src/ha_mcp/tools/tools_logs.py

@@ -22,10 +22,11 @@ from .log_common import (
     _validate_log_slug,
 )
 from .log_sources import CoreLogSourcesMixin
+from .log_sources_fault import FaultLogSourceMixin
 from .log_sources_supervisor import SupervisorLogSourcesMixin
 
 
-class LogTools(CoreLogSourcesMixin, SupervisorLogSourcesMixin):
+class LogTools(CoreLogSourcesMixin, SupervisorLogSourcesMixin, FaultLogSourceMixin):
     """Dispatches ``ha_get_logs`` to one log source and shapes the response."""
 
     def __init__(self, client: Any) -> None:
@@ -76,6 +77,10 @@ class LogTools(CoreLogSourcesMixin, SupervisorLogSourcesMixin):
             # logger reports per-integration levels, not time-ordered events;
             # 'order' does not apply (a warning is emitted upstream).
             return await self._get_logger_info(limit=limit, search=search)
+        if source == "fault_log":
+            return await self._get_fault_log(
+                limit=limit, search=search, offset=offset, order=order
+            )
         if source == "system_service":
             assert slug is not None  # guaranteed by _validate_log_slug
             return await self._get_system_service_log(
@@ -171,6 +176,7 @@ def register_logs_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
             "supervisor",
             "system_service",
             "logger",
+            "fault_log",
         ] = "logbook",
         # Shared parameters
         limit: int | None = None,
@@ -180,7 +186,8 @@ def register_logs_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
             Field(
                 description=(
                     "Sort order for time-ordered sources (logbook, system, "
-                    "error_log, supervisor, system_service): 'newest' (default) "
+                    "error_log, supervisor, system_service, fault_log): "
+                    "'newest' (default) "
                     "returns most-recent first; 'oldest' returns chronological-"
                     "first. Ignored for source='logger', and for "
                     "source='error_log' with structured=True (that summary is "
@@ -197,10 +204,12 @@ def register_logs_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
             Field(
                 ge=0,
                 description=(
-                    "Page deeper into source='logbook' and source='error_log' "
-                    "(ignored for other sources). On error_log it counts raw "
-                    "log lines back from the newest entry; pass the response's "
-                    "'next_offset' to continue while 'has_more' is true."
+                    "Page deeper into source='logbook', 'error_log' and "
+                    "'fault_log' (ignored for other sources). On error_log it "
+                    "counts raw log lines back from the newest entry; on "
+                    "fault_log it counts lines from the start of the assembled "
+                    "crash text. Pass the response's 'next_offset' to continue "
+                    "while 'has_more' is true."
                 ),
             ),
         ] = 0,
@@ -245,6 +254,15 @@ def register_logs_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
         - "system_service": HA-Supervisor-managed system service logs (requires
           slug ∈ {supervisor, host, core, dns, audio, cli, multicast, observer})
         - "logger": Effective log level per integration via logger/log_info (confirms logger.set_level changes took effect)
+        - "fault_log": HA Core's faulthandler crash dump (home-assistant.log.fault).
+          Written only when HA dies from a native fatal signal (segfault, abort,
+          Python fatal error), which never reaches journald or error_log. Empty
+          on a healthy install (crash_recorded=False). Whole crash blocks are
+          ordered (newest first by default) with each block's lines kept in
+          place so the traceback reads correctly; search keeps every block
+          that mentions the term; offset/limit page through the assembled
+          text. Reads through the "HA-MCP File & YAML Tools"
+          entry (component >= 2.1.4).
 
         **Prefer source='system' for triage.** It returns HA's own deduplicated
         system_log entries with counts, first_occurred and full tracebacks; of
@@ -258,10 +276,12 @@ def register_logs_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
         cap, or for the per-component rollup.
 
         **Shared params:** limit, search (keyword filter on entries/lines; matches integration domain for source='logger')
-        **Order:** order='newest' (default) returns most-recent first; order='oldest' returns chronological-first. Applies to all time-ordered sources (logbook, system, error_log, supervisor, system_service); ignored for source='logger' and for error_log with structured=True. For raw-text sources (error_log, supervisor, system_service) it sets the read direction of the most-recent window.
+        **Order:** order='newest' (default) returns most-recent first; order='oldest' returns chronological-first. Applies to all time-ordered sources (logbook, system, error_log, supervisor, system_service, fault_log); ignored for source='logger' and for error_log with structured=True. For raw-text sources (error_log, supervisor, system_service) it sets the read direction of the most-recent window; fault_log orders whole crash blocks instead of lines.
         **Logbook params:** hours_back, entity_id, end_time, compact (default True — strips attribute dicts to save context)
-        **Pagination (logbook + error_log):** offset pages deeper; ignored for the
-            other sources. Logbook responses carry has_more plus a
+        **Pagination (logbook + error_log + fault_log):** offset pages deeper; ignored for the
+            other sources. fault_log always reads a fixed window from the end of
+            the file, orders its crash blocks, and pages the assembled text
+            from the start with has_more/next_offset. Logbook responses carry has_more plus a
             pagination_hint. On error_log, offset counts raw log lines back from
             the newest entry (journald entries on Supervisor-backed installs),
             both modes read a bounded window per call — so `level`/`search`

{ha_mcp_dev-8.4.3.dev2542 → ha_mcp_dev-8.4.3.dev2546/src/ha_mcp_dev.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 8.4.3.dev2542
+Version: 8.4.3.dev2546
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT

{ha_mcp_dev-8.4.3.dev2542 → ha_mcp_dev-8.4.3.dev2546}/src/ha_mcp_dev.egg-info/SOURCES.txt

@@ -208,6 +208,7 @@ src/ha_mcp/tools/helpers.py
 src/ha_mcp/tools/integration_reconfigure.py
 src/ha_mcp/tools/log_common.py
 src/ha_mcp/tools/log_sources.py
+src/ha_mcp/tools/log_sources_fault.py
 src/ha_mcp/tools/log_sources_supervisor.py
 src/ha_mcp/tools/reference_validator.py
 src/ha_mcp/tools/registry.py