feat: session-aware game-skill + OCP playback

Per-session playback state in OVOSCommonPlaybackSkill (state events emit via
message.reply so they route to the originating session) and game_skill on the
context-gated layers (probing skill_will_match with its session). OCPCommonPlayback
deprecation is handled in #423.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: JarbasAl

ovos_workshop/skills/common_play.py

@@ -17,6 +17,8 @@
 from typing import List, Callable, Optional, Dict
 
 from ovos_bus_client import Message
+from ovos_bus_client.message import dig_for_message
+from ovos_bus_client.session import SessionManager
 from ovos_config.locations import get_xdg_cache_save_path
 from ovos_utils import camel_case_split
 from ovos_utils.log import LOG
@@ -109,15 +111,44 @@ def __init__(self, *args,
         self.__prev_handler = prev_handler
         self.__resume_handler = resume_handler
         self._stop_event = Event()
-        self._playing = Event()
-        self._paused = Event()
+        # OCP is session aware: track playing/paused state per session_id so
+        # several sessions can play (and pause/stop) independently
+        self._playing_sessions = set()
+        self._paused_sessions = set()
         # TODO new default icon
         self.skill_icon = skill_icon or ""
 
         self.ocp_matchers: Dict[str, AhocorasickNER] = {}
         self._ocp_ents: Dict[str, List[str]] = {}
         super().__init__(*args, **kwargs)
 
+    # --- per-session playback state (OCP is session aware) ------------------
+    @staticmethod
+    def get_session_id(message: Optional[Message] = None) -> str:
+        """Resolve the session id for the current/given message."""
+        message = message or dig_for_message()
+        return SessionManager.get(message).session_id
+
+    def is_playing_in(self, session_id: str) -> bool:
+        return session_id in self._playing_sessions
+
+    def is_paused_in(self, session_id: str) -> bool:
+        return session_id in self._paused_sessions
+
+    @property
+    def playing_sessions(self) -> List[str]:
+        return list(self._playing_sessions)
+
+    @property
+    def is_playing(self) -> bool:
+        """True if the *current* session is playing (back-compat property)."""
+        return self.is_playing_in(self.get_session_id())
+
+    @property
+    def is_paused(self) -> bool:
+        """True if the *current* session is paused (back-compat property)."""
+        return self.is_paused_in(self.get_session_id())
+
     def _read_skill_name_voc(self):
         """
         Load skill name aliases from a vocabulary file or generate them from the class name if not found.
@@ -456,14 +487,15 @@ def __handle_ocp_play(self, message):
         
         If a playback handler is registered, it is called with the message if accepted, and the player state is set to PLAYING. Logs an error if no playback handler is implemented.
         """
-        self._playing.set()
-        self._paused.clear()
+        sid = self.get_session_id(message)
+        self._playing_sessions.add(sid)
+        self._paused_sessions.discard(sid)
         if self.__playback_handler:
             params = signature(self.__playback_handler).parameters
             kwargs = {"message": message} if "message" in params else {}
             self.__playback_handler(**kwargs)
-            self.bus.emit(Message("ovos.common_play.player.state",
-                                  {"state": PlayerState.PLAYING}))
+            self.bus.emit(message.reply("ovos.common_play.player.state",
+                                        {"state": PlayerState.PLAYING}))
         else:
             LOG.error(f"Playback requested but {self.skill_id} handler not "
                       "implemented")
@@ -474,13 +506,14 @@ def __handle_ocp_pause(self, message):
         
         If no pause handler is implemented, logs an error.
         """
-        self._paused.set()
+        sid = self.get_session_id(message)
+        self._paused_sessions.add(sid)
         if self.__pause_handler:
             params = signature(self.__pause_handler).parameters
             kwargs = {"message": message} if "message" in params else {}
             if self.__pause_handler(**kwargs):
-                self.bus.emit(Message("ovos.common_play.player.state",
-                                      {"state": PlayerState.PAUSED}))
+                self.bus.emit(message.reply("ovos.common_play.player.state",
+                                            {"state": PlayerState.PAUSED}))
         else:
             LOG.error(f"Pause requested but {self.skill_id} handler not "
                       "implemented")
@@ -489,13 +522,14 @@ def __handle_ocp_resume(self, message):
         """
         Handles OCP resume requests by invoking the registered resume handler and updating the player state to PLAYING if successful. Logs an error if no resume handler is implemented.
         """
-        self._paused.clear()
+        sid = self.get_session_id(message)
+        self._paused_sessions.discard(sid)
         if self.__resume_handler:
             params = signature(self.__resume_handler).parameters
             kwargs = {"message": message} if "message" in params else {}
             if self.__resume_handler(**kwargs):
-                self.bus.emit(Message("ovos.common_play.player.state",
-                                      {"state": PlayerState.PLAYING}))
+                self.bus.emit(message.reply("ovos.common_play.player.state",
+                                            {"state": PlayerState.PLAYING}))
         else:
             LOG.error(f"Resume requested but {self.skill_id} handler not "
                       "implemented")
@@ -520,13 +554,14 @@ def __handle_ocp_prev(self, message):
 
     def __handle_ocp_stop(self, message):
         # for skills managing their own playback
-        if self._playing.is_set():
-            self._paused.clear()
+        sid = self.get_session_id(message)
+        if sid in self._playing_sessions:
+            self._paused_sessions.discard(sid)
             self.stop()
             self.gui.release()
-            self.bus.emit(Message("ovos.common_play.player.state",
-                                  {"state": PlayerState.STOPPED}))
-            self._playing.clear()
+            self.bus.emit(message.reply("ovos.common_play.player.state",
+                                        {"state": PlayerState.STOPPED}))
+            self._playing_sessions.discard(sid)
 
     def __handle_stop_search(self, message):
         self._stop_event.set()

ovos_workshop/skills/game_skill.py

@@ -2,15 +2,17 @@
 from typing import Optional, Dict, Iterable
 
 from ovos_bus_client.message import Message
+from ovos_bus_client.session import SessionManager
 from ovos_bus_client.util import get_message_lang
 from ovos_utils.ocp import MediaType, MediaEntry, PlaybackType, Playlist, PlayerState
 from ovos_utils.parse import match_one, MatchStrategy
 
 from ovos_workshop.decorators import ocp_featured_media, ocp_search
 from ovos_workshop.skills.common_play import OVOSCommonPlaybackSkill
+from ovos_workshop.skills.converse import ConversationalSkill
 
 
-class OVOSGameSkill(OVOSCommonPlaybackSkill):
+class OVOSGameSkill(OVOSCommonPlaybackSkill, ConversationalSkill):
     """ To integrate with the OpenVoiceOS Common Playback framework
 
     "play" intent is shared with media and managed by OCP pipeline
@@ -82,13 +84,8 @@ def _ocp_search(self, phrase: str, media_type: MediaType) -> Iterable[MediaEntry
             entry.match_confidence = conf
             yield entry
 
-    @property
-    def is_playing(self) -> bool:
-        return self._playing.is_set()
-
-    @property
-    def is_paused(self) -> bool:
-        return self._paused.is_set()
+    # is_playing / is_paused (and per-session variants) are provided by
+    # OVOSCommonPlaybackSkill and are session aware.
 
     @abc.abstractmethod
     def on_play_game(self):
@@ -119,13 +116,14 @@ def on_load_game(self):
 
     def stop_game(self):
         """to be called by skills if they want to stop game programatically"""
-        if self.is_playing:
-            self._paused.clear()
+        sid = self.get_session_id()
+        if self.is_playing_in(sid):
+            self._paused_sessions.discard(sid)
             self.gui.release()
             self.log.debug("changing OCP state: PlayerState.STOPPED ")
             self.bus.emit(Message("ovos.common_play.player.state",
                                   {"state": PlayerState.STOPPED}))
-            self._playing.clear()
+            self._playing_sessions.discard(sid)
             self.on_stop_game()
             return True
         return False
@@ -134,17 +132,35 @@ def stop(self) -> bool:
         """NOTE: not meant to be called by the skill, this is a callback"""
         return self.stop_game()
 
+    # pipelines that are NOT a real intent match (they should not count when a
+    # game asks "would an intent be selected for this utterance?")
+    _NON_INTENT_PIPELINES = ("converse", "fallback", "common_query", "stop")
+
     def calc_intent(self, utterance: str, lang: str, timeout=1.0) -> Optional[Dict[str, str]]:
-        """helper to check what intent would be selected by ovos-core"""
+        """helper to check what intent would be selected by ovos-core
+
+        NOTE: converse, common_query, stop and fallbacks are intentionally
+        ignored here - this reports only a genuine intent-parser match (adapt /
+        padatious / padacioso), which is what gates whether a layer intent will
+        fire for the utterance.
+        """
         # let's see what intent ovos-core will assign to the utterance
-        # NOTE: converse, common_query and fallbacks are not included in this check
         response = self.bus.wait_for_response(Message("intent.service.intent.get",
                                                       {"utterance": utterance, "lang": lang}),
                                               "intent.service.intent.reply",
                                               timeout=timeout)
         if not response:
             return None
-        return response.data["intent"]
+        intent = response.data.get("intent")
+        if not intent:
+            return None
+        # the full pipeline runs converse first; a game is "active" so converse
+        # would always claim the utterance. Ignore non-intent-parser pipelines so
+        # this reflects whether a *layer intent* would actually match.
+        pipeline = (intent.get("intent_service") or "").lower()
+        if any(p in pipeline for p in self._NON_INTENT_PIPELINES):
+            return None
+        return intent
 
 
 class ConversationalGameSkill(OVOSGameSkill):
@@ -158,16 +174,20 @@ def on_load_game(self):
         self.speak_dialog("cant_load_game")
 
     def on_pause_game(self):
-        """called by ocp_pipeline on 'pause' if game is being played"""
-        self._paused.set()
+        """called by ocp_pipeline on 'pause' if game is being played
+
+        NOTE: the per-session paused state is already set by the OCP framework
+        before this handler runs."""
         self.acknowledge()
         # individual skills can change default value if desired
         if self.settings.get("pause_dialog", False):
             self.speak_dialog("game_pause")
 
     def on_resume_game(self):
-        """called by ocp_pipeline on 'resume/unpause' if game is being played and paused"""
-        self._paused.clear()
+        """called by ocp_pipeline on 'resume/unpause' if game is being played and paused
+
+        NOTE: the per-session paused state is already cleared by the OCP
+        framework before this handler runs."""
         self.acknowledge()
         # individual skills can change default value if desired
         if self.settings.get("pause_dialog", False):
@@ -183,10 +203,14 @@ def on_stop_game(self):
         auto-save may be implemented here"""
 
     @abc.abstractmethod
-    def on_game_command(self, utterance: str, lang: str):
+    def on_game_command(self, utterance: str, lang: str,
+                        message: Optional[Message] = None):
         """pipe user input that wasnt caught by intents to the game
         do any intent matching or normalization here
         don't forget to self.speak the game output too!
+
+        @param message: the utterance Message (carries the session); use it to
+            key per-session game state so several sessions can play at once.
         """
 
     def on_abandon_game(self):
@@ -198,6 +222,34 @@ def on_abandon_game(self):
         on_game_stop will be called after this handler"""
 
     # converse
+    def can_converse(self, message: Message) -> bool:
+        """A game wants to converse while it is being played (or paused), EXCEPT
+        when one of its own context-gated layer intents would match the
+        utterance - those must be handled by the intent pipeline (adapt), not
+        swallowed by converse.
+
+        This lets the converse pipeline route only the free-form input that no
+        layer intent matched into `on_game_command`.
+        """
+        if not (self.is_playing or self.is_paused):
+            return False
+        try:
+            utterance = message.data.get("utterances", [""])[0]
+            lang = get_message_lang(message)
+            # The converse pipeline runs *before* adapt, so while a game is
+            # active converse would otherwise always claim the utterance and
+            # prevent layer intents from matching. Probe the intent service
+            # (read-only) excluding the converse stage (to avoid re-entering
+            # this very check); if one of our context-gated layer intents would
+            # match, let adapt handle it instead of swallowing it here.
+            if utterance and self.skill_will_match(
+                    utterance, lang, exclude_pipeline=["ovos-converse-pipeline-plugin"],
+                    session=SessionManager.get(message)):
+                return False
+        except Exception as e:
+            self.log.debug(f"can_converse intent-gate failed: {e}")
+        return True
+
     def skill_will_trigger(self, utterance: str, lang: str, skill_id: Optional[str] = None, timeout=0.8) -> bool:
         """helper to check if this skill would be selected by ovos-core with the given utterance
 
@@ -230,15 +282,18 @@ def _async_cmd(self, message: Message):
         utterance = message.data["utterances"][0]
         lang = get_message_lang(message)
         self.log.debug(f"Piping utterance to game: {utterance}")
-        self.on_game_command(utterance, lang)
+        self.on_game_command(utterance, lang, message)
 
     def converse(self, message: Message) -> bool:
         try:
             utterance = message.data["utterances"][0]
             lang = get_message_lang(message)
-            # let the user implemented intents do the job if they can handle the utterance
-            # otherwise pipe utterance to the game handler
-            if self.skill_will_trigger(utterance, lang):
+            # let the user implemented (context-gated) intents do the job if they
+            # can handle the utterance, otherwise pipe utterance to the game
+            # handler. Probe excludes converse to avoid re-entrancy.
+            if self.skill_will_match(utterance, lang,
+                                     exclude_pipeline=["ovos-converse-pipeline-plugin"],
+                                     session=SessionManager.get(message)):
                 self.log.debug("Skill intent will trigger, don't pipe utterance to game")
                 return False
 

test/unittests/skills/test_common_play_extended.py

@@ -89,13 +89,16 @@ def test_skill_icon_default_empty(self) -> None:
     def test_search_handlers_initially_empty(self) -> None:
         self.assertIsInstance(self.skill._search_handlers, list)
 
-    def test_playing_event_not_set(self) -> None:
-        """_playing event is not set on init (not actively playing)."""
-        self.assertFalse(self.skill._playing.is_set())
-
-    def test_paused_event_not_set(self) -> None:
-        """_paused event is not set on init."""
-        self.assertFalse(self.skill._paused.is_set())
+    def test_no_playing_sessions_on_init(self) -> None:
+        """No session is marked as playing on init (not actively playing)."""
+        self.assertEqual(self.skill._playing_sessions, set())
+        self.assertEqual(self.skill.playing_sessions, [])
+        self.assertFalse(self.skill.is_playing)
+
+    def test_no_paused_sessions_on_init(self) -> None:
+        """No session is marked as paused on init."""
+        self.assertEqual(self.skill._paused_sessions, set())
+        self.assertFalse(self.skill.is_paused)
 
     def test_register_media_type(self) -> None:
         """register_media_type adds a new type to supported_media."""

test/unittests/skills/test_game_skill_extended.py

@@ -27,19 +27,24 @@ class ConcreteGameSkill(OVOSGameSkill):
         """Minimal concrete subclass implementing all abstract methods."""
 
         def on_play_game(self):
-            self._playing.set()
+            sid = self.get_session_id()
+            self._playing_sessions.add(sid)
+            self._paused_sessions.discard(sid)
 
         def on_pause_game(self):
-            self._paused.set()
-            self._playing.clear()
+            sid = self.get_session_id()
+            self._paused_sessions.add(sid)
+            self._playing_sessions.discard(sid)
 
         def on_resume_game(self):
-            self._paused.clear()
-            self._playing.set()
+            sid = self.get_session_id()
+            self._paused_sessions.discard(sid)
+            self._playing_sessions.add(sid)
 
         def on_stop_game(self):
-            self._playing.clear()
-            self._paused.clear()
+            sid = self.get_session_id()
+            self._playing_sessions.discard(sid)
+            self._paused_sessions.discard(sid)
 
         def on_save_game(self):
             pass
@@ -158,13 +163,13 @@ def test_stop_game_when_not_playing_returns_false(self) -> None:
 
     def test_stop_game_when_playing_returns_true(self) -> None:
         """stop_game returns True when game is playing."""
-        self.skill._playing.set()
+        self.skill._playing_sessions.add(self.skill.get_session_id())
         result = self.skill.stop_game()
         self.assertTrue(result)
 
     def test_stop_game_clears_playing(self) -> None:
-        """stop_game clears the _playing event."""
-        self.skill._playing.set()
+        """stop_game clears the per-session playing state."""
+        self.skill._playing_sessions.add(self.skill.get_session_id())
         self.skill.stop_game()
         self.assertFalse(self.skill.is_playing)