Surface snapshot description on the DAP stopped event

Summary:
VS Code renders ``body.description`` from the most recent
``stopped`` event next to the session row in CALL STACK, so we use
it to show the snapshot's display label (index / timestamp /
exception type). Two wrinkles discovered the hard way:

1. An absent ``description`` *clears* the field rather than
   preserving the previous value, so we set it on every ``stopped``
   emission.

2. On initial launch there's a race: whatever description the
   adapter provides on the first ``stopped`` event gets overwritten
   by VS Code's own CALL STACK bootstrap. Sending a throwaway
   ``"Snapshot"`` event first, immediately followed by the real
   description event, lets the second one stick — that's what the
   user actually sees.

Plumbing:

* New ``_snapshot_display_name(snapshot)`` helper formats
  ``"Snapshot {N}/{M} — HH:MM:SS.fff UTC (ExceptionType)"``.
  Timestamps are formatted via
  ``datetime.fromtimestamp(ts, tz=datetime.timezone.utc)`` so the
  label is the same for teammates opening the same ``.pytb`` from
  different wall-clock timezones. Timestamp failures narrow to
  ``(ValueError, OSError, OverflowError, TypeError)`` and log at
  ``WARNING`` so bug reports can surface the real cause; the
  description just loses the timestamp decoration.
* ``_send_stopped_event`` gains a ``bootstrap`` kwarg; the only
  caller that sets it is ``handle_launch``, which now emits a
  bootstrap event followed by the real one. Restart / jump /
  continue / step handlers keep emitting a single real
  ``stopped`` event.

Reviewed By: aperez

Differential Revision: D103561267

fbshipit-source-id: eef79284274b0ef9cff2db0644c831f3f855b17d

Author: pdepetro

dap/session.py

@@ -14,6 +14,7 @@
 
 from __future__ import annotations
 
+import datetime
 import logging
 import os
 import re
@@ -264,6 +265,13 @@ def handle_launch(self, arguments: dict[str, Any]) -> dict[str, Any] | None:
         self._load_snapshot(start_index)
 
         self._emit_thread_events_started()
+        # Bootstrap-then-real emission pattern: VS Code overwrites the
+        # CALL STACK description on the very first ``stopped`` event of a
+        # launch, so we send a throwaway ``"Snapshot"`` first and
+        # immediately follow it with the real description. The second
+        # event is what the user actually sees. See
+        # :meth:`_send_stopped_event` for the full rationale.
+        self._send_stopped_event(bootstrap=True)
         self._send_stopped_event()
         return None
 
@@ -772,7 +780,22 @@ def _reconcile_thread_events(self, old_threads: set[int]) -> None:
                 "thread", {"reason": "started", "threadId": tid}
             )
 
-    def _send_stopped_event(self) -> None:
+    def _send_stopped_event(self, *, bootstrap: bool = False) -> None:
+        """Emit a ``stopped`` event for the current snapshot.
+
+        VS Code displays ``body.description`` in the CALL STACK panel
+        (next to the session row) and keeps whatever the most recent
+        ``stopped`` event provided — an absent ``description`` *clears*
+        the field rather than preserving the prior value. That's why we
+        set it on every emission.
+
+        The ``bootstrap`` flag is an initial-launch quirk: the very first
+        ``stopped`` event of the session is subject to a race where VS
+        Code overwrites whichever description the adapter provided.
+        Sending a bootstrap event (with a generic ``"Snapshot"`` label)
+        immediately followed by the real one lets the "real" description
+        settle in as the one the user sees.
+        """
         snapshot = self._current_snapshot
         if snapshot is None:
             return
@@ -792,12 +815,15 @@ def _send_stopped_event(self) -> None:
         has_exception = any(
             st.exception_object is not None for st in snapshot.stacktraces.values()
         )
-        body = {
+        description = "Snapshot" if bootstrap else self._snapshot_display_name(snapshot)
+        body: dict[str, Any] = {
             "reason": "exception" if has_exception else "pause",
             "threadId": thread_id,
             "preserveFocusHint": False,
             "allThreadsStopped": True,
         }
+        if description:
+            body["description"] = description
         self._dispatcher.send_event("stopped", body)
 
     # ---------------------------------------------------------------
@@ -904,6 +930,63 @@ def _require_snapshot(self) -> Snapshot:
             raise DispatchError("no current snapshot; did launch succeed?")
         return self._current_snapshot
 
+    # ---------------------------------------------------------------
+    # Display-name helpers
+    # ---------------------------------------------------------------
+
+    def _snapshot_display_name(self, snapshot: Snapshot) -> str | None:
+        """One-line description of the current snapshot.
+
+        Surfaced via the ``stopped`` event's ``description`` field, which
+        VS Code renders next to the session row in CALL STACK. Keep it
+        short — the field is a single-line label and VS Code truncates.
+
+        Default format::
+
+            Snapshot {N}/{M} — {HH:MM:SS.fff} ({ExceptionType})
+
+        Returns ``None`` to suppress the description entirely.
+        """
+        parts: list[str] = []
+        try:
+            total = self._require_reader().snapshot_count()
+        except DispatchError:
+            total = 1
+        if total > 1:
+            parts.append(f"Snapshot {self._snapshot_index + 1}/{total}")
+        else:
+            parts.append("Snapshot")
+
+        try:
+            # ``snapshot.timestamp`` is microseconds since the Unix epoch.
+            # Format using UTC so cross-timezone teams opening the same
+            # ``.pytb`` see identical labels in CALL STACK (the label
+            # otherwise depends on the viewer's local wall clock, which
+            # is confusing when correlating snapshots with server-side
+            # timestamps).
+            ts_seconds = int(snapshot.timestamp) / 1_000_000.0
+            dt = datetime.datetime.fromtimestamp(ts_seconds, tz=datetime.timezone.utc)
+            parts.append("— " + dt.strftime("%H:%M:%S.%f")[:-3] + " UTC")
+        except (ValueError, OSError, OverflowError, TypeError) as e:
+            # Concrete failure modes of ``int()`` (TypeError / ValueError),
+            # ``fromtimestamp()`` (OverflowError / OSError on Windows for
+            # out-of-range timestamps), and attribute access on a
+            # malformed Snapshot (AttributeError is intentionally NOT
+            # caught — it signals a real bug, not a bad timestamp). Log
+            # at warning so bug reports can surface the real cause; the
+            # description field just loses the timestamp decoration.
+            logger.warning(
+                "failed to format timestamp for snapshot display name: %s", e
+            )
+
+        for st in snapshot.stacktraces.values():
+            exc = st.exception_object
+            if exc is not None:
+                parts.append(f"({type(exc).__name__})")
+                break
+
+        return " ".join(parts) if parts else None
+
 
 # ---------------------------------------------------------------
 # Module-private formatting helpers

dap/tests/test_session.py

@@ -166,21 +166,29 @@ def test_launch_emits_initial_events(self) -> None:
         self._launch_with_snapshots([snap])
 
         messages = _drain_messages(self.stream)
-        # We expect: launch response, initialized, thread(s), stopped.
-        # We deliberately emit NO ``process`` event and NO ``description``
-        # on the stopped event — both surfaces (CALL STACK session row
-        # and thread row) ended up fighting for the same cell in ways
-        # VS Code wouldn't render consistently. The Tintype Snapshots
-        # sidebar group description is the single authoritative cursor
-        # surface.
+        # We expect: launch response, initialized, thread(s), two
+        # stopped events (bootstrap + real). The bootstrap carries a
+        # generic ``"Snapshot"`` description so VS Code has something to
+        # overwrite on its initial-launch race; the real event that
+        # follows sets the actual display name the user sees in the
+        # CALL STACK panel. We still emit NO ``process`` event — that
+        # surface is owned by the Tintype Snapshots sidebar.
         event_names = [m.get("event") for m in messages if m["type"] == "event"]
         self.assertIn("initialized", event_names)
         self.assertNotIn("process", event_names)
         self.assertIn("thread", event_names)
-        self.assertIn("stopped", event_names)
+        self.assertEqual(event_names.count("stopped"), 2)
 
-        stopped_event = next(m for m in messages if m.get("event") == "stopped")
-        self.assertNotIn("description", stopped_event["body"])
+        stopped_events = [m for m in messages if m.get("event") == "stopped"]
+        # First is bootstrap — generic "Snapshot" label.
+        self.assertEqual(stopped_events[0]["body"]["description"], "Snapshot")
+        # Second is the real one — must include a richer description.
+        self.assertIn("description", stopped_events[1]["body"])
+        self.assertIn("Snapshot", stopped_events[1]["body"]["description"])
+        self.assertNotEqual(
+            stopped_events[0]["body"]["description"],
+            stopped_events[1]["body"]["description"],
+        )
 
     def test_launch_fails_on_empty_snapshot_file(self) -> None:
         reader = MagicMock()
@@ -669,6 +677,30 @@ def test_tintype_jump_rejects_non_integer_index(self) -> None:
         self.assertFalse(resp["success"])
         self.assertIn("int", resp.get("message", ""))
 
+    def test_tintype_jump_rejects_bool_index(self) -> None:
+        """``bool`` is a subclass of ``int`` in Python, so a bare
+        ``isinstance(raw_index, int)`` check would happily accept
+        ``True`` / ``False`` as indices 1 / 0. The handler explicitly
+        rejects bools first; cover both values so a refactor that
+        drops the ``isinstance(raw_index, bool)`` guard doesn't silently
+        re-introduce the issue."""
+        self._first_two_snapshot_launch()
+        for seq_num, bad_index in ((410, True), (411, False)):
+            with self.subTest(index=bad_index):
+                self.stream.seek(0)
+                self.stream.truncate()
+                _send_request(
+                    self.session,
+                    self.dispatcher,
+                    seq=seq_num,
+                    command="tintypeJumpToSnapshot",
+                    arguments={"index": bad_index},
+                )
+                resp = _drain_messages(self.stream)[0]
+                self.assertFalse(resp["success"])
+                self.assertIn("int", resp.get("message", ""))
+                self.assertIn("bool", resp.get("message", ""))
+
     def test_attach_routes_through_launch_handler(self) -> None:
         """An ``attach`` request should run the full launch flow.
 
@@ -763,15 +795,18 @@ def test_restart_jumps_cursor_to_first_snapshot_and_re_emits_stopped(
         # emit one.
         self.assertNotIn("process", event_names)
 
-        # Stopped event must NOT carry a ``description`` field (would
-        # leak into the CALL STACK session row and get stuck there).
+        # Stopped event now carries the snapshot ``description``. Unlike
+        # launch, restart only emits a single stopped event (no bootstrap)
+        # — the VS Code race is an initial-launch quirk, so subsequent
+        # stops take effect on the first try.
         stopped_events = [
             m
             for m in messages
             if m.get("type") == "event" and m.get("event") == "stopped"
         ]
         self.assertEqual(len(stopped_events), 1)
-        self.assertNotIn("description", stopped_events[0]["body"])
+        self.assertIn("description", stopped_events[0]["body"])
+        self.assertIn("Snapshot", stopped_events[0]["body"]["description"])
 
         # The cursor must now be back on snapshot #0.
         self.assertEqual(self.session._snapshot_index, 0)
@@ -1374,5 +1409,116 @@ def test_set_default_exclude_frame_paths_replaces_wholesale(self) -> None:
         self.assertEqual(hints, ["normal", "normal"])
 
 
+class StoppedEventDescriptionTest(unittest.TestCase):
+    """``stopped`` events carry a ``description`` field with the snapshot's
+    display name. On launch we send a bootstrap ``"Snapshot"`` event first so
+    VS Code has something to overwrite on its initial-launch race, followed
+    by the real description event the user actually sees."""
+
+    def setUp(self) -> None:
+        self.stream = RecordingStream()
+        self.dispatcher = Dispatcher(self.stream)
+        self.session = SnapshotDebugSession(self.dispatcher)
+        self.session.wire()
+
+    def _launch_with_snapshots(self, snapshots: list[Any]) -> MagicMock:
+        reader = MagicMock()
+        reader.snapshot_count.return_value = len(snapshots)
+        reader.get_all_source_files.return_value = []
+        reader.get_all_snapshots.return_value = snapshots
+        reader.get_snapshot_at_index.side_effect = (
+            lambda i: snapshots[i] if 0 <= i < len(snapshots) else None
+        )
+        with (
+            patch("tintype.dap.session.SnapshotReader", return_value=reader),
+            patch("tintype.dap.session.os.path.isfile", return_value=True),
+        ):
+            _send_request(
+                self.session,
+                self.dispatcher,
+                seq=1,
+                command="launch",
+                arguments={"pytbPath": "/fake/snap.pytb"},
+            )
+        return reader
+
+    def test_launch_description_includes_timestamp_and_index(self) -> None:
+        st = _make_stacktrace(
+            100, [_make_frame("/a/b.py", "foo", 1, {})], thread_name="MainThread"
+        )
+        snap = _make_snapshot([st], ts=1_700_000_000_000_000)
+        self._launch_with_snapshots([snap])
+
+        stopped_events = [
+            m for m in _drain_messages(self.stream) if m.get("event") == "stopped"
+        ]
+        real = stopped_events[-1]["body"]
+        self.assertIn("description", real)
+        self.assertIn("Snapshot", real["description"])
+        # HH:MM:SS.fff pattern must show up in the real-stop description.
+        self.assertRegex(real["description"], r"\d{2}:\d{2}:\d{2}\.\d{3}")
+
+    def test_description_mentions_exception_type(self) -> None:
+        st = _make_stacktrace(
+            100,
+            [_make_frame("/a/b.py", "foo", 1, {})],
+            thread_name="MainThread",
+            exception=KeyError("missing"),
+        )
+        snap = _make_snapshot([st])
+        self._launch_with_snapshots([snap])
+
+        real = [m for m in _drain_messages(self.stream) if m.get("event") == "stopped"][
+            -1
+        ]["body"]
+        self.assertIn("KeyError", real["description"])
+
+    def test_description_updates_across_snapshot_jumps(self) -> None:
+        snap1 = _make_snapshot(
+            [
+                _make_stacktrace(
+                    100,
+                    [_make_frame("/a/b.py", "foo", 1, {})],
+                    thread_name="MainThread",
+                )
+            ],
+            ts=1_700_000_000_000_000,
+        )
+        snap2 = _make_snapshot(
+            [
+                _make_stacktrace(
+                    100,
+                    [_make_frame("/a/b.py", "foo", 2, {})],
+                    thread_name="MainThread",
+                )
+            ],
+            ts=1_700_000_005_000_000,
+        )
+        self._launch_with_snapshots([snap1, snap2])
+
+        launch_desc = [
+            m for m in _drain_messages(self.stream) if m.get("event") == "stopped"
+        ][-1]["body"]["description"]
+        self.assertIn("1/2", launch_desc)
+
+        self.stream.seek(0)
+        self.stream.truncate()
+        _send_request(
+            self.session,
+            self.dispatcher,
+            seq=50,
+            command="tintypeJumpToSnapshot",
+            arguments={"index": 1},
+        )
+        jump_events = [
+            m for m in _drain_messages(self.stream) if m.get("event") == "stopped"
+        ]
+        # Jump emits exactly one stopped event (no bootstrap).
+        self.assertEqual(len(jump_events), 1)
+        jump_desc = jump_events[0]["body"]["description"]
+        self.assertIn("2/2", jump_desc)
+        self.assertNotEqual(launch_desc, jump_desc)
+
+
 if __name__ == "__main__":
     unittest.main()