refactor study voice bridge boundary

Author: MomiJiSan

app/agent_server.py

@@ -13,6 +13,7 @@
 
 import mimetypes
 import json
+from collections.abc import Mapping
 mimetypes.add_type("application/javascript", ".js")
 import asyncio
 import uuid
@@ -1648,36 +1649,97 @@ async def _emit_agent_status_update(lanlan_name: Optional[str] = None) -> None:
         pass
 
 
+VOICE_TRANSCRIPT_CUSTOM_EVENT_TYPE = "voice_transcript"
+VOICE_TRANSCRIPT_CUSTOM_EVENT_TIMEOUT_SECONDS = 1.0
+
+
+def _voice_bridge_noop(reason: str, **extra: object) -> Dict[str, Any]:
+    return {
+        "action": "noop",
+        "reason": str(reason or "noop"),
+        **extra,
+    }
+
+
+def _voice_transcript_request_has_text(event: Mapping[str, object] | None) -> bool:
+    if not isinstance(event, Mapping):
+        return False
+    return bool(str(event.get("transcript") or "").strip())
+
+
+def _voice_transcript_custom_event_args(event: Mapping[str, object]) -> Dict[str, object]:
+    metadata = event.get("metadata")
+    return {
+        "transcript": str(event.get("transcript") or "").strip(),
+        "lanlan_name": str(event.get("lanlan_name") or ""),
+        "metadata": dict(metadata) if isinstance(metadata, Mapping) else {},
+    }
+
+
+def _voice_bridge_action_from_dispatch_results(dispatch_results: object) -> Dict[str, Any]:
+    if not isinstance(dispatch_results, list) or not dispatch_results:
+        return _voice_bridge_noop("no_subscribers")
+
+    failure_count = 0
+    for item in dispatch_results:
+        if not isinstance(item, Mapping):
+            continue
+        if not bool(item.get("success")):
+            failure_count += 1
+            continue
+        result = item.get("result")
+        if not isinstance(result, Mapping):
+            continue
+        action = str(result.get("action") or "").strip()
+        if not action:
+            continue
+        payload: Dict[str, Any] = dict(result)
+        payload["action"] = action
+        plugin_id = str(item.get("plugin_id") or "").strip()
+        if plugin_id:
+            payload.setdefault("source_plugin", plugin_id)
+        source_event_id = str(item.get("event_id") or "").strip()
+        if source_event_id:
+            payload.setdefault("source_event_id", source_event_id)
+        return payload
+
+    return _voice_bridge_noop("no_handler_result", failures=failure_count)
+
+
+async def _dispatch_voice_transcript_custom_event(
+    event: Mapping[str, object],
+) -> Dict[str, Any]:
+    from plugin.server.application.plugins.dispatch_service import PluginDispatchService
+
+    dispatch_results = await PluginDispatchService().trigger_custom_event_subscribers(
+        event_type=VOICE_TRANSCRIPT_CUSTOM_EVENT_TYPE,
+        args=_voice_transcript_custom_event_args(event),
+        timeout=VOICE_TRANSCRIPT_CUSTOM_EVENT_TIMEOUT_SECONDS,
+    )
+    return _voice_bridge_action_from_dispatch_results(dispatch_results)
+
+
 async def _handle_voice_transcript_request(event: Dict[str, Any]) -> None:
     event_id = str((event or {}).get("event_id") or "")
     lanlan_name = (event or {}).get("lanlan_name")
-    result: Dict[str, Any] = {"action": "noop", "reason": "unavailable"}
+    result: Dict[str, Any] = _voice_bridge_noop("unavailable")
 
     try:
-        from plugin.server.application.plugins import voice_transcript_bridge
-
-        if not voice_transcript_bridge.voice_transcript_request_has_text(event):
-            result = voice_transcript_bridge.voice_transcript_noop("empty_transcript")
+        if not _voice_transcript_request_has_text(event):
+            result = _voice_bridge_noop("empty_transcript")
         elif not Modules.analyzer_enabled:
-            result = voice_transcript_bridge.voice_transcript_noop("agent_disabled")
+            result = _voice_bridge_noop("agent_disabled")
         elif not Modules.agent_flags.get("user_plugin_enabled", False):
-            result = voice_transcript_bridge.voice_transcript_noop(
-                "user_plugin_disabled"
-            )
+            result = _voice_bridge_noop("user_plugin_disabled")
         else:
             lifecycle_ready = bool(Modules.plugin_lifecycle_started)
             if not lifecycle_ready:
                 lifecycle_ready = await _ensure_plugin_lifecycle_started()
 
             if not lifecycle_ready:
-                result = voice_transcript_bridge.voice_transcript_noop(
-                    "plugin_lifecycle_start_failed"
-                )
+                result = _voice_bridge_noop("plugin_lifecycle_start_failed")
             else:
-                result = await voice_transcript_bridge.resolve_voice_transcript_request(
-                    event,
-                    timeout=voice_transcript_bridge.VOICE_TRANSCRIPT_DISPATCH_TIMEOUT_SECONDS,
-                )
+                result = await _dispatch_voice_transcript_custom_event(event)
     except Exception as exc:
         logger.debug(
             "[VoiceBridge] plugin dispatch failed: event_id=%s lanlan=%s err=%s",

plugin/plugins/study_companion/__init__.py

@@ -78,6 +78,13 @@
 from .ui_api import build_open_ui_payload
 from .ui_api import build_contribution_settings_payload, build_knowledge_map_payload
 from .ui_api import build_habit_dashboard_payload, build_pomodoro_status_payload
+from .voice_contracts import (
+    VOICE_TRANSCRIPT_EVENT_ID,
+    VOICE_TRANSCRIPT_EVENT_TYPE,
+    voice_transcript_cancel_response,
+    voice_transcript_noop,
+    voice_transcript_prime_context,
+)
 from .voice_filter import VoiceFilter, _derive_subject, build_context_for_catgirl
 
 
@@ -744,8 +751,8 @@ def _screen_classification_context(self) -> dict[str, Any]:
         return dict(self._state.last_screen_classification)
 
     @custom_event(
-        event_type="voice_transcript",
-        id="handle_transcript",
+        event_type=VOICE_TRANSCRIPT_EVENT_TYPE,
+        id=VOICE_TRANSCRIPT_EVENT_ID,
         name="Handle study voice transcript",
         description="Filter realtime study voice transcripts and return a voice-session action.",
         input_schema={
@@ -768,13 +775,13 @@ async def handle_voice_transcript(
     ):
         text = str(transcript or "").strip()
         if not text:
-            return Ok({"action": "noop", "reason": "empty_transcript"})
+            return Ok(voice_transcript_noop("empty_transcript"))
         metadata_payload = metadata if isinstance(metadata, dict) else {}
         session_key = _voice_session_key(lanlan_name, metadata_payload)
 
         async with self._lock:
             if self._state.status != STATUS_READY:
-                return Ok({"action": "noop", "reason": "not_ready"})
+                return Ok(voice_transcript_noop("not_ready"))
             state_snapshot_payload = self._state.to_dict()
 
         # Voice filtering only needs a point-in-time view; avoid holding the
@@ -806,9 +813,9 @@ async def handle_voice_transcript(
             extra_names=[lanlan_name],
         )
         if filter_result is None:
-            return Ok({"action": "noop", "reason": "not_matched"})
+            return Ok(voice_transcript_noop("not_matched"))
         if not bool(filter_result.get("should_relay")):
-            return Ok({"action": "cancel_response", "filter": dict(filter_result)})
+            return Ok(voice_transcript_cancel_response(filter_payload=filter_result))
 
         state_snapshot = SimpleNamespace(**state_snapshot_payload)
         context_text = build_context_for_catgirl(
@@ -819,20 +826,18 @@ async def handle_voice_transcript(
         ).strip()
         if not context_text:
             return Ok(
-                {
-                    "action": "noop",
-                    "reason": "empty_context",
-                    "filter": dict(filter_result),
-                }
+                voice_transcript_noop(
+                    "empty_context",
+                    filter=dict(filter_result),
+                )
             )
         return Ok(
-            {
-                "action": "prime_context",
-                "context": context_text,
-                "skipped": False,
-                "filter": dict(filter_result),
-                "lanlan_name": str(lanlan_name or ""),
-            }
+            voice_transcript_prime_context(
+                context_text,
+                skipped=False,
+                filter_payload=filter_result,
+                lanlan_name=str(lanlan_name or ""),
+            )
         )
 
     async def _update_screen_classification(

…r/application/plugins/event_contracts.py …ugins/study_companion/voice_contracts.pyplugin/server/application/plugins/event_contracts.py renamed to plugin/plugins/study_companion/voice_contracts.py plugin/server/application/plugins/event_contracts.py renamed to plugin/plugins/study_companion/voice_contracts.py

@@ -5,6 +5,7 @@
 from typing import Any
 
 VOICE_TRANSCRIPT_EVENT_TYPE = "voice_transcript"
+VOICE_TRANSCRIPT_EVENT_ID = "handle_transcript"
 
 VOICE_TRANSCRIPT_ACTION_NOOP = "noop"
 VOICE_TRANSCRIPT_ACTION_CANCEL_RESPONSE = "cancel_response"
@@ -21,6 +22,49 @@
 }
 
 
+def voice_transcript_noop(reason: str, **extra: object) -> dict[str, object]:
+    payload = dict(extra)
+    payload.update(
+        {
+            "action": VOICE_TRANSCRIPT_ACTION_NOOP,
+            "reason": str(reason or "noop"),
+        }
+    )
+    return payload
+
+
+def voice_transcript_cancel_response(
+    *,
+    filter_payload: Mapping[str, object] | None = None,
+    **extra: object,
+) -> dict[str, object]:
+    payload: dict[str, object] = dict(extra)
+    payload["action"] = VOICE_TRANSCRIPT_ACTION_CANCEL_RESPONSE
+    if filter_payload is not None:
+        payload["filter"] = dict(filter_payload)
+    return payload
+
+
+def voice_transcript_prime_context(
+    context: str,
+    *,
+    skipped: bool = False,
+    filter_payload: Mapping[str, object] | None = None,
+    **extra: object,
+) -> dict[str, object]:
+    payload: dict[str, object] = dict(extra)
+    payload.update(
+        {
+            "action": VOICE_TRANSCRIPT_ACTION_PRIME_CONTEXT,
+            "context": str(context or "").strip(),
+            "skipped": bool(skipped),
+        }
+    )
+    if filter_payload is not None:
+        payload["filter"] = dict(filter_payload)
+    return payload
+
+
 def _coerce_priority(value: object) -> float:
     if isinstance(value, bool):
         return 0.0
@@ -80,12 +124,11 @@ def _normalize_voice_transcript_candidate(
 
 def arbitrate_voice_transcript_results(dispatch_results: object) -> dict[str, Any]:
     if not isinstance(dispatch_results, list) or not dispatch_results:
-        return {
-            "action": VOICE_TRANSCRIPT_ACTION_NOOP,
-            "reason": "no_subscribers",
-            "priority": 0.0,
-            "skipped": False,
-        }
+        return voice_transcript_noop(
+            "no_subscribers",
+            priority=0.0,
+            skipped=False,
+        )
 
     selected: tuple[int, float, int, dict[str, Any]] | None = None
     noop_count = 0
@@ -112,42 +155,29 @@ def arbitrate_voice_transcript_results(dispatch_results: object) -> dict[str, An
     if selected is not None:
         return selected[3]
     if noop_count:
-        return {
-            "action": VOICE_TRANSCRIPT_ACTION_NOOP,
-            "reason": "all_noop",
-            "priority": 0.0,
-            "skipped": False,
-            "handlers": noop_count,
-            "failures": failure_count,
-        }
-    return {
-        "action": VOICE_TRANSCRIPT_ACTION_NOOP,
-        "reason": "no_handler_result",
-        "priority": 0.0,
-        "skipped": False,
-        "failures": failure_count,
-    }
-
-
-def arbitrate_custom_event_result(
-    *,
-    event_type: str,
-    dispatch_results: object,
-) -> dict[str, Any]:
-    if event_type == VOICE_TRANSCRIPT_EVENT_TYPE:
-        return arbitrate_voice_transcript_results(dispatch_results)
-    return {
-        "action": "noop",
-        "reason": "no_event_contract",
-        "event_type": event_type,
-    }
+        return voice_transcript_noop(
+            "all_noop",
+            priority=0.0,
+            skipped=False,
+            handlers=noop_count,
+            failures=failure_count,
+        )
+    return voice_transcript_noop(
+        "no_handler_result",
+        priority=0.0,
+        skipped=False,
+        failures=failure_count,
+    )
 
 
 __all__ = [
     "VOICE_TRANSCRIPT_ACTION_CANCEL_RESPONSE",
     "VOICE_TRANSCRIPT_ACTION_NOOP",
     "VOICE_TRANSCRIPT_ACTION_PRIME_CONTEXT",
+    "VOICE_TRANSCRIPT_EVENT_ID",
     "VOICE_TRANSCRIPT_EVENT_TYPE",
-    "arbitrate_custom_event_result",
     "arbitrate_voice_transcript_results",
+    "voice_transcript_cancel_response",
+    "voice_transcript_noop",
+    "voice_transcript_prime_context",
 ]

plugin/server/application/plugins/dispatch_service.py

@@ -8,9 +8,6 @@
 
 from plugin.core.state import state
 from plugin.logging_config import get_logger
-from plugin.server.application.plugins.event_contracts import (
-    arbitrate_custom_event_result,
-)
 from plugin.server.domain import RUNTIME_ERRORS
 from plugin.server.domain.errors import ServerDomainError
 
@@ -295,22 +292,3 @@ async def _dispatch_handler(plugin_id: str, handler_event_id: str) -> dict[str,
                 *(_dispatch_handler(plugin_id, event_id) for plugin_id, event_id in handlers)
             )
         )
-
-    async def trigger_arbitrated_custom_event(
-        self,
-        *,
-        event_type: str,
-        event_id: str = "",
-        args: object,
-        timeout: float,
-    ) -> dict[str, object]:
-        dispatch_results = await self.trigger_custom_event_subscribers(
-            event_type=event_type,
-            event_id=event_id,
-            args=args,
-            timeout=timeout,
-        )
-        return arbitrate_custom_event_result(
-            event_type=event_type,
-            dispatch_results=dispatch_results,
-        )