feat(plugins): request_on_demand() / end_on_demand() -- plugins ask for the screen in-process (#768)

* feat(plugins): request_on_demand() / end_on_demand() -- plugins ask for the screen in-process

Four plugins (birdnet-go, mqtt-notifications, on-air, pomodoro-timer) take
the screen by writing the display_on_demand_request mailbox, which the
display reads once a second while the control socket is up and which stage 5
removes. This is the in-process way in that stage needed.

- BasePlugin.request_on_demand(mode=None, duration=None, pinned=False) and
  end_on_demand(), safe from any thread, go through PluginManager to
  DisplayController.submit_plugin_on_demand, which only queues (at most 32)
  and wakes the render thread through ControlServer.wake(). The render
  thread applies them in _drain_control_commands, after socket commands,
  through _handle_on_demand_request, so they land within a frame; without a
  socket, on the next pending-changes pass.
- A plugin's stop ends only its own session; a mailbox stop still ends any.
- Both answer the request id, or None with no display in the process (web
  interface, check_plugin.py), a full queue, or a mock manager -- a plugin's
  cue to write the mailbox, which the display still reads.
- docs/PLUGIN_API_REFERENCE.md documents the hasattr pattern for plugins
  that must keep working on older cores; IPC_CONTROL_SOCKET.md and the
  CHANGELOG are updated.

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

* fix(display): wire the on-demand handler only on a manager that has it

Tests and the golden traces stand in simpler plugin managers.

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

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

src/plugin_system/plugin_manager.py

@@ -15,6 +15,7 @@ import sys
 import time
 import threading
 import types
+import uuid
 from pathlib import Path
 from typing import Callable, Dict, List, NamedTuple, Optional, Any, Tuple, Union
 import logging
@@ -214,6 +215,9 @@ class PluginManager:
         # add_update_listener(). A tuple, replaced rather than mutated, so the
         # worker can iterate it without a lock.
         self._update_listeners: Tuple[Callable[[str], None], ...] = ()
+        # Where plugins' on-demand requests go: the display controller's
+        # submit_plugin_on_demand. See set_on_demand_handler().
+        self._on_demand_handler: Optional[Callable[[Dict[str, Any]], bool]] = None
         # Config changes that found the plugin's lock busy, latest per plugin,
         # with the instance they were meant for. See apply_config_change().
         self._deferred_config_changes: Dict[str, Tuple[Any, Dict[str, Any]]] = {}
@@ -1844,3 +1848,73 @@ class PluginManager:
             done = sorted(self._completed_updates)
             self._completed_updates.clear()
             return done
+
+    # -- on-demand requests from plugins -------------------------------------
+
+    def set_on_demand_handler(
+            self, handler: Optional[Callable[[Dict[str, Any]], bool]]) -> None:
+        """Route plugins' on-demand requests to ``handler`` (None: nowhere).
+
+        The display controller sets its ``submit_plugin_on_demand`` here
+        before any plugin loads. The handler takes a mailbox-shaped request
+        from any thread, queues it for the render thread and returns True,
+        or False when it could not. A plugin manager with no handler (the
+        web interface's, a test's, scripts/check_plugin.py's) has no screen
+        to give, so request_on_demand() there answers None.
+        """
+        self._on_demand_handler = handler
+
+    def request_on_demand(self, plugin_id: str, mode: Optional[str] = None,
+                          duration: Optional[float] = None,
+                          pinned: bool = False) -> Optional[str]:
+        """Ask the display to show ``plugin_id`` now. Safe from any thread.
+
+        BasePlugin.request_on_demand() lands here; see it for the arguments.
+        Returns the request id once the display has queued the request (it
+        is applied on the render thread within a frame or so), or None when
+        this process has no display to ask or its queue is full.
+        """
+        if not isinstance(plugin_id, str) or not plugin_id:
+            raise ValueError('plugin_id is required')
+        if mode is not None and (not isinstance(mode, str) or not mode):
+            raise ValueError('mode must be a non-empty string or None')
+        if duration is not None:
+            if isinstance(duration, bool) or not isinstance(duration, (int, float)):
+                raise ValueError('duration must be a number of seconds or None')
+            if not math.isfinite(duration) or duration <= 0:
+                duration = None   # the display reads these as "no limit" too
+            else:
+                duration = float(duration)
+        return self._submit_on_demand({
+            'action': 'start', 'plugin_id': plugin_id, 'mode': mode,
+            'duration': duration, 'pinned': bool(pinned)})
+
+    def end_on_demand(self, plugin_id: str) -> Optional[str]:
+        """Give the screen back, if ``plugin_id``'s on-demand session has it.
+
+        BasePlugin.end_on_demand() lands here. A session the plugin does not
+        own (the user started another plugin from the web interface, say) is
+        left alone. Returns the request id once queued, or None as
+        request_on_demand() does.
+        """
+        if not isinstance(plugin_id, str) or not plugin_id:
+            raise ValueError('plugin_id is required')
+        return self._submit_on_demand({'action': 'stop', 'plugin_id': plugin_id})
+
+    def _submit_on_demand(self, request: Dict[str, Any]) -> Optional[str]:
+        # __dict__.get: tests build bare managers with PluginManager.__new__.
+        handler = self.__dict__.get('_on_demand_handler')
+        if handler is None:
+            return None
+        request_id = str(uuid.uuid4())
+        request.update({'request_id': request_id, 'timestamp': time.time(),
+                        'source': 'plugin'})
+        try:
+            accepted = handler(request)
+        except Exception as exc:  # pylint: disable=broad-except
+            self._warn_rate_limited(
+                "on-demand-handler",
+                "The on-demand request from plugin %s failed: %r",
+                request.get('plugin_id'), exc)
+            return None
+        return request_id if accepted else None