Merge branch 'fix/demote-stateless-session-disconnect-log' of https://github.com/swissmo/ha-mcp into fix/demote-stateless-session-disconnect-log

Author: swissmo

custom_components/ha_mcp_tools/embedded_server.py

@@ -718,6 +718,14 @@ async def _async_wait_for_pending_install(self) -> None:
 
     async def _async_ensure_package(
         self, *, defer_mutations: bool = False
+    ) -> str | None:
+        """Use the externally managed package or ensure a managed install."""
+        if self._hass.config.skip_pip:
+            return await self._async_externally_managed_package_version()
+        return await self._async_ensure_managed_package(defer_mutations=defer_mutations)
+
+    async def _async_ensure_managed_package(
+        self, *, defer_mutations: bool = False
     ) -> str | None:
         """Ensure ``ha-mcp`` is importable, installing the pip spec if needed.
 
@@ -888,6 +896,85 @@ async def _async_ensure_package(
             self._store_installed_spec()
         return version
 
+    async def _async_externally_managed_package_version(self) -> str:
+        """Validate and return the package supplied outside Home Assistant.
+
+        skip_pip means the surrounding system owns this interpreter. This
+        path therefore performs metadata/importability reads only: it never
+        calls Home Assistant's requirements manager, UV, or the config-entry
+        marker writers used by manual and automatic installs.
+        """
+        importable_version: str | None = await self._hass.async_add_executor_job(
+            _installed_ha_mcp_version
+        )
+        stable_version: str | None = await self._hass.async_add_executor_job(
+            _installed_dist_version, DIST_NAME_STABLE
+        )
+        dev_version: str | None = await self._hass.async_add_executor_job(
+            _installed_dist_version, DIST_NAME_DEV
+        )
+        target_dist = dist_for_channel(self._channel)
+        target_version = (
+            stable_version if target_dist == DIST_NAME_STABLE else dev_version
+        )
+        other_dist = (
+            DIST_NAME_DEV if target_dist == DIST_NAME_STABLE else DIST_NAME_STABLE
+        )
+        other_version = (
+            dev_version if target_dist == DIST_NAME_STABLE else stable_version
+        )
+
+        if importable_version is None:
+            raise EmbeddedServerError(
+                "Home Assistant was started with skip_pip enabled, so HA-MCP "
+                "will not install the externally managed server package. Use "
+                f"the system package manager to install {target_dist} "
+                f"{MIN_EMBEDDED_SERVER_VERSION} or newer, then reload this "
+                "integration.",
+                kind="package",
+            )
+
+        if stable_version is not None and dev_version is not None:
+            raise EmbeddedServerError(
+                f"Both {DIST_NAME_STABLE} {stable_version} and "
+                f"{DIST_NAME_DEV} {dev_version} are installed while skip_pip "
+                "is enabled. They share the ha_mcp import package, so HA-MCP "
+                "cannot safely select one without modifying the environment. "
+                "Use the system package manager to leave exactly one installed, "
+                "then reload this integration.",
+                kind="package",
+            )
+
+        if target_version is None:
+            raise EmbeddedServerError(
+                f"The configured {self._channel} channel expects {target_dist}, "
+                f"but only {other_dist} {other_version} is installed while "
+                "skip_pip is enabled. Use the system package manager to install "
+                f"{target_dist} {MIN_EMBEDDED_SERVER_VERSION} or newer, or "
+                f"change the HA-MCP release channel to match {other_dist}, then "
+                "reload this integration.",
+                kind="package",
+            )
+
+        if not _is_compatible_embedded_version(target_version):
+            raise EmbeddedServerError(
+                f"The externally managed {target_dist} {target_version} is "
+                "incompatible while skip_pip is enabled; this in-process "
+                f"component requires {MIN_EMBEDDED_SERVER_VERSION} or newer. "
+                "Upgrade it with the system package manager, then reload this "
+                "integration.",
+                kind="package",
+            )
+
+        _LOGGER.info(
+            "HA-MCP externally managed %s package ready (version %s; "
+            "skip_pip enabled, channel %s)",
+            target_dist,
+            target_version,
+            self._channel,
+        )
+        return target_version
+
     async def _async_remove_legacy_target(
         self, target_dist: str, installed_version: str | None
     ) -> None:

custom_components/ha_mcp_tools/embedded_setup.py

@@ -608,6 +608,10 @@ async def async_maybe_auto_update(
     logged at debug and skipped; the next refresh retries. Genuine bugs
     propagate per the repo's no-silent-failure convention.
     """
+    if hass.config.skip_pip:
+        # The system package manager owns ha-mcp; never reload to mutate it.
+        return
+
     if not bool(entry.options.get(OPT_AUTO_UPDATE, DEFAULT_AUTO_UPDATE)):
         # Auto-update turned off: stay on the currently-installed version.
         return

custom_components/ha_mcp_tools/update.py

@@ -109,8 +109,10 @@ def latest_version(self) -> str | None:
 
     @property
     def auto_update(self) -> bool:
-        """Reflect the entry's automatic-update option."""
-        return bool(self._entry.options.get(OPT_AUTO_UPDATE, DEFAULT_AUTO_UPDATE))
+        """Reflect the effective automatic-update policy."""
+        return not self.coordinator.hass.config.skip_pip and bool(
+            self._entry.options.get(OPT_AUTO_UPDATE, DEFAULT_AUTO_UPDATE)
+        )
 
     @property
     def release_url(self) -> str | None:
@@ -126,8 +128,10 @@ def release_url(self) -> str | None:
 
     @property
     def supported_features(self) -> UpdateEntityFeature:
-        """RELEASE_NOTES only on the stable channel — dev builds have no tags."""
-        features = UpdateEntityFeature.INSTALL
+        """Expose install only when Home Assistant may manage the package."""
+        features = UpdateEntityFeature(0)
+        if not self.coordinator.hass.config.skip_pip:
+            features |= UpdateEntityFeature.INSTALL
         data = self.coordinator.data
         if data is not None and data.dist != DIST_NAME_DEV:
             features |= UpdateEntityFeature.RELEASE_NOTES
@@ -257,6 +261,14 @@ async def async_install(
         that can still fail (review finding).
         """
         data = self.coordinator.data
+        if self.coordinator.hass.config.skip_pip:
+            raise HomeAssistantError(
+                "The HA-MCP server package is externally managed by the system "
+                "package manager because Home Assistant was started with "
+                "skip_pip. Install the update there, then reload this "
+                "integration."
+            )
+
         target = version or self.latest_version
         if target is None:
             raise HomeAssistantError("No target version available to install.")

docs/beta.md

@@ -177,18 +177,31 @@ token grants. If the token is missing or invalid, Puppet lands on the login
 page and (by its design) restarts; ha-mcp surfaces this as a clear "set the
 engine's access token" error rather than a silent failure.
 
-Puppet's theme and dark-mode renderer controls used to dispatch Home
-Assistant's `settheme` event on every cold render, which Home Assistant
-persisted on the frontend profile of the user whose token the engine runs with
-— and synced to that user's real web and mobile sessions, flipping a dark-mode
-user's whole UI to light on every screenshot (#1909). Recent Puppet versions
-fixed that cold-render dispatch, so ha-mcp's snapshot/restore bracket around
-each capture is now disabled (#1991); the guard code is retained so it can be
-switched back on if a future engine regression reintroduces the write. If you
-run an older Puppet build, update the app (or your self-hosted sidecar
-image) — older engines still persist the theme selection and will keep
-flipping it. A dedicated Puppet account remains a sound belt-and-suspenders
-setup. Language selection is local to Puppet's browser session.
+Puppet dispatches Home Assistant's `settheme` event on cold renders, which
+Home Assistant persists on the frontend profile of the user whose token the
+engine runs with — and syncs to that user's real web and mobile sessions,
+flipping that user's whole UI on every screenshot (#1909). Upstream stopped
+the dispatch for renders that request no theme
+(balloob/home-assistant-addons#89), but by its own title only for that case,
+and it is unreleased as of Puppet 2.6.0 — so on current releases every render
+writes.
+
+The screenshot and dashboard-get tools **detect** this and report it, but
+never write: they read the engine account's saved theme before and after the
+render and, when it changed, emit a warning naming the previous value. Undoing
+it is a separate, explicitly write-annotated call —
+`ha_manage_theme(action="set_engine_theme", value=..., expected_current=...)`
+— passing both values from the warning, so a theme changed in the meantime is
+refused rather than overwritten — so these tools stay
+honestly `readOnlyHint: True` (#1991). `ha_manage_theme(action=
+"get_engine_theme")` inspects the same value. Note this is the engine
+account's *per-user* profile, a different layer from the backend default that
+`action="set"` changes.
+
+**Give the engine its own Home Assistant user and long-lived token** and the
+problem stops mattering: the write lands on an account nobody looks at, so no
+real session is disturbed. The warning is still emitted — ha-mcp has no signal
+telling it an account is dedicated — but it becomes safe to ignore. Language selection is local to Puppet's browser session.
 
 To change the Puppet engine app's own options (such as `keep_browser_open`)
 or to restart it, use `ha_manage_app`; the screenshot tools only render and
@@ -262,10 +275,15 @@ render failure to a warning so it never breaks a write that already committed.
 `include_screenshot` (get) does not commit a dashboard/config write, and the
 screenshot *is* the requested payload, so a total render failure surfaces as
 an error (matching the standalone `ha_get_dashboard_screenshot` tool) rather
-than a warning a caller might miss. Because Puppet can persist theme/dark
-preferences (and the theme-restore bracket writes frontend user data to undo
-that), screenshot operations are blocked in server Read Only Mode; ordinary
-dashboard get/list/search calls remain available.
+than a warning a caller might miss. Screenshot operations stay **available** in server Read
+Only Mode: both entry points are `readOnlyHint: True`, so the transform does
+not hide them and the middleware does not block them (#1991 removed the
+exemption that used to block them, pinned by
+`test_dashboard_config_screenshot_now_passes`). Rendering still makes Puppet
+persist theme/dark preferences on the engine account, and ha-mcp still reports
+that in warnings — so in Read Only Mode you get the warning but cannot act on
+it, since `ha_manage_theme` is exempted only for its read actions
+(`get_engine_theme` inspects the value; `set_engine_theme` stays blocked).
 
 **Raw rendered paths remain constrained.** `ha_get_dashboard_screenshot`
 validates legacy `dashboard_path` values (rejects URLs, query strings,

homeassistant-addon-dev/config.yaml

@@ -1,6 +1,6 @@
 name: "Home Assistant MCP Server (Dev)"
 description: "Development channel - AI assistant integration via MCP (unstable)"
-version: "8.3.0.dev2411"
+version: "8.3.0.dev2415"
 slug: "ha_mcp_dev"
 url: "https://github.com/homeassistant-ai/ha-mcp"
 stage: experimental

site/src/data/tools.json

@@ -699,11 +699,11 @@
           "default": false
         },
         "theme": {
-          "type": "Annotated[str | None, Field(description=\"Installed Home Assistant frontend theme name, applied to this render. The engine user's saved theme preference is restored after the capture (best effort).\")]",
+          "type": "Annotated[str | None, Field(description=\"Installed Home Assistant frontend theme name, applied to this render. The engine persists this on the engine account's profile; this tool reports the change in warnings but does not undo it (see ha_manage_theme action='set_engine_theme').\")]",
           "default": null
         },
         "dark_mode": {
-          "type": "Annotated[bool, Field(description=\"Render the requested theme in dark mode, applied to this render. The engine user's saved theme preference is restored after the capture (best effort).\")]",
+          "type": "Annotated[bool, Field(description=\"Render the requested theme in dark mode, applied to this render. The engine persists this on the engine account's profile; this tool reports the change in warnings but does not undo it (see ha_manage_theme action='set_engine_theme').\")]",
           "default": false
         },
         "language": {
@@ -3415,16 +3415,28 @@
   {
     "name": "ha_manage_theme",
     "title": "Manage Frontend Themes",
-    "description": "Manage Home Assistant frontend themes.\n\nWhen NOT to use: themes are YAML files - Home Assistant has no API to\ncreate or edit them. Installing community themes goes through HACS\n(ha_manage_hacs); editing custom theme files goes through\nha_config_set_yaml (beta, edits themes/<name>.yaml keyed by theme name\nand attempts an automatic theme reload).\n\nWhen to use: action='list' discovers installed theme names and the\ncurrent defaults; action='set' selects the backend default theme\n(optionally per light/dark mode).\n\nCaveats: action='set' changes the backend-selected default only -\nusers who explicitly picked a theme in their profile keep their\nchoice. Theme names are validated by Home Assistant at call time.\n\nEXAMPLES:\n- List themes: ha_manage_theme(action=\"list\")\n- Set default theme: ha_manage_theme(action=\"set\", theme_name=\"nord\")\n- Set dark-mode theme: ha_manage_theme(\n      action=\"set\", theme_name=\"nord\", mode=\"dark\")\n- Restore built-in default: ha_manage_theme(\n      action=\"set\", theme_name=\"default\")",
+    "description": "Manage Home Assistant frontend themes.\n\nWhen NOT to use: themes are YAML files - Home Assistant has no API to\ncreate or edit them. Installing community themes goes through HACS\n(ha_manage_hacs); editing custom theme files goes through\nha_config_set_yaml (beta, edits themes/<name>.yaml keyed by theme name\nand attempts an automatic theme reload).\n\nWhen to use: action='list' discovers installed theme names and the\ncurrent defaults; action='set' selects the backend default theme\n(optionally per light/dark mode).\n\nSCREENSHOT-ENGINE ACTIONS (per-user, not the backend default):\nTaking a dashboard screenshot makes the Puppet engine write the saved\ntheme of the Home Assistant user its token belongs to, which also\nflips that user's live web and mobile sessions. The screenshot tools\nare read-only and only *report* this; use action='set_engine_theme'\nwith the value quoted in their warning to put it back, and\naction='get_engine_theme' to inspect it. These act on that engine\naccount's per-user profile via frontend/set_user_data, which is a\ndifferent layer from the backend default that action='set' changes.\nGiving the engine its own dedicated user and token avoids the issue\nentirely.\n\nCaveats: action='set' changes the backend-selected default only -\nusers who explicitly picked a theme in their profile keep their\nchoice. Theme names are validated by Home Assistant at call time.\n\nEXAMPLES:\n- List themes: ha_manage_theme(action=\"list\")\n- Set default theme: ha_manage_theme(action=\"set\", theme_name=\"nord\")\n- Set dark-mode theme: ha_manage_theme(\n      action=\"set\", theme_name=\"nord\", mode=\"dark\")\n- Restore built-in default: ha_manage_theme(\n      action=\"set\", theme_name=\"default\")\n- Inspect the engine account's theme: ha_manage_theme(\n      action=\"get_engine_theme\")\n- Undo a screenshot's theme change (pass BOTH values from the\n  warning, so a theme changed since then is not overwritten):\n  ha_manage_theme(action=\"set_engine_theme\",\n      value={\"theme\": \"\", \"dark\": False},\n      expected_current={\"theme\": \"default\", \"dark\": True})",
     "inputSchema": {
       "properties": {
         "action": {
-          "type": "Annotated[ThemeAction, Field(description='Theme operation: list installed themes or set the default theme.')]"
+          "type": "Annotated[ThemeAction, Field(description=\"Theme operation: 'list' installed themes, 'set' the backend default theme, or read/restore the screenshot engine account's own per-user theme with 'get_engine_theme' / 'set_engine_theme' (a different layer from the backend default).\")]"
         },
         "theme_name": {
           "type": "Annotated[str | None, Field(description=\"Theme name when action='set'. Must be an installed theme; 'default' restores the built-in theme, 'none' resets the chosen mode to the built-in default.\", default=None)]",
           "default": null
         },
+        "expected_current": {
+          "type": "Annotated[dict[str, Any] | None, JSON_STRING_COERCION, Field(description=\"Guard for action='set_engine_theme': the stored theme is read immediately before the write and the write is skipped if it no longer equals this. Omitting this value or passing null both mean 'expect no stored theme', enforced like any other value; the guard is always applied unless force is set. Best-effort, not atomic -- Home Assistant exposes no conditional write, so a change landing between that read and the write is not caught. Pass the expected_current value quoted in the screenshot tool's warning.\", default=None)]",
+          "default": null
+        },
+        "force": {
+          "type": "Annotated[bool, Field(description=\"action='set_engine_theme' only: skip the expected_current guard and overwrite unconditionally. Leave false unless you intend to discard whatever is stored.\", default=False)]",
+          "default": false
+        },
+        "value": {
+          "type": "Annotated[dict[str, Any] | None, JSON_STRING_COERCION, Field(description=\"Frontend user-data theme object when action='set_engine_theme', e.g. {'theme': '', 'dark': False}. An empty dict restores default/auto behavior. Take this verbatim from the warning a screenshot tool emitted.\", default=None)]",
+          "default": null
+        },
         "mode": {
           "type": "Annotated[Literal['light', 'dark'] | None, Field(description=\"Which mode the theme applies to when action='set'. Defaults to light.\", default=None)]",
           "default": null