"""Lightpanda local engine for Browser Use mode.

With ``browser.engine: lightpanda``, Browser Use mode spawns one ``lightpanda
serve`` per browser session and points ``browser_exec`` at its CDP endpoint
(``BU_CDP_URL``); the built-in ``browser_*`` tools keep going through
``agent-browser --engine lightpanda``. ``tools.browser_tool`` owns the session
cache, inactivity reaper and atexit sweep, calling :func:`launch_lightpanda`,
:func:`stop_lightpanda` and :func:`reap_orphaned_lightpanda` (for processes a
crashed Hermes left behind).
"""

import json
import logging
import os
import shutil
import socket
import subprocess
import threading
import time
from dataclasses import dataclass
from pathlib import Path
from typing import Dict, Optional, Tuple

logger = logging.getLogger(__name__)

LIGHTPANDA_INSTALL_URL = "https://lightpanda.io/docs/run-locally/installation/one-liner"
LIGHTPANDA_INSTALL_HINT = (
    f"Install Lightpanda from {LIGHTPANDA_INSTALL_URL} and make sure " "`lightpanda` is on PATH"
)

_READY_TIMEOUT_S = 10.0
_POLL_INTERVAL_S = 0.1
_STDERR_TAIL_LIMIT = 2000

_servers: Dict[str, "LightpandaServer"] = {}
_servers_lock = threading.Lock()


@dataclass
class LightpandaServer:
    session_name: str
    port: int
    proc: subprocess.Popen
    log_path: str
    start_time: Optional[int] = None

    @property
    def cdp_url(self) -> str:
        # HTTP discovery URL; the browser-use harness resolves /json/version itself.
        return f"http://127.0.0.1:{self.port}"

    def is_alive(self) -> bool:
        return self.proc.poll() is None


def _home_candidates() -> list:
    home = Path.home()
    candidates = [
        home / ".lightpanda" / "lightpanda", home / ".local" / "bin" / "lightpanda"
    ]
    try:
        from hermes_constants import get_hermes_home

        candidates.append(Path(get_hermes_home()) / "bin" / "lightpanda")
    except Exception as e:  # pragma: no cover - defensive
        logger.debug("hermes home unavailable for lightpanda lookup: %s", e)
    return candidates


def find_lightpanda_binary() -> Optional[str]:
    """Return the lightpanda executable, or None.

    Order: PATH (with the same Homebrew/managed-node fallbacks agent-browser
    gets), then the locations the Lightpanda installer and agent-browser use
    (``~/.lightpanda/lightpanda``, ``~/.local/bin/lightpanda``), then
    ``$HERMES_HOME/bin/lightpanda``. Lightpanda has no Windows build.
    """
    if os.name == "nt":
        logger.debug("Lightpanda has no Windows build")
        return None
    path_env = os.environ.get("PATH", "")
    try:
        from tools.browser_tool import _merge_browser_path

        path_env = _merge_browser_path(path_env)
    except Exception as e:
        logger.debug("browser PATH merge unavailable: %s", e)
    found = shutil.which("lightpanda", path=path_env)
    if found:
        return found
    for candidate in _home_candidates():
        if candidate.is_file() and os.access(candidate, os.X_OK):
            return str(candidate)
    return None


def _pick_free_loopback_port() -> int:
    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
        sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
        sock.bind(("127.0.0.1", 0))
        return int(sock.getsockname()[1])


def _state_dir() -> Path:
    from hermes_constants import get_hermes_home

    path = Path(get_hermes_home()) / "cache" / "browser-use" / "lightpanda"
    path.mkdir(parents=True, exist_ok=True)
    return path


def _record_path(session_name: str) -> Path:
    return _state_dir() / f"{session_name}.json"


def _browser_env() -> dict:
    try:
        from tools.browser_tool import _build_browser_env

        return _build_browser_env()
    except Exception as e:
        logger.debug("credential-scrubbed browser env unavailable: %s", e)
        return os.environ.copy()


def _cdp_ready(url: str) -> bool:
    try:
        from hermes_cli.browser_connect import is_browser_debug_ready

        return is_browser_debug_ready(url, timeout=0.2)
    except Exception as e:
        logger.debug("CDP readiness probe failed for %s: %s", url, e)
        return False


def _read_log_tail(path: str) -> str:
    try:
        with open(path, "rb") as fh:
            data = fh.read()
    except OSError:
        return ""
    text = data[-_STDERR_TAIL_LIMIT:].decode("utf-8", errors="replace").strip()
    lines = [line for line in text.splitlines() if line.strip()]
    return lines[-1] if lines else ""


def _terminate(proc: subprocess.Popen) -> None:
    try:
        if proc.poll() is None:
            proc.terminate()
            try:
                proc.wait(timeout=5)
            except Exception:
                proc.kill()
    except Exception as e:
        logger.debug("lightpanda terminate failed: %s", e)


def _safe_start_time(pid: int) -> Optional[int]:
    try:
        from tools.process_registry import ProcessRegistry

        return ProcessRegistry._safe_host_start_time(pid)
    except Exception:
        return None


def _tree_kill(pid: int, expected_start) -> None:
    """Tree-kill ``pid`` via ProcessRegistry, verifying its start time first."""
    from tools.process_registry import ProcessRegistry

    ProcessRegistry._terminate_host_pid(pid, expected_start=expected_start)


def _kill_server(server: LightpandaServer) -> None:
    """Tree-kill a live server, falling back to plain terminate on any failure."""
    try:
        _tree_kill(server.proc.pid, server.start_time)
    except Exception as e:
        logger.debug("lightpanda tree-kill failed for %s: %s", server.session_name, e)
        _terminate(server.proc)
    try:
        server.proc.wait(timeout=5)
    except Exception:
        _terminate(server.proc)


def _write_record(server: LightpandaServer) -> None:
    record = {
        "pid": server.proc.pid,
        "port": server.port,
        "owner_pid": os.getpid(),
        "start_time": server.start_time,
        "started_at": time.time(),
    }
    try:
        _record_path(server.session_name).write_text(json.dumps(record), encoding="utf-8")
    except OSError as e:
        logger.debug("could not write lightpanda record for %s: %s", server.session_name, e)


def _unlink_record(session_name: str) -> None:
    try:
        _record_path(session_name).unlink(missing_ok=True)
    except OSError as e:
        logger.debug("could not remove lightpanda record for %s: %s", session_name, e)


def launch_lightpanda(
    session_name: str, *, block_private_networks: bool = False
) -> Tuple[Optional[LightpandaServer], Optional[str]]:
    """Start ``lightpanda serve`` on a free loopback port for ``session_name``.

    Returns ``(server, None)`` once ``/json/version`` answers, or
    ``(None, error)`` with an actionable message. The child's stderr goes to
    ``$HERMES_HOME/cache/browser-use/lightpanda/<session>.log`` so a chatty
    process can never block on a pipe; only the tail is read on failure.
    """
    binary = find_lightpanda_binary()
    if not binary:
        if os.name == "nt":
            return None, (
                "browser.engine is 'lightpanda' but Lightpanda has no Windows "
                "build. Set browser.engine to auto (or run Hermes under WSL2)."
            )
        return None, (
            "browser.engine is 'lightpanda' but no lightpanda binary was found "
            "on PATH, ~/.lightpanda or ~/.local/bin. "
            f"{LIGHTPANDA_INSTALL_HINT}, or set browser.engine to auto."
        )

    port = _pick_free_loopback_port()
    argv = [binary, "serve", "--host", "127.0.0.1", "--port", str(port)]
    if block_private_networks:
        argv.append("--block-private-networks")
    log_path = str(_state_dir() / f"{session_name}.log")

    # find_lightpanda_binary() returns None on nt, so no Windows spawn branch is needed.
    try:
        with open(log_path, "wb") as log_file:
            proc = subprocess.Popen(
                argv,
                stdin=subprocess.DEVNULL,
                stdout=subprocess.DEVNULL,
                stderr=log_file,
                env=_browser_env(),
                start_new_session=True,
            )
    except (OSError, subprocess.SubprocessError) as e:
        return None, f"Failed to launch lightpanda serve ({binary}): {e}"

    url = f"http://127.0.0.1:{port}"
    deadline = time.monotonic() + _READY_TIMEOUT_S
    while True:
        rc = proc.poll()
        if rc is not None:
            tail = _read_log_tail(log_path)
            detail = f": {tail}" if tail else ""
            return None, (
                f"lightpanda serve exited with code {rc} before {url}/json/version "
                f"answered{detail}"
            )
        if _cdp_ready(url):
            break
        if time.monotonic() >= deadline:
            _terminate(proc)
            tail = _read_log_tail(log_path)
            detail = f" (last stderr line: {tail})" if tail else ""
            return None, (
                f"lightpanda serve did not expose {url}/json/version within "
                f"{int(_READY_TIMEOUT_S)}s{detail}"
            )
        time.sleep(_POLL_INTERVAL_S)

    server = LightpandaServer(
        session_name=session_name,
        port=port,
        proc=proc,
        log_path=log_path,
        start_time=_safe_start_time(proc.pid),
    )
    _write_record(server)
    with _servers_lock:
        _servers[session_name] = server
    logger.info(
        "Started lightpanda serve (pid %s, port %s) for session %s", proc.pid, port, session_name
    )
    return server, None


def get_server(session_name: str) -> Optional[LightpandaServer]:
    with _servers_lock:
        return _servers.get(session_name)


def stop_lightpanda(session_name: str) -> None:
    """Stop the server for ``session_name`` (tree-kill) and drop its record."""
    with _servers_lock:
        server = _servers.pop(session_name, None)
    if server is not None and server.is_alive():
        _kill_server(server)
    _unlink_record(session_name)
    if server is not None:
        logger.debug("Stopped lightpanda serve for session %s", session_name)


def stop_all_lightpanda() -> None:
    """Stop every server this process started. Idempotent; safe from atexit."""
    with _servers_lock:
        names = list(_servers)
    for name in names:
        try:
            stop_lightpanda(name)
        except Exception as e:
            logger.debug("lightpanda stop failed for %s: %s", name, e)


def _is_lightpanda_process(pid: int, port, start_time) -> bool:
    """True only when ``pid`` is verifiably the ``lightpanda serve`` we recorded."""
    try:
        import psutil

        proc = psutil.Process(pid)
        if "lightpanda" not in proc.name().lower():
            return False
        cmdline = proc.cmdline()
        if "serve" not in cmdline or str(port) not in cmdline:
            return False
    except Exception:
        return False
    if start_time:
        try:
            from gateway.status import get_process_start_time

            return get_process_start_time(pid) == start_time
        except Exception:
            return False
    return True


def reap_orphaned_lightpanda() -> int:
    """Kill ``lightpanda serve`` processes whose owning Hermes is gone.

    Records are written by :func:`launch_lightpanda`; a live owner (another
    Hermes process, or this one still tracking the session) is never
    touched, and a PID is only signalled after psutil confirms it is still
    a ``lightpanda serve`` on the recorded port. Returns the reap count.
    """
    try:
        state_dir = _state_dir()
    except Exception as e:
        logger.debug("lightpanda state dir unavailable: %s", e)
        return 0
    try:
        from gateway.status import _pid_exists
    except Exception:  # pragma: no cover - defensive
        return 0

    reaped = 0
    for record_path in sorted(state_dir.glob("*.json")):
        session_name = record_path.stem
        try:
            record = json.loads(record_path.read_text(encoding="utf-8"))
        except (OSError, ValueError):
            record_path.unlink(missing_ok=True)
            continue
        owner_pid = record.get("owner_pid")
        if owner_pid == os.getpid():
            with _servers_lock:
                if session_name in _servers:
                    continue
        elif owner_pid and _pid_exists(int(owner_pid)):
            continue
        pid = record.get("pid")
        if not pid or not _is_lightpanda_process(int(pid), record.get("port"), record.get("start_time")):
            record_path.unlink(missing_ok=True)
            continue
        try:
            _tree_kill(int(pid), record.get("start_time"))
            reaped += 1
            logger.info("Reaped orphaned lightpanda serve pid %s (session %s)", pid, session_name)
        except Exception as e:
            logger.debug("orphan lightpanda kill failed for pid %s: %s", pid, e)
        record_path.unlink(missing_ok=True)
    return reaped