iflow-mcp_janspoerer-mcp_browser_use 0.1.0__py3-none-any.whl

mcp_browser_use/locking/action_lock.py

@@ -0,0 +1,190 @@
+"""Action lock management for coordinating browser actions across processes."""
+
+import os
+import json
+import time
+import asyncio
+from typing import Dict, Any, Optional
+
+# Global intra-process lock
+MCP_INTRA_PROCESS_LOCK: Optional[asyncio.Lock] = None
+
+
+def get_intra_process_lock() -> asyncio.Lock:
+    """Get or create the intra-process asyncio lock."""
+    global MCP_INTRA_PROCESS_LOCK
+    if MCP_INTRA_PROCESS_LOCK is None:
+        MCP_INTRA_PROCESS_LOCK = asyncio.Lock()
+    return MCP_INTRA_PROCESS_LOCK
+
+
+def _read_softlock(path: str) -> Dict[str, Any]:
+    """Read softlock JSON file."""
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            return json.load(f) or {}
+    except FileNotFoundError:
+        return {}
+    except Exception:
+        return {}
+
+
+def _write_softlock(path: str, state: Dict[str, Any]):
+    """Write softlock JSON file atomically."""
+    tmp = f"{path}.tmp"
+    with open(tmp, "w", encoding="utf-8") as f:
+        json.dump(state, f)
+    os.replace(tmp, path)
+
+
+def _acquire_softlock(owner: str, ttl: int, wait: bool = True, wait_timeout: float = None) -> Dict[str, Any]:
+    """
+    Acquire a softlock for the given owner.
+
+    Args:
+        owner: Identifier of the lock owner
+        ttl: Time to live in seconds
+        wait: Whether to wait for the lock
+        wait_timeout: Maximum time to wait (defaults to ACTION_LOCK_WAIT_SECS)
+
+    Returns:
+        Dictionary with lock acquisition status
+    """
+    from .file_mutex import _lock_paths, _file_mutex, _now
+    from ..constants import FILE_MUTEX_STALE_SECS, ACTION_LOCK_WAIT_SECS
+
+    if wait_timeout is None:
+        wait_timeout = ACTION_LOCK_WAIT_SECS
+
+    softlock_json, softlock_mutex, _ = _lock_paths()
+    deadline = _now() + max(0.0, wait_timeout)
+
+    while True:
+        try:
+            with _file_mutex(softlock_mutex, stale_secs=FILE_MUTEX_STALE_SECS, wait_timeout=min(5.0, max(0.1, deadline - _now()))):
+                state = _read_softlock(softlock_json)
+                cur_owner = state.get("owner")
+                expires_at = float(state.get("expires_at", 0.0))
+
+                if not cur_owner or expires_at <= _now() or cur_owner == owner:
+                    new_exp = _now() + ttl
+                    _write_softlock(softlock_json, {"owner": owner, "expires_at": new_exp})
+                    return {"acquired": True, "owner": owner, "expires_at": new_exp}
+
+                result = {
+                    "acquired": False,
+                    "owner": cur_owner,
+                    "expires_at": float(expires_at),
+                    "message": "busy",
+                }
+        except TimeoutError:
+            if not wait or _now() >= deadline:
+                # Best-effort read without mutex for context
+                state = _read_softlock(softlock_json)
+                return {
+                    "acquired": False,
+                    "owner": state.get("owner"),
+                    "expires_at": float(state.get("expires_at", 0.0)) if state.get("expires_at") else None,
+                    "message": "mutex_timeout",
+                }
+
+        if not wait or _now() >= deadline:
+            return result
+        time.sleep(0.05)
+
+
+def _release_action_lock(owner: str) -> bool:
+    """
+    Release the action lock if owned by the given owner.
+
+    Args:
+        owner: Identifier of the lock owner
+
+    Returns:
+        True if lock was released, False otherwise
+    """
+    from .file_mutex import _lock_paths, _file_mutex
+    from ..constants import FILE_MUTEX_STALE_SECS
+
+    softlock_json, softlock_mutex, _ = _lock_paths()
+    with _file_mutex(softlock_mutex, stale_secs=FILE_MUTEX_STALE_SECS, wait_timeout=5.0):
+        state = _read_softlock(softlock_json)
+        if state.get("owner") == owner:
+            _write_softlock(softlock_json, {})
+            return True
+        return False
+
+
+def _renew_action_lock(owner: str, ttl: int) -> bool:
+    """
+    Extend the action lock if owned by `owner`, or if stale. No-op if owned by someone else and not stale.
+    Also updates the window registry heartbeat as a piggyback optimization.
+
+    Args:
+        owner: Identifier of the lock owner
+        ttl: Time to live in seconds
+
+    Returns:
+        True if we wrote a new expiry, False otherwise
+    """
+    from .file_mutex import _lock_paths, _file_mutex, _now
+    from .window_registry import _update_window_heartbeat
+    from ..constants import FILE_MUTEX_STALE_SECS
+
+    softlock_json, softlock_mutex, _ = _lock_paths()
+    try:
+        with _file_mutex(softlock_mutex, stale_secs=FILE_MUTEX_STALE_SECS, wait_timeout=1.0):
+            state = _read_softlock(softlock_json)
+            cur_owner = state.get("owner")
+            expires_at = float(state.get("expires_at", 0.0) or 0.0)
+
+            if cur_owner == owner or expires_at <= _now():
+                new_exp = _now() + int(ttl)
+                _write_softlock(softlock_json, {"owner": owner, "expires_at": new_exp})
+
+                # Piggyback: update window heartbeat while we're renewing the lock
+                try:
+                    _update_window_heartbeat(owner)
+                except Exception:
+                    pass  # Non-critical
+
+                return True
+            return False
+    except Exception:
+        return False
+
+
+def _acquire_action_lock_or_error(owner: str) -> Optional[str]:
+    """
+    Acquire action lock or return error message.
+
+    Args:
+        owner: Identifier of the lock owner
+
+    Returns:
+        None if lock acquired, error JSON string otherwise
+    """
+    from ..constants import ACTION_LOCK_TTL_SECS, ACTION_LOCK_WAIT_SECS
+
+    res = _acquire_softlock(owner=owner, ttl=ACTION_LOCK_TTL_SECS, wait=True, wait_timeout=ACTION_LOCK_WAIT_SECS)
+    if res.get("acquired"):
+        return None
+
+    return json.dumps({
+        "ok": False,
+        "error": "locked",
+        "owner": res.get("owner"),
+        "expires_at": res.get("expires_at"),
+        "lock_ttl_seconds": ACTION_LOCK_TTL_SECS,
+    })
+
+
+__all__ = [
+    'get_intra_process_lock',
+    '_read_softlock',
+    '_write_softlock',
+    '_acquire_softlock',
+    '_release_action_lock',
+    '_renew_action_lock',
+    '_acquire_action_lock_or_error',
+]

mcp_browser_use/locking/file_mutex.py

@@ -0,0 +1,139 @@
+"""File-based mutex and startup lock implementation."""
+
+import os
+import time
+import shutil
+import tempfile
+import contextlib
+import psutil
+from pathlib import Path
+
+
+def _now() -> float:
+    """Return current time as float timestamp."""
+    return time.time()
+
+
+def _lock_paths():
+    """
+    Get paths for lock files based on profile key.
+
+    Returns:
+        Tuple of (softlock_json, softlock_mutex, startup_mutex) paths
+    """
+    # Import here to avoid circular dependency
+    from ..config.environment import profile_key, get_env_config
+    from ..config.paths import get_lock_dir
+
+    key = profile_key(get_env_config())  # stable across processes; independent of port
+    base = Path(get_lock_dir())
+    base.mkdir(parents=True, exist_ok=True)
+    softlock_json = base / f"{key}.softlock.json"
+    softlock_mutex = base / f"{key}.softlock.mutex"
+    startup_mutex = base / f"{key}.startup.mutex"
+    return str(softlock_json), str(softlock_mutex), str(startup_mutex)
+
+
+@contextlib.contextmanager
+def _file_mutex(path: str, stale_secs: int, wait_timeout: float):
+    """
+    Simple cross-process mutex via an exclusive file create.
+    Removes stale mutex if older than stale_secs.
+    """
+    start = _now()
+    p = Path(path)
+    while True:
+        try:
+            fd = os.open(str(p), os.O_CREAT | os.O_EXCL | os.O_RDWR)
+            break
+        except FileExistsError:
+            try:
+                st = p.stat()
+                if _now() - st.st_mtime > stale_secs:
+                    p.unlink(missing_ok=True)
+                    continue
+            except FileNotFoundError:
+                continue
+            if _now() - start > wait_timeout:
+                raise TimeoutError(f"Timed out waiting for mutex {p}")
+            time.sleep(0.05)
+    try:
+        yield
+    finally:
+        try:
+            os.close(fd)
+        except Exception:
+            pass
+        try:
+            p.unlink(missing_ok=True)
+        except Exception:
+            pass
+
+
+def start_lock_dir(config: dict) -> str:
+    """Get path to startup lock directory for the given profile."""
+    from ..config.environment import profile_key
+    return os.path.join(tempfile.gettempdir(), f"mcp_chrome_start_lock_{profile_key(config)}")
+
+
+def acquire_start_lock(config: dict, timeout_sec: float = None) -> bool:
+    """
+    Acquire startup lock to ensure only one process starts Chrome.
+
+    Args:
+        config: Configuration dictionary
+        timeout_sec: Timeout in seconds (defaults to START_LOCK_WAIT_SEC from helpers)
+
+    Returns:
+        True if lock acquired, False on timeout
+    """
+    if timeout_sec is None:
+        from ..constants import START_LOCK_WAIT_SEC
+        timeout_sec = START_LOCK_WAIT_SEC
+
+    lock_dir = start_lock_dir(config)
+    deadline = time.time() + timeout_sec
+    while time.time() < deadline:
+        try:
+            os.mkdir(lock_dir)
+            with open(os.path.join(lock_dir, "pid"), "w") as f:
+                f.write(str(os.getpid()))
+            return True
+        except FileExistsError:
+            # If owner died, break it
+            pid_file = os.path.join(lock_dir, "pid")
+            try:
+                if os.path.exists(pid_file):
+                    with open(pid_file, "r") as f:
+                        pid_txt = f.read().strip()
+                    pid = int(pid_txt) if pid_txt.isdigit() else None
+                else:
+                    pid = None
+            except Exception:
+                pid = None
+            if pid and not psutil.pid_exists(pid):
+                try:
+                    shutil.rmtree(lock_dir, ignore_errors=True)
+                    continue
+                except Exception:
+                    pass
+            time.sleep(0.05)
+    return False
+
+
+def release_start_lock(config: dict) -> None:
+    """Release startup lock."""
+    try:
+        shutil.rmtree(start_lock_dir(config), ignore_errors=True)
+    except Exception:
+        pass
+
+
+__all__ = [
+    '_now',
+    '_lock_paths',
+    '_file_mutex',
+    'start_lock_dir',
+    'acquire_start_lock',
+    'release_start_lock',
+]

mcp_browser_use/locking/window_registry.py

@@ -0,0 +1,178 @@
+"""Window registry for tracking browser window ownership across processes."""
+
+import os
+import json
+import time
+import psutil
+from pathlib import Path
+from typing import Dict, Any, Optional
+
+import logging
+logger = logging.getLogger(__name__)
+
+
+def _window_registry_path() -> str:
+    """Get path to window registry file for this profile."""
+    from ..config.environment import profile_key, get_env_config
+    from ..config.paths import get_lock_dir
+
+    key = profile_key(get_env_config())
+    return str(Path(get_lock_dir()) / f"{key}.window_registry.json")
+
+
+def _read_window_registry() -> Dict[str, Any]:
+    """Read the window registry. Returns empty dict if not found or invalid."""
+    path = _window_registry_path()
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            return json.load(f) or {}
+    except FileNotFoundError:
+        return {}
+    except Exception:
+        return {}
+
+
+def _write_window_registry(registry: Dict[str, Any]):
+    """Write window registry atomically using temp file + rename."""
+    path = _window_registry_path()
+    tmp = f"{path}.tmp"
+    try:
+        with open(tmp, "w", encoding="utf-8") as f:
+            json.dump(registry, f, indent=2)
+        os.replace(tmp, path)
+    except Exception:
+        pass  # Non-critical if write fails
+
+
+def _register_window(agent_id: str, target_id: str, window_id: Optional[int]):
+    """Register a window as owned by this agent."""
+    registry = _read_window_registry()
+    registry[agent_id] = {
+        "target_id": target_id,
+        "window_id": window_id,
+        "pid": os.getpid(),
+        "last_heartbeat": time.time(),
+        "created_at": time.time(),
+    }
+    _write_window_registry(registry)
+
+
+def _update_window_heartbeat(agent_id: str):
+    """Update the heartbeat timestamp for this agent's window."""
+    registry = _read_window_registry()
+    if agent_id in registry:
+        registry[agent_id]["last_heartbeat"] = time.time()
+        _write_window_registry(registry)
+
+
+def _unregister_window(agent_id: str):
+    """Remove this agent's window from the registry."""
+    registry = _read_window_registry()
+    if agent_id in registry:
+        del registry[agent_id]
+        _write_window_registry(registry)
+
+
+def cleanup_orphaned_windows(driver, *, close_on_stale: bool = False):
+    """
+    Close windows owned by dead processes. Optionally close very stale windows if explicitly enabled.
+
+    - Default behavior: only close when the owning PID no longer exists.
+    - Stale heartbeats are logged but not closed by default to avoid killing idle sessions.
+
+    Args:
+        driver: Selenium WebDriver instance
+        close_on_stale: If True, also close windows with stale heartbeats (default False)
+    """
+    from ..constants import WINDOW_REGISTRY_STALE_THRESHOLD
+
+    # If you have a registry/file lock, acquire it here
+    # with _registry_lock():
+    registry = _read_window_registry()
+    now = time.time()
+
+    to_remove: list[str] = []
+    changed = False
+
+    # Optional: detect already-missing targets to avoid noisy close attempts
+    try:
+        targets_resp = driver.execute_cdp_cmd("Target.getTargets", {})
+        known_targets = {t.get("targetId") for t in targets_resp.get("targetInfos", [])}
+    except Exception:
+        known_targets = None  # fall back to best-effort without pre-check
+
+    for agent_id, info in list(registry.items()):
+        pid = info.get("pid")
+        last_hb = info.get("last_heartbeat")
+        target_id = info.get("target_id")
+
+        # Robustness: skip weird records
+        if target_id is None:
+            logger.info(f"Removing registry entry with no target_id: agent={agent_id}, pid={pid}")
+            to_remove.append(agent_id)
+            changed = True
+            continue
+
+        # Compute states safely
+        try:
+            is_dead = bool(pid) and not psutil.pid_exists(int(pid))
+        except Exception:
+            # If pid cannot be parsed, treat as unknown (do not close)
+            is_dead = False
+
+        is_stale = False
+        if isinstance(last_hb, (int, float)):
+            try:
+                is_stale = (now - float(last_hb)) > WINDOW_REGISTRY_STALE_THRESHOLD
+            except Exception:
+                is_stale = False
+
+        # If target is already gone, just drop the registry entry
+        if known_targets is not None and target_id not in known_targets:
+            logger.info(f"Target already gone; pruning registry entry: agent={agent_id}, target={target_id}")
+            to_remove.append(agent_id)
+            changed = True
+            continue
+
+        # Decide whether to close
+        should_close = is_dead or (close_on_stale and is_stale)
+        if not should_close:
+            if is_stale:
+                logger.debug(f"Stale heartbeat but not closing (agent={agent_id}, pid={pid})")
+            continue
+
+        # Try to close the target
+        try:
+            res = driver.execute_cdp_cmd("Target.closeTarget", {"targetId": target_id})
+            success = (res.get("success", True) if isinstance(res, dict) else True)
+            logger.info(
+                f"Closed orphaned window: agent={agent_id}, target={target_id}, "
+                f"dead={is_dead}, stale={is_stale}, success={success}"
+            )
+        except Exception as e:
+            # Even if we fail to close a window of a dead process, remove the entry to avoid leaks
+            logger.debug(f"Could not close target {target_id} for agent {agent_id}: {e}")
+
+        to_remove.append(agent_id)
+        changed = True
+
+    # Clean up registry
+    if to_remove:
+        for agent_id in to_remove:
+            registry.pop(agent_id, None)
+        _write_window_registry(registry)
+        logger.info(f"Cleaned up {len(to_remove)} window registry entry(ies)")
+    elif changed:
+        # In case we changed something else
+        _write_window_registry(registry)
+
+
+__all__ = [
+    '_window_registry_path',
+    '_read_window_registry',
+    '_write_window_registry',
+    '_register_window',
+    '_update_window_heartbeat',
+    '_unregister_window',
+    'cleanup_orphaned_windows',
+]

mcp_browser_use/tools/__init__.py

@@ -0,0 +1,59 @@
+# mcp_browser_use/tools/__init__.py
+"""
+MCP tool implementations - async wrappers that return JSON responses.
+
+This package contains high-level tool implementations that:
+- Wrap lower-level helpers/actions
+- Return JSON-serialized responses
+- Include error handling and diagnostics
+- Provide page snapshots
+"""
+
+from .browser_management import (
+    start_browser,
+    unlock_browser,
+    close_browser,
+    force_close_all_chrome,
+)
+
+from .navigation import (
+    navigate_to_url,
+    scroll,
+)
+
+from .interaction import (
+    fill_text,
+    click_element,
+    send_keys,
+    wait_for_element,
+)
+
+from .debugging import (
+    get_debug_diagnostics_info,
+    debug_element,
+)
+
+from .screenshots import (
+    take_screenshot,
+)
+
+__all__ = [
+    # Browser management
+    'start_browser',
+    'unlock_browser',
+    'close_browser',
+    'force_close_all_chrome',
+    # Navigation
+    'navigate_to_url',
+    'scroll',
+    # Interaction
+    'fill_text',
+    'click_element',
+    'send_keys',
+    'wait_for_element',
+    # Debugging
+    'get_debug_diagnostics_info',
+    'debug_element',
+    # Screenshots
+    'take_screenshot',
+]