ha-mcp-dev 9.1.0.dev3282__tar.gz → 9.1.0.dev3285__tar.gz

{ha_mcp_dev-9.1.0.dev3282 → ha_mcp_dev-9.1.0.dev3285}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 9.1.0.dev3282
+Version: 9.1.0.dev3285
 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.1.0.dev3282 → ha_mcp_dev-9.1.0.dev3285}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "9.1.0.dev3282"
+version = "9.1.0.dev3285"
 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.1.0.dev3282 → ha_mcp_dev-9.1.0.dev3285}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "9.1.0.dev3282"
+version = "9.1.0.dev3285"
 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.1.0.dev3282 → ha_mcp_dev-9.1.0.dev3285}/src/ha_mcp/backup_manager.py

@@ -108,11 +108,12 @@ from .backup_todo import fetch_todo_item, restore_todo_item
 from .backup_todo import snapshot_item as todo_snapshot_item
 from .backup_zones import fetch_zone, restore_zone
 from .client.rest_client import (
+    HomeAssistantAuthError,
     HomeAssistantCommandError,
     HomeAssistantConnectionError,
     HomeAssistantError,
 )
-from .errors import ErrorCode
+from .errors import ErrorCode, get_error_code
 from .storage_helper_types import SIMPLE_HELPER_TYPES
 from .utils.data_paths import get_data_dir
 from .utils.registry_update_lock import registry_update_lock
@@ -2021,9 +2022,8 @@ async def _ws_send(client: Any, message: dict[str, Any]) -> Any:
         client.base_url, client.token, verify_ssl=client.verify_ssl
     )
     if error or ws_client is None:
-        # ``error`` is a structured-error envelope; the message can live
-        # under either error.error.message (nested) or error.message
-        # (flat, as ``create_error_response`` actually produces).
+        # ``error`` is get_connected_ws_client's nested envelope; the flat
+        # ``error["message"]`` read is a defensive fallback.
         if isinstance(error, dict):
             err_obj = error.get("error", error)
             msg = (
@@ -2031,11 +2031,10 @@ async def _ws_send(client: Any, message: dict[str, Any]) -> Any:
             ) or error.get("message", "WS connect failed")
         else:
             msg = "WS connect failed"
-        # Typed connection error so the outer ``_CAPTURE_TRANSIENT_ERRORS``
-        # tuple catches it; a bare ``RuntimeError`` would propagate past
-        # ``maybe_snapshot``'s catch and break the wrapped write — exactly
-        # what the best-effort contract on the decorator forbids.
-        raise HomeAssistantConnectionError(msg)
+        # Typed so ``_CAPTURE_TRANSIENT_ERRORS`` catches it (a bare ``RuntimeError``
+        # would break the best-effort write); a rejected token reports AUTH_*.
+        auth = str(get_error_code(error or {})).startswith("AUTH_")
+        raise (HomeAssistantAuthError if auth else HomeAssistantConnectionError)(msg)
     try:
         cmd_type = message.pop("type")
         envelope = await ws_client.send_command(cmd_type, **message)

{ha_mcp_dev-9.1.0.dev3282 → ha_mcp_dev-9.1.0.dev3285}/src/ha_mcp/client/rest_client.py

@@ -90,16 +90,17 @@ class HomeAssistantConnectionError(HomeAssistantError):
 class HomeAssistantCommandNotSent(HomeAssistantConnectionError):
     """A WS command that provably never left the process.
 
-    Raised by ``HomeAssistantWebSocketClient.send_command`` ONLY at its single
-    provably-never-sent site: the entry-guard reject (socket not authenticated), where
-    nothing is transmitted. Subclass of ``HomeAssistantConnectionError`` so every
-    existing broad handler is unaffected, yet a write consumer can catch this type
-    FIRST to fall back to the legacy path safely — the write provably never happened,
-    so a legacy first fire cannot double-apply. A ``send_json_message`` failure is NOT
-    this type: ``websocket.send()`` raising does not prove the frame was untransmitted
-    (bytes may already be on the socket when the close surfaces), so send_command
-    re-raises the original exception and the consumer treats it as ambiguous. A
-    post-send socket close (mid-await) likewise raises a plain
+    Raised by ``HomeAssistantWebSocketClient.send_command``'s entry guard (socket not
+    authenticated) and by ``send_websocket_message`` when no attempt obtained a client
+    (raised from the acquisition error, so a rejected token survives as ``__cause__``).
+    A subclass of ``HomeAssistantConnectionError``, so broad handlers are unaffected,
+    yet a write consumer can catch it FIRST: the write provably never happened, so a
+    legacy first fire cannot double-apply. Check ``__cause__`` before such a fallback:
+    resending a rejected token over REST adds a 401 toward Home Assistant's IP ban. A
+    ``send_json_message`` failure is NOT this type: ``websocket.send()`` raising does
+    not prove the frame was untransmitted (bytes may already be on the socket when the
+    close surfaces), so send_command re-raises the original exception and the consumer
+    treats it as ambiguous. A post-send socket close (mid-await) likewise raises a plain
     ``HomeAssistantConnectionError`` (the close handler sets it on the pending future),
     so type alone distinguishes never-sent from sent-then-dropped/ambiguous.
     """
@@ -1955,12 +1956,11 @@ class HomeAssistantClient:
 
         max_retries = 2
         retry_delay = 0.5  # seconds
+        # Whether an earlier attempt got past acquisition, so may have sent.
+        sent_before = False
 
         for attempt in range(max_retries):
             # Whether the failure happened before a usable connection existed.
-            # Failing to obtain one is transport death whatever class the
-            # manager raises; an auth failure or the pool-lock guard's bare
-            # ``Exception`` is not a connection error; type cannot decide this.
             acquiring = True
             try:
                 # Use per-client WebSocket keyed to this client's credentials
@@ -1996,34 +1996,33 @@ class HomeAssistantClient:
                         f"retrying after {retry_delay}s: {error_str}"
                     )
                     await asyncio.sleep(retry_delay)
+                    sent_before = sent_before or not acquiring
                     continue
 
                 # Phase first, type second. Failing before a client exists is
-                # evidence about the transport whatever class was raised; an
-                # auth failure or the pool-lock guard's bare ``Exception`` is not
-                # a no-answer class, so that case cannot be decided by type.
-                # Past acquisition only the no-answer classes count:
-                # ``send_command`` deliberately re-raises the original
-                # ``ConnectionClosed`` / ``ConnectionResetError`` from the send
-                # rather than wrapping it, to keep at-most-once semantics for
-                # write callers, so those arrive here untranslated. Anything
-                # else (a ``ValueError`` from building the message, say) is a
-                # bug rather than evidence about the connection.
+                # transport evidence whatever was raised: an auth failure or the
+                # pool-lock guard's bare ``Exception`` is no no-answer class.
+                # Past acquisition only those classes count (``send_command``
+                # re-raises the original ``ConnectionClosed`` /
+                # ``ConnectionResetError`` to keep writes at-most-once); anything
+                # else is Home Assistant's own answer or a local bug.
                 if acquiring or isinstance(e, _NO_ANSWER_ERRORS):
                     # One error channel for "no answer came back" (#1947): the
-                    # caller decides the policy, rather than every consumer
-                    # having to notice a marker on an otherwise ordinary
-                    # failure envelope. Callers that legitimately continue on a
-                    # missing answer catch this and say in ``warnings`` what
-                    # they skipped; callers whose output would read as a
-                    # negative finding let it propagate.
+                    # caller decides the policy. Callers that legitimately continue
+                    # on a missing answer catch this and say in ``warnings`` what
+                    # they skipped; callers whose output would read as a negative
+                    # finding let it propagate.
                     logger.error(
                         f"WebSocket transport failed ({message.get('type')}): {e}"
                     )
-                    if isinstance(e, HomeAssistantConnectionError):
-                        # Already the right class — re-raise unchanged so
-                        # subtypes (``HomeAssistantCommandNotSent``) and the
-                        # original traceback survive.
+                    if acquiring and not sent_before:
+                        # No attempt obtained a client, so nothing was sent.
+                        raise HomeAssistantCommandNotSent(error_str) from e
+                    if isinstance(e, HomeAssistantConnectionError) and not (
+                        sent_before and isinstance(e, HomeAssistantCommandNotSent)
+                    ):
+                        # Re-raised unchanged so subtypes and the traceback
+                        # survive; not "never sent" once an attempt may have sent.
                         raise
                     raise HomeAssistantConnectionError(error_str) from e
 

{ha_mcp_dev-9.1.0.dev3282 → ha_mcp_dev-9.1.0.dev3285}/src/ha_mcp/client/websocket_client.py

@@ -764,8 +764,8 @@ class HomeAssistantWebSocketClient:
             Response from Home Assistant
         """
         if not self._state.is_ready:
-            # PRE-SEND and the ONLY provably-never-sent site: nothing is transmitted at
-            # this entry guard. Raise the never-sent subtype so an at-most-once write
+            # PRE-SEND and send_command's only provably-never-sent site: nothing is
+            # transmitted here. Raise the never-sent subtype so an at-most-once write
             # consumer can fall back to legacy safely (a subclass of
             # HomeAssistantConnectionError, so every existing broad handler is
             # unaffected). A later send() failure is NOT never-sent (see below).

{ha_mcp_dev-9.1.0.dev3282 → ha_mcp_dev-9.1.0.dev3285}/src/ha_mcp/tools/addon_connection_hints.py

@@ -1,7 +1,29 @@
-"""Connection-failure guidance shared by app HTTP and WebSocket proxies."""
+"""Failure guidance for Supervisor calls and the app HTTP and WebSocket proxies."""
+
+from typing import Any
 
 from .._version import is_running_in_addon
 from ..client.rest_client import HomeAssistantClient
+from ..errors import ErrorCode
+
+_SUPERVISOR_AVAILABILITY_SUGGESTION = (
+    "Check Home Assistant connection and Supervisor availability"
+)
+_APP_SUPPORT_SUGGESTION = "Check that this installation supports apps (add-ons)."
+
+
+def add_supervisor_error_suggestions(error_details: dict[str, Any]) -> None:
+    """Add Supervisor guidance to a failed call's error; a refused token says
+    nothing about app support, so it gets none."""
+    code = str(error_details.get("code", ""))
+    if code == ErrorCode.RESOURCE_NOT_FOUND.value:
+        error_details["suggestion"] = _SUPERVISOR_AVAILABILITY_SUGGESTION
+        error_details["suggestions"] = [_SUPERVISOR_AVAILABILITY_SUGGESTION]
+    if not code.startswith("AUTH_"):
+        error_details["suggestions"] = [
+            *error_details.get("suggestions", []),
+            _APP_SUPPORT_SUGGESTION,
+        ]
 
 
 def addon_connection_failure_suggestions(

{ha_mcp_dev-9.1.0.dev3282 → ha_mcp_dev-9.1.0.dev3285}/src/ha_mcp/tools/component_api.py

@@ -158,11 +158,20 @@ class ComponentDiscoveryError(RuntimeError):
 
 
 def _checked_caps(
-    client: Any, caps: ComponentCaps | None, strict: bool
+    client: Any,
+    caps: ComponentCaps | None,
+    strict: bool,
+    *,
+    cause: Exception | None = None,
 ) -> ComponentCaps | None:
-    """Keep read fallbacks while exposing failed discovery to write callers."""
+    """Keep read fallbacks while exposing failed discovery to write callers.
+
+    ``cause`` is the exception that failed this call's own probe; a strict caller
+    gets it as ``__cause__``. A failure cached by an earlier call gets no cause:
+    the OAuth proxy client is one cache key for every user's token.
+    """
     if strict and (failure := _PROBE_FAILURES.get(client)):
-        raise ComponentDiscoveryError(failure)
+        raise ComponentDiscoveryError(failure) from cause
     return caps
 
 
@@ -282,6 +291,7 @@ async def get_component_caps(
 
     With ``strict=True``, failed or malformed discovery raises
     ``ComponentDiscoveryError``, including failures cached by earlier read tools.
+    When this call's own probe failed, its exception is the ``__cause__``.
     A definitive unknown command, unsupported schema, or valid capability list
     without the requested command still permits legacy routing. The default
     retains best-effort read behavior. Inconclusive failures expire after 30
@@ -342,8 +352,8 @@ async def get_component_caps(
             else:
                 _store_transient_negative(client)
                 _PROBE_FAILURES[client] = f"{INFO_COMMAND} failed: {exc}"
-            return _checked_caps(client, None, strict)
-        except (HomeAssistantConnectionError, HomeAssistantCommandTimeout):
+            return _checked_caps(client, None, strict, cause=exc)
+        except (HomeAssistantConnectionError, HomeAssistantCommandTimeout) as exc:
             logger.debug(
                 "%s probe skipped: WS unavailable", INFO_COMMAND, exc_info=True
             )
@@ -351,14 +361,14 @@ async def get_component_caps(
             _PROBE_FAILURES[client] = (
                 f"{INFO_COMMAND} probe could not reach Home Assistant"
             )
-            return _checked_caps(client, None, strict)
-        except Exception:
+            return _checked_caps(client, None, strict, cause=exc)
+        except Exception as exc:
             # Read callers retain best-effort fallback; strict write callers
             # must not confuse an unexpected fault with capability absence.
             logger.debug("%s probe failed unexpectedly", INFO_COMMAND, exc_info=True)
             _store_transient_negative(client)
             _PROBE_FAILURES[client] = f"{INFO_COMMAND} probe failed unexpectedly"
-            return _checked_caps(client, None, strict)
+            return _checked_caps(client, None, strict, cause=exc)
 
         caps = _parse_caps(response)
         if caps is not None and caps.schema_version != SUPPORTED_SCHEMA_VERSION:

{ha_mcp_dev-9.1.0.dev3282 → ha_mcp_dev-9.1.0.dev3285}/src/ha_mcp/tools/component_dashboard_edit.py

@@ -14,7 +14,10 @@ from .component_api import (
     invalidate_caps,
     is_unknown_command,
 )
-from .dashboard_edit_errors import raise_dashboard_edit_error
+from .dashboard_edit_errors import (
+    raise_dashboard_edit_error,
+    raise_dashboard_edit_unsent,
+)
 
 WS_DASHBOARD_EDIT = "ha_mcp_tools/dashboard_edit"
 _LOGGER = logging.getLogger(__name__)
@@ -148,7 +151,7 @@ async def edit_dashboard_via_component(
         _LOGGER.warning(
             "Unable to prepare the dashboard edit connection", exc_info=True
         )
-        raise_dashboard_edit_error(url_path, "load_failed", str(exc), False, action)
+        raise_dashboard_edit_unsent(exc, url_path, action, "load_failed")
 
     kwargs: dict[str, Any] = {"url_path": url_path}
     if expected_hash is not None:

{ha_mcp_dev-9.1.0.dev3282 → ha_mcp_dev-9.1.0.dev3285}/src/ha_mcp/tools/component_todo.py

@@ -5,24 +5,30 @@ todo services and reads the stored rows back from the list entity.
 ``todo_item`` returns ``None`` when the component did not run the action, so
 the caller uses Core's WebSocket commands instead: the capability is absent,
 the command was not sent, Core answered ``unknown_command``, or the component
-lacks Core's todo parts. A reply with ``success: False`` is the component's
-refusal: a check before the write, or Core's schema or validation error after
-which the list's rows were unchanged. The one exception is ``move_failed``: the
-update was applied and the move after it failed, as its message says.
+lacks Core's todo parts. A command not sent because the token was rejected
+raises instead, since those commands would resend the token. A reply with
+``success: False`` is the component's refusal: a check before the write, or
+Core's schema or validation error after which the list's rows were unchanged.
+The one exception is ``move_failed``: the update was applied and the move
+after it failed, as its message says.
 """
 
 from __future__ import annotations
 
 from typing import Any
 
-from ..client.rest_client import HomeAssistantCommandNotSent, HomeAssistantError
+from ..client.rest_client import (
+    HomeAssistantAuthError,
+    HomeAssistantCommandNotSent,
+    HomeAssistantError,
+)
 from ..errors import ErrorCode, create_error_response
 from .component_api import (
     component_supports,
     get_component_caps,
     invalidate_caps,
 )
-from .helpers import raise_tool_error
+from .helpers import exception_to_structured_error, raise_tool_error
 
 WS_TODO_ITEM = "ha_mcp_tools/todo_item"
 CAPABILITY = "todo_item"
@@ -44,14 +50,18 @@ async def todo_item(
     """The component's reply to one action on ``entity_id``; None when it did
     not run it. A sent command that got no answer, or that the component
     failed to answer, raises ``HomeAssistantError``: a write's outcome is then
-    unknown."""
+    unknown. A command not sent because the token was rejected raises
+    ``HomeAssistantCommandNotSent``."""
     if not component_supports(await get_component_caps(client), CAPABILITY):
         return None
     try:
         result = await client.send_websocket_message(
             {"type": WS_TODO_ITEM, "entity_id": entity_id, "action": action, **fields}
         )
-    except HomeAssistantCommandNotSent:
+    except HomeAssistantCommandNotSent as exc:
+        if isinstance(exc.__cause__, HomeAssistantAuthError):
+            # Core's WebSocket commands would resend the rejected token.
+            raise
         return None
     if not result.get("success"):
         if result.get("error_code") == "unknown_command":
@@ -73,6 +83,9 @@ async def todo_call(
     sent without an answer is reported as unknown."""
     try:
         reply = await todo_item(client, entity_id, action, **fields)
+    except HomeAssistantCommandNotSent as e:
+        # Nothing was sent, so the outcome is known.
+        exception_to_structured_error(e, context={"entity_id": entity_id})
     except HomeAssistantError as e:
         if action == "resolve":
             raise

{ha_mcp_dev-9.1.0.dev3282 → ha_mcp_dev-9.1.0.dev3285}/src/ha_mcp/tools/config_entry_identity.py

@@ -319,12 +319,12 @@ async def _registry_rows(
             type(err).__name__,
             err,
         )
-        raise (
-            err
-            if isinstance(err, HomeAssistantConnectionError)
-            else HomeAssistantConnectionError(
-                f"{method_name} transport unavailable for {entry_id}"
-            )
+        if isinstance(err, HomeAssistantConnectionError):
+            # Re-raised as is: chaining it to itself would drop its cause, such
+            # as the auth error behind a token rejected on reconnect.
+            raise
+        raise HomeAssistantConnectionError(
+            f"{method_name} transport unavailable for {entry_id}"
         ) from err
     if not isinstance(result, list) or any(not isinstance(row, dict) for row in result):
         raise HomeAssistantAPIError(

{ha_mcp_dev-9.1.0.dev3282 → ha_mcp_dev-9.1.0.dev3285}/src/ha_mcp/tools/config_helpers/registry.py

@@ -243,9 +243,10 @@ def _apply_registry_check(
     if fail_closed and not ok:
         if exc is not None:
             # The transport wrap re-raises acquisition failures as
-            # HomeAssistantConnectionError ``from`` the original exception
-            # (phase-before-type, pinned by
-            # test_failure_to_acquire_a_client_raises), so an auth rejection
+            # HomeAssistantCommandNotSent (a plain HomeAssistantConnectionError
+            # once an earlier attempt obtained a client) ``from`` the original
+            # exception (phase-before-type, pinned by
+            # test_failure_to_acquire_a_client_is_not_sent), so an auth rejection
             # during connect survives only in the ``__cause__`` chain —
             # discriminate on it the same way the envelope branch below
             # discriminates on ``error_code``.

{ha_mcp_dev-9.1.0.dev3282 → ha_mcp_dev-9.1.0.dev3285}/src/ha_mcp/tools/dashboard_edit_errors.py

@@ -7,9 +7,14 @@ from typing import Any, NoReturn
 
 from ha_mcp._vendor.fastmcp.exceptions import ToolError
 
+from ..client.rest_client import HomeAssistantAuthError
 from ..errors import ErrorCode, create_error_response, get_error_code, get_error_message
 from .dashboard_read_errors import CONFIG_NOT_FOUND_CODE
-from .helpers import extract_tool_error_message, raise_tool_error
+from .helpers import (
+    exception_to_structured_error,
+    extract_tool_error_message,
+    raise_tool_error,
+)
 
 _MODE_SUGGESTIONS = [
     "Use a storage-mode dashboard created through the Home Assistant UI or API",
@@ -106,6 +111,29 @@ def raise_dashboard_edit_error(
     )
 
 
+def raise_dashboard_edit_unsent(
+    exc: Exception, url_path: str | None, action: str, reason: str
+) -> NoReturn:
+    """Raise for an edit that failed before anything was sent; a token rejected
+    on connect (the error itself or its ``__cause__``) is reported as that auth
+    error instead of under the code ``reason`` maps to. That includes a token
+    rejected on this call's capability probe; a probe failure cached by an
+    earlier call arrives without a cause and keeps ``reason``'s code."""
+    auth = exc if isinstance(exc, HomeAssistantAuthError) else exc.__cause__
+    if isinstance(auth, HomeAssistantAuthError):
+        exception_to_structured_error(
+            auth,
+            context={
+                "action": action,
+                "url_path": url_path,
+                "reason": reason,
+                "write_committed": False,
+                "post_write_verified": False,
+            },
+        )
+    raise_dashboard_edit_error(url_path, reason, str(exc), False, action)
+
+
 def raise_dashboard_edit_fetch_error(
     exc: ToolError, url_path: str, action: str
 ) -> NoReturn:

{ha_mcp_dev-9.1.0.dev3282 → ha_mcp_dev-9.1.0.dev3285}/src/ha_mcp/tools/entity_removal.py

@@ -12,10 +12,15 @@ from __future__ import annotations
 from collections.abc import Callable
 from typing import Any
 
-from ..client.rest_client import HomeAssistantConnectionError, HomeAssistantError
+from ..client.rest_client import (
+    HomeAssistantCommandNotSent,
+    HomeAssistantConnectionError,
+    HomeAssistantError,
+)
 from ..errors import ErrorCode
 from .config_helpers.listing import listed_items
 from .config_helpers.schemas import SIMPLE_HELPER_TYPES
+from .helpers import exception_to_structured_error
 
 
 def _unread(entity_id: str, reason: Any) -> list[str]:
@@ -82,7 +87,8 @@ async def remove_registry_entries(
 ) -> dict[str, Any]:
     """Remove each id in turn; each lands in ``removed``, ``skipped`` (Core's
     not_found: already absent) or ``errors``. A lost connection stops the run
-    and lists the ids it never reached, which are safe to retry."""
+    and lists the ids it never sent, which are safe to retry: the ones after the
+    failing id, and the failing id too when its command provably never left."""
     removed: list[str] = []
     skipped: list[str] = []
     errors: list[dict[str, str]] = []
@@ -93,14 +99,18 @@ async def remove_registry_entries(
                 {"type": "config/entity_registry/remove", "entity_id": eid}
             )
         except HomeAssistantConnectionError as exc:
+            # CONNECTION_FAILED, CONNECTION_TIMEOUT for a timed-out command,
+            # or AUTH_* when the token was rejected on reconnect.
+            structured = exception_to_structured_error(exc, raise_error=False)
             errors.append(
                 {
                     "entity_id": eid,
-                    "code": ErrorCode.CONNECTION_FAILED.value,
+                    "code": structured["error"]["code"],
                     "message": str(exc),
                 }
             )
-            not_attempted = list(entity_ids[index + 1 :])
+            unsent = isinstance(exc, HomeAssistantCommandNotSent)
+            not_attempted = list(entity_ids[index if unsent else index + 1 :])
             break
         if result.get("success"):
             removed.append(eid)

{ha_mcp_dev-9.1.0.dev3282 → ha_mcp_dev-9.1.0.dev3285}/src/ha_mcp/tools/helpers.py

@@ -22,6 +22,7 @@ from ..client.rest_client import (
     HomeAssistantAPIError,
     HomeAssistantAuthError,
     HomeAssistantCommandError,
+    HomeAssistantCommandTimeout,
     HomeAssistantConnectionError,
 )
 from ..client.websocket_client import HomeAssistantWebSocketClient
@@ -321,6 +322,10 @@ async def get_connected_ws_client(
             if isinstance(reason, str)
             else "WebSocket connection could not be established"
         )
+        if isinstance(ws_client.last_connect_exception, HomeAssistantAuthError):
+            return None, create_auth_error(
+                "Home Assistant rejected the WebSocket token", details=details
+            )
         return None, create_connection_error(
             "Failed to connect to Home Assistant WebSocket",
             details=details,
@@ -365,9 +370,20 @@ def _classify_exception(
 
     # Type-based classification
     match error:
+        case HomeAssistantConnectionError() if isinstance(
+            error.__cause__, HomeAssistantAuthError
+        ):
+            # send_websocket_message wraps a failure to obtain a client in a
+            # connection error raised from the original, so a token rejected
+            # on (re)connect arrives here wrapped: classify the cause by its
+            # own text.
+            cause = error.__cause__
+            return _classify_exception(cause, str(cause).lower(), error_msg, context)
         case HomeAssistantConnectionError():
+            # send_websocket_message raises a command timeout as the cause.
+            timeout = isinstance(error.__cause__, HomeAssistantCommandTimeout)
             result = create_connection_error(
-                error_msg, timeout="timeout" in error_str, context=context
+                error_msg, timeout=timeout or "timeout" in error_str, context=context
             )
         case HomeAssistantAdminRequiredError():
             result = create_error_response(

{ha_mcp_dev-9.1.0.dev3282 → ha_mcp_dev-9.1.0.dev3285}/src/ha_mcp/tools/log_sources_logbook.py

@@ -24,6 +24,7 @@ from typing import Any, Literal, NoReturn
 from ha_mcp._vendor.fastmcp.exceptions import ToolError
 
 from ..client.rest_client import (
+    HomeAssistantAuthError,
     HomeAssistantCommandError,
     HomeAssistantCommandTimeout,
     HomeAssistantConnectionError,
@@ -298,10 +299,12 @@ class LogbookLogSourceMixin:
         """Run the component's Core-processor command, or ``None`` to fall back.
 
         ``None`` means the component is absent, downgraded (``unknown_command``
-        drops the cached capability) or the transport failed before Home
-        Assistant saw the request. Core's own rejections surface unchanged, and
-        a timeout surfaces instead of falling back — the recorder query is
-        still running inside Home Assistant.
+        drops the cached capability) or the transport gave no answer: no
+        connection, or one that dropped before the reply. Core's own rejections
+        surface unchanged; a timeout (the recorder query still runs inside Home
+        Assistant) surfaces instead of falling back, and so does a token
+        rejected on the command itself. A token already rejected on the
+        capability probe falls back.
         """
         caps = await get_component_caps(self._client)
         if not component_supports(caps, LOGBOOK_EVENTS_CAPABILITY):
@@ -314,6 +317,9 @@ class LogbookLogSourceMixin:
         except HomeAssistantConnectionError as exc:
             if _wrapped_timeout(exc):
                 self._raise_logbook_timeout(command["start_time"], command["end_time"])
+            if isinstance(exc.__cause__, HomeAssistantAuthError):
+                # The fallbacks would resend the rejected token.
+                exception_to_structured_error(exc)
             return None
         except HomeAssistantCommandError as exc:
             if not is_unknown_command(exc):
@@ -346,7 +352,12 @@ class LogbookLogSourceMixin:
         except HomeAssistantConnectionError as exc:
             if _wrapped_timeout(exc):
                 self._raise_logbook_timeout(command["start_time"], command["end_time"])
-            self._raise_logbook_ws_required(command.get("device_ids"))
+            if isinstance(exc.__cause__, HomeAssistantAuthError):
+                # A token rejected on connect is not a WebSocket outage.
+                exception_to_structured_error(
+                    exc, context={"device_ids": command.get("device_ids")}
+                )
+            self._raise_logbook_ws_required(command.get("device_ids"), reason=str(exc))
         except HomeAssistantCommandError as exc:
             if not is_unknown_command(exc):
                 raise