Wire AC_remote_* commands and facade re-exports for remote_desktop

JE-Chen · JE-Chen · commit b7c832090ea3 · 2026-04-26T18:23:32.000+08:00
A small registry singleton holds at most one host and one viewer so JSON
action scripts and the GUI can talk to the running pair without juggling
handles. The new AC_start_remote_host / AC_stop_remote_host /
AC_remote_host_status, AC_remote_connect / AC_remote_disconnect /
AC_remote_viewer_status / AC_remote_send_input commands are thin
adapters over the registry, so the executor stays unaware of the host
and viewer classes' lifecycle details.

Tests cover the AC_* command surface and an end-to-end round-trip
(executor-driven host start, viewer connect, send_input, disconnect,
stop) with stub frame provider and dispatcher so no real screen capture
or OS input is needed.
diff --git a/je_auto_control/__init__.py b/je_auto_control/__init__.py
@@ -68,6 +68,16 @@
     LLMBackend, LLMNotAvailableError, LLMPlanError,
     plan_actions, run_from_description,
 )
+# Remote desktop (headless)
+from je_auto_control.utils.remote_desktop import (
+    AuthenticationError as RemoteDesktopAuthError,
+    InputDispatchError as RemoteDesktopInputError,
+    ProtocolError as RemoteDesktopProtocolError,
+    RemoteDesktopHost, RemoteDesktopViewer,
+)
+from je_auto_control.utils.remote_desktop.registry import (
+    registry as remote_desktop_registry,
+)
 # MCP server (headless stdio bridge for Claude / other MCP clients)
 from je_auto_control.utils.mcp_server import (
     AuditLogger, HttpMCPServer, MCPContent, MCPPrompt, MCPPromptArgument,
@@ -258,6 +268,10 @@ def start_autocontrol_gui(*args, **kwargs):
     # LLM action planner
     "LLMBackend", "LLMNotAvailableError", "LLMPlanError",
     "plan_actions", "run_from_description",
+    # Remote desktop
+    "RemoteDesktopHost", "RemoteDesktopViewer",
+    "RemoteDesktopAuthError", "RemoteDesktopInputError",
+    "RemoteDesktopProtocolError", "remote_desktop_registry",
     "generate_html", "generate_html_report", "generate_json", "generate_json_report", "generate_xml",
     "generate_xml_report", "get_dir_files_as_list", "create_project_dir", "start_autocontrol_socket_server",
     "callback_executor", "package_manager", "ShellManager", "default_shell_manager",
diff --git a/je_auto_control/utils/executor/action_executor.py b/je_auto_control/utils/executor/action_executor.py
@@ -27,6 +27,9 @@
     plan_actions as llm_plan_actions,
     run_from_description as llm_run_from_description,
 )
+from je_auto_control.utils.remote_desktop.registry import (
+    registry as remote_desktop_registry,
+)
 from je_auto_control.utils.ocr.ocr_engine import (
     click_text as ocr_click_text,
     find_text_regex as ocr_find_text_regex,
@@ -101,6 +104,49 @@ def _vlm_locate_as_list(description: str,
     return None if coords is None else [coords[0], coords[1]]
 
 
+def _remote_start_host(token: str,
+                       bind: str = "127.0.0.1",
+                       port: int = 0,
+                       fps: float = 10.0,
+                       quality: int = 70,
+                       region: Optional[List[int]] = None,
+                       max_clients: int = 4) -> Dict[str, Any]:
+    """Executor adapter: start the singleton remote-desktop host."""
+    return remote_desktop_registry.start_host(
+        token=token, bind=bind, port=int(port),
+        fps=float(fps), quality=int(quality),
+        region=region, max_clients=int(max_clients),
+    )
+
+
+def _remote_stop_host() -> Dict[str, Any]:
+    return remote_desktop_registry.stop_host()
+
+
+def _remote_host_status() -> Dict[str, Any]:
+    return remote_desktop_registry.host_status()
+
+
+def _remote_connect(host: str, port: int, token: str,
+                    timeout: float = 5.0) -> Dict[str, Any]:
+    """Executor adapter: connect the singleton viewer."""
+    return remote_desktop_registry.connect_viewer(
+        host=host, port=int(port), token=token, timeout=float(timeout),
+    )
+
+
+def _remote_disconnect() -> Dict[str, Any]:
+    return remote_desktop_registry.disconnect_viewer()
+
+
+def _remote_viewer_status() -> Dict[str, Any]:
+    return remote_desktop_registry.viewer_status()
+
+
+def _remote_send_input(action: Dict[str, Any]) -> Dict[str, Any]:
+    return remote_desktop_registry.send_input(action)
+
+
 def _llm_plan_for_executor(description: str,
                            examples: Optional[list] = None,
                            model: Optional[str] = None,
@@ -296,6 +342,17 @@ def __init__(self):
             # LLM action planner
             "AC_llm_plan": _llm_plan_for_executor,
             "AC_llm_run": _llm_run_for_executor,
+
+            # Remote desktop host (this machine streams to others)
+            "AC_start_remote_host": _remote_start_host,
+            "AC_stop_remote_host": _remote_stop_host,
+            "AC_remote_host_status": _remote_host_status,
+
+            # Remote desktop viewer (this machine controls others)
+            "AC_remote_connect": _remote_connect,
+            "AC_remote_disconnect": _remote_disconnect,
+            "AC_remote_viewer_status": _remote_viewer_status,
+            "AC_remote_send_input": _remote_send_input,
         }
 
     def known_commands(self) -> set:
diff --git a/je_auto_control/utils/remote_desktop/__init__.py b/je_auto_control/utils/remote_desktop/__init__.py
@@ -17,11 +17,12 @@
     AuthenticationError, MessageType, ProtocolError,
     decode_frame_header, encode_frame,
 )
+from je_auto_control.utils.remote_desktop.registry import registry
 from je_auto_control.utils.remote_desktop.viewer import RemoteDesktopViewer
 
 __all__ = [
     "RemoteDesktopHost", "RemoteDesktopViewer",
     "InputDispatchError", "AuthenticationError", "ProtocolError",
     "MessageType", "encode_frame", "decode_frame_header",
-    "dispatch_input",
+    "dispatch_input", "registry",
 ]
diff --git a/je_auto_control/utils/remote_desktop/registry.py b/je_auto_control/utils/remote_desktop/registry.py
@@ -0,0 +1,94 @@
+"""Process-global singletons used by AC_remote_* executor commands.
+
+JSON action scripts and the GUI both want to talk to one running host
+and at most one active viewer without juggling handles. Holding those
+references here keeps :mod:`action_executor` thin and avoids circular
+imports between the executor and the host/viewer classes.
+"""
+from typing import Any, Dict, Optional, Sequence
+
+from je_auto_control.utils.remote_desktop.host import RemoteDesktopHost
+from je_auto_control.utils.remote_desktop.viewer import RemoteDesktopViewer
+
+
+class _RemoteDesktopRegistry:
+    """Hold one host + one viewer for the executor command surface."""
+
+    def __init__(self) -> None:
+        self._host: Optional[RemoteDesktopHost] = None
+        self._viewer: Optional[RemoteDesktopViewer] = None
+
+    @property
+    def host(self) -> Optional[RemoteDesktopHost]:
+        return self._host
+
+    @property
+    def viewer(self) -> Optional[RemoteDesktopViewer]:
+        return self._viewer
+
+    def start_host(self, token: str,
+                   bind: str = "127.0.0.1",
+                   port: int = 0,
+                   fps: float = 10.0,
+                   quality: int = 70,
+                   region: Optional[Sequence[int]] = None,
+                   max_clients: int = 4) -> Dict[str, Any]:
+        """Stop any existing host, then start a fresh one with the given config."""
+        self.stop_host()
+        host = RemoteDesktopHost(
+            token=token, bind=bind, port=int(port),
+            fps=float(fps), quality=int(quality),
+            region=region, max_clients=int(max_clients),
+        )
+        host.start()
+        self._host = host
+        return self.host_status()
+
+    def stop_host(self, timeout: float = 2.0) -> Dict[str, Any]:
+        """Stop the active host (if any) and clear the slot."""
+        if self._host is not None:
+            self._host.stop(timeout=timeout)
+            self._host = None
+        return self.host_status()
+
+    def host_status(self) -> Dict[str, Any]:
+        host = self._host
+        if host is None:
+            return {"running": False, "port": 0, "connected_clients": 0}
+        return {
+            "running": host.is_running,
+            "port": host.port,
+            "connected_clients": host.connected_clients,
+        }
+
+    def connect_viewer(self, host: str, port: int, token: str,
+                       timeout: float = 5.0) -> Dict[str, Any]:
+        """Disconnect any existing viewer, then connect a fresh one."""
+        self.disconnect_viewer()
+        viewer = RemoteDesktopViewer(host=host, port=int(port), token=token)
+        viewer.connect(timeout=float(timeout))
+        self._viewer = viewer
+        return self.viewer_status()
+
+    def disconnect_viewer(self, timeout: float = 2.0) -> Dict[str, Any]:
+        """Disconnect the active viewer (if any) and clear the slot."""
+        if self._viewer is not None:
+            self._viewer.disconnect(timeout=timeout)
+            self._viewer = None
+        return self.viewer_status()
+
+    def viewer_status(self) -> Dict[str, Any]:
+        viewer = self._viewer
+        if viewer is None:
+            return {"connected": False}
+        return {"connected": viewer.connected}
+
+    def send_input(self, action: Dict[str, Any]) -> Dict[str, Any]:
+        """Forward ``action`` through the connected viewer, raise if offline."""
+        if self._viewer is None or not self._viewer.connected:
+            raise ConnectionError("no remote viewer is connected")
+        self._viewer.send_input(action)
+        return {"sent": True}
+
+
+registry = _RemoteDesktopRegistry()
diff --git a/test/unit_test/headless/test_remote_desktop_executor.py b/test/unit_test/headless/test_remote_desktop_executor.py
@@ -0,0 +1,117 @@
+"""Tests for the AC_remote_* executor commands and registry singleton."""
+import time
+
+import pytest
+
+from je_auto_control.utils.executor.action_executor import executor
+from je_auto_control.utils.remote_desktop.registry import registry
+
+
+@pytest.fixture(autouse=True)
+def reset_registry():
+    """Tear down any leftover host/viewer before and after each test."""
+    registry.disconnect_viewer()
+    registry.stop_host()
+    yield
+    registry.disconnect_viewer()
+    registry.stop_host()
+
+
+def _wait_until(predicate, timeout: float = 2.0,
+                interval: float = 0.02) -> bool:
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        if predicate():
+            return True
+        time.sleep(interval)
+    return predicate()
+
+
+def test_known_commands_include_remote_desktop():
+    assert "AC_start_remote_host" in executor.known_commands()
+    assert "AC_stop_remote_host" in executor.known_commands()
+    assert "AC_remote_host_status" in executor.known_commands()
+    assert "AC_remote_connect" in executor.known_commands()
+    assert "AC_remote_disconnect" in executor.known_commands()
+    assert "AC_remote_viewer_status" in executor.known_commands()
+    assert "AC_remote_send_input" in executor.known_commands()
+
+
+def test_start_host_then_status_via_executor():
+    captured = []
+
+    def stub_provider() -> bytes:
+        return b"test-frame"
+
+    # Reach into the registry to install a stub provider so this test
+    # never touches PIL.ImageGrab; mirrors what GUI would do for a fake.
+    from je_auto_control.utils.remote_desktop.host import RemoteDesktopHost
+
+    host = RemoteDesktopHost(
+        token="t", bind="127.0.0.1", port=0, fps=50.0, quality=70,
+        frame_provider=stub_provider, input_dispatcher=captured.append,
+    )
+    host.start()
+    registry._host = host  # noqa: SLF001  # test-only injection
+
+    record = executor.execute_action([["AC_remote_host_status"]])
+    status_value = next(iter(record.values()))
+    assert status_value["running"] is True
+    assert status_value["port"] > 0
+
+
+def test_start_host_with_blank_token_records_error():
+    record = executor.execute_action([
+        ["AC_start_remote_host", {"token": ""}],
+    ])
+    assert any("ValueError" in repr(v) for v in record.values())
+
+
+def test_send_input_without_viewer_records_connection_error():
+    record = executor.execute_action([
+        ["AC_remote_send_input", {"action": {"action": "ping"}}],
+    ])
+    assert any("ConnectionError" in repr(v) for v in record.values())
+
+
+def test_remote_round_trip_through_executor():
+    """Start host + connect viewer + send input via executor commands."""
+    record = executor.execute_action([
+        ["AC_start_remote_host", {
+            "token": "tok", "bind": "127.0.0.1", "port": 0,
+            "fps": 50, "quality": 70,
+        }],
+    ])
+    start_status = next(iter(record.values()))
+    assert start_status["running"] is True
+    port = start_status["port"]
+    assert port > 0
+
+    # Replace the default frame provider (PIL.ImageGrab) with a stub so
+    # the test does not depend on a real screen being available.
+    registry._host._frame_provider = lambda: b"executor-frame"  # noqa: SLF001
+    captured = []
+    registry._host._dispatch = captured.append  # noqa: SLF001
+
+    executor.execute_action([
+        ["AC_remote_connect", {
+            "host": "127.0.0.1", "port": port, "token": "tok",
+        }],
+    ])
+    viewer_status = registry.viewer_status()
+    assert viewer_status["connected"] is True
+    assert _wait_until(lambda: registry.host.connected_clients == 1)
+
+    executor.execute_action([
+        ["AC_remote_send_input", {
+            "action": {"action": "mouse_move", "x": 5, "y": 7},
+        }],
+    ])
+    assert _wait_until(lambda: captured == [
+        {"action": "mouse_move", "x": 5, "y": 7}
+    ])
+
+    executor.execute_action([["AC_remote_disconnect"]])
+    assert registry.viewer_status()["connected"] is False
+    executor.execute_action([["AC_stop_remote_host"]])
+    assert registry.host_status()["running"] is False

Original file line number	Diff line number	Diff line change
`@@ -17,11 +17,12 @@`
`17`	`17`	`AuthenticationError, MessageType, ProtocolError,`
`18`	`18`	`decode_frame_header, encode_frame,`
`19`	`19`	`)`
	`20`	`+from je_auto_control.utils.remote_desktop.registry import registry`
`20`	`21`	`from je_auto_control.utils.remote_desktop.viewer import RemoteDesktopViewer`
`21`	`22`
`22`	`23`	`__all__ = [`
`23`	`24`	`"RemoteDesktopHost", "RemoteDesktopViewer",`
`24`	`25`	`"InputDispatchError", "AuthenticationError", "ProtocolError",`
`25`	`26`	`"MessageType", "encode_frame", "decode_frame_header",`
`26`		`- "dispatch_input",`
	`27`	`+ "dispatch_input", "registry",`
`27`	`28`	`]`