homeassistant-ai
diff --git a/‎custom_components/ha_mcp_tools/websocket_api.py‎
Lines changed: 912 additions & 1 deletion b/‎custom_components/ha_mcp_tools/websocket_api.py‎
Lines changed: 912 additions & 1 deletion
diff --git a/‎scripts/codeql_quality_gate.py‎
Lines changed: 10 additions & 0 deletions b/‎scripts/codeql_quality_gate.py‎
Lines changed: 10 additions & 0 deletions
diff --git a/‎src/ha_mcp/client/rest_client.py‎
Lines changed: 18 additions & 0 deletions b/‎src/ha_mcp/client/rest_client.py‎
Lines changed: 18 additions & 0 deletions
diff --git a/‎src/ha_mcp/client/websocket_client.py‎
Lines changed: 14 additions & 1 deletion b/‎src/ha_mcp/client/websocket_client.py‎
Lines changed: 14 additions & 1 deletion
@@ -113,6 +113,16 @@
         "_coerce_tool_states. CodeQL's single-file analysis misses the "
         "cross-module import, so the declaration looks dead.",
     ),
+    (
+        "py/unused-global-variable",
+        "src/ha_mcp/tools/util_helpers.py",
+        "_SERVICE_TO_STATE",
+        "Cross-module use: util_helpers is the leaf module that owns the single "
+        "_SERVICE_TO_STATE map, imported and read by tools_service.py (ha_call_service) "
+        "and device_control.py (ha_bulk_control) as the confirmation-state hint. "
+        "CodeQL's single-file analysis misses the cross-module import, so the "
+        "declaration looks dead.",
+    ),
     (
         "py/unused-import",
         "packaging/binary/pyinstaller_hooks/runtime_hook.py",
 
@@ -48,6 +48,24 @@ class HomeAssistantConnectionError(HomeAssistantError):
     """Connection error to Home Assistant."""
 
 
+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
+    ``HomeAssistantConnectionError`` (the close handler sets it on the pending future),
+    so type alone distinguishes never-sent from sent-then-dropped/ambiguous.
+    """
+
+
 class HomeAssistantAuthError(HomeAssistantError):
     """Authentication error with Home Assistant.
 
 
@@ -23,6 +23,7 @@
 from ..config import get_global_settings
 from .rest_client import (
     HomeAssistantCommandError,
+    HomeAssistantCommandNotSent,
     HomeAssistantCommandTimeout,
     HomeAssistantConnectionError,
     _is_ssl_error,
@@ -616,7 +617,12 @@ async def send_command(self, command_type: str, **kwargs: Any) -> dict[str, Any]
             Response from Home Assistant
         """
         if not self._state.is_ready:
-            raise HomeAssistantConnectionError("WebSocket not authenticated")
+            # 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
+            # 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).
+            raise HomeAssistantCommandNotSent("WebSocket not authenticated")
 
         # Pull the wait timeout out of kwargs rather than making it a positional
         # parameter: callers unpack a ``dict[str, object]`` via
@@ -635,6 +641,13 @@ async def send_command(self, command_type: str, **kwargs: Any) -> dict[str, Any]
         try:
             await self.send_json_message(message)
         except Exception:
+            # AMBIGUOUS, not never-sent: websocket.send() raising (e.g. a
+            # ConnectionClosed detected mid-write) does NOT prove the frame was not
+            # transmitted — bytes may already be on the socket when the close surfaces.
+            # Re-raise the ORIGINAL exception unchanged so an at-most-once write
+            # consumer treats it like a post-send drop (ambiguous -> partial, never
+            # re-fired), NOT as never-sent; only the readiness guard above is provably
+            # never-sent. Still cancel the pending future so it cannot leak.
             self.cancel_pending_response(message_id)
             raise