feat: session-aware game-skill + OCP playback (stacked on IntentLayers)

Per-session playback state in OVOSCommonPlaybackSkill (state emits via
message.reply so they route to the originating session) and game_skill adopting
the context-gated layers. OCPCommonPlaybackSkill deprecation is handled separately
in #423.

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

Author: JarbasAl

.claude/settings.local.json

@@ -0,0 +1,31 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(PYTHONPATH=/home/miro/AgentWorkspaces/OpenVoiceOS/core/ovos-core pip install padacioso -q)",
+      "Bash(PYTHONPATH=/home/miro/AgentWorkspaces/OpenVoiceOS/core/ovos-core python3 -c \"from ovoscope import get_minicroft, End2EndTest; print\\('ok'\\)\")",
+      "Bash(python3 -c \"import padacioso; print\\(padacioso.__file__\\)\")",
+      "Bash(pip install:*)",
+      "Bash(python3 -m pytest test/unittests/skills/test_base.py::TestOVOSSkill::test_ask_yesno test/unittests/skills/test_base.py::TestOVOSSkill::test_ask_selection -v -p no:ovoscope)",
+      "Bash(python3 -m pytest test/unittests/test_ask_e2e.py -v -p no:ovoscope)",
+      "Bash(git add:*)",
+      "Bash(git commit -m ':*)",
+      "Bash(git push:*)",
+      "Bash(python3 -c \"from ovos_option_matcher_fuzzy import FuzzyOptionMatcherPlugin; import inspect; print\\(inspect.signature\\(FuzzyOptionMatcherPlugin.match_option\\)\\)\")",
+      "Bash(python3 -c \"from ovos_plugin_manager.templates.option_matcher import OptionMatcherEngine; import inspect; print\\(inspect.signature\\(OptionMatcherEngine.match_option\\)\\)\")",
+      "Bash(python3:*)",
+      "Bash(git:*)",
+      "Bash(gh pr:*)",
+      "Bash(gh run:*)",
+      "Bash(PYTHONPATH=/home/miro/AgentWorkspaces/OpenVoiceOS/core/ovos-core python3 -m pytest test/unittests/test_ask_e2e.py -v --timeout=30)",
+      "Bash(/home/miro/AgentWorkspaces/OpenVoiceOS/.venv/bin/python -m pytest test/unittests/test_ask_e2e.py -v -p no:ovoscope --timeout=30)",
+      "Bash(/home/miro/AgentWorkspaces/OpenVoiceOS/.venv/bin/pip install:*)",
+      "Bash(/home/miro/AgentWorkspaces/OpenVoiceOS/.venv/bin/python -m pytest test/unittests/test_ask_e2e.py -v --timeout=30)",
+      "Bash(/home/miro/AgentWorkspaces/OpenVoiceOS/.venv/bin/python -m ensurepip -q)",
+      "Bash(/home/miro/AgentWorkspaces/OpenVoiceOS/.venv/bin/python -m pip install pytest pytest-timeout -q)",
+      "Bash(/home/miro/AgentWorkspaces/OpenVoiceOS/.venv/bin/python -m ensurepip)",
+      "Bash(/home/miro/AgentWorkspaces/OpenVoiceOS/.venv/bin/python -m pip install -e \".[test]\" -q)",
+      "Bash(/home/miro/AgentWorkspaces/OpenVoiceOS/.venv/bin/python -m pytest test/unittests/test_ask_e2e.py -v --timeout=60 -s)",
+      "Bash(/home/miro/AgentWorkspaces/OpenVoiceOS/.venv/bin/python:*)"
+    ]
+  }
+}

AGENTS.md

@@ -0,0 +1,52 @@
+# AGENTS.md — ovos-workshop
+
+Base classes, decorators, and helpers for building OpenVoiceOS skills and applications. This is the framework every OVOS skill subclasses (`OVOSSkill`, `FallbackSkill`, `OVOSCommonPlaybackSkill`, etc.) plus the skill loader/launcher.
+
+## Setup
+
+```bash
+pip install -e .
+pip install -e .[test]   # adds ovos-core, ovoscope, pytest, pytest-cov, ovos-translate-server-plugin
+```
+
+## Test
+
+```bash
+pytest test/unittests
+pytest test/end2end
+```
+
+The end2end suite expects the bundled fixture skills under `test/end2end/session/` to be installed first (see `coverage.yml` for the exact list: `skill-ovos-hello-world`, `skill-ovos-fallback-unknown`, `skill-ovos-fallback-unknownv1`, `skill-converse_test`).
+
+## Lint/Typecheck
+
+Lint runs in CI via the gh-automations `lint.yml@dev` reusable workflow. No local lint/typecheck config is committed.
+
+## Layout
+
+- `ovos_workshop/skills/` — skill base classes: `ovos.py` (`OVOSSkill`, the canonical base), `fallback.py`, `common_play.py` (`OVOSCommonPlaybackSkill`), `game_skill.py`, `active.py`, `passive.py`, `auto_translatable.py` (`UniversalSkill`/`UniversalFallback`), `idle_display_skill.py`, `converse.py`, `intent_provider.py`, `api.py`, `layers.py`.
+- `ovos_workshop/decorators/` — `intent_handler`/context decorators (`__init__.py`), `killable.py`, `layers.py`, `ocp.py`, `fallback_handler.py`.
+- `ovos_workshop/skill_launcher.py` — loads skill plugins/dirs (`find_skill_plugins`, `get_skill_directories`), defines `SKILL_BASE_CLASSES`; provides the `ovos-skill-launcher` console script.
+- `ovos_workshop/app.py` — `OVOSAbstractApplication` (a skill that can run without the intent service).
+- `ovos_workshop/intents.py`, `resource_files.py`, `settings.py`, `filesystem.py`, `permissions.py`, `backwards_compat.py` — supporting subsystems.
+- `test/unittests`, `test/end2end` — test suites.
+
+Console-script entry point (this repo): `ovos-skill-launcher`. Downstream skills register under the `opm.skills` entry-point group and subclass these base classes — this repo defines that contract.
+
+## Conventions
+
+- Branches: work on `dev`, stable on `master`. Never `main`.
+- Never edit `ovos_workshop/version.py` — gh-automations bumps semver from conventional-commit prefixes (`feat:` / `fix:` / `feat!:`).
+- New repos private by default.
+- Commit identity: JarbasAi <jarbasai@mailfence.com>.
+- Reference `OpenVoiceOS/gh-automations` reusable workflows at `@dev`.
+- No Neon / `neon-*` references.
+- No meta-commentary in docs/commits/code (no history, no dates).
+- CI is provided by OpenVoiceOS/gh-automations.
+
+## Gotchas
+
+- Test directory is `test/` (not `tests/`); CI `test_path` is `test/unittests`.
+- `coverage.yml` is hand-rolled (not the gh-automations `coverage.yml@dev` reusable workflow) — it pins Python 3.14 in the runner while `build-tests` and the package target 3.9; touch with care.
+- `backwards_compat.py` carries deprecated shims explicitly marked for removal; do not rely on it for new code.
+- Many `# TODO` markers in `intents.py` and `common_play.py` reflect upstream OCP limitations, not quick fixes.

TODO.md

@@ -0,0 +1,33 @@
+# TODO — ovos-workshop
+
+## Open issues
+
+- [ ] #380 Dependency Dashboard
+- [ ] #370 Incomplete OCP keyword deregistration functionality in OVOSCommonPlaybackSkill
+- [ ] #367 Improve CSV parsing in load_ocp_keyword_from_csv method
+- [ ] #331 Converse does not respect mute
+- [ ] #203 feat - verbosity level
+- [ ] #202 feat - "local_only" kwarg in intent decorators
+- [ ] #194 settings changed decorator
+- [ ] #191 missing tests for conversational intents
+- [ ] #175 OVOSSkill full CRUD for events
+- [ ] #56 Proposal: adding metadata to dialog files
+
+## Gaps
+
+- [ ] `coverage.yml` is a hand-rolled workflow rather than the gh-automations `coverage.yml@dev` reusable workflow; it pins runner Python 3.14 while the package supports 3.9.
+- [ ] Committed scratch artifact `downstream_report.txt` is tracked in the repo root.
+- [ ] `ovos_workshop.egg-info/` present in the working tree (not tracked; confirm `.gitignore` covers it).
+- [ ] Missing tests for conversational intents (tracked as #191).
+
+## Code TODOs
+
+- [ ] `ovos_workshop/intents.py:98` at least one should support aliases
+- [ ] `ovos_workshop/intents.py:119` CLIENT_ENTITY_NAME magic string unclear
+- [ ] `ovos_workshop/intents.py:404` consider properties with setters to prevent duplicates
+- [ ] `ovos_workshop/intents.py:521` will create duplicates of already detached intents
+- [ ] `ovos_workshop/backwards_compat.py:8` remove this file in next stable release
+- [ ] `ovos_workshop/skills/common_play.py:201` aliases per lang
+- [ ] `ovos_workshop/skills/common_play.py:358` not yet supported upstream
+- [ ] `ovos_workshop/skills/common_play.py:373` wont accept methods with killable_event
+- [ ] `ovos_workshop/skills/idle_display_skill.py:65` rm in ovos-gui, only for compat

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()