webpilot-engine 2.0.3__tar.gz → 2.0.5__tar.gz

{webpilot_engine-2.0.3 → webpilot_engine-2.0.5}/PKG-INFO

@@ -1,11 +1,16 @@
 Metadata-Version: 2.4
 Name: webpilot-engine
-Version: 2.0.3
+Version: 2.0.5
 Summary: WebPilot: Enterprise Autonomous Browser Engine, Universal Form Inspector & AI Agent Web Runtime
 Author: Abdulkarim Salih, WebPilot Core Team
 License: MIT
+Project-URL: Homepage, https://github.com/AbdulkarimSSS/webpilot
+Project-URL: Documentation, https://github.com/AbdulkarimSSS/webpilot#readme
+Project-URL: Repository, https://github.com/AbdulkarimSSS/webpilot.git
+Project-URL: Bug Tracker, https://github.com/AbdulkarimSSS/webpilot/issues
+Project-URL: Changelog, https://github.com/AbdulkarimSSS/webpilot/blob/master/CHANGELOG.md
 Keywords: webpilot,browser-runtime,ai-agent,web-automation,playwright,form-filler,ats-automation,sap-successfactors,workday,browser-supervisor,process-isolation
-Classifier: Development Status :: 5 - Production/Stable
+Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Topic :: Software Development :: Testing
 Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
@@ -28,7 +33,7 @@ Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
 Requires-Dist: pytest-mock>=3.12.0; extra == "dev"
 Requires-Dist: Faker>=24.0.0; extra == "dev"
 Provides-Extra: mcp
-Requires-Dist: mcp>=1.0.0; extra == "mcp"
+Requires-Dist: mcp<2,>=1.0.0; extra == "mcp"
 
 # WebPilot: Autonomous Multi-Tier Browser Automation Engine & AI Agent Web Runtime
 

{webpilot_engine-2.0.3 → webpilot_engine-2.0.5}/adapters/browser_adapter.py

@@ -253,15 +253,10 @@ class BrowserAdapter(BrowserAdapterProtocol):
                 args=["--disable-blink-features=AutomationControlled"],
             )
             try:
-                if sys.platform == "win32":
-                    ps_c = f'(Get-CimInstance Win32_Process | Where-Object {{ $_.ParentProcessId -eq {os.getpid()} }}).ProcessId | Select-Object -First 1'
-                    out = subprocess.check_output(["powershell", "-NoProfile", "-Command", ps_c], text=True).strip()
-                    if out.isdigit():
-                        self.browser_pid = int(out)
-                else:
-                    out = subprocess.check_output(["pgrep", "-P", str(os.getpid())], text=True).strip().split()
-                    if out and out[0].isdigit():
-                        self.browser_pid = int(out[0])
+                from common.process_manager import get_process_manager
+                children = get_process_manager().get_child_pids(os.getpid())
+                if children:
+                    self.browser_pid = children[0]
             except Exception:
                 pass
 

{webpilot_engine-2.0.3 → webpilot_engine-2.0.5}/adapters/live_session_manager.py

@@ -124,16 +124,8 @@ class LiveSessionManager:
         pid = state.get("pid")
         if pid:
             try:
-                # Terminate on Windows
-                if sys.platform == "win32":
-                    subprocess.run(
-                        ["taskkill", "/F", "/T", "/PID", str(pid)],
-                        stdout=subprocess.DEVNULL,
-                        stderr=subprocess.DEVNULL,
-                    )
-                else:
-                    os.kill(pid, 9)
-                return True
+                from common.process_manager import get_process_manager
+                return get_process_manager().kill_process_tree(pid, force=True)
             except Exception:
                 pass
         return False
@@ -210,13 +202,16 @@ class LiveSessionManager:
             time.sleep(0.2)
 
         if not active:
-            if sys.platform == "win32" and proc_pid:
+            if proc_pid:
                 try:
-                    subprocess.run(
-                        ["taskkill", "/F", "/T", "/PID", str(proc_pid)],
-                        stdout=subprocess.DEVNULL,
-                        stderr=subprocess.DEVNULL,
-                    )
+                    if sys.platform == "win32":
+                        subprocess.run(
+                            ["taskkill", "/F", "/T", "/PID", str(proc_pid)],
+                            stdout=subprocess.DEVNULL,
+                            stderr=subprocess.DEVNULL,
+                        )
+                    else:
+                        os.kill(proc_pid, 9)
                 except Exception:
                     pass
             raise RuntimeError(f"Chromium failed to open CDP port {port} within 5 seconds.")
@@ -264,62 +259,23 @@ class LiveSessionManager:
     @classmethod
     def _launch_wmi_process(cls, cmd_str: str, cwd: Optional[str] = None) -> Optional[int]:
         """Launches a detached process via Windows WMI outside any parent Job Object."""
+        from common.process_manager import get_process_manager
         working_dir = cwd or PROJECT_ROOT
-        ps_script = f"""
-$startup = ([wmiclass]"Win32_ProcessStartup").CreateInstance()
-$startup.ShowWindow = 0
-$proc = ([wmiclass]"Win32_Process").Create(@'
-{cmd_str}
-'@, $null, $startup)
-if ($proc.ReturnValue -eq 0) {{
-    Write-Output $proc.ProcessId
-}} else {{
-    exit 1
-}}
-"""
-        try:
-            encoded = base64.b64encode(ps_script.encode("utf-16le")).decode("ascii")
-            res = subprocess.run(
-                ["powershell", "-NoProfile", "-NonInteractive", "-EncodedCommand", encoded],
-                capture_output=True,
-                text=True,
-                timeout=10,
-            )
-            out = res.stdout.strip()
-            if res.returncode == 0 and out.isdigit():
-                return int(out)
-            else:
-                print(f"[!] WMI launch non-zero/non-digit: code={res.returncode}, out='{out}', err='{res.stderr.strip()}'")
-        except Exception as exc:
-            print(f"[!] WMI launch exception: {exc}")
-        return None
+        return get_process_manager().launch_detached(cmd_str, cwd=working_dir)
 
     @classmethod
     def _spawn_watchdog_supervisor(cls, browser_pid: int, port: int, timeout_seconds: int) -> None:
         """Launches a lightweight detached background watchdog to terminate idle browser."""
-        watchdog_cmd = f'"{sys.executable}" -m adapters.live_session_manager {browser_pid} {port} {timeout_seconds}'
-
-        if sys.platform == "win32":
-            wmi_pid = cls._launch_wmi_process(watchdog_cmd)
-            if wmi_pid is not None:
-                return
-
-        popen_kwargs: Dict[str, Any] = {
-            "stdout": subprocess.DEVNULL,
-            "stderr": subprocess.DEVNULL,
-        }
-        if sys.platform == "win32":
-            popen_kwargs["creationflags"] = subprocess.DETACHED_PROCESS | subprocess.CREATE_NEW_PROCESS_GROUP
-        else:
-            popen_kwargs["start_new_session"] = True
-
-        try:
-            subprocess.Popen(
-                [sys.executable, "-m", "adapters.live_session_manager", str(browser_pid), str(port), str(timeout_seconds)],
-                **popen_kwargs,
-            )
-        except Exception:
-            pass
+        from common.process_manager import get_process_manager
+        watchdog_cmd = [
+            sys.executable,
+            "-m",
+            "adapters.live_session_manager",
+            str(browser_pid),
+            str(port),
+            str(timeout_seconds),
+        ]
+        get_process_manager().launch_detached(watchdog_cmd, cwd=PROJECT_ROOT)
 
 
 if __name__ == "__main__":

{webpilot_engine-2.0.3 → webpilot_engine-2.0.5}/builder.py

@@ -34,7 +34,17 @@ class FormPayloadBuilder:
 
     @staticmethod
     def load_from_file(filepath: str) -> List[Tuple[str, Any]]:
-        """Load field key-value pairs from an external JSON file."""
+        """Load field key-value pairs from an external JSON file or stdin ('-' or '@stdin')."""
+        import sys
+        from common.secrets import resolve_secret_value
+
+        if filepath in ("-", "@stdin"):
+            try:
+                raw_data = json.load(sys.stdin)
+            except Exception as exc:
+                raise ValidationError(f"Invalid JSON read from standard input: {exc}") from exc
+            return FormPayloadBuilder.normalize_payload(raw_data)
+
         if not os.path.isfile(filepath):
             raise ConfigurationError(f"Form payload data file not found: {filepath}")
 
@@ -48,18 +58,21 @@ class FormPayloadBuilder:
 
     @staticmethod
     def normalize_payload(raw_data: Union[Dict[str, Any], List[Any]]) -> List[Tuple[str, Any]]:
-        """Normalizes dict or list structures into a clean list of (field, value) pairs."""
+        """Normalizes dict or list structures into a clean list of (field, value) pairs and resolves secrets."""
+        from common.secrets import resolve_secret_value
+
         fields: List[Tuple[str, Any]] = []
 
         if isinstance(raw_data, dict):
             for k, v in raw_data.items():
-                fields.append((str(k), v))
+                fields.append((str(k), resolve_secret_value(v, prompt_label=str(k))))
         elif isinstance(raw_data, list):
             for item in raw_data:
                 if isinstance(item, (list, tuple)) and len(item) == 2:
-                    fields.append((str(item[0]), item[1]))
+                    fields.append((str(item[0]), resolve_secret_value(item[1], prompt_label=str(item[0]))))
                 elif isinstance(item, dict) and "key" in item and "value" in item:
-                    fields.append((str(item["key"]), item["value"]))
+                    k = str(item["key"])
+                    fields.append((k, resolve_secret_value(item["value"], prompt_label=k)))
                 else:
                     raise ValidationError(f"Unrecognized payload entry structure: {item}")
         else:
@@ -68,16 +81,8 @@ class FormPayloadBuilder:
         return fields
 
     @staticmethod
-    def parse_cli_fill_arguments(fill_args: Optional[List[str]]) -> List[Tuple[str, str]]:
-        """Parses CLI --fill 'key=value' arguments into key-value pairs."""
-        if not fill_args:
-            return []
-
-        parsed: List[Tuple[str, str]] = []
-        for item in fill_args:
-            if "=" in item:
-                k, v = item.split("=", 1)
-                parsed.append((k.strip(), v.strip()))
-            else:
-                raise ValidationError(f"Invalid fill argument format: '{item}' (Expected 'key=value')")
-        return parsed
+    def parse_cli_fill_arguments(fill_args: Optional[List[str]]) -> List[Tuple[str, Any]]:
+        """Parses CLI --fill arguments into key-value pairs and resolves secrets (@env, @stdin, @file)."""
+        from common.secrets import parse_and_resolve_fill_args
+        return parse_and_resolve_fill_args(fill_args)
+

{webpilot_engine-2.0.3 → webpilot_engine-2.0.5}/cli.py

@@ -116,11 +116,29 @@ def apply_cmd(args: argparse.Namespace) -> None:
     """Executes the universal form filling and submission workflow."""
     auto_inspect = not getattr(args, "no_auto_inspect", False)
 
+    from common.secrets import parse_and_resolve_fill_args
+    from builder import FormPayloadBuilder
+
+    raw_fill_args = args.fill or []
+    resolved_pairs = parse_and_resolve_fill_args(raw_fill_args)
+    effective_fill_args = [f"{k}={v}" for k, v in resolved_pairs]
+
+    effective_data_path = args.data
+    if args.data in ("-", "@stdin"):
+        try:
+            stdin_json = json.load(sys.stdin)
+            stdin_pairs = FormPayloadBuilder.normalize_payload(stdin_json)
+            effective_fill_args.extend([f"{k}={v}" for k, v in stdin_pairs])
+            effective_data_path = None
+        except Exception as exc:
+            print(f"[!] Error reading JSON payload from stdin: {exc}", file=sys.stderr)
+            sys.exit(1)
+
     if getattr(args, "standalone", False):
         req = ApplyRequestContext(
             url=args.url,
-            data_path=args.data,
-            fill_arguments=args.fill or [],
+            data_path=effective_data_path,
+            fill_arguments=effective_fill_args,
             press_buttons=args.press or [],
             upload_files=args.upload or [],
             cookies_path=args.cookies,
@@ -165,8 +183,8 @@ def apply_cmd(args: argparse.Namespace) -> None:
     req = SupervisorActionRequest(
         action="apply",
         url=args.url,
-        data_path=args.data,
-        fill_arguments=args.fill or [],
+        data_path=effective_data_path,
+        fill_arguments=effective_fill_args,
         press_buttons=args.press or [],
         upload_files=args.upload or [],
         cookies_path=args.cookies,

webpilot_engine-2.0.5/common/__init__.py

@@ -0,0 +1,17 @@
+"""Common utilities package for universal web applier."""
+
+from common.text import clean_label, truncate_text
+from common.cookies import sanitize_cookies, load_and_sanitize_cookies, save_cookies
+from common.retry import with_retry
+from common.logging import redact_sensitive, log_event
+
+__all__ = [
+    "clean_label",
+    "truncate_text",
+    "sanitize_cookies",
+    "load_and_sanitize_cookies",
+    "save_cookies",
+    "with_retry",
+    "redact_sensitive",
+    "log_event",
+]

webpilot_engine-2.0.5/common/cookies.py

@@ -0,0 +1,48 @@
+"""Cookie sanitization and persistence helpers for Playwright."""
+
+import json
+import os
+from typing import Any, Dict, List, Optional
+from core.exceptions import ValidationError
+
+INVALID_COOKIE_KEYS = ("hostOnly", "session", "storeId", "id")
+VALID_SAME_SITE_VALUES = ("Strict", "Lax", "None")
+
+def sanitize_cookies(raw_cookies: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+    """Sanitizes raw cookie objects ensuring full Playwright compatibility."""
+    if not isinstance(raw_cookies, list):
+        raise ValidationError(f"Expected list of cookies, got {type(raw_cookies).__name__}")
+
+    sanitized: List[Dict[str, Any]] = []
+    for c in raw_cookies:
+        if not isinstance(c, dict):
+            continue
+        cookie = dict(c)
+        same_site = str(cookie.get("sameSite", "")).capitalize()
+        if same_site in VALID_SAME_SITE_VALUES:
+            cookie["sameSite"] = same_site
+        else:
+            cookie.pop("sameSite", None)
+
+        for key in INVALID_COOKIE_KEYS:
+            cookie.pop(key, None)
+
+        sanitized.append(cookie)
+
+    return sanitized
+
+def load_and_sanitize_cookies(filepath: str) -> List[Dict[str, Any]]:
+    """Loads a JSON cookie file from disk and returns sanitized cookie dictionaries."""
+    if not os.path.isfile(filepath):
+        raise FileNotFoundError(f"Cookie file not found: {filepath}")
+
+    with open(filepath, "r", encoding="utf-8") as f:
+        raw_cookies = json.load(f)
+
+    return sanitize_cookies(raw_cookies)
+
+def save_cookies(filepath: str, cookies: List[Dict[str, Any]]) -> None:
+    """Persists cookie objects to disk formatted cleanly."""
+    os.makedirs(os.path.dirname(os.path.abspath(filepath)), exist_ok=True)
+    with open(filepath, "w", encoding="utf-8") as f:
+        json.dump(cookies, f, indent=2, ensure_ascii=False)

webpilot_engine-2.0.5/common/logging.py

@@ -0,0 +1,52 @@
+"""Structured logging and sensitive data redaction utilities."""
+
+import re
+from typing import Any, Dict, List, Set, Union
+
+SENSITIVE_KEY_PATTERNS: Set[str] = {
+    "password",
+    "secret",
+    "token",
+    "api_key",
+    "apikey",
+    "national_id",
+    "iqama",
+    "ssn",
+    "credentials",
+    "auth",
+    "cookie",
+}
+
+
+def redact_sensitive(data: Any) -> Any:
+    """Recursively redacts sensitive keys and values from dictionaries, lists, or strings."""
+    if isinstance(data, dict):
+        redacted = {}
+        for k, v in data.items():
+            k_lower = str(k).lower().strip()
+            if any(p in k_lower for p in SENSITIVE_KEY_PATTERNS):
+                redacted[k] = "[REDACTED]"
+            else:
+                redacted[k] = redact_sensitive(v)
+        return redacted
+
+    if isinstance(data, list):
+        return [redact_sensitive(item) for item in data]
+
+    if isinstance(data, tuple):
+        return tuple(redact_sensitive(item) for item in data)
+
+    if isinstance(data, str):
+        # Redact patterns resembling 9-10 digit national IDs (excluding all-zeros placeholders)
+        masked = re.sub(r"\b(?!0{9,10}\b)[1-9]\d{8,9}\b", "[REDACTED_ID]", data)
+        # Redact email addresses
+        masked = re.sub(r"[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+", "[REDACTED_EMAIL]", masked)
+        return masked
+
+    return data
+
+
+def log_event(level: str, operation: str, context: Dict[str, Any]) -> None:
+    """Prints a structured log line with sensitive fields automatically redacted."""
+    safe_ctx = redact_sensitive(context)
+    print(f"[{level.upper()}] {operation} | {safe_ctx}")

webpilot_engine-2.0.5/common/process_manager.py

@@ -0,0 +1,259 @@
+"""Cross-Platform Process Management and Isolation Layer.
+
+Isolates OS-specific process lifecycle mechanisms (WMI, CIM, taskkill on Windows;
+killpg, pgrep, signals on POSIX/Linux/macOS) behind a clean, unified ProcessManager interface.
+"""
+
+from __future__ import annotations
+
+import base64
+import os
+import signal
+import subprocess
+import sys
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List, Optional, Union
+
+
+class BaseProcessManager(ABC):
+    """Abstract interface for system process management and detached lifecycle execution."""
+
+    @abstractmethod
+    def launch_detached(
+        self,
+        cmd: Union[str, List[str]],
+        cwd: Optional[str] = None,
+        env: Optional[Dict[str, str]] = None,
+    ) -> Optional[int]:
+        """Launches a detached process decoupled from the caller's terminal and process group."""
+        pass
+
+    @abstractmethod
+    def kill_process_tree(self, pid: int, force: bool = True) -> bool:
+        """Kills the target process and all descendant child processes (cascading teardown)."""
+        pass
+
+    @abstractmethod
+    def get_child_pids(self, parent_pid: int) -> List[int]:
+        """Returns direct child process IDs for the given parent PID."""
+        pass
+
+    @abstractmethod
+    def is_process_running(self, pid: int) -> bool:
+        """Checks if a process with the specified PID is currently active."""
+        pass
+
+
+class WindowsProcessManager(BaseProcessManager):
+    """Windows-specific implementation using PowerShell WMI/CIM and taskkill."""
+
+    def launch_detached(
+        self,
+        cmd: Union[str, List[str]],
+        cwd: Optional[str] = None,
+        env: Optional[Dict[str, str]] = None,
+    ) -> Optional[int]:
+        target_cwd = cwd or os.getcwd()
+        if isinstance(cmd, list):
+            cmd_str = " ".join(f'"{arg}"' if " " in arg and not arg.startswith('"') else arg for arg in cmd)
+        else:
+            cmd_str = cmd
+
+        # Primary approach: Win32_Process.Create via WMI to break out of terminal Job Objects
+        ps_script = f"""
+$cwd = '{target_cwd}'
+$cmd = @'
+{cmd_str}
+'@
+$startup = ([wmiclass]'Win32_ProcessStartup').CreateInstance()
+$startup.ShowWindow = 0
+$proc = ([wmiclass]'Win32_Process').Create($cmd, $cwd, $startup)
+if ($proc.ReturnValue -eq 0) {{
+    Write-Output $proc.ProcessId
+}} else {{
+    exit 1
+}}
+"""
+        try:
+            encoded = base64.b64encode(ps_script.encode("utf-16le")).decode("ascii")
+            res = subprocess.run(
+                ["powershell", "-NoProfile", "-NonInteractive", "-EncodedCommand", encoded],
+                capture_output=True,
+                text=True,
+                timeout=10,
+            )
+            out = res.stdout.strip()
+            if res.returncode == 0 and out.isdigit():
+                return int(out)
+        except Exception:
+            pass
+
+        # Fallback approach: subprocess.Popen with DETACHED_PROCESS
+        try:
+            cmd_args = cmd if isinstance(cmd, list) else cmd_str
+            creation_flags = (
+                getattr(subprocess, "DETACHED_PROCESS", 0x00000008)
+                | getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0x00000200)
+            )
+            proc = subprocess.Popen(
+                cmd_args,
+                cwd=target_cwd,
+                env=env,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+                stdin=subprocess.DEVNULL,
+                creationflags=creation_flags,
+            )
+            return proc.pid
+        except Exception:
+            return None
+
+    def kill_process_tree(self, pid: int, force: bool = True) -> bool:
+        if not pid or pid <= 0:
+            return False
+        args = ["taskkill"]
+        if force:
+            args.append("/F")
+        args.extend(["/T", "/PID", str(pid)])
+        try:
+            res = subprocess.run(
+                args,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+                timeout=10,
+            )
+            return res.returncode == 0
+        except Exception:
+            return False
+
+    def get_child_pids(self, parent_pid: int) -> List[int]:
+        if not parent_pid or parent_pid <= 0:
+            return []
+        try:
+            ps_c = f"(Get-CimInstance Win32_Process | Where-Object {{ $_.ParentProcessId -eq {parent_pid} }}).ProcessId"
+            out = subprocess.check_output(
+                ["powershell", "-NoProfile", "-NonInteractive", "-Command", ps_c],
+                text=True,
+                stderr=subprocess.DEVNULL,
+                timeout=8,
+            ).strip()
+            pids = []
+            for line in out.splitlines():
+                line = line.strip()
+                if line.isdigit():
+                    pids.append(int(line))
+            return pids
+        except Exception:
+            return []
+
+    def is_process_running(self, pid: int) -> bool:
+        if not pid or pid <= 0:
+            return False
+        try:
+            ps_c = f"(Get-Process -Id {pid} -ErrorAction SilentlyContinue) -ne $null"
+            out = subprocess.check_output(
+                ["powershell", "-NoProfile", "-NonInteractive", "-Command", ps_c],
+                text=True,
+                stderr=subprocess.DEVNULL,
+                timeout=5,
+            ).strip()
+            return out.lower() == "true"
+        except Exception:
+            return False
+
+
+class PosixProcessManager(BaseProcessManager):
+    """POSIX/Linux/macOS implementation using setsid, signal.SIGKILL, and pgrep."""
+
+    def launch_detached(
+        self,
+        cmd: Union[str, List[str]],
+        cwd: Optional[str] = None,
+        env: Optional[Dict[str, str]] = None,
+    ) -> Optional[int]:
+        target_cwd = cwd or os.getcwd()
+        try:
+            cmd_args = cmd if isinstance(cmd, list) else cmd.split()
+            proc = subprocess.Popen(
+                cmd_args,
+                cwd=target_cwd,
+                env=env,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+                stdin=subprocess.DEVNULL,
+                start_new_session=True,  # setsid decoupling
+            )
+            return proc.pid
+        except Exception:
+            return None
+
+    def kill_process_tree(self, pid: int, force: bool = True) -> bool:
+        if not pid or pid <= 0:
+            return False
+        sig = signal.SIGKILL if force else signal.SIGTERM
+        killed = False
+        # Strategy 1: Process group kill if leader
+        try:
+            pgid = os.getpgid(pid)
+            os.killpg(pgid, sig)
+            killed = True
+        except Exception:
+            pass
+
+        # Strategy 2: pkill children then kill target
+        try:
+            subprocess.run(["pkill", "-P", str(pid)], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+            os.kill(pid, sig)
+            killed = True
+        except Exception:
+            pass
+
+        return killed
+
+    def get_child_pids(self, parent_pid: int) -> List[int]:
+        if not parent_pid or parent_pid <= 0:
+            return []
+        try:
+            out = subprocess.check_output(
+                ["pgrep", "-P", str(parent_pid)],
+                text=True,
+                stderr=subprocess.DEVNULL,
+                timeout=5,
+            ).strip()
+            pids = []
+            for line in out.splitlines():
+                line = line.strip()
+                if line.isdigit():
+                    pids.append(int(line))
+            return pids
+        except Exception:
+            return []
+
+    def is_process_running(self, pid: int) -> bool:
+        if not pid or pid <= 0:
+            return False
+        try:
+            os.kill(pid, 0)
+            return True
+        except OSError:
+            return False
+
+
+_GLOBAL_PROCESS_MANAGER: Optional[BaseProcessManager] = None
+
+
+def get_process_manager() -> BaseProcessManager:
+    """Returns the platform-appropriate ProcessManager singleton."""
+    global _GLOBAL_PROCESS_MANAGER
+    if _GLOBAL_PROCESS_MANAGER is None:
+        if sys.platform == "win32":
+            _GLOBAL_PROCESS_MANAGER = WindowsProcessManager()
+        else:
+            _GLOBAL_PROCESS_MANAGER = PosixProcessManager()
+    return _GLOBAL_PROCESS_MANAGER
+
+
+def set_process_manager(manager: Optional[BaseProcessManager]) -> None:
+    """Allows injecting custom or mock ProcessManager implementations for testing."""
+    global _GLOBAL_PROCESS_MANAGER
+    _GLOBAL_PROCESS_MANAGER = manager