feat(device_utils): surface WebSocket errors on UtilResponse (closes #29)

UtilResponse gains ws_error / ws_close_code so a consumer can distinguish a
clean WebSocket completion from an errored, abnormally-closed, or
never-started one (previously the error was only logged and discarded):
- on_error records the first transport error (was a discard-only lambda);
- _on_close records the close code and flags a non-1000 abnormal close;
- start_with_trigger records ws_error when the WS factory returns None or
  raises during setup.

Additive and backward-compatible: ws_error stays None on a clean completion
or a trigger-only command. Adds unit tests for each path.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: tmunzer-AIDE

src/mistapi/device_utils/__tools/__ws_wrapper.py

@@ -219,6 +219,13 @@ def __init__(
         self.ws_required: bool = False
         self.ws_data: list[str] = []
         self.ws_raw_events: list[str] = []
+        # Set when the WebSocket leg did NOT complete cleanly (transport error,
+        # abnormal close, or failure to start). Stays None on a clean completion or
+        # a trigger-only command, so `ws_error is not None` is a reliable
+        # "did not cleanly confirm" signal for consumers. ws_close_code records the
+        # WebSocket close status code when one was received.
+        self.ws_error: str | None = None
+        self.ws_close_code: int | None = None
         self._queue: queue.Queue[str | None] = queue.Queue()
         self._closed = threading.Event()
         self._await_timeout: float | None = None
@@ -349,8 +356,22 @@ def _on_open(self):
         # Start the max duration timer
         self._timeout_handler(Timer.MAX_DURATION, TimerAction.START)
 
+    def _on_error(self, error):
+        LOGGER.error("Error: %s", error)
+        # Record the first WebSocket transport error so a consumer can tell an
+        # errored stream from a clean one (otherwise the error is only logged).
+        if self.util_response.ws_error is None:
+            self.util_response.ws_error = str(error)
+
     def _on_close(self, code, msg):
         LOGGER.info("WebSocket closed: %s - %s", code, msg)
+        self.util_response.ws_close_code = code
+        # An abnormal close (anything other than a normal 1000 / no-status close)
+        # is recorded as an error so a clean completion is distinguishable.
+        if code is not None and code != 1000 and self.util_response.ws_error is None:
+            self.util_response.ws_error = (
+                f"WebSocket closed abnormally (code {code}): {msg}"
+            )
         self._stop_all_timers()
         self.util_response._queue.put(None)  # sentinel for receive()
         self.util_response._closed.set()  # signal completion
@@ -507,7 +528,7 @@ def start(self, ws) -> UtilResponse:
         """
         self.ws = ws
         ws.on_message(self._handle_message)
-        ws.on_error(lambda error: LOGGER.error("Error: %s", error))
+        ws.on_error(self._on_error)
         ws.on_close(self._on_close)
         ws.on_open(self._on_open)
 
@@ -564,6 +585,9 @@ def _run():
                         self.start(ws)
                         return  # start() / _on_close manages _closed
                     LOGGER.error("WS factory returned None")
+                    # The WebSocket leg was expected but never started; record it so
+                    # consumers don't mistake this for a clean trigger-only completion.
+                    self.util_response.ws_error = "WebSocket factory returned None"
                 else:
                     LOGGER.error(
                         "Failed to trigger command: %s - %s",
@@ -572,6 +596,8 @@ def _run():
                     )
             except Exception as e:
                 LOGGER.error("Error during trigger: %s", e)
+                if self.util_response.ws_error is None:
+                    self.util_response.ws_error = f"WebSocket setup error: {e}"
             # Mark done (failure or WS factory returned None)
             self.util_response._queue.put(None)
             self.util_response._closed.set()

tests/unit/test_ws_wrapper.py

@@ -183,3 +183,77 @@ def test_render_trims_trailing_spaces_and_empty_lines(self) -> None:
         rendered = s.render()
         assert rendered == "A"
         assert not rendered.endswith(" ")
+
+
+# ------------------------------------------------------------------
+# ws_error / ws_close_code (issue #29): let consumers distinguish a clean
+# WebSocket completion from an errored / abnormal / never-started one.
+# ------------------------------------------------------------------
+class TestUtilResponseWsErrorDefaults:
+    def test_defaults_are_none(self) -> None:
+        r = UtilResponse()
+        assert r.ws_error is None
+        assert r.ws_close_code is None
+
+
+class TestOnError:
+    def test_records_first_error(self) -> None:
+        w = _make_wrapper()
+        w._on_error(Exception("boom"))
+        assert w.util_response.ws_error == "boom"
+
+    def test_does_not_overwrite_existing(self) -> None:
+        w = _make_wrapper()
+        w._on_error(Exception("first"))
+        w._on_error(Exception("second"))
+        assert w.util_response.ws_error == "first"
+
+
+class TestOnClose:
+    def test_normal_close_is_clean(self) -> None:
+        w = _make_wrapper()
+        w._on_close(1000, "")
+        assert w.util_response.ws_close_code == 1000
+        assert w.util_response.ws_error is None
+
+    def test_abnormal_close_sets_error(self) -> None:
+        w = _make_wrapper()
+        w._on_close(1006, "abnormal closure")
+        assert w.util_response.ws_close_code == 1006
+        assert "1006" in (w.util_response.ws_error or "")
+
+    def test_no_status_close_is_not_flagged(self) -> None:
+        w = _make_wrapper()
+        w._on_close(None, "")
+        assert w.util_response.ws_close_code is None
+        assert w.util_response.ws_error is None
+
+
+class TestStartWithTriggerWsError:
+    """A WS-backed command whose WebSocket never starts must record ws_error so it
+    is not mistaken for a clean trigger-only completion."""
+
+    @staticmethod
+    def _trigger(status: int = 200, data=None):
+        return Mock(status_code=status, data=data if data is not None else {})
+
+    def test_ws_factory_returning_none_sets_ws_error(self) -> None:
+        w = _make_wrapper()
+        w.start_with_trigger(
+            trigger_fn=lambda: self._trigger(),
+            ws_factory_fn=lambda trigger: None,
+        )
+        w.util_response.wait(timeout=5)
+        assert w.util_response.done
+        assert w.util_response.ws_required is False  # WS never started
+        assert w.util_response.ws_error == "WebSocket factory returned None"
+
+    def test_ws_factory_raising_sets_ws_error(self) -> None:
+        def boom(trigger):
+            raise RuntimeError("factory kaboom")
+
+        w = _make_wrapper()
+        w.start_with_trigger(trigger_fn=lambda: self._trigger(), ws_factory_fn=boom)
+        w.util_response.wait(timeout=5)
+        assert w.util_response.done
+        assert "factory kaboom" in (w.util_response.ws_error or "")