ha-mcp-dev 8.2.0.dev2320__tar.gz → 8.2.0.dev2323__tar.gz

{ha_mcp_dev-8.2.0.dev2320/src/ha_mcp_dev.egg-info → ha_mcp_dev-8.2.0.dev2323}/PKG-INFO

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.2.0.dev2320"
+version = "8.2.0.dev2323"
 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.2.0.dev2320 → ha_mcp_dev-8.2.0.dev2323}/src/ha_mcp/client/rest_client.py

@@ -40,6 +40,10 @@ logger = logging.getLogger(__name__)
 # so the request did not execute and retrying is safe even for writes.
 _RETRYABLE_STATUS = frozenset({502, 503, 504})
 _MAX_REQUEST_ATTEMPTS = 3
+# Journald window requested for the Core error log on Supervisor-backed
+# installs. Both such branches of get_error_log() build their request from this
+# constant, so the window they ask for cannot drift apart.
+_ERROR_LOG_LINES = 20000
 
 
 class HomeAssistantError(Exception):
@@ -586,7 +590,11 @@ class HomeAssistantClient:
         """
         if is_running_in_addon():
             logger.debug("Fetching error log via Supervisor direct (core service)")
-            return await self._supervisor_logs_get("core")
+            # An explicit `lines` is required: without it Supervisor applies its
+            # 100-line default, which is far too short a slice to tell what keeps
+            # repeating. `_get_supervisor_log` plumbs the same parameter for the
+            # same reason (#1734).
+            return await self._supervisor_logs_get("core", lines=_ERROR_LOG_LINES)
 
         if await self._is_supervised_install():
             logger.debug(
@@ -594,7 +602,7 @@ class HomeAssistantClient:
             )
             raw_response = await self._raw_request(
                 "GET",
-                "/hassio/core/logs?lines=20000",
+                f"/hassio/core/logs?lines={_ERROR_LOG_LINES}",
                 headers={"Accept": "text/plain"},
             )
             return raw_response.text
@@ -619,11 +627,21 @@ class HomeAssistantClient:
         glitch or HTTP error returns False without setting the cache,
         so the next call re-probes. This is the only path that
         intentionally fails open — caller proceeds on the historical
-        Container branch (which on HAOS will also fail, but with a
-        clearer 404 than a probe-side exception would surface).
-
-        Auth / connection / HTTP errors are caught explicitly; runtime
-        bugs (TypeError, AttributeError) and BaseException derivatives
+        Container branch.
+
+        A 401 is deliberately excluded from that fail-open: it is a
+        definitive answer about the credential rather than a transient
+        glitch, and swallowing it strands exactly the install class this
+        probe exists for. Failing open sends a Supervised caller down
+        the Container branch to ``/api/error_log``, which HA Core never
+        registers under ``SUPERVISOR`` (see ``get_error_log``), so the
+        auth failure resurfaces as a 404 and the caller answers with
+        connection advice instead of "re-create the LLAT". Letting
+        ``HomeAssistantAuthError`` propagate reaches the auth handler
+        directly. Transport / HTTP fail-open is unchanged.
+
+        Connection / HTTP errors are caught explicitly; runtime bugs
+        (TypeError, AttributeError) and BaseException derivatives
         (KeyboardInterrupt, CancelledError) deliberately propagate so
         they're not silenced as "not supervised".
         """
@@ -632,16 +650,17 @@ class HomeAssistantClient:
         try:
             config = await self._request("GET", "/config")
         except (
-            HomeAssistantAuthError,
             HomeAssistantAPIError,
             HomeAssistantConnectionError,
             httpx.HTTPError,
             TimeoutError,
         ) as exc:
-            # Fail-open on transport / HTTP-layer failures only. Note:
-            # a 401 here likely means the LLA is bad and the /error_log
-            # fallback will also 401 — the user gets a clearer auth error
-            # from that path than a swallowed probe error would surface.
+            # Fail-open on transport / HTTP-layer failures only.
+            # HomeAssistantAuthError is deliberately absent: a 401 is a
+            # definitive verdict on the credential, and failing open on
+            # it routes a Supervised caller to /api/error_log — a route
+            # that does not exist there — turning the auth error into a
+            # 404 (see the docstring).
             # Logged at WARNING so it's visible at default log levels
             # without spamming on every call (probe runs at most once
             # per session per outcome).

{ha_mcp_dev-8.2.0.dev2320 → ha_mcp_dev-8.2.0.dev2323}/src/ha_mcp/settings_ui/locales/README.md

@@ -37,11 +37,16 @@ register the engine imitates, a component catalog left at a key or two rests
 entirely on whichever of them addresses the reader —
 `test_every_shipped_component_catalog_gets_reader_addressing_samples` pins that
 one. Leaving that catalog empty is fine, but the moment you author anything in
-it, at least one key must be one whose English addresses the reader in the
-second person, and it must carry a non-empty translation — a key left blank is
+it, at least two keys must be ones whose English addresses the reader in the
+second person, and each must carry a non-empty translation — a key left blank is
 skipped like a missing one rather than sampled empty. Most component strings do
 not address the reader, so starting at the top of the file leaves the catalog
-anchorless and that check red until you add one that does. To fill them in your own PR instead, run
+anchorless and that check red until you add ones that do. Two rather than one
+because the run likeliest to need the register is the one that rewords such a
+key: that queues it, and a queued key is dropped from the candidates, so a
+surface resting on a single anchor loses its register in exactly that run —
+`test_component_samples_survive_their_own_anchor_being_queued` pins the
+survival. To fill them in your own PR instead, run
 `scripts/translate_locales.py` yourself and review its output like any
 other diff. Also add the new code to the locale list in the repository-root
 `AGENTS.md`

{ha_mcp_dev-8.2.0.dev2320 → ha_mcp_dev-8.2.0.dev2323}/src/ha_mcp/settings_ui/locales/en.json

@@ -128,7 +128,7 @@
     "features.enable_strict_mandatory_bps.label": "Strict best-practices mode",
     "features.enable_strict_mandatory_bps.help": "Strict mode: prevents the client from using the tool until it can prove that it read the best practices. While on, the six best-practice write tools (automations, scripts, scenes, helpers, dashboards, raw YAML) are blocked and return an error directing the client to read the best-practices skill via ha_get_skill_guide and pass back the acknowledgment key it obtains there. While on, the ha_get_skill_guide tool is locked enabled — it is the only publisher of the acknowledgment key. Child of the \"Attach best-practice skills on writes\" option above and inert while that parent is off. Requires restart to take effect.",
     "features.enable_beta_features.label": "Enable beta features (master)",
-    "features.enable_beta_features.help": "⚠ DANGER — these tools can PERMANENTLY DAMAGE your Home Assistant installation. They write to your YAML config, your filesystem, install custom components, run arbitrary sandboxed Python, and edit tool docstrings the AI sees. There is no warranty and no support guarantee — you enable them at your OWN RISK. Take a Home Assistant backup before turning this on, and never enable in production without one. Master gate for the 5 experimental sub-flags below; sub-flags are ignored at runtime while this master is off, even when explicitly set to true. The same toggle is also surfaced in the web settings UI under \"Beta features (dangerous)\" — either surface reflects the other on restart.",
+    "features.enable_beta_features.help": "⚠ DANGER — these tools can PERMANENTLY DAMAGE your Home Assistant installation. They write to your YAML config, your filesystem, install custom components, run arbitrary sandboxed Python, and edit tool docstrings the AI sees. There is no warranty and no support guarantee — you enable them at your OWN RISK. Take a Home Assistant backup before turning this on, and never enable in production without one. Master gate for the experimental sub-flags below; sub-flags are ignored at runtime while this master is off, even when explicitly set to true. The same toggle is also surfaced in the web settings UI under \"Beta features (dangerous)\" — either surface reflects the other on restart.",
     "features.enable_yaml_config_editing.label": "Enable YAML config editing (beta)",
     "features.enable_yaml_config_editing.help": "Beta feature. Allows AI assistants to add, replace, or remove top-level keys in configuration.yaml and packages/*.yaml. Only whitelisted keys are allowed (e.g., template, sensor, command_line, mqtt, knx); core keys like homeassistant, http, and recorder are blocked. Each edit validates YAML syntax, runs a config check, and creates an automatic backup. Changes to most keys require a full HA restart to take effect. See docs/beta.md for known limitations. Dedicated tools (automations, scripts, scenes, helpers, template sensors) should be preferred when available. REQUIRES the master \"Enable beta features\" toggle above (and in the web UI) to be on — otherwise this sub-flag is ignored at runtime regardless of its value here.",
     "features.enable_yaml_edit_confirm.label": "Require confirmation for YAML edits (diff preview)",
@@ -441,7 +441,7 @@
     "addon.enable_security_policy_tool.name": "Let AI agents edit tool security policies",
     "addon.enable_security_policy_tool.description": "Registers the ha_manage_security_policy tool, which lets connected AI agents read and rewrite the tool security policies — including removing approval gates. Off by default. Independent of the Tool Security Policies option above: this controls who can edit the rules, not whether they are enforced. The tool cannot see or decide pending approvals. To keep a human in the loop, gate the tool before enabling it: switch on \"security gated\" for Manage Security Policy in the Tools tab of the web UI. Requires restart to take effect.",
     "addon.enable_auto_backup.name": "Enable auto-backup of edits",
-    "addon.enable_auto_backup.description": "Captures a per-entity snapshot before every wrapped write/destructive MCP tool call (automation, script, scene, helper, dashboard, label, category, group, zone, area, calendar, todo, entity, integration, and sibling remove/delete tools). Snapshots are saved as YAML files under /data/ha_mcp_backups/ (override via HAMCP_BACKUP_DIR) and listed, restored, or deleted via the Backups tab in the web settings UI or via ha_manage_backup(scope='edits', ...). Best-effort — failures log a WARNING but never block the underlying write. On by default; uncheck to opt out. Requires restart to take effect.",
+    "addon.enable_auto_backup.description": "Captures a per-entity snapshot before every wrapped write/destructive MCP tool call (automation, script, scene, helper, dashboard, dashboard resource, label, category, group, zone, area, calendar, todo, entity, device, integration, and sibling remove/delete tools). The auto-backup throttle bounds how often that happens: 0 (default) captures on every such call, N>0 at most one snapshot per N minutes per entity. Snapshots are saved as YAML files under /data/ha_mcp_backups/ (override via HAMCP_BACKUP_DIR) and listed, restored, or deleted via the Backups tab in the web settings UI or via ha_manage_backup(scope='edits', ...). For those domains the capture is best-effort — a failure logs a WARNING and the write proceeds. The file and raw-YAML tools are the exception: ha_write_file, ha_delete_file and ha_config_set_yaml treat the snapshot as a precondition, so a write through them is refused while this is off, and a failed capture blocks it. On by default; unchecking opts out of the best-effort captures and takes the file and raw-YAML tools out of service with them. Requires restart to take effect.",
     "addon.auto_backup_throttle_minutes.name": "Auto-backup throttle (minutes)",
     "addon.auto_backup_throttle_minutes.description": "Per-entity throttle window. 0 (default) captures a snapshot on every wrapped write. N>0 captures at most one snapshot per N minutes per entity. Range 0–1440.",
     "addon.auto_backup_retain_per_entity.name": "Auto-backup retention (per entity)",

ha_mcp_dev-8.2.0.dev2323/src/ha_mcp/settings_ui/locales/eo.json

@@ -0,0 +1,26 @@
+{
+  "meta": {
+    "native_name": "Esperanto",
+    "dir": "ltr"
+  },
+  "messages": {
+    "accessibility.storage_blocked": "Via retumilo blokas la konservadon de retejaj datumoj; viaj elektoj validas nur por ĉi tiu seanco.",
+    "actions.approve": "Aprobi",
+    "actions.deny": "Rifuzi",
+    "notice.restart.standalone": "⚠ Ŝanĝoj konservitaj. Restartigu la procezon ha-mcp, poste aktualigu la liston de MCP-iloj en via AI-kliento.",
+    "policies.operators.exists": "ekzistas",
+    "policies.operators.exists_long": "ekzistas (iu ajn valoro)",
+    "policies.operators.eq": "egalas",
+    "policies.operators.neq": "NE egalas",
+    "policies.operators.in": "estas unu el",
+    "policies.operators.not_in": "NE estas unu el",
+    "policies.operators.contains": "enhavas",
+    "policies.operators.regex": "kongruas kun regula esprimo",
+    "policies.operators.gt": "estas pli granda ol",
+    "policies.operators.lt": "estas pli malgranda ol",
+    "policies.pending.already_decided": "Ĉi tiu aprobo jam estis {decision}, eble de alia langeto aŭ seanco.",
+    "policies.pending.decision.approved": "aprobita",
+    "policies.pending.decision.denied": "rifuzita",
+    "visibility.errors.conflict": "La agordo estis ŝanĝita en alia langeto aŭ seanco. Reŝargu la paĝon, poste reapliku viajn ŝanĝojn."
+  }
+}

{ha_mcp_dev-8.2.0.dev2320 → ha_mcp_dev-8.2.0.dev2323}/src/ha_mcp/settings_ui/settings.js

@@ -1936,7 +1936,7 @@ const FEATURE_META = {
   },
   enable_beta_features: {
     label: "Enable beta features (master)",
-    help: "⚠ DANGER — these tools can PERMANENTLY DAMAGE your Home Assistant installation. They write to your YAML config, your filesystem, install custom components, run arbitrary sandboxed Python, and edit tool docstrings the AI sees. There is no warranty and no support guarantee — you enable them at your OWN RISK. Take a Home Assistant backup before turning this on, and never enable in production without one. Master gate for the 5 experimental sub-flags below; sub-flags are ignored at runtime while this master is off, even when explicitly set to true. The same toggle is also surfaced in the web settings UI under \"Beta features (dangerous)\" — either surface reflects the other on restart.",
+    help: "⚠ DANGER — these tools can PERMANENTLY DAMAGE your Home Assistant installation. They write to your YAML config, your filesystem, install custom components, run arbitrary sandboxed Python, and edit tool docstrings the AI sees. There is no warranty and no support guarantee — you enable them at your OWN RISK. Take a Home Assistant backup before turning this on, and never enable in production without one. Master gate for the experimental sub-flags below; sub-flags are ignored at runtime while this master is off, even when explicitly set to true. The same toggle is also surfaced in the web settings UI under \"Beta features (dangerous)\" — either surface reflects the other on restart.",
   },
   enable_yaml_config_editing: {
     label: "Enable YAML config editing (beta)",

ha_mcp_dev-8.2.0.dev2323/src/ha_mcp/tools/error_log_parsing.py

@@ -0,0 +1,365 @@
+"""Structured summarisation of Home Assistant's raw error log.
+
+``ha_get_logs(source='error_log')`` returns raw text by default. A busy
+instance produces a 50-200 KB log in which the same handful of errors repeat
+thousands of times, so the raw form can exhaust an agent's context while
+conveying very little. This module collapses it into counted, deduplicated,
+component-grouped issues.
+
+Split out of ``tools_utility`` under AGENTS.md § Module Size: the parsing is
+self-contained and shares nothing with the tool plumbing but its input string.
+"""
+
+import re
+from typing import Any, NamedTuple
+
+# Full HA log line, e.g.
+# "2026-05-27 10:15:23.456 ERROR (MainThread) [homeassistant.components.zha] msg"
+# Distinct from `_LOG_LEVEL_RE` in `tools_utility`, which only sniffs the level
+# out of a line for the raw path's filter.
+# The thread field is matched lazily instead of as `\([^)]*\)`: since Python 3.10
+# an unnamed thread is called "Thread-1 (target_fn)", so the field itself can
+# contain parentheses, and a class that cannot cross them drops every line those
+# threads log.
+_HA_LOG_LINE_RE = re.compile(
+    r"^(\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}(?:\.\d+)?)"
+    r"\s+(DEBUG|INFO|WARNING|ERROR|CRITICAL)"
+    r"\s+\(.*?\)"
+    r"\s+\[([^\]]+)\]"
+    r"\s+(.+)$",
+    re.IGNORECASE,
+)
+_MAX_MESSAGE_LEN = 200
+_COMPONENT_PREFIX_DEPTH = 3
+_CUSTOM_COMPONENT_PREFIX_DEPTH = 2
+_DEFAULT_TOP_N = 20
+_MAX_COMPONENTS = 50
+# Marks a message the 200-char cap cut short, so a truncated entry is never
+# mistaken for the whole message.
+_TRUNCATION_MARK = "…[truncated]"
+# Tie-breaker for issues with equal counts: a same-count CRITICAL outranks an
+# INFO. Ordering only — not a filter, and not tied to VALID_LOG_LEVELS.
+_LEVEL_SEVERITY = {"CRITICAL": 4, "ERROR": 3, "WARNING": 2, "INFO": 1, "DEBUG": 0}
+# Shared by both response paths, because an empty fetch reads as an all-clear on
+# either one: an agent that receives no log content and no warning reports "no
+# errors" to the user. Only the remedy differs, so each path appends its own.
+_EMPTY_FETCH_WARNING = (
+    "A running Home Assistant always logs something, so this is an empty or "
+    "failed fetch, NOT evidence that the log is clean."
+)
+
+# Supervisor-backed installs (add-on, HAOS, supervised) read HA Core's journald
+# stream, where every line is wrapped in ANSI colour codes:
+#   "\x1b[31m2026-08-02 08:12:27.290 ERROR (MainThread) [x] msg\x1b[0m"
+# Only container/pip installs read the plain home-assistant.log file.
+# Two independent reasons to strip, not one chain:
+#   * the leading code alone is already fatal — _HA_LOG_LINE_RE is ^-anchored
+#     and str.strip() does not remove ESC, so the line matches nothing and no
+#     `message` is produced at all;
+#   * the trailing reset is what a leading-only strip would leave behind: it
+#     lands inside `message` and splits the dedup key for one recurring error.
+# Strip both ends, always.
+_ANSI_RE = re.compile(r"\x1b\[[0-9;]*[A-Za-z]")
+
+
+def _strip_ansi(text: str) -> str:
+    """Remove ANSI escape sequences (journald colour codes) from a log line."""
+    return _ANSI_RE.sub("", text)
+
+
+def _normalize_timestamp(timestamp: str) -> str:
+    """Put a matched timestamp on one date/time separator.
+
+    Every timestamp comparison downstream is lexicographic — the covered
+    window, an issue's ``first_seen``/``last_seen`` bounds, and the recency
+    tiebreaker. ``_HA_LOG_LINE_RE`` accepts both the space and the ``T`` form
+    (case-insensitively), and ``" "`` sorts below every digit while ``"T"``
+    sorts above them, so a stream mixing the two forms would corrupt all three
+    at once. HA core emits the space form, so normalize onto that: real logs
+    come out byte-identical and only the ISO-8601 variant is rewritten.
+
+    The date is fixed-width in the pattern (``\\d{4}-\\d{2}-\\d{2}``), so the
+    separator is always at index 10 — replacing by position also covers the
+    lowercase ``t`` that ``re.IGNORECASE`` admits.
+    """
+    return timestamp[:10] + " " + timestamp[11:]
+
+
+def _get_component_prefix(logger_name: str) -> str:
+    """Extract the component prefix (first N dotted segments) of a logger name.
+
+    A custom integration's identity is ``custom_components.<domain>`` — one
+    segment shallower than a core component — so its modules roll up into one
+    bucket instead of one per module.
+    """
+    parts = logger_name.split(".")
+    depth = (
+        _CUSTOM_COMPONENT_PREFIX_DEPTH
+        if parts[0] == "custom_components"
+        else _COMPONENT_PREFIX_DEPTH
+    )
+    if len(parts) >= depth:
+        return ".".join(parts[:depth])
+    return logger_name
+
+
+def _truncate_message(message: str) -> str:
+    """Cap a message for display, marking it when it was cut."""
+    if len(message) <= _MAX_MESSAGE_LEN:
+        return message
+    return message[:_MAX_MESSAGE_LEN] + _TRUNCATION_MARK
+
+
+class _ExtractedLines(NamedTuple):
+    """Tallies from one pass over the raw log; every input line lands in one.
+
+    ``matched`` counts lines that are valid HA log lines *before* ``level`` and
+    ``search`` run; ``entries`` holds the subset that survived them. The two are
+    kept apart because they answer different questions: only ``matched == 0``
+    means the parser could not read the log, while ``matched > 0`` with no
+    entries just means the filters excluded everything.
+
+    ``total input lines == blank + unparseable + matched`` holds by construction.
+    """
+
+    entries: list[dict[str, str]]
+    matched: int
+    unparseable: int
+    blank: int
+    window_start: str | None
+    window_end: str | None
+
+
+def _extract_log_entries(
+    lines: list[str],
+    search: str | None = None,
+    level: str | None = None,
+) -> _ExtractedLines:
+    """Parse raw log lines into entries plus the per-line tallies around them.
+
+    Split out from ``_parse_error_log_structured`` to keep both under the repo's
+    complexity ceiling. A line counts as unparseable only when it does not match
+    the HA log format at all — lines dropped by ``level``/``search`` are simply
+    absent from ``entries``, never counted as unparseable.
+    """
+    entries: list[dict[str, str]] = []
+    matched = 0
+    unparseable = 0
+    blank = 0
+    window_start: str | None = None
+    window_end: str | None = None
+    needle = search.lower() if search else None
+
+    for line in lines:
+        # Strip ANSI *before* matching: on Supervisor-backed installs the line
+        # arrives colour-wrapped. Both ends matter for separate reasons — the
+        # leading code alone already defeats the ^-anchor so the line matches
+        # nothing, and a leading-only strip would leave the trailing reset
+        # inside `message`, splitting the dedup key for one recurring error.
+        clean = _strip_ansi(line).strip()
+        if not clean:
+            blank += 1
+            continue
+        match = _HA_LOG_LINE_RE.match(clean)
+        if not match:
+            unparseable += 1
+            continue
+        matched += 1
+        timestamp, log_level, logger_name, message = match.groups()
+        timestamp = _normalize_timestamp(timestamp)
+        # Widen the covered window on every parseable line, filtered or not:
+        # it describes the log slice that was read, not the summary's contents.
+        if window_start is None or timestamp < window_start:
+            window_start = timestamp
+        if window_end is None or timestamp > window_end:
+            window_end = timestamp
+        log_level = log_level.upper()
+        if level and log_level != level:
+            continue
+        if (
+            needle
+            and needle not in message.lower()
+            and needle not in logger_name.lower()
+        ):
+            continue
+        entries.append(
+            {
+                "timestamp": timestamp,
+                "level": log_level,
+                "logger": logger_name,
+                # Kept whole: the display cap is applied at dedup time, because
+                # keying on a capped message merges two errors that differ only
+                # past the cap into one issue with a summed count.
+                "message": message,
+            }
+        )
+
+    return _ExtractedLines(
+        entries=entries,
+        matched=matched,
+        unparseable=unparseable,
+        blank=blank,
+        window_start=window_start,
+        window_end=window_end,
+    )
+
+
+def _parse_error_log_structured(
+    raw_text: str,
+    search: str | None = None,
+    level: str | None = None,
+    top_n: int = _DEFAULT_TOP_N,
+) -> dict[str, Any]:
+    """Parse the raw error log into a deduplicated, component-grouped summary.
+
+    ``source='error_log'`` normally returns raw text. A busy instance produces a
+    50-200 KB log in which the same handful of errors repeat thousands of times,
+    so the raw form can exhaust an agent's context while conveying very little.
+    This collapses identical (level, logger, message) triples into counted
+    issues, groups them by component, and returns only the ``top_n`` noisiest.
+
+    Every input line is accounted for exactly once, because "not in the summary"
+    has several causes that must not be conflated:
+
+    * ``total_raw_lines``   - lines in the input, and the sum of the next three
+    * ``blank_lines``       - empty after ANSI stripping
+    * ``unparseable_lines`` - not the HA log format at all (traceback bodies,
+      continuation lines, format drift)
+    * ``matched_lines``     - valid log lines, before ``level``/``search``
+    * ``parsed_entries``    - the subset of ``matched_lines`` the filters kept
+
+    Only ``matched_lines == 0`` says the parser could not read the log; a small
+    ``parsed_entries`` under a narrow filter is the feature working, not data
+    loss. Counts are bounded by the fetched window (``window_start`` ..
+    ``window_end``): Supervisor-backed installs read a capped journald slice, so
+    there the window can be far shorter than the log's full history.
+    """
+    lines = raw_text.splitlines() if raw_text else []
+    total_raw_lines = len(lines)
+    extracted = _extract_log_entries(lines, search=search, level=level)
+    parsed = extracted.entries
+
+    # Dedupe on (level, logger, message), keyed on the FULL message: two errors
+    # that differ only past the display cap are distinct issues, and a capped
+    # key merges them into one with a summed count. Level belongs in the key
+    # too: the same text is logged at different levels, and a level-less key
+    # would report a later ERROR under the level of the first line to carry it.
+    dedup: dict[tuple[str, str, str], dict[str, Any]] = {}
+    for entry in parsed:
+        key = (entry["level"], entry["logger"], entry["message"])
+        record = dedup.get(key)
+        if record is None:
+            record = {
+                "logger": entry["logger"],
+                "level": entry["level"],
+                "message": _truncate_message(entry["message"]),
+                "count": 0,
+                "first_seen": entry["timestamp"],
+                "last_seen": entry["timestamp"],
+            }
+            dedup[key] = record
+        record["count"] += 1
+        # Bounds, not last-write-wins: a log whose lines are not perfectly
+        # ordered would otherwise drag last_seen backwards, which also
+        # misplaces the issue in the recency tiebreaker below.
+        record["first_seen"] = min(record["first_seen"], entry["timestamp"])
+        record["last_seen"] = max(record["last_seen"], entry["timestamp"])
+
+    # Count first, then severity, then recency. Python's sort is stable, so
+    # count alone would return the *oldest* of a tied run — and on a log whose
+    # messages embed volatile ids every issue ties at count 1, which quietly
+    # turns "top 20 issues" into "the 20 oldest".
+    all_issues = sorted(
+        dedup.values(),
+        key=lambda i: (
+            i["count"],
+            _LEVEL_SEVERITY.get(i["level"], 0),
+            i["last_seen"],
+        ),
+        reverse=True,
+    )
+
+    by_component: dict[str, dict[str, Any]] = {}
+    for issue in all_issues:
+        prefix = _get_component_prefix(issue["logger"])
+        bucket = by_component.setdefault(
+            prefix, {"total_occurrences": 0, "issue_count": 0}
+        )
+        bucket["total_occurrences"] += issue["count"]
+        bucket["issue_count"] += 1
+
+    top_issues = [
+        {
+            "component": _get_component_prefix(issue["logger"]),
+            "logger": issue["logger"],
+            "level": issue["level"],
+            "message": issue["message"],
+            "count": issue["count"],
+            "first_seen": issue["first_seen"],
+            "last_seen": issue["last_seen"],
+        }
+        for issue in all_issues[:top_n]
+    ]
+
+    # Cap by_component too: a log with thousands of distinct loggers would
+    # otherwise make the response unbounded, contradicting the whole premise.
+    ranked_components = sorted(
+        by_component.items(),
+        key=lambda kv: kv[1]["total_occurrences"],
+        reverse=True,
+    )
+    component_table = dict(ranked_components[:_MAX_COMPONENTS])
+
+    summary: dict[str, Any] = {
+        "total_raw_lines": total_raw_lines,
+        "blank_lines": extracted.blank,
+        "unparseable_lines": extracted.unparseable,
+        "matched_lines": extracted.matched,
+        "parsed_entries": len(parsed),
+        "unique_issues": len(all_issues),
+        "components_affected": len(by_component),
+        "showing_top_n": min(top_n, len(all_issues)),
+        "showing_components": len(component_table),
+        # Counts describe this window only. On Supervisor-backed installs the
+        # fetch is a capped journald slice, so an issue's count here is not its
+        # count since it first occurred.
+        "window_start": extracted.window_start,
+        "window_end": extracted.window_end,
+    }
+
+    result: dict[str, Any] = {
+        "success": True,
+        "source": "error_log",
+        "structured": True,
+        "summary": summary,
+        "top_issues": top_issues,
+        "by_component": component_table,
+    }
+
+    # An empty summary has three causes and they need different answers, so the
+    # branch keys on `matched_lines` — the pre-filter count. Keying on the raw
+    # unparseable count instead reports format drift for an ordinary filtered
+    # result, because tracebacks alone push a healthy log past 90% unparseable.
+    # Degraded-operation notices go in the top-level `warnings` list — the one
+    # channel this repo's tools use — never a singular `warning` string.
+    if extracted.matched == 0:
+        if extracted.unparseable > 0:
+            result["warnings"] = [
+                f"No log lines could be parsed ({extracted.unparseable} of "
+                f"{total_raw_lines} did not match the expected Home Assistant log "
+                "format). This summary is NOT evidence that the log is clean - "
+                "re-run with structured=False to read the raw text."
+            ]
+        else:
+            result["warnings"] = [
+                f"No log entries arrived to parse ({total_raw_lines} lines "
+                f"fetched, none of them log entries). {_EMPTY_FETCH_WARNING} "
+                "Re-run with structured=False to see the raw response."
+            ]
+    elif not parsed:
+        result["warnings"] = [
+            f"None of the {extracted.matched} parsed log entries matched the "
+            "requested filters. The log itself parsed fine, so this reflects "
+            "the filters, not a parse failure."
+        ]
+    return result