ha-mcp-dev 9.0.0.dev3172__tar.gz → 9.0.0.dev3178__tar.gz

{ha_mcp_dev-9.0.0.dev3172 → ha_mcp_dev-9.0.0.dev3178}/PKG-INFO

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

{ha_mcp_dev-9.0.0.dev3172 → ha_mcp_dev-9.0.0.dev3178}/pyproject.toml

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

{ha_mcp_dev-9.0.0.dev3172 → ha_mcp_dev-9.0.0.dev3178}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "9.0.0.dev3172"
+version = "9.0.0.dev3178"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 # Upper bound widened to <3.15 so the package installs on Home Assistant's

ha_mcp_dev-9.0.0.dev3178/src/ha_mcp/client/error_log_journald.py

@@ -0,0 +1,241 @@
+"""Journald window paging for the raw error log (Supervisor-backed installs).
+
+Supervisor answers ``?lines=N`` with the N newest journald entries, and an
+``offset`` counts back from the newest one. That anchor moves whenever Home
+Assistant logs another line, so a caller paging on the number can re-read or
+skip entries between two calls. Supervisor also returns ``X-First-Cursor``,
+which identifies the first (oldest) entry of the block it served, and accepts
+``Range: entries=<cursor>:<skip>:<count>``; HA's own log viewer pages on that
+cursor for exactly this reason.
+
+This module turns that into an opaque token carrying both the cursor and the
+number of entries a page consumed from it: ``cursor:<X-First-Cursor>:<skip>``.
+A page requested with a token is fetched entirely behind that resume point, so
+lines logged in between cannot shift it and a page that returned only part of
+its fetched window still resumes exactly. ``journald_page`` never computes
+the skip itself -- only the tool layer knows which records a page returned --
+so the token is built there and this module only applies it.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+
+from .models import ErrorLogPage
+
+logger = logging.getLogger(__name__)
+
+CURSOR_TOKEN_PREFIX = "cursor:"
+
+
+@dataclass(frozen=True)
+class JournaldPage:
+    """One journald block plus the cursor of its oldest entry."""
+
+    text: str
+    first_cursor: str | None
+
+
+JournaldFetch = Callable[[str], Awaitable[JournaldPage]]
+
+
+def is_cursor_token(value: object) -> bool:
+    """True when ``value`` is a paging token produced by this module."""
+    return (
+        isinstance(value, str)
+        and value.startswith(CURSOR_TOKEN_PREFIX)
+        and bool(value[len(CURSOR_TOKEN_PREFIX) :])
+    )
+
+
+def cursor_token(cursor: str, skip: int) -> str:
+    """Build the opaque ``next_offset`` value resuming ``skip`` entries in.
+
+    ``skip`` is the offset of the resume point from ``cursor`` (the oldest entry
+    of the page's fetched window); the next block ends one entry before it.
+    After a page that returned records, entry ``skip`` is the oldest entry the
+    page returned, so the next block starts with the entries fetched behind it.
+    A held-back tail sets it one past the tail's last line. Zero resumes
+    strictly behind ``cursor``, which is what a page that used its whole window
+    needs.
+    """
+    if skip < 0:
+        raise ValueError(f"skip must not be negative, got {skip}")
+    return f"{CURSOR_TOKEN_PREFIX}{cursor}:{skip}"
+
+
+def parse_cursor_token(token: str) -> tuple[str, int]:
+    """Split ``token`` into its cursor and skip; raises ``ValueError`` if malformed.
+
+    The cursor itself never contains ``:`` (systemd cursors separate their
+    fields with ``;``), but the skip is still split off from the right so a
+    future cursor format cannot be mistaken for it.
+    """
+    if not token.startswith(CURSOR_TOKEN_PREFIX):
+        raise ValueError("not a cursor token")
+    cursor, separator, skip = token[len(CURSOR_TOKEN_PREFIX) :].rpartition(":")
+    if not separator or not cursor or not skip.isdigit():
+        raise ValueError(
+            "cursor token must read 'cursor:<cursor>:<entries>' as returned in "
+            "'next_offset'"
+        )
+    return cursor, int(skip)
+
+
+def token_cursor(token: str) -> str:
+    """The cursor carried by ``token``; raises ``ValueError`` when malformed."""
+    return parse_cursor_token(token)[0]
+
+
+def token_skip(token: str) -> int:
+    """The skip carried by ``token``; raises ``ValueError`` when malformed."""
+    return parse_cursor_token(token)[1]
+
+
+def range_header(lines: int, offset: int = 0) -> str:
+    """The ``Range`` expression for the ``offset``-th window back from newest."""
+    return f"entries=:{-(offset + lines - 1)}:{lines}"
+
+
+def cursor_range_header(cursor: str, skip: int, lines: int) -> str:
+    """The expression returning ``lines`` entries strictly behind ``cursor:skip``.
+
+    Gatewayd reads ``entries=<cursor>:<num_skip>:<num_entries>`` forward from
+    ``cursor + num_skip``, so ending the block just behind the resume point
+    (``cursor + skip``) means starting ``lines`` entries earlier. That makes a
+    cursor page the exact unfetched remainder: nothing the caller already saw
+    is repeated and nothing between pages is dropped.
+    """
+    return f"entries={cursor}:{skip - lines}:{lines}"
+
+
+def container_page(text: str, lines: int, offset: int) -> ErrorLogPage:
+    """Window the whole-file ``/api/error_log`` body client-side.
+
+    Paging is exact here: the whole file is in hand, so ``has_more`` is simply
+    whether anything precedes the window.
+    """
+    all_lines = text.splitlines()
+    end = len(all_lines) - offset
+    if end <= 0:
+        return ErrorLogPage(text="", has_more=False)
+    start = max(end - lines, 0)
+    return ErrorLogPage(
+        text="\n".join(all_lines[start:end]),
+        has_more=start > 0,
+        first_cursor=None,
+    )
+
+
+def first_cursor(response: object) -> str | None:
+    """Supervisor's ``X-First-Cursor`` from ``response``, when it carries one."""
+    headers = getattr(response, "headers", None)
+    if not headers:
+        return None
+    value = headers.get("X-First-Cursor")
+    return value or None
+
+
+async def journald_page(
+    lines: int,
+    offset: int | str,
+    fetch: JournaldFetch,
+) -> ErrorLogPage:
+    """One journald window, anchored on the newest entry or on a cursor token."""
+    if is_cursor_token(offset):
+        if not isinstance(offset, str):  # pragma: no cover - narrows the type
+            raise ValueError("cursor token must be a string")
+        cursor, skip = parse_cursor_token(offset)
+        return await _cursor_page(lines, cursor, skip, fetch)
+    if isinstance(offset, str):
+        raise ValueError("offset must be a non-negative integer or a cursor token")
+    return await _newest_page(lines, offset, fetch)
+
+
+async def _newest_page(lines: int, offset: int, fetch: JournaldFetch) -> ErrorLogPage:
+    page = await fetch(range_header(lines, offset))
+    text_lines = page.text.splitlines()
+    if len(text_lines) < lines:
+        # Nothing clamps a window smaller than asked for, so a short window is
+        # the end of the journal.
+        return ErrorLogPage(text=page.text, has_more=False)
+    has_more = await _has_older_than(page.first_cursor, fetch)
+    return ErrorLogPage(
+        text=page.text,
+        has_more=has_more,
+        first_cursor=page.first_cursor,
+    )
+
+
+async def _cursor_page(
+    lines: int, cursor: str, skip: int, fetch: JournaldFetch
+) -> ErrorLogPage:
+    page = await fetch(cursor_range_header(cursor, skip, lines))
+    entries = page.text.splitlines()
+    has_more = await _has_older_than(page.first_cursor, fetch)
+    if entries and not has_more and page.first_cursor:
+        # The block starts at the journal's head, so gatewayd clamped its start
+        # and kept reading forward: it may run past the resume point and repeat
+        # entries the previous page already returned. Keep only what precedes
+        # the resume point.
+        entries = entries[
+            : await _entries_before_resume(
+                cursor, skip, len(entries), page.first_cursor, fetch
+            )
+        ]
+    return ErrorLogPage(
+        text="\n".join(entries),
+        has_more=has_more,
+        first_cursor=page.first_cursor,
+    )
+
+
+async def _entries_before_resume(
+    cursor: str,
+    skip: int,
+    count: int,
+    head: str,
+    fetch: JournaldFetch,
+) -> int:
+    """How many entries of a head-clamped block precede the resume point.
+
+    Gatewayd anchors ``entries=<cursor>:<skip>:<count>`` at ``cursor + skip``
+    and reads ``count`` entries forward. A skip that runs past the journal's
+    start is clamped to the head rather than rejected, so the block it returns
+    can contain entries at or after the resume point. Those entries duplicate
+    the previous page and, without trimming, hide the oldest ones behind them.
+
+    The resume point is ``skip`` entries after ``cursor``. Asking for the single
+    entry ``k`` entries before it returns the head exactly when ``k`` reaches it
+    (at or past the head the start clamps there), which binary-searches its
+    position without needing per-entry cursors — Supervisor rejects a JSON
+    Accept, so cursors are the only per-entry identity it will not serve.
+    """
+    low, high = 0, count
+    while low < high:
+        middle = (low + high) // 2
+        probe = await fetch(f"entries={cursor}:{skip - middle}:1")
+        if probe.first_cursor == head:
+            high = middle
+        else:
+            low = middle + 1
+    return low
+
+
+async def _has_older_than(cursor: str | None, fetch: JournaldFetch) -> bool:
+    """True when an entry precedes ``cursor``.
+
+    Gatewayd clamps a skip that runs past the journal's start to its head
+    block instead of answering with an empty one, so the block's length says
+    nothing here. Its first cursor does: only a clamped probe starts on the
+    anchor entry itself. (The HA frontend uses the same signal to detect the
+    end of history.)
+    """
+    if not cursor:
+        return False
+    probe = await fetch(cursor_range_header(cursor, 0, 2))
+    if not probe.text.splitlines():
+        return False
+    return probe.first_cursor != cursor

{ha_mcp_dev-9.0.0.dev3172 → ha_mcp_dev-9.0.0.dev3178}/src/ha_mcp/client/models.py

@@ -10,9 +10,15 @@ class ErrorLogPage:
     """One bounded window of the error log, plus whether older history exists.
 
     ``has_more`` cannot be derived by the caller from ``text``: a journald
-    window that comes back full may or may not have anything behind it (see
-    ``_journald_error_log_page``), and only the fetching route knows which.
+    window that comes back full may or may not have anything behind it, and
+    only the fetching route knows which.
+
+    ``first_cursor`` is Supervisor's ``X-First-Cursor`` for the block -- the
+    oldest entry this window served -- and is ``None`` on installs that read a
+    whole log file. The tool layer turns it into the ``next_offset`` token, so
+    the cursor travels as data instead of being re-derived from the text.
     """
 
     text: str
     has_more: bool
+    first_cursor: str | None = None

{ha_mcp_dev-9.0.0.dev3172 → ha_mcp_dev-9.0.0.dev3178}/src/ha_mcp/client/rest_client.py

@@ -8,7 +8,6 @@ import logging
 import os
 import ssl
 import time
-from collections.abc import Awaitable, Callable
 from dataclasses import dataclass
 from typing import Any, NoReturn
 
@@ -18,6 +17,13 @@ from .._vendor.websockets.exceptions import WebSocketException
 from .._version import get_supervisor_base_url, is_running_in_addon
 from ..config import get_global_settings
 from .admin_routes import is_admin_only_route
+from .error_log_journald import (
+    JournaldPage,
+    container_page,
+    first_cursor,
+    journald_page,
+    range_header,
+)
 from .models import ErrorLogPage
 from .supervisor_client import make_supervisor_httpx_client
 
@@ -62,16 +68,6 @@ _MAX_REQUEST_ATTEMPTS = 3
 # client mirrors that on every route, so all install types serve the same slice.
 # Shared with the tool layer, which sizes its fetch window against it.
 MIN_LOG_WINDOW_LINES = 2
-# Entries the has_more probe reads from just behind a full window. A one-entry
-# probe compared one rendered line, which a boundary duplicate (the same
-# timestamp-less traceback line logged twice) could false-match into "end of
-# history". Comparing a block this deep requires that many CONSECUTIVE
-# identical lines to straddle the boundary — and then the history a false stop
-# skips is more of the same duplicates. Timestamps cannot close the gap
-# instead: the colliding lines are exactly the ones without them, and
-# journald's cursor/timestamp metadata exists only in the journal export
-# format, which the hassio-proxy route cannot request.
-_PROBE_ENTRIES = 8
 NON_ADMIN_TOKEN_WARNING = (
     "ha-mcp does not officially support non-admin Home Assistant tokens. They "
     "still work, but admin-only operations fail. Use a long-lived access token "
@@ -898,126 +894,26 @@ class HomeAssistantClient:
         logger.debug("Checking configuration")
         return await self._request("POST", "/config/core/check_config")
 
-    @staticmethod
-    def _journald_range_header(lines: int, offset: int = 0) -> str:
-        """Build Supervisor's journald ``Range`` header for a bounded window.
-
-        Supervisor's log endpoints accept
-        ``Range: entries=<cursor>:<num_skip>:<num_entries>`` and build
-        ``entries=:-{N-1}:{N}`` themselves for a ``?lines=N`` request
-        (supervisor/api/host.py). ``offset`` moves the window that many entries
-        further back, so the returned slice ends ``offset`` entries before the
-        newest one.
-
-        A ``lines=1`` window is only expressible with a non-zero ``offset``: at
-        ``offset=0`` the header degenerates to ``entries=:0:1``, whose
-        non-negative skip reads from the OLDEST entry instead of the newest.
-        Callers anchoring at the newest entry pass ``lines`` already floored at
-        ``MIN_LOG_WINDOW_LINES``; the one-entry probe always carries an offset.
-        """
-        # Negate the computed skip rather than prefixing "-" so the degenerate
-        # skip of 0 renders as ":0:" (non-negative, reads from the oldest
-        # entry) instead of the ill-formed ":-0:".
-        return f"entries=:{-(offset + lines - 1)}:{lines}"
+    async def _supervisor_core_logs(self, range_header: str) -> JournaldPage:
+        """Fetch one journald window straight from Supervisor, with its cursor."""
+        response = await self._supervisor_logs_response(
+            "core",
+            headers={"Accept": "text/plain", "Range": range_header},
+            params={"no_colors": "true"},
+        )
+        return JournaldPage(response.text, first_cursor(response))
 
-    @staticmethod
-    def _container_error_log_page(text: str, lines: int, offset: int) -> ErrorLogPage:
-        """Window the whole-file ``/api/error_log`` body client-side.
-
-        Same tail semantics as the journald Range the Supervisor-backed
-        branches request, so ``get_error_log`` answers with the same slice of
-        history on every install type. Paging is exact here — the whole file is
-        in hand, so ``has_more`` is simply whether anything precedes the window.
-        An ``offset`` past the start of the file yields an empty final page.
-        """
-        all_lines = text.splitlines()
-        end = len(all_lines) - offset
-        if end <= 0:
-            return ErrorLogPage(text="", has_more=False)
-        start = max(end - lines, 0)
-        return ErrorLogPage(text="\n".join(all_lines[start:end]), has_more=start > 0)
-
-    async def _supervisor_core_logs(self, lines: int, offset: int) -> str:
-        """Fetch a journald window of HA Core's log straight from Supervisor."""
-        return await self._supervisor_logs_get("core", lines=lines, offset=offset)
-
-    async def _proxied_core_logs(self, lines: int, offset: int) -> str:
-        """Fetch the same window through HA Core's hassio proxy with the LLA."""
+    async def _proxied_core_logs(self, range_header: str) -> JournaldPage:
+        """The same window through HA Core's hassio proxy."""
         response = await self._raw_request(
             "GET",
             "/hassio/core/logs",
-            headers={
-                "Accept": "text/plain",
-                "Range": self._journald_range_header(lines, offset),
-            },
+            headers={"Accept": "text/plain", "Range": range_header},
             params={"no_colors": "true"},
         )
-        return response.text
-
-    async def _journald_error_log_page(
-        self,
-        lines: int,
-        offset: int,
-        fetch: Callable[[int, int], Awaitable[str]],
-    ) -> ErrorLogPage:
-        """Read one journald window and settle ``has_more`` with a 1-entry probe.
-
-        systemd's journal-gatewayd does not guard the negative-skip branch the
-        way it guards the positive one (``sd_journal_previous_skip(-n_skip + 1)``
-        returns no END_OF_STREAM): an offset past the start of the journal
-        CLAMPS to the oldest entry and still answers with a full window. So a
-        saturated window proves nothing about what lies behind it, and a
-        count-based ``has_more`` would stay true forever — an agent following
-        the pagination hint would loop on identical pages.
-
-        Hence: a short or empty window means the journal really is exhausted
-        (nothing clamps a window smaller), and a saturated one is settled by
-        asking for the ``_PROBE_ENTRIES`` entries that should sit just behind
-        it. If the journal has nothing there, the clamp starts the probe at
-        the same oldest entry the window starts with, so the probe block
-        equals the window's opening lines — identity means end of history. A
-        differing block proves deeper history (an under-full span behind the
-        window also clamps and misaligns, which correctly reads as "more").
-        The identity check also terminates the degraded case where an
-        intermediary strips the ``Range`` header (RFC 7233 permits it): both
-        requests then return Supervisor's default window and compare equal.
-
-        The saturation test counts lines only to decide whether to probe, never
-        to answer: one journald entry can be a multi-line traceback, so the line
-        count over-estimates entries and can only over-trigger the probe, which
-        then gives the real answer. In practice the two rarely diverge here:
-        docker's journald log driver — how HAOS captures Core's output —
-        ingests stdout line by line, one journal entry per rendered line, so
-        multi-line entries reach this endpoint only from native journal-API
-        writers.
-
-        Known imprecision, accepted: the identity check can still stop one
-        page early when the compared block — ``_PROBE_ENTRIES`` lines, or the
-        window's own length when that is smaller — is byte-identical across
-        the boundary (see the constant's comment for why timestamps cannot
-        disambiguate instead). The failure
-        direction is a missed page of exactly those duplicates — bounded,
-        unlike the infinite loop a count-based ``has_more`` produces on the
-        clamp.
-        """
-        text = await fetch(lines, offset)
-        if not text or len(text.splitlines()) < lines:
-            return ErrorLogPage(text=text, has_more=False)
-        probe = await fetch(_PROBE_ENTRIES, offset + lines)
-        probe_lines = probe.splitlines()
-        window_lines = text.splitlines()
-        # Compare the shared-length prefix: with a window smaller than the
-        # probe (lines < _PROBE_ENTRIES), an end-of-history clamp returns a
-        # probe LONGER than the window, and a full-length compare would read
-        # that as "more history" forever — the small-limit loop this method
-        # exists to prevent.
-        shared = min(len(probe_lines), len(window_lines))
-        return ErrorLogPage(
-            text=text,
-            has_more=shared > 0 and probe_lines[:shared] != window_lines[:shared],
-        )
+        return JournaldPage(response.text, first_cursor(response))
 
-    async def get_error_log(self, lines: int, offset: int = 0) -> ErrorLogPage:
+    async def get_error_log(self, lines: int, offset: int | str = 0) -> ErrorLogPage:
         """Get a bounded window of the Home Assistant error log.
 
         ``lines`` is the number of log lines to fetch and ``offset`` how many
@@ -1054,15 +950,14 @@ class HomeAssistantClient:
           keep the historical ``/api/error_log`` proxy path.
 
         The two Supervisor-backed branches express the window as a journald
-        ``Range`` header (see ``_journald_range_header``) and settle
-        ``has_more`` with a one-entry probe (see ``_journald_error_log_page``).
-        HA Core's hassio proxy forwards that header for its log paths
-        (``PATHS_LOGS`` in ``homeassistant/components/hassio/http.py``); an
-        intermediary that stripped it would degrade to Supervisor's 100-line
-        default, never to an unbounded fetch, and the probe still terminates
-        paging. ``/api/error_log`` is a whole-file plain-text endpoint with no
-        window support, so the container branch reads the file and applies the
-        same window client-side, where paging is exact.
+        ``Range`` header, either anchored on the newest entry (integer
+        ``offset``) or on an opaque cursor token from an earlier page; see
+        :mod:`ha_mcp.client.error_log_journald`. Working from Supervisor's
+        ``X-First-Cursor`` keeps a page stable while Home Assistant logs more
+        lines between two calls. ``/api/error_log`` is a whole-file plain-text
+        endpoint with no window support, so the container branch reads the file
+        and applies the same window client-side, where paging is exact and
+        integer offsets stay the contract.
 
         The middle branch was discovered by the HAOS E2E tier (#1326): the
         test harness runs ha-mcp externally against a booted HAOS, hits
@@ -1085,7 +980,7 @@ class HomeAssistantClient:
                     logger.debug(
                         "Fetching error log via Supervisor direct (core service)"
                     )
-                    return await self._journald_error_log_page(
+                    return await journald_page(
                         window, offset, self._supervisor_core_logs
                     )
 
@@ -1094,15 +989,18 @@ class HomeAssistantClient:
                         "Fetching error log via HA Core /hassio/core/logs proxy "
                         "(supervised)"
                     )
-                    return await self._journald_error_log_page(
-                        window, offset, self._proxied_core_logs
-                    )
+                    return await journald_page(window, offset, self._proxied_core_logs)
 
+                if isinstance(offset, str):
+                    raise HomeAssistantAPIError(
+                        "Cursor-token paging needs a Supervisor-backed install; "
+                        "the container /api/error_log endpoint has no cursor"
+                    )
                 logger.debug("Fetching error log via HA Core proxy (Container/pip)")
                 raw_response = await self._raw_request(
                     "GET", "/error_log", headers={"Accept": "text/plain"}
                 )
-                return self._container_error_log_page(raw_response.text, window, offset)
+                return container_page(raw_response.text, window, offset)
         except TimeoutError as e:
             raise HomeAssistantConnectionError(
                 f"Timeout fetching the error log after {self.timeout}s: "
@@ -1309,18 +1207,6 @@ class HomeAssistantClient:
             HomeAssistantConnectionError: Timeout or transport error, with
                 distinct messages so callers can tell them apart.
         """
-        token = os.environ.get("SUPERVISOR_TOKEN", "")
-        if not token:
-            # The is_running_in_addon() gate already keys off SUPERVISOR_TOKEN
-            # being truthy, so a direct caller landing here without one is a
-            # detection/config mismatch — fail-fast with a distinct message
-            # so operators don't read it as "token rejected".
-            raise HomeAssistantAuthError(
-                f"Supervisor token absent at call time for /{path}/logs "
-                "(addon-mode gate fired but SUPERVISOR_TOKEN env var not set)"
-            )
-
-        relative_path = f"/{path}/logs"
         headers = {"Accept": "text/plain"}
         # Presence-triggered flag: journald output carries ANSI escapes otherwise.
         params: dict[str, Any] = {"no_colors": "true"}
@@ -1330,14 +1216,36 @@ class HomeAssistantClient:
             # An offset window with no size asked for falls back to the
             # smallest one the Range syntax can express.
             size = lines if lines is not None else MIN_LOG_WINDOW_LINES
-            headers["Range"] = self._journald_range_header(size, offset)
+            headers["Range"] = range_header(size, offset)
             params.pop("lines", None)
         logger.debug(
-            "Fetching %s%s via Supervisor direct (%s)",
+            "Fetching %s/%s/logs via Supervisor direct (%s)",
             get_supervisor_base_url(),
-            relative_path,
+            path,
             f"range={headers['Range']}" if offset is not None else f"lines={lines}",
         )
+        response = await self._supervisor_logs_response(path, headers, params)
+        return response.text
+
+    async def _supervisor_logs_response(
+        self, path: str, headers: dict[str, str], params: dict[str, Any]
+    ) -> httpx.Response:
+        """Send one Supervisor ``/logs`` request and map its failures.
+
+        Split from ``_supervisor_logs_get`` so the error-log route can read
+        Supervisor's ``X-First-Cursor`` while plain-text callers keep the body.
+        """
+        token = os.environ.get("SUPERVISOR_TOKEN", "")
+        if not token:
+            # The is_running_in_addon() gate already keys off SUPERVISOR_TOKEN
+            # being truthy, so a direct caller landing here without one is a
+            # detection/config mismatch — fail-fast with a distinct message
+            # so operators don't read it as "token rejected".
+            raise HomeAssistantAuthError(
+                f"Supervisor token absent at call time for /{path}/logs "
+                "(addon-mode gate fired but SUPERVISOR_TOKEN env var not set)"
+            )
+        relative_path = f"/{path}/logs"
 
         try:
             async with asyncio.timeout(self.timeout):
@@ -1393,7 +1301,7 @@ class HomeAssistantClient:
                 status_code=response.status_code,
                 response_data={"message": text_body, "path": path},
             )
-        return response.text
+        return response
 
     async def _get_addon_logs_via_supervisor(
         self, slug: str, lines: int | None = None

{ha_mcp_dev-9.0.0.dev3172 → ha_mcp_dev-9.0.0.dev3178}/src/ha_mcp/config.py

@@ -167,6 +167,16 @@ def set_embedded_connection(
         _apply_embedded_connection(_settings)
 
 
+def is_embedded_mode() -> bool:
+    """True when ha-mcp runs in-process inside Home Assistant.
+
+    Set by the custom component's in-process server entry via
+    ``set_embedded_connection``; false for the CLI, the HTTP launchers and the
+    app (add-on) build.
+    """
+    return bool(_EMBEDDED_CONNECTION)
+
+
 def get_embedded_config_dir() -> str | None:
     """Home Assistant's configuration directory, when running embedded.
 

{ha_mcp_dev-9.0.0.dev3172 → ha_mcp_dev-9.0.0.dev3178}/src/ha_mcp/log_filters.py

@@ -159,6 +159,36 @@ def _add_filter_once(logger_name: str, filter_cls: type[logging.Filter]) -> None
     logger.addFilter(filter_cls())
 
 
+def route_fastmcp_logs_to_root() -> None:
+    """Hand FastMCP's own log records to the embedding application.
+
+    The vendored FastMCP configures the ``fastmcp`` logger at import time with
+    ``propagate = False`` and a RichHandler of its own. In the in-process
+    embedded server that means its records bypass Home Assistant's logging:
+    they reach Core's stream without HA's header, never reach ``system_log``,
+    and error-log record grouping reads them as continuation lines of whatever
+    record preceded them. Clearing the handlers and letting the logger
+    propagate gives HA's handler the record, so it is formatted, level-gated
+    and grouped like any other Core record.
+
+    The import-time INFO level is dropped too (``NOTSET``), so ``fastmcp``
+    follows Home Assistant's default level and honours ``logger.set_level``
+    (or a ``logger:`` entry) for it like any integration's logger. Leaving it
+    at INFO would let FastMCP records through at a level HA was told to hide;
+    a threshold filter on Core's handlers would instead override the user's
+    own level for ``fastmcp`` and would stay attached to Core's handlers after
+    the embedded entry unloads.
+
+    Only the embedded server calls this. The CLI and the app launchers own
+    their stdout/stderr and must keep FastMCP's own handler.
+    """
+    logger = logging.getLogger("fastmcp")
+    for handler in list(logger.handlers):
+        logger.removeHandler(handler)
+    logger.propagate = True
+    logger.setLevel(logging.NOTSET)
+
+
 def install_sdk_log_filters() -> None:
     """Attach the suppression/demotion filters above to their MCP SDK loggers.
 
@@ -170,3 +200,10 @@ def install_sdk_log_filters() -> None:
     """
     _add_filter_once("mcp.server.streamable_http", StatelessSessionLogFilter)
     _add_filter_once("mcp.server.streamable_http_manager", SessionDisconnectLogFilter)
+    # Embedded-only: give FastMCP's own records to Home Assistant's logging so
+    # they carry HA's header, respect HA's levels and reach system_log. The CLI
+    # and app launchers own their output and keep FastMCP's handler.
+    from .config import is_embedded_mode
+
+    if is_embedded_mode():
+        route_fastmcp_logs_to_root()