browser-control-and-automation-cli 0.1.1.dev3__py3-none-any.whl

browser_cli/daemon/client.py

@@ -0,0 +1,280 @@
+"""Client helpers for daemon-backed commands."""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import os
+import signal
+import subprocess
+import sys
+import time
+import uuid
+from pathlib import Path
+from typing import Any
+
+from browser_cli import __version__
+from browser_cli.agent_scope import resolve_agent_id
+from browser_cli.constants import get_app_paths
+from browser_cli.errors import (
+    AmbiguousRefError,
+    BrowserCliError,
+    BrowserUnavailableError,
+    BusyTabError,
+    DaemonNotAvailableError,
+    EmptyContentError,
+    InvalidInputError,
+    NoActiveTabError,
+    NoSnapshotContextError,
+    NoVisibleTabsError,
+    OperationFailedError,
+    ProfileUnavailableError,
+    RefNotFoundError,
+    StaleSnapshotError,
+    TabNotFoundError,
+    TemporaryReadError,
+)
+
+from .transport import (
+    DAEMON_RUNTIME_VERSION,
+    ensure_run_dir,
+    probe_socket,
+    read_run_info,
+    remove_run_info,
+    safe_remove_socket,
+)
+
+STARTUP_TIMEOUT_SECONDS = 15.0
+STARTUP_PROBE_INTERVAL_SECONDS = 0.1
+TERMINATE_GRACE_SECONDS = 3.0
+
+
+def send_command(
+    action: str,
+    args: dict[str, Any] | None = None,
+    *,
+    start_if_needed: bool = True,
+) -> dict[str, Any]:
+    if action == "stop" and not probe_socket():
+        return {
+            "ok": True,
+            "data": {"stopped": False, "already_stopped": True},
+            "meta": {"action": "stop", "agent_id": resolve_agent_id()},
+        }
+    if start_if_needed:
+        ensure_daemon_running()
+    elif not probe_socket():
+        raise DaemonNotAvailableError()
+    return asyncio.run(_send_command_async(action, args or {}))
+
+
+async def _send_command_async(action: str, args: dict[str, Any]) -> dict[str, Any]:
+    app_paths = get_app_paths()
+    try:
+        reader, writer = await asyncio.open_unix_connection(str(app_paths.socket_path))
+    except OSError as exc:
+        raise DaemonNotAvailableError(str(exc)) from exc
+    request_payload = {
+        "action": action,
+        "args": args,
+        "agent_id": resolve_agent_id(),
+        "request_id": uuid.uuid4().hex,
+    }
+    writer.write((json.dumps(request_payload) + "\n").encode("utf-8"))
+    await writer.drain()
+    raw = await reader.readline()
+    writer.close()
+    with contextlib.suppress(Exception):
+        await writer.wait_closed()
+    if not raw:
+        raise DaemonNotAvailableError("Browser daemon closed the connection without a response.")
+    payload = json.loads(raw.decode("utf-8"))
+    if payload.get("ok"):
+        return payload
+    raise _error_from_payload(payload)
+
+
+def ensure_daemon_running() -> None:
+    run_info = read_run_info()
+    if probe_socket() and _run_info_is_compatible(run_info):
+        return
+    if probe_socket():
+        _cleanup_stale_runtime()
+        if probe_socket():
+            return
+    _cleanup_stale_runtime()
+    if probe_socket():
+        return
+    _spawn_daemon()
+
+
+def wait_for_daemon_stop(*, timeout_seconds: float = TERMINATE_GRACE_SECONDS) -> bool:
+    deadline = time.time() + timeout_seconds
+    while time.time() < deadline:
+        if not probe_socket():
+            return True
+        time.sleep(0.1)
+    return not probe_socket()
+
+
+def cleanup_runtime(*, fast_kill: bool = False) -> bool:
+    app_paths = get_app_paths()
+    had_runtime_state = bool(read_run_info() is not None or app_paths.socket_path.exists())
+    _cleanup_stale_runtime(fast_kill=fast_kill)
+    return had_runtime_state
+
+
+def run_info_is_compatible(run_info: dict[str, Any] | None) -> bool:
+    return _run_info_is_compatible(run_info)
+
+
+def _spawn_daemon() -> None:
+    ensure_run_dir()
+    app_paths = get_app_paths()
+    existing_pythonpath = os.environ.get("PYTHONPATH", "")
+    source_root = Path(__file__).resolve().parents[2]
+    pythonpath_parts = [str(source_root)]
+    if existing_pythonpath:
+        pythonpath_parts.append(existing_pythonpath)
+    env = os.environ.copy()
+    env["PYTHONPATH"] = os.pathsep.join(pythonpath_parts)
+    log_handle = app_paths.daemon_log_path.open("ab")
+    process = None
+    try:
+        process = subprocess.Popen(
+            _build_daemon_command(app_paths.home),
+            stdout=log_handle,
+            stderr=subprocess.STDOUT,
+            env=env,
+            start_new_session=True,
+        )
+    finally:
+        log_handle.close()
+    if _wait_for_socket(timeout_seconds=STARTUP_TIMEOUT_SECONDS):
+        return
+    if process is not None:
+        _terminate_process_tree(process.pid)
+    run_info = read_run_info()
+    details = f"run_info={run_info}" if run_info else f"log={app_paths.daemon_log_path}"
+    raise DaemonNotAvailableError(f"Timed out waiting for browser daemon startup ({details}).")
+
+
+def _build_daemon_command(home: Path) -> list[str]:
+    return [sys.executable, "-m", "browser_cli.daemon", "--home", str(home)]
+
+
+def _wait_for_socket(*, timeout_seconds: float) -> bool:
+    deadline = time.time() + timeout_seconds
+    while time.time() < deadline:
+        if probe_socket():
+            return True
+        time.sleep(STARTUP_PROBE_INTERVAL_SECONDS)
+    return False
+
+
+def _cleanup_stale_runtime(*, fast_kill: bool = False) -> None:
+    run_info = read_run_info()
+    socket_reachable = probe_socket()
+    if run_info is not None:
+        pid = _coerce_pid(run_info.get("pid"))
+        if pid is not None and _pid_exists(pid):
+            if fast_kill and not socket_reachable:
+                _signal_process_tree(pid, signal.SIGKILL)
+                _wait_for_pid_exit(pid, timeout_seconds=1.0)
+            else:
+                _terminate_process_tree(pid)
+    remove_run_info()
+    with contextlib.suppress(FileNotFoundError):
+        safe_remove_socket()
+
+
+def _run_info_is_compatible(run_info: dict[str, Any] | None) -> bool:
+    if not isinstance(run_info, dict):
+        return False
+    return (
+        str(run_info.get("package_version") or "") == __version__
+        and str(run_info.get("runtime_version") or "") == DAEMON_RUNTIME_VERSION
+    )
+
+
+def _coerce_pid(value: Any) -> int | None:
+    try:
+        pid = int(value)
+    except (TypeError, ValueError):
+        return None
+    return pid if pid > 0 else None
+
+
+def _pid_exists(pid: int) -> bool:
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+    else:
+        return True
+
+
+def _terminate_process_tree(pid: int) -> None:
+    _signal_process_tree(pid, signal.SIGTERM)
+    if _wait_for_pid_exit(pid, timeout_seconds=TERMINATE_GRACE_SECONDS):
+        return
+    _signal_process_tree(pid, signal.SIGKILL)
+    _wait_for_pid_exit(pid, timeout_seconds=1.0)
+
+
+def _signal_process_tree(pid: int, sig: signal.Signals) -> None:
+    try:
+        os.killpg(pid, sig)
+    except ProcessLookupError:
+        return
+    except OSError:
+        try:
+            os.kill(pid, sig)
+        except OSError:
+            return
+
+
+def _wait_for_pid_exit(pid: int, *, timeout_seconds: float) -> bool:
+    deadline = time.time() + timeout_seconds
+    while time.time() < deadline:
+        if not _pid_exists(pid):
+            return True
+        time.sleep(0.1)
+    return not _pid_exists(pid)
+
+
+def _error_from_payload(payload: dict[str, Any]) -> BrowserCliError:
+    error_code = str(payload.get("error_code") or "OPERATION_FAILED")
+    message = str(payload.get("error_message") or "Daemon command failed.")
+    if error_code == "INVALID_INPUT":
+        return InvalidInputError(message)
+    if error_code == "NO_ACTIVE_TAB":
+        return NoActiveTabError(message)
+    if error_code == "NO_VISIBLE_TABS":
+        return NoVisibleTabsError(message)
+    if error_code == "AGENT_ACTIVE_TAB_BUSY":
+        return BusyTabError(message)
+    if error_code == "TAB_NOT_FOUND":
+        return TabNotFoundError(message)
+    if error_code == "REF_NOT_FOUND":
+        return RefNotFoundError(message)
+    if error_code == "NO_SNAPSHOT_CONTEXT":
+        return NoSnapshotContextError(message)
+    if error_code == "AMBIGUOUS_REF":
+        return AmbiguousRefError(message)
+    if error_code == "STALE_SNAPSHOT":
+        return StaleSnapshotError(message)
+    if error_code == "DAEMON_NOT_AVAILABLE":
+        return DaemonNotAvailableError(message)
+    if error_code == "BROWSER_UNAVAILABLE":
+        return BrowserUnavailableError(message)
+    if error_code == "PROFILE_UNAVAILABLE":
+        return ProfileUnavailableError(message)
+    if error_code == "EMPTY_CONTENT":
+        return EmptyContentError(message)
+    if error_code == "TEMPORARY_FAILURE":
+        return TemporaryReadError(message)
+    return OperationFailedError(message, error_code=error_code)

browser_cli/daemon/models.py

@@ -0,0 +1,63 @@
+"""Daemon request and response models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(slots=True)
+class DaemonRequest:
+    action: str
+    args: dict[str, Any]
+    agent_id: str
+    request_id: str
+
+    @classmethod
+    def from_dict(cls, payload: dict[str, Any]) -> DaemonRequest:
+        return cls(
+            action=str(payload.get("action") or "").strip(),
+            args=dict(payload.get("args") or {}),
+            agent_id=str(payload.get("agent_id") or "").strip(),
+            request_id=str(payload.get("request_id") or "").strip(),
+        )
+
+
+@dataclass(slots=True)
+class DaemonResponse:
+    ok: bool
+    data: dict[str, Any] | None = None
+    meta: dict[str, Any] = field(default_factory=dict)
+    error_code: str | None = None
+    error_message: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        payload: dict[str, Any] = {
+            "ok": self.ok,
+            "data": self.data or {},
+            "meta": self.meta,
+        }
+        if not self.ok:
+            payload["error_code"] = self.error_code
+            payload["error_message"] = self.error_message
+        return payload
+
+    @classmethod
+    def success(cls, data: dict[str, Any], *, meta: dict[str, Any] | None = None) -> DaemonResponse:
+        return cls(ok=True, data=data, meta=meta or {})
+
+    @classmethod
+    def failure(
+        cls,
+        *,
+        error_code: str,
+        error_message: str,
+        meta: dict[str, Any] | None = None,
+    ) -> DaemonResponse:
+        return cls(
+            ok=False,
+            data={},
+            meta=meta or {},
+            error_code=error_code,
+            error_message=error_message,
+        )

browser_cli/daemon/runtime_presentation.py

@@ -0,0 +1,167 @@
+"""Daemon-owned runtime presentation model derived from raw runtime facts."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def build_runtime_presentation(raw_status: dict[str, Any]) -> dict[str, Any]:
+    browser_started = bool(raw_status.get("browser_started"))
+    active_driver = str(raw_status.get("active_driver") or "not-started")
+    pending_rebind = _as_dict_or_none(raw_status.get("pending_rebind"))
+    extension = dict(raw_status.get("extension") or {})
+    workspace_window_state = dict(raw_status.get("workspace_window_state") or {})
+    tabs = dict(raw_status.get("tabs") or {})
+    busy_tab_count = int(tabs.get("busy_count") or 0)
+    binding_state = str(workspace_window_state.get("binding_state") or "absent")
+    extension_connected = bool(extension.get("connected"))
+    capability_complete = bool(extension.get("capability_complete"))
+    stability = dict(raw_status.get("stability") or {})
+    cleanup_failures = int(stability.get("cleanup_failures") or 0)
+    last_cleanup_error = str(stability.get("last_cleanup_error") or "").strip() or None
+
+    execution_path = {
+        "active_driver": active_driver,
+        "pending_rebind": pending_rebind,
+        "safe_point_wait": pending_rebind is not None,
+        "last_transition": _as_dict_or_none(raw_status.get("last_transition")),
+    }
+    workspace_state = {
+        "window_id": workspace_window_state.get("window_id"),
+        "tab_count": int(workspace_window_state.get("tab_count") or 0),
+        "managed_tab_count": int(workspace_window_state.get("managed_tab_count") or 0),
+        "binding_state": binding_state,
+        "busy_tab_count": busy_tab_count,
+    }
+
+    overall_state = "healthy"
+    summary_reason = "Browser CLI runtime is healthy."
+    recovery_guidance = ["Browser CLI can continue normally."]
+
+    if not browser_started:
+        summary_reason = "Browser runtime is idle and will start on the next browser command."
+        recovery_guidance = ["Run a browser command to initialize runtime state."]
+    elif active_driver == "not-started":
+        overall_state = "broken"
+        summary_reason = "Browser runtime reports started but no active driver is selected."
+        recovery_guidance = [
+            "Refresh runtime status to confirm the state.",
+            "Reload Browser CLI if the runtime remains driverless.",
+        ]
+    elif pending_rebind is not None:
+        overall_state = "recovering"
+        summary_reason = _pending_rebind_summary(pending_rebind)
+        recovery_guidance = _pending_rebind_guidance(pending_rebind)
+    elif active_driver != "extension":
+        overall_state = "degraded"
+        summary_reason = "Browser CLI is running on Playwright instead of extension mode."
+        recovery_guidance = [
+            "Agent can continue on the managed profile backend.",
+            "Reconnect the extension if real Chrome mode should be restored.",
+        ]
+    elif not extension_connected or not capability_complete:
+        overall_state = "degraded"
+        if extension_connected:
+            summary_reason = "Extension is connected but its required capabilities are incomplete."
+        else:
+            summary_reason = "Extension mode is selected but the extension is disconnected."
+        recovery_guidance = [
+            "Reconnect or reload the extension.",
+            "Refresh runtime status after extension health changes.",
+        ]
+    elif binding_state in {"stale", "absent"}:
+        overall_state = "degraded"
+        if binding_state == "stale":
+            summary_reason = "Workspace binding is stale while extension mode is active."
+        else:
+            summary_reason = "Browser CLI no longer has a trusted extension workspace binding."
+        recovery_guidance = [
+            "Rebuild workspace binding to restore Browser CLI-owned tab tracking.",
+            "Reconnect the extension if workspace state does not recover.",
+        ]
+    elif cleanup_failures:
+        overall_state = "degraded"
+        summary_reason = "Browser CLI recorded recent cleanup failures during runtime transitions."
+        recovery_guidance = [
+            "Run `browser-cli reload` if cleanup failures continue to appear.",
+            "Refresh runtime status after the reload finishes.",
+        ]
+
+    return {
+        "overall_state": overall_state,
+        "summary_reason": summary_reason,
+        "execution_path": execution_path,
+        "workspace_state": workspace_state,
+        "stability": {
+            **stability,
+            "last_cleanup_error": last_cleanup_error,
+        },
+        "recovery_guidance": recovery_guidance,
+        "available_actions": _available_actions(
+            active_driver=active_driver,
+            pending_rebind=pending_rebind,
+            extension_connected=extension_connected,
+            capability_complete=capability_complete,
+            binding_state=binding_state,
+        ),
+    }
+
+
+def _available_actions(
+    *,
+    active_driver: str,
+    pending_rebind: dict[str, Any] | None,
+    extension_connected: bool,
+    capability_complete: bool,
+    binding_state: str,
+) -> list[str]:
+    actions = ["refresh-status"]
+    if (
+        pending_rebind is not None
+        or active_driver != "extension"
+        or not extension_connected
+        or not capability_complete
+    ):
+        actions.append("reconnect-extension")
+    if active_driver == "extension" and binding_state in {"stale", "absent"}:
+        if "reconnect-extension" not in actions:
+            actions.append("reconnect-extension")
+        actions.append("rebuild-workspace-binding")
+    return actions
+
+
+def _pending_rebind_summary(pending_rebind: dict[str, Any]) -> str:
+    target = str(pending_rebind.get("target") or "unknown")
+    reason = str(pending_rebind.get("reason") or "pending-rebind")
+    if reason == "extension-disconnected-waiting-command" and target == "playwright":
+        return (
+            "Extension disconnected; Browser CLI will switch to Playwright at the next safe point."
+        )
+    if reason == "extension-connected" and target == "extension":
+        return (
+            "Extension reconnected; Browser CLI will restore extension mode at the next safe point."
+        )
+    return f"Browser CLI is waiting to rebind the active driver to {target} at the next safe point."
+
+
+def _pending_rebind_guidance(pending_rebind: dict[str, Any]) -> list[str]:
+    target = str(pending_rebind.get("target") or "unknown")
+    if target == "playwright":
+        return [
+            "Agent can continue while Browser CLI waits for the safe-point fallback.",
+            "Reconnect the extension if real Chrome mode should be restored later.",
+        ]
+    if target == "extension":
+        return [
+            "Wait for the current command boundary, then refresh runtime status.",
+            "Browser CLI will resume extension mode at the next safe point.",
+        ]
+    return [
+        "Wait for the current command boundary, then refresh runtime status.",
+    ]
+
+
+def _as_dict_or_none(value: Any) -> dict[str, Any] | None:
+    if isinstance(value, dict):
+        return dict(value)
+    return None

browser_cli/daemon/server.py

@@ -0,0 +1,103 @@
+"""Daemon server entrypoint."""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import logging
+import os
+import signal
+import time
+
+from browser_cli import __version__
+from browser_cli.constants import get_app_paths
+
+from .app import BrowserDaemonApp
+from .models import DaemonRequest, DaemonResponse
+from .transport import (
+    DAEMON_RUNTIME_VERSION,
+    ensure_run_dir,
+    remove_run_info,
+    safe_remove_socket,
+    write_run_info,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class BrowserDaemonServer:
+    def __init__(self, app: BrowserDaemonApp | None = None) -> None:
+        self._app = app or BrowserDaemonApp()
+        self._server: asyncio.AbstractServer | None = None
+
+    async def serve(self) -> None:
+        app_paths = get_app_paths()
+        logger.info("Starting Browser CLI daemon")
+        loop = asyncio.get_running_loop()
+        installed_signal_handlers: list[signal.Signals] = []
+        for sig in (signal.SIGINT, signal.SIGTERM, signal.SIGHUP):
+            try:
+                loop.add_signal_handler(sig, self._app.state.shutdown_event.set)
+                installed_signal_handlers.append(sig)
+            except (NotImplementedError, RuntimeError):
+                pass
+        ensure_run_dir()
+        if app_paths.socket_path.exists():
+            safe_remove_socket(app_paths.socket_path)
+        try:
+            await self._app.state.browser_service.ensure_extension_listener_started()
+            self._server = await asyncio.start_unix_server(
+                self._handle_client,
+                path=str(app_paths.socket_path),
+            )
+            with contextlib.suppress(OSError):
+                os.chmod(app_paths.socket_path, 0o600)
+            write_run_info(
+                {
+                    "transport": "unix",
+                    "socket": str(app_paths.socket_path),
+                    "pid": os.getpid(),
+                    "pgid": os.getpgrp(),
+                    "home": str(app_paths.home),
+                    "started_at": time.time(),
+                    "package_version": __version__,
+                    "runtime_version": DAEMON_RUNTIME_VERSION,
+                }
+            )
+            logger.info("Browser CLI daemon listening on %s", app_paths.socket_path)
+            await self._app.state.shutdown_event.wait()
+        finally:
+            logger.info("Stopping Browser CLI daemon")
+            if self._server is not None:
+                self._server.close()
+                await self._server.wait_closed()
+                self._server = None
+            await self._app.state.browser_service.stop()
+            remove_run_info()
+            with contextlib.suppress(FileNotFoundError):
+                safe_remove_socket(app_paths.socket_path)
+            for sig in installed_signal_handlers:
+                with contextlib.suppress(Exception):
+                    loop.remove_signal_handler(sig)
+
+    async def _handle_client(
+        self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter
+    ) -> None:
+        try:
+            raw = await reader.readline()
+            if not raw:
+                return
+            payload = json.loads(raw.decode("utf-8"))
+            request = DaemonRequest.from_dict(payload)
+            response = await self._app.execute(request)
+        except Exception as exc:  # pragma: no cover
+            response = DaemonResponse.failure(
+                error_code="DAEMON_PROTOCOL_ERROR",
+                error_message=str(exc),
+            )
+        writer.write((json.dumps(response.to_dict()) + "\n").encode("utf-8"))
+        await writer.drain()
+        writer.close()
+        with contextlib.suppress(Exception):
+            await writer.wait_closed()

browser_cli/daemon/state.py

@@ -0,0 +1,15 @@
+"""Shared daemon state."""
+
+from __future__ import annotations
+
+import asyncio
+
+from browser_cli.daemon.browser_service import BrowserService
+from browser_cli.tabs import TabRegistry
+
+
+class DaemonState:
+    def __init__(self) -> None:
+        self.tabs = TabRegistry()
+        self.browser_service = BrowserService(self.tabs)
+        self.shutdown_event = asyncio.Event()