Fix CI failures on PR #196: ruff F401 + pytester plugin double-load

* Add Self-healing + WebRunner bridge symbols to je_auto_control/__init__.py
  __all__ (ruff F401 fires when re-exported names aren't listed).
* Add PresenceError / PresenceListener / PresenceRegistry / ROLE_*  /
  ViewerPresence / default_presence_registry to
  je_auto_control/utils/remote_desktop/__init__.py __all__.
* Stub generator: bare project-class annotations now fall back to ``Any``
  rather than emitting an unresolved name; ``NoneType`` → ``None``;
  dotted module references → ``Any``; header imports widened to
  include ``Callable`` / ``Mapping`` / ``Sequence``; ``# ruff: noqa: F401``
  pragma on the generated stub so unused typing imports are tolerated.
* Regenerate je_auto_control/actions.pyi.
* test_pytest_plugin: stop passing ``-p`` to the inner pytester run —
  the package is pip-installed in CI which activates the pytest11
  entry point, so the explicit ``-p`` was double-registering the
  plugin and aborting the inner run before a summary line. Use
  ``runpytest_subprocess()`` + ``result.ret == 1`` instead.

Author: JE-Chen

je_auto_control/__init__.py

@@ -465,6 +465,14 @@ def start_autocontrol_gui(*args, **kwargs):
     # A/B locator framework
     "ABRunOutcome", "ab_best_strategy", "ab_locate",
     "ab_report_for", "default_ab_store",
+    # Self-healing locator (image → VLM fallback)
+    "HealEvent", "HealEventLog", "HealOutcome", "SelfHealError",
+    "default_heal_log", "self_heal_click", "self_heal_locate",
+    # WebRunner bridge (browser automation via je_web_runner)
+    "WebRunnerBridgeError", "is_webrunner_available",
+    "list_webrunner_commands", "run_webrunner_action",
+    "run_webrunner_actions", "web_current_url", "web_open",
+    "web_quit", "web_screenshot",
     # Remote desktop
     "RemoteDesktopHost", "RemoteDesktopViewer",
     "RemoteDesktopAuthError", "RemoteDesktopInputError",

je_auto_control/actions.pyi

@@ -1,16 +1,44 @@
 # AUTOGENERATED by je_auto_control.utils.stubs.generator — do not edit.
 # Regenerate with: python -m je_auto_control.utils.stubs.generator
-from typing import Any, Dict, List, Optional, Tuple, Union
+# ruff: noqa: F401  # generated stub keeps typing imports for forward use
+from typing import (
+    Any, Callable, Dict, List, Mapping, Optional,
+    Sequence, Tuple, Union,
+)
 
 def AC_a11y_click(name: str | None = ..., role: str | None = ..., app_name: str | None = ...) -> bool:
     """Click the center of the first element matching the filters."""
 
+def AC_a11y_dump(app_name: str | None = ..., max_results: int = ...) -> Dict[str, Any]:
+    """Executor adapter: dump the accessibility tree as nested dict."""
+
 def AC_a11y_find(name: str | None = ..., role: str | None = ..., app_name: str | None = ...) -> dict | None:
     """Executor adapter: find an accessibility element, return its dict."""
 
 def AC_a11y_list(app_name: str | None = ..., max_results: int = ...) -> List[dict]:
     """Executor adapter: list accessibility elements as plain dicts."""
 
+def AC_a11y_record_events() -> List[Dict[str, Any]]:
+    """Executor adapter: peek at events without stopping the recorder."""
+
+def AC_a11y_record_start(app_name: str | None = ..., poll_interval_s: float = ..., min_movement_px: int = ...) -> Dict[str, Any]:
+    """Executor adapter: start the singleton accessibility recorder."""
+
+def AC_a11y_record_stop() -> List[Dict[str, Any]]:
+    """Executor adapter: stop the recorder and return the captured events."""
+
+def AC_ab_best_strategy(target_id: str) -> Dict[str, Any]:
+    ...
+
+def AC_ab_clear() -> Dict[str, Any]:
+    ...
+
+def AC_ab_locate(target_id: str, strategies: Dict[str, Dict[str, Any]], max_parallel: int = ..., record: bool = ...) -> Dict[str, Any]:
+    """Executor adapter: race N locator strategies for the same target."""
+
+def AC_ab_report(target_id: str) -> Dict[str, Any]:
+    ...
+
 def AC_add_package_to_callback_executor(package: str) -> None:
     """將套件成員加入 CallbackExecutor"""
 
@@ -77,7 +105,7 @@ def AC_check_key_is_press(keycode: int | str) -> bool | None:
 def AC_click_mouse(mouse_keycode: int | str, x: int = ..., y: int = ...) -> Tuple[int, int, int]:
     """在指定座標按下並放開滑鼠按鍵"""
 
-def AC_click_text(target: str, mouse_keycode: int | str = ..., lang: str = ..., region: Sequence[int] | None = ..., min_confidence: float = ..., case_sensitive: bool = ..., backend: str | je_auto_control.utils.ocr.backends.base.OCRBackend | None = ...) -> Tuple[int, int]:
+def AC_click_text(target: str, mouse_keycode: int | str = ..., lang: str = ..., region: Sequence[int] | None = ..., min_confidence: float = ..., case_sensitive: bool = ..., backend: Any = ...) -> Tuple[int, int]:
     """Locate ``target`` text and click its centre."""
 
 def AC_clipboard_get() -> str:
@@ -98,6 +126,18 @@ def AC_config_export() -> Dict[str, Any]:
 def AC_config_import(bundle: Dict[str, Any], dry_run: bool = ...) -> Dict[str, Any]:
     """Executor adapter: apply a config bundle dict to the user config root."""
 
+def AC_costs_clear() -> Dict[str, Any]:
+    ...
+
+def AC_costs_list(limit: int = ...) -> List[Dict[str, Any]]:
+    ...
+
+def AC_costs_record(provider: str, model: str, input_tokens: int, output_tokens: int, label: str | None = ..., run_id: str | None = ..., user: str | None = ...) -> Dict[str, Any]:
+    """Executor adapter: append one LLM call to the cost-telemetry log."""
+
+def AC_costs_summary(limit: int = ...) -> Dict[str, Any]:
+    """Executor adapter: aggregate cost events by model / provider / day."""
+
 def AC_create_project(project_path: str = ..., parent_name: str = ...) -> None:
     """Create project directory structure and templates."""
 
@@ -122,7 +162,7 @@ def AC_email_trigger_start() -> Dict[str, Any]:
 def AC_email_trigger_stop() -> Dict[str, Any]:
     ...
 
-def AC_execute_action(action_list: list | dict, raise_on_error: bool = ..., _validated: bool = ..., dry_run: bool = ..., step_callback: Callable[[list], NoneType] | None = ...) -> Dict[str, str]:
+def AC_execute_action(action_list: list | dict, raise_on_error: bool = ..., _validated: bool = ..., dry_run: bool = ..., step_callback: Callable[[list], None] | None = ...) -> Dict[str, str]:
     """執行 action list"""
 
 def AC_execute_files(execute_files_list: list) -> List[Dict[str, str]]:
@@ -131,6 +171,15 @@ def AC_execute_files(execute_files_list: list) -> List[Dict[str, str]]:
 def AC_execute_process(exe_path: str) -> None:
     """Start an external executable file."""
 
+def AC_failure_hook_clear() -> Dict[str, Any]:
+    ...
+
+def AC_failure_hook_fire(source: str, source_id: str, error_text: str = ..., script_path: str | None = ..., screenshot_path: str | None = ..., log_tail: str = ..., metadata: Dict[str, Any] | None = ...) -> List[Dict[str, Any]]:
+    """Executor adapter: file a ticket through every registered backend."""
+
+def AC_failure_hook_list() -> List[Dict[str, Any]]:
+    ...
+
 def AC_find_text_regex(pattern: str, lang: str = ..., region: List[int] | None = ..., min_confidence: float = ..., flags: int = ...) -> List[dict]:
     """Executor adapter: regex OCR search returning JSON-friendly dicts."""
 
@@ -230,7 +279,7 @@ def AC_locate_and_click(image: Any, mouse_keycode: int | str, detect_threshold:
 def AC_locate_image_center(image: Any, detect_threshold: float = ..., draw_image: bool = ...) -> Tuple[int, int]:
     """找出單一影像並回傳中心座標"""
 
-def AC_locate_text(target: str, lang: str = ..., region: Sequence[int] | None = ..., min_confidence: float = ..., case_sensitive: bool = ..., backend: str | je_auto_control.utils.ocr.backends.base.OCRBackend | None = ...) -> Tuple[int, int]:
+def AC_locate_text(target: str, lang: str = ..., region: Sequence[int] | None = ..., min_confidence: float = ..., case_sensitive: bool = ..., backend: Any = ...) -> Tuple[int, int]:
     """Return the centre (x, y) of the first match; raise if not found."""
 
 def AC_mouse_left(x: int | None = ..., y: int | None = ...) -> Tuple[int, int, int]:
@@ -374,10 +423,10 @@ def AC_set_record_enable(set_enable: bool = ...) -> None:
 def AC_shell_command(shell_command: str | List[str]) -> None:
     """Execute shell command with shell=False."""
 
-def AC_start_mcp_http_server(host: str = ..., port: int = ..., mcp: je_auto_control.utils.mcp_server.server.MCPServer | None = ..., auth_token: str | None = ..., ssl_context: ssl.SSLContext | None = ...) -> HttpMCPServer:
+def AC_start_mcp_http_server(host: str = ..., port: int = ..., mcp: Any = ..., auth_token: str | None = ..., ssl_context: Any = ...) -> Any:
     """Start and return an :class:`HttpMCPServer`; convenience wrapper."""
 
-def AC_start_mcp_server() -> MCPServer:
+def AC_start_mcp_server() -> Any:
     """Start a stdio MCP server in the foreground; blocks until EOF."""
 
 def AC_start_remote_host(token: str, bind: str = ..., port: int = ..., fps: float = ..., quality: int = ..., region: List[int] | None = ..., max_clients: int = ...) -> Dict[str, Any]:
@@ -419,7 +468,7 @@ def AC_usb_watch_start(poll_interval_s: float = ...) -> Dict[str, Any]:
 def AC_usb_watch_stop() -> Dict[str, Any]:
     ...
 
-def AC_vlm_click(description: str, screen_region: List[int] | None = ..., model: str | None = ..., backend: je_auto_control.utils.vision.backends.base.VLMBackend | None = ...) -> bool:
+def AC_vlm_click(description: str, screen_region: List[int] | None = ..., model: str | None = ..., backend: Any = ...) -> bool:
     """Locate by description, then click the center of the match."""
 
 def AC_vlm_locate(description: str, screen_region: List[int] | None = ..., model: str | None = ...) -> List[int] | None:
@@ -434,7 +483,7 @@ def AC_wait_region_idle(region: List[int], timeout_s: float = ..., poll_interval
 def AC_wait_screen_stable(region: List[int] | None = ..., timeout_s: float = ..., poll_interval_s: float = ..., stable_for_s: float = ..., max_pixel_diff: int = ...) -> Dict[str, Any]:
     """Executor adapter: smart wait for the screen to stop moving."""
 
-def AC_wait_text(target: str, lang: str = ..., region: Sequence[int] | None = ..., timeout: float = ..., poll: float = ..., min_confidence: float = ..., case_sensitive: bool = ..., backend: str | je_auto_control.utils.ocr.backends.base.OCRBackend | None = ...) -> Tuple[int, int]:
+def AC_wait_text(target: str, lang: str = ..., region: Sequence[int] | None = ..., timeout: float = ..., poll: float = ..., min_confidence: float = ..., case_sensitive: bool = ..., backend: Any = ...) -> Tuple[int, int]:
     """Poll until ``target`` appears on screen; raise on timeout."""
 
 def AC_wait_window(title_substring: str, timeout: float = ..., poll: float = ..., case_sensitive: bool = ...) -> int:

je_auto_control/utils/remote_desktop/__init__.py

@@ -181,4 +181,7 @@ def is_webrtc_available() -> bool:
     "is_audio_backend_available",
     "ClipboardSyncError",
     "FileReceiver", "FileSendResult", "FileTransferError", "send_file",
+    "PresenceError", "PresenceListener", "PresenceRegistry",
+    "ROLE_CONTROLLER", "ROLE_OBSERVER", "ViewerPresence",
+    "default_presence_registry",
 ]

je_auto_control/utils/stubs/generator.py

@@ -26,7 +26,11 @@
 _HEADER = (
     "# AUTOGENERATED by je_auto_control.utils.stubs.generator — do not edit.\n"
     "# Regenerate with: python -m je_auto_control.utils.stubs.generator\n"
-    "from typing import Any, Dict, List, Optional, Tuple, Union\n"
+    "# ruff: noqa: F401  # generated stub keeps typing imports for forward use\n"
+    "from typing import (\n"
+    "    Any, Callable, Dict, List, Mapping, Optional,\n"
+    "    Sequence, Tuple, Union,\n"
+    ")\n"
     "\n"
 )
 
@@ -116,15 +120,47 @@ def _render_return(sig: Optional[inspect.Signature]) -> str:
     return _annotation_str(sig.return_annotation, default="Any")
 
 
+_BUILTIN_TYPES = frozenset({
+    "bool", "bytes", "bytearray", "complex", "dict", "float", "frozenset",
+    "int", "list", "memoryview", "object", "range", "set", "str", "tuple",
+    "type", "None",
+})
+
+
 def _annotation_str(annotation: Any, *, default: str) -> str:
     if annotation is inspect.Parameter.empty:
         return default
     if isinstance(annotation, type):
-        return annotation.__name__
+        name = annotation.__name__
+        # Project-owned classes aren't imported into the stub, so fall
+        # back to ``Any`` rather than emit a bare name that won't
+        # resolve. Builtins keep their names.
+        return name if name in _BUILTIN_TYPES else "Any"
     text = str(annotation)
     # ``typing`` is re-exported at the top of the stub, so strip the
     # prefix from both leading and embedded uses (``List[typing.Dict[…]]``).
-    return text.replace("typing.", "")
+    text = text.replace("typing.", "")
+    # ``inspect.signature`` renders ``type(None)`` as ``NoneType``; the
+    # name only resolves if ``types.NoneType`` is imported. ``None``
+    # works as a type annotation everywhere and reads cleaner.
+    text = text.replace("NoneType", "None")
+    # Any dotted reference that isn't a typing builtin would need the
+    # owning module imported into the stub. Rather than transitively
+    # import the world, fall back to ``Any``; the function name still
+    # autocompletes, the precise type just shows as Any.
+    if _has_module_reference(text):
+        return "Any"
+    return text
+
+
+def _has_module_reference(text: str) -> bool:
+    """True iff ``text`` still references a non-typing dotted name."""
+    if "." not in text:
+        return False
+    # Allow ellipsis-style forward refs that survive the typing.strip
+    # without an actual module reference (e.g. ``Callable[..., int]``).
+    sanitised = text.replace("...", "")
+    return "." in sanitised
 
 
 def _first_doc_line(handler: Callable[..., Any]) -> Optional[str]:

test/unit_test/headless/test_pytest_plugin.py

@@ -163,7 +163,14 @@ def test_pyproject_registers_pytest11_entry_point():
 
 
 def test_plugin_capture_screenshot_on_failure(pytester, monkeypatch):
-    """End-to-end: a failing test marked @autocontrol gets a screenshot."""
+    """End-to-end: a failing test marked @autocontrol gets a screenshot.
+
+    The plugin loads via the ``pytest11`` entry point declared in
+    ``pyproject.toml`` whenever the package is pip-installed (CI uses
+    ``pip install -e .``). We deliberately don't pass ``-p`` here —
+    doing so would double-register the plugin on installed runs and
+    abort the inner pytest before a summary line is emitted.
+    """
     pytester.makepyfile(
         """
         import pytest
@@ -188,8 +195,14 @@ def _patch_screenshot(tmp_path):
         """,
     )
     pytester.syspathinsert()
-    result = pytester.runpytest("-p", "je_auto_control.utils.pytest_plugin.plugin")
-    result.assert_outcomes(failed=1)
+    result = pytester.runpytest_subprocess()
+    # ret == 1 means the inner test ran and failed (which is what we
+    # asked it to do). Checking exit code is more robust than parsing
+    # the summary line, which can vary across pytest versions.
+    assert result.ret == 1, (
+        f"inner pytest exit {result.ret}; stdout tail: "
+        f"{result.stdout.str()[-400:]!r}"
+    )
 
 
 def test_plugin_no_screenshot_for_unmarked_failure(pytester):
@@ -200,7 +213,10 @@ def test_plain_failure():
         """,
     )
     pytester.syspathinsert()
-    result = pytester.runpytest("-p", "je_auto_control.utils.pytest_plugin.plugin")
-    result.assert_outcomes(failed=1)
+    result = pytester.runpytest_subprocess()
+    assert result.ret == 1, (
+        f"inner pytest exit {result.ret}; stdout tail: "
+        f"{result.stdout.str()[-400:]!r}"
+    )
     out = result.stdout.str()
     assert "autocontrol-screenshot" not in out