@bitseek/hermes-webui 0.1.0-beta.0

package/vendor/agent-frontend-shell/api/system_health.py

@@ -0,0 +1,167 @@
+"""Safe aggregate host resource metrics for the WebUI VPS panel (#693).
+
+The browser only needs coarse CPU/RAM/disk usage. Keep this module intentionally
+small and dependency-free: no process lists, command strings, user identities,
+environment variables, or filesystem topology leave the server.
+"""
+
+from __future__ import annotations
+
+import shutil
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+_PROC_STAT = Path("/proc/stat")
+_PROC_MEMINFO = Path("/proc/meminfo")
+_CPU_SAMPLE_SECONDS = 0.05
+
+
+def _checked_at() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _clamp_percent(value: Any) -> float:
+    try:
+        numeric = float(value)
+    except (TypeError, ValueError):
+        return 0.0
+    if numeric < 0:
+        numeric = 0.0
+    if numeric > 100:
+        numeric = 100.0
+    return round(numeric, 1)
+
+
+def _read_proc_stat_cpu() -> tuple[int, int]:
+    """Return (idle_ticks, total_ticks) from Linux /proc/stat."""
+    with _PROC_STAT.open("r", encoding="utf-8") as handle:
+        first = handle.readline().strip().split()
+    if not first or first[0] != "cpu":
+        raise RuntimeError("proc_stat_unavailable")
+    values = [int(part) for part in first[1:]]
+    if len(values) < 4:
+        raise RuntimeError("proc_stat_unavailable")
+    idle = values[3] + (values[4] if len(values) > 4 else 0)
+    total = sum(values)
+    if total <= 0:
+        raise RuntimeError("proc_stat_unavailable")
+    return idle, total
+
+
+def _cpu_delta_percent(start: tuple[int, int], end: tuple[int, int]) -> float:
+    idle_delta = end[0] - start[0]
+    total_delta = end[1] - start[1]
+    if total_delta <= 0:
+        return 0.0
+    busy_delta = max(0, total_delta - max(0, idle_delta))
+    return _clamp_percent((busy_delta / total_delta) * 100.0)
+
+
+def _cpu_percent() -> float:
+    """Sample aggregate CPU usage without psutil.
+
+    A short local sample avoids storing cross-request state and returns a stable
+    percentage on the first poll. Unsupported platforms raise a safe error code.
+    """
+    start = _read_proc_stat_cpu()
+    time.sleep(_CPU_SAMPLE_SECONDS)
+    end = _read_proc_stat_cpu()
+    return _cpu_delta_percent(start, end)
+
+
+def _read_meminfo_kib() -> dict[str, int]:
+    data: dict[str, int] = {}
+    with _PROC_MEMINFO.open("r", encoding="utf-8") as handle:
+        for line in handle:
+            key, _, rest = line.partition(":")
+            if not key or not rest:
+                continue
+            parts = rest.strip().split()
+            if not parts:
+                continue
+            try:
+                data[key] = int(parts[0])
+            except ValueError:
+                continue
+    return data
+
+
+def _memory_usage() -> dict[str, int | float]:
+    meminfo = _read_meminfo_kib()
+    total = int(meminfo.get("MemTotal") or 0) * 1024
+    if total <= 0:
+        raise RuntimeError("meminfo_unavailable")
+    available_kib = meminfo.get("MemAvailable")
+    if available_kib is None:
+        available_kib = (
+            meminfo.get("MemFree", 0)
+            + meminfo.get("Buffers", 0)
+            + meminfo.get("Cached", 0)
+            + meminfo.get("SReclaimable", 0)
+            - meminfo.get("Shmem", 0)
+        )
+    available = max(0, int(available_kib) * 1024)
+    used = max(0, min(total, total - available))
+    return {
+        "used_bytes": used,
+        "total_bytes": total,
+        "percent": _clamp_percent((used / total) * 100.0),
+    }
+
+
+def _disk_usage() -> dict[str, int | float]:
+    usage = shutil.disk_usage("/")
+    total = int(usage.total)
+    if total <= 0:
+        raise RuntimeError("disk_unavailable")
+    used = int(usage.used)
+    return {
+        "used_bytes": used,
+        "total_bytes": total,
+        "percent": _clamp_percent((used / total) * 100.0),
+    }
+
+
+def _safe_error(metric: str, exc: Exception) -> dict[str, str]:
+    # Keep this intentionally coarse. Exception messages can contain local paths
+    # on unusual platforms; the browser only needs a safe unavailable reason.
+    return {"metric": metric, "code": type(exc).__name__}
+
+
+def build_system_health_payload() -> dict[str, Any]:
+    metrics: dict[str, Any] = {"cpu": None, "memory": None, "disk": None}
+    errors: list[dict[str, str]] = []
+
+    collectors = {
+        "cpu": _cpu_percent,
+        "memory": _memory_usage,
+        "disk": _disk_usage,
+    }
+    for name, collect in collectors.items():
+        try:
+            value = collect()
+            if name == "cpu":
+                metrics[name] = {"percent": _clamp_percent(value)}
+            else:
+                metrics[name] = {
+                    "used_bytes": max(0, int(value["used_bytes"])),
+                    "total_bytes": max(0, int(value["total_bytes"])),
+                    "percent": _clamp_percent(value["percent"]),
+                }
+        except Exception as exc:
+            errors.append(_safe_error(name, exc))
+
+    available = any(metrics[name] is not None for name in metrics)
+    status = "ok" if available and not errors else "partial" if available else "unavailable"
+    return {
+        "status": status,
+        "available": available,
+        "checked_at": _checked_at(),
+        "cpu": metrics["cpu"],
+        "memory": metrics["memory"],
+        "disk": metrics["disk"],
+        "errors": errors,
+    }

package/vendor/agent-frontend-shell/api/terminal.py

@@ -0,0 +1,410 @@
+"""Embedded workspace terminal support for Hermes Web UI.
+
+The terminal is intentionally independent from the agent execution path.  It
+starts a shell with an explicit cwd/env per process and never mutates
+process-global os.environ, which avoids expanding the session-env race tracked
+in the agent execution layer.
+"""
+
+from __future__ import annotations
+
+import errno
+import atexit
+import codecs
+import fcntl
+import os
+import queue
+import select
+import shutil
+import signal
+import struct
+import subprocess
+import termios
+import threading
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+def _set_nonblocking(fd: int) -> None:
+    flags = fcntl.fcntl(fd, fcntl.F_GETFL)
+    fcntl.fcntl(fd, fcntl.F_SETFL, flags | os.O_NONBLOCK)
+
+
+def _winsize(rows: int, cols: int) -> bytes:
+    rows = max(8, min(int(rows or 24), 80))
+    cols = max(20, min(int(cols or 80), 240))
+    return struct.pack("HHHH", rows, cols, 0, 0)
+
+
+def _safe_close_fd(fd: int) -> None:
+    try:
+        os.close(fd)
+    except OSError:
+        pass
+
+
+@dataclass
+class TerminalSession:
+    session_id: str
+    workspace: str
+    proc: subprocess.Popen
+    master_fd: int
+    rows: int = 24
+    cols: int = 80
+    output: queue.Queue = field(default_factory=lambda: queue.Queue(maxsize=2000))
+    closed: threading.Event = field(default_factory=threading.Event)
+    reader: threading.Thread | None = None
+
+    def is_alive(self) -> bool:
+        return not self.closed.is_set() and self.proc.poll() is None
+
+    def put_output(self, event: str, payload: dict) -> None:
+        try:
+            self.output.put_nowait((event, payload))
+        except queue.Full:
+            # Keep the terminal responsive by dropping the oldest queued chunk.
+            try:
+                self.output.get_nowait()
+            except queue.Empty:
+                pass
+            try:
+                self.output.put_nowait((event, payload))
+            except queue.Full:
+                pass
+
+
+_TERMINALS: dict[str, TerminalSession] = {}
+_LOCK = threading.RLock()
+_spawn_queue: queue.Queue = queue.Queue()
+_spawn_supervisor_started = False
+_spawn_supervisor_lock = threading.Lock()
+_spawn_supervisor_thread: threading.Thread | None = None
+
+
+@dataclass
+class _SpawnRequest:
+    kwargs: dict
+    done: threading.Event = field(default_factory=threading.Event)
+    timed_out: threading.Event = field(default_factory=threading.Event)
+    lock: threading.Lock = field(default_factory=threading.Lock)
+    proc: subprocess.Popen | None = None
+    error: BaseException | None = None
+
+
+def _reap_abandoned_spawn(proc: subprocess.Popen) -> bool:
+    if proc.poll() is not None:
+        return True
+    try:
+        os.killpg(proc.pid, signal.SIGHUP)
+    except (OSError, ProcessLookupError):
+        try:
+            proc.terminate()
+        except (OSError, ProcessLookupError):
+            pass
+    try:
+        proc.wait(timeout=1.0)
+    except subprocess.TimeoutExpired:
+        try:
+            os.killpg(proc.pid, signal.SIGKILL)
+        except (OSError, ProcessLookupError):
+            try:
+                proc.kill()
+            except (OSError, ProcessLookupError):
+                pass
+        try:
+            proc.wait(timeout=1.0)
+        except (subprocess.TimeoutExpired, ProcessLookupError):
+            pass
+    if proc.poll() is None:
+        print("terminal abandoned spawn cleanup failed", flush=True)
+        return False
+    return True
+
+
+def _spawn_supervisor_loop() -> None:
+    while True:
+        request = None
+        try:
+            request = _spawn_queue.get()
+            try:
+                proc = subprocess.Popen(**request.kwargs)
+                with request.lock:
+                    if request.timed_out.is_set():
+                        _reap_abandoned_spawn(proc)
+                    else:
+                        request.proc = proc
+                    request.done.set()
+            except BaseException as exc:
+                with request.lock:
+                    try:
+                        request.error = exc
+                    except BaseException:
+                        pass
+                    request.done.set()
+        except BaseException as exc:
+            if request is not None:
+                try:
+                    request.error = exc
+                except BaseException:
+                    pass
+                try:
+                    request.done.set()
+                except BaseException:
+                    pass
+            time.sleep(0.01)
+
+
+def _spawn_supervisor_entry() -> None:
+    while True:
+        try:
+            _spawn_supervisor_loop()
+        except BaseException:
+            time.sleep(0.01)
+            pass
+
+
+def _ensure_spawn_supervisor() -> None:
+    global _spawn_supervisor_started, _spawn_supervisor_thread
+    with _spawn_supervisor_lock:
+        if _spawn_supervisor_started and _spawn_supervisor_thread and _spawn_supervisor_thread.is_alive():
+            return
+        thread = threading.Thread(target=_spawn_supervisor_entry, daemon=True)
+        thread.start()
+        _spawn_supervisor_thread = thread
+        _spawn_supervisor_started = True
+
+
+_ensure_spawn_supervisor()
+
+
+# NOTE on parent-death-signal: a previous version of this module set
+# PR_SET_PDEATHSIG via a preexec_fn to terminate orphaned PTY shells when the
+# WebUI process crashed.  That broke every Linux user (#2853): WebUI runs a
+# ThreadingHTTPServer, so the Popen call happens on a short-lived per-request
+# thread, and PR_SET_PDEATHSIG is per-thread.  The PTY shell registered the
+# spawning thread as its "parent" and was killed with SIGTERM the instant that
+# thread joined — within ~10 ms of opening the terminal — surfacing as the
+# `[terminal closed]` banner.  The graceful path is covered by
+# `atexit.register(close_all_terminals)` and the explicit `close_terminal`
+# call sites; hard kills of the WebUI process leak the shell, which is the
+# tradeoff for working on Linux at all.
+
+
+def _decode_terminal_output(decoder, data: bytes) -> str:
+    """Decode PTY bytes without stripping terminal control sequences."""
+    return decoder.decode(data)
+
+
+def _shell_path() -> str:
+    shell = os.environ.get("SHELL") or ""
+    if shell and Path(shell).exists():
+        return shell
+    return shutil.which("zsh") or shutil.which("bash") or shutil.which("sh") or "/bin/sh"
+
+
+def _shell_argv(shell: str) -> list[str]:
+    name = Path(shell).name
+    if name in {"zsh", "bash", "sh"}:
+        return [shell, "-i"]
+    return [shell]
+
+
+def _reader_loop(term: TerminalSession) -> None:
+    decoder = codecs.getincrementaldecoder("utf-8")("replace")
+    try:
+        while not term.closed.is_set():
+            if term.proc.poll() is not None:
+                break
+            try:
+                ready, _, _ = select.select([term.master_fd], [], [], 0.25)
+            except (OSError, ValueError):
+                break
+            if not ready:
+                continue
+            try:
+                data = os.read(term.master_fd, 8192)
+            except OSError as exc:
+                if exc.errno in (errno.EIO, errno.EBADF):
+                    break
+                raise
+            if not data:
+                break
+            text = _decode_terminal_output(decoder, data)
+            if text:
+                term.put_output("output", {"text": text})
+    except Exception as exc:
+        term.put_output("terminal_error", {"error": str(exc)})
+    finally:
+        term.closed.set()
+        code = term.proc.poll()
+        term.put_output("terminal_closed", {"exit_code": code})
+
+
+def _set_size(term: TerminalSession, rows: int, cols: int) -> None:
+    term.rows = max(8, min(int(rows or term.rows or 24), 80))
+    term.cols = max(20, min(int(cols or term.cols or 80), 240))
+    try:
+        fcntl.ioctl(term.master_fd, termios.TIOCSWINSZ, _winsize(term.rows, term.cols))
+    except OSError:
+        pass
+    try:
+        if term.proc.poll() is None:
+            os.killpg(term.proc.pid, signal.SIGWINCH)
+    except (OSError, ProcessLookupError):
+        pass
+
+
+def start_terminal(session_id: str, workspace: Path, rows: int = 24, cols: int = 80, restart: bool = False) -> TerminalSession:
+    """Start or return the embedded terminal for a WebUI session."""
+    sid = str(session_id or "").strip()
+    if not sid:
+        raise ValueError("session_id is required")
+    cwd = str(Path(workspace).expanduser().resolve())
+    if not Path(cwd).is_dir():
+        raise ValueError("workspace is not a directory")
+
+    with _LOCK:
+        current = _TERMINALS.get(sid)
+        if current and current.is_alive() and not restart and current.workspace == cwd:
+            _set_size(current, rows, cols)
+            return current
+        if current:
+            close_terminal(sid)
+
+        master_fd, slave_fd = os.openpty()
+        # Build a safe env: allowlist common shell vars, strip API keys and secrets.
+        # The PTY shell is an interactive UI surface — do not leak server credentials.
+        _SAFE_ENV_KEYS = {
+            "PATH", "HOME", "USER", "LOGNAME", "SHELL", "LANG", "LC_ALL",
+            "LC_CTYPE", "LC_MESSAGES", "LANGUAGE", "TZ", "TMPDIR", "TEMP",
+            "XDG_RUNTIME_DIR", "XDG_CONFIG_HOME", "XDG_DATA_HOME",
+        }
+        env = {k: v for k, v in os.environ.items() if k in _SAFE_ENV_KEYS}
+        env.update(
+            {
+                "TERM": "xterm-256color",
+                "COLORTERM": "truecolor",
+                "COLUMNS": str(cols),
+                "LINES": str(rows),
+                "PWD": cwd,
+                "HERMES_WEBUI_TERMINAL": "1",
+            }
+        )
+        shell = _shell_path()
+        # Keep the shell in its own process group for explicit cleanup via
+        # close_terminal()/close_all_terminals(); do not use PDEATHSIG here.
+        request = _SpawnRequest(
+            {
+                "args": _shell_argv(shell),
+                "cwd": cwd,
+                "env": env,
+                "stdin": slave_fd,
+                "stdout": slave_fd,
+                "stderr": slave_fd,
+                "close_fds": True,
+                # Required so cleanup can signal the whole interactive shell tree.
+                "start_new_session": True,
+            }
+        )
+        _ensure_spawn_supervisor()
+        _spawn_queue.put(request)
+        try:
+            if not request.done.wait(timeout=5.0):
+                timed_out = False
+                with request.lock:
+                    if not request.done.is_set():
+                        request.timed_out.set()
+                        timed_out = True
+                if timed_out:
+                    raise TimeoutError("terminal spawn timeout - supervisor unresponsive")
+            if request.error:
+                raise request.error
+            proc = request.proc
+            if proc is None:
+                raise RuntimeError("terminal spawn failed without process")
+        except BaseException:
+            _safe_close_fd(master_fd)
+            _safe_close_fd(slave_fd)
+            raise
+        os.close(slave_fd)
+        _set_nonblocking(master_fd)
+
+        term = TerminalSession(
+            session_id=sid,
+            workspace=cwd,
+            proc=proc,
+            master_fd=master_fd,
+            rows=rows,
+            cols=cols,
+        )
+        _set_size(term, rows, cols)
+        term.reader = threading.Thread(target=_reader_loop, args=(term,), daemon=True)
+        term.reader.start()
+        _TERMINALS[sid] = term
+        return term
+
+
+def get_terminal(session_id: str) -> TerminalSession | None:
+    with _LOCK:
+        term = _TERMINALS.get(str(session_id or ""))
+        if term and term.is_alive():
+            return term
+        return term
+
+
+def write_terminal(session_id: str, data: str) -> None:
+    term = get_terminal(session_id)
+    if not term or not term.is_alive():
+        raise KeyError("terminal not running")
+    os.write(term.master_fd, str(data or "").encode("utf-8", errors="replace"))
+
+
+def resize_terminal(session_id: str, rows: int, cols: int) -> None:
+    term = get_terminal(session_id)
+    if not term:
+        raise KeyError("terminal not running")
+    _set_size(term, rows, cols)
+
+
+def close_terminal(session_id: str) -> bool:
+    sid = str(session_id or "")
+    with _LOCK:
+        term = _TERMINALS.pop(sid, None)
+    if not term:
+        return False
+    term.closed.set()
+    try:
+        if term.proc.poll() is None:
+            try:
+                os.killpg(term.proc.pid, signal.SIGHUP)
+            except ProcessLookupError:
+                pass
+            try:
+                term.proc.wait(timeout=1.5)
+            except subprocess.TimeoutExpired:
+                try:
+                    os.killpg(term.proc.pid, signal.SIGKILL)
+                except ProcessLookupError:
+                    pass
+                try:
+                    term.proc.wait(timeout=1.0)
+                except (subprocess.TimeoutExpired, ProcessLookupError):
+                    pass
+    finally:
+        try:
+            os.close(term.master_fd)
+        except OSError:
+            pass
+    return True
+
+
+def close_all_terminals() -> None:
+    """Best-effort reap of embedded shells during graceful WebUI shutdown."""
+    with _LOCK:
+        session_ids = list(_TERMINALS)
+    for session_id in session_ids:
+        close_terminal(session_id)
+
+
+atexit.register(close_all_terminals)