@bitseek/hermes-webui 0.1.0-beta.0

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

@@ -0,0 +1,284 @@
+"""Append-only WebUI run event journal helpers.
+
+This is the first #1925 journal/replay slice.  It mirrors SSE events emitted by
+the existing in-process streaming path without changing execution ownership.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import threading
+import time
+from pathlib import Path
+from typing import Iterable
+
+RUN_JOURNAL_DIR_NAME = "_run_journal"
+_SAFE_ID_RE = re.compile(r"^[A-Za-z0-9_.-]+$")
+_WRITER_LOCKS: dict[tuple[str, str, str], threading.Lock] = {}
+_WRITER_LOCKS_GUARD = threading.Lock()
+_TERMINAL_SSE_EVENTS = {"done", "cancel", "apperror", "error", "stream_end"}
+_FSYNC_MODE_ENV = "HERMES_WEBUI_RUN_JOURNAL_FSYNC"
+_FSYNC_MODE_EAGER = "eager"
+_FSYNC_MODE_TERMINAL_ONLY = "terminal-only"
+
+
+def _default_session_dir() -> Path:
+    from api.models import SESSION_DIR
+
+    return Path(SESSION_DIR)
+
+
+def _validate_id(value: str, field: str) -> str:
+    cleaned = str(value or "").strip()
+    if not cleaned or "/" in cleaned or "\\" in cleaned or not _SAFE_ID_RE.fullmatch(cleaned):
+        raise ValueError(f"invalid {field}")
+    return cleaned
+
+
+def _run_path(session_id: str, run_id: str, session_dir: Path | None = None) -> Path:
+    sid = _validate_id(session_id, "session_id")
+    rid = _validate_id(run_id, "run_id")
+    root = Path(session_dir) if session_dir is not None else _default_session_dir()
+    return root / RUN_JOURNAL_DIR_NAME / sid / f"{rid}.jsonl"
+
+
+def _lock_for(path: Path) -> threading.Lock:
+    key = (str(path.parent), path.name, str(os.getpid()))
+    with _WRITER_LOCKS_GUARD:
+        lock = _WRITER_LOCKS.get(key)
+        if lock is None:
+            lock = threading.Lock()
+            _WRITER_LOCKS[key] = lock
+        return lock
+
+
+def _read_jsonl(path: Path) -> tuple[list[dict], list[dict]]:
+    events: list[dict] = []
+    malformed: list[dict] = []
+    try:
+        lines = path.read_text(encoding="utf-8").splitlines()
+    except FileNotFoundError:
+        return events, malformed
+    for line_no, raw in enumerate(lines, start=1):
+        if not raw.strip():
+            continue
+        try:
+            parsed = json.loads(raw)
+        except json.JSONDecodeError:
+            malformed.append({"line": line_no, "raw": raw})
+            continue
+        if isinstance(parsed, dict):
+            events.append(parsed)
+        else:
+            malformed.append({"line": line_no, "raw": raw})
+    return events, malformed
+
+
+def _next_seq(path: Path) -> int:
+    events, _malformed = _read_jsonl(path)
+    seqs = [int(event.get("seq") or 0) for event in events if isinstance(event.get("seq"), int)]
+    return (max(seqs) + 1) if seqs else 1
+
+
+def _terminal_state_for_event(event_name: str, payload) -> str | None:
+    name = str(event_name or "")
+    if name == "done" or name == "stream_end":
+        return "completed"
+    if name == "cancel":
+        return "interrupted-by-user"
+    if name in {"apperror", "error"}:
+        err_type = str((payload or {}).get("type") or "").strip().lower() if isinstance(payload, dict) else ""
+        if err_type in {"cancelled", "canceled"}:
+            return "interrupted-by-user"
+        if err_type == "interrupted":
+            return "interrupted-by-crash"
+        return "errored"
+    return None
+
+
+def _run_journal_fsync_mode() -> str:
+    raw = os.environ.get(_FSYNC_MODE_ENV, _FSYNC_MODE_TERMINAL_ONLY)
+    mode = str(raw or "").strip().lower()
+    if mode in {_FSYNC_MODE_EAGER, _FSYNC_MODE_TERMINAL_ONLY}:
+        return mode
+    return _FSYNC_MODE_TERMINAL_ONLY
+
+
+def _should_fsync_event(terminal_state: str | None) -> bool:
+    if _run_journal_fsync_mode() == _FSYNC_MODE_EAGER:
+        return True
+    return bool(terminal_state)
+
+
+def _fsync_parent_dir(path: Path) -> None:
+    try:
+        dir_fd = os.open(path.parent, getattr(os, "O_DIRECTORY", 0))
+        try:
+            os.fsync(dir_fd)
+        finally:
+            os.close(dir_fd)
+    except OSError:
+        pass
+
+
+def append_run_event(
+    session_id: str,
+    run_id: str,
+    event_name: str,
+    payload=None,
+    *,
+    session_dir: Path | None = None,
+    seq: int | None = None,
+    created_at: float | None = None,
+) -> dict:
+    """Append one durable run event and fsync it according to the journal policy."""
+    path = _run_path(session_id, run_id, session_dir=session_dir)
+    payload = payload if payload is not None else {}
+    event_name = str(event_name or "").strip()
+    if not event_name:
+        raise ValueError("event_name is required")
+    with _lock_for(path):
+        assigned_seq = int(seq) if seq is not None else _next_seq(path)
+        terminal_state = _terminal_state_for_event(event_name, payload)
+        event = {
+            "version": 1,
+            "event_id": f"{run_id}:{assigned_seq}",
+            "seq": assigned_seq,
+            "run_id": str(run_id),
+            "session_id": str(session_id),
+            "event": event_name,
+            "type": event_name,
+            "created_at": float(created_at if created_at is not None else time.time()),
+            "terminal": bool(terminal_state),
+            "terminal_state": terminal_state,
+            "payload": payload,
+        }
+        path.parent.mkdir(parents=True, exist_ok=True)
+        created_file = not path.exists()
+        line = json.dumps(event, ensure_ascii=False, separators=(",", ":")) + "\n"
+        fd = os.open(path, os.O_CREAT | os.O_APPEND | os.O_WRONLY, 0o600)
+        with os.fdopen(fd, "a", encoding="utf-8") as fh:
+            fh.write(line)
+            fh.flush()
+            if _should_fsync_event(terminal_state):
+                os.fsync(fh.fileno())
+        if created_file:
+            _fsync_parent_dir(path)
+        return event
+
+
+class RunJournalWriter:
+    """Stateful writer for one WebUI stream/run."""
+
+    def __init__(self, session_id: str, run_id: str, *, session_dir: Path | None = None):
+        self.session_id = _validate_id(session_id, "session_id")
+        self.run_id = _validate_id(run_id, "run_id")
+        self.session_dir = Path(session_dir) if session_dir is not None else None
+        self._path = _run_path(self.session_id, self.run_id, session_dir=self.session_dir)
+        self._lock = _lock_for(self._path)
+        with self._lock:
+            self._next_seq = _next_seq(self._path)
+
+    def append_sse_event(self, event_name: str, payload=None) -> dict:
+        with self._lock:
+            seq = self._next_seq
+            self._next_seq += 1
+        return append_run_event(
+            self.session_id,
+            self.run_id,
+            event_name,
+            payload or {},
+            session_dir=self.session_dir,
+            seq=seq,
+        )
+
+
+def read_run_events(
+    session_id: str,
+    run_id: str,
+    *,
+    after_seq: int | None = None,
+    session_dir: Path | None = None,
+) -> dict:
+    path = _run_path(session_id, run_id, session_dir=session_dir)
+    events, malformed = _read_jsonl(path)
+    if after_seq is not None:
+        events = [event for event in events if int(event.get("seq") or 0) > int(after_seq)]
+    return {
+        "session_id": str(session_id),
+        "run_id": str(run_id),
+        "events": events,
+        "malformed": malformed,
+    }
+
+
+def _summary_from_events(session_id: str, run_id: str, events: Iterable[dict]) -> dict:
+    ordered = [event for event in events if isinstance(event, dict)]
+    last = ordered[-1] if ordered else None
+    terminal_events = [event for event in ordered if event.get("terminal")]
+    terminal = next(
+        (event for event in reversed(terminal_events) if event.get("event") != "stream_end"),
+        terminal_events[-1] if terminal_events else None,
+    )
+    status = terminal.get("terminal_state") if terminal else ("running" if ordered else "unknown")
+    return {
+        "session_id": str(session_id),
+        "run_id": str(run_id),
+        "stream_id": str(run_id),
+        "event_count": len(ordered),
+        "last_seq": int((last or {}).get("seq") or 0),
+        "last_event_id": (last or {}).get("event_id"),
+        "terminal": bool(terminal),
+        "terminal_state": status,
+        "last_event": (last or {}).get("event"),
+    }
+
+
+def latest_run_summary(session_id: str, run_id: str, *, session_dir: Path | None = None) -> dict:
+    journal = read_run_events(session_id, run_id, session_dir=session_dir)
+    return _summary_from_events(session_id, run_id, journal.get("events") or [])
+
+
+def find_run_summary(run_id: str, *, session_dir: Path | None = None) -> dict | None:
+    rid = _validate_id(run_id, "run_id")
+    root = Path(session_dir) if session_dir is not None else _default_session_dir()
+    journal_root = root / RUN_JOURNAL_DIR_NAME
+    for path in journal_root.glob(f"*/{rid}.jsonl"):
+        session_id = path.parent.name
+        events, _malformed = _read_jsonl(path)
+        summary = _summary_from_events(session_id, rid, events)
+        summary["path"] = str(path)
+        return summary
+    return None
+
+
+def stale_interrupted_event(session_id: str, run_id: str, *, after_seq: int | None = None) -> dict | None:
+    summary = latest_run_summary(session_id, run_id)
+    if summary.get("terminal") or not summary.get("event_count"):
+        return None
+    seq = int(summary.get("last_seq") or 0) + 1
+    if after_seq is not None and seq <= int(after_seq):
+        return None
+    payload = {
+        "type": "interrupted",
+        "message": "The live worker stopped before this run finished.",
+        "hint": "The transcript was restored to the last journaled event. Start a new turn if you still need the task to continue.",
+        "session_id": session_id,
+        "stream_id": run_id,
+        "journal_last_seq": summary.get("last_seq"),
+    }
+    return {
+        "version": 1,
+        "event_id": f"{run_id}:{seq}",
+        "seq": seq,
+        "run_id": run_id,
+        "session_id": session_id,
+        "event": "apperror",
+        "type": "apperror",
+        "created_at": time.time(),
+        "terminal": True,
+        "terminal_state": "lost-worker-bookkeeping",
+        "payload": payload,
+        "synthetic": True,
+    }

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

@@ -0,0 +1,156 @@
+"""HTTP client boundary for a supervised Hermes WebUI runner backend.
+
+This module intentionally contains no process-local run maps, stream queues,
+cancellation registries, approval/clarify queues, or cached agent instances. It
+is only a JSON-over-HTTP transport used by ``RunnerRuntimeAdapter`` when an
+operator explicitly configures a runner endpoint.
+"""
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any
+
+
+_RUNNER_BASE_URL_ENV = "HERMES_WEBUI_RUNNER_BASE_URL"
+_RUNNER_API_KEY_ENV = "HERMES_WEBUI_RUNNER_API_KEY"
+
+
+class RunnerClientError(RuntimeError):
+    """Raised when a configured runner endpoint rejects or fails a request."""
+
+
+def runner_client_configured(environ: dict[str, str] | None = None) -> bool:
+    source = os.environ if environ is None else environ
+    return bool(str(source.get(_RUNNER_BASE_URL_ENV) or "").strip())
+
+
+class HttpRunnerClient:
+    """Small JSON HTTP client for the external/supervised runner boundary."""
+
+    def __init__(self, *, base_url: str, api_key: str = ""):
+        self.base_url = str(base_url or "").strip().rstrip("/")
+        if not self.base_url:
+            raise ValueError("runner base_url is required")
+        # Hardening: the runner endpoint is operator-configured, but reject any
+        # non-HTTP(S) scheme so a misconfigured HERMES_WEBUI_RUNNER_BASE_URL
+        # (e.g. file:///etc/passwd or ftp://) can never be handed to urlopen.
+        _scheme = urllib.parse.urlsplit(self.base_url).scheme.lower()
+        if _scheme not in ("http", "https"):
+            raise ValueError(
+                f"runner base_url must be http(s); got scheme '{_scheme or '(none)'}'"
+            )
+        self.api_key = str(api_key or "").strip()
+
+    @classmethod
+    def from_env(cls, environ: dict[str, str] | None = None) -> "HttpRunnerClient":
+        source = os.environ if environ is None else environ
+        base_url = str(source.get(_RUNNER_BASE_URL_ENV) or "").strip()
+        if not base_url:
+            raise NotImplementedError("runner-local chat backend is not configured")
+        return cls(base_url=base_url, api_key=str(source.get(_RUNNER_API_KEY_ENV) or ""))
+
+    def start_run(self, request) -> dict[str, Any]:
+        return self._post("/v1/runs", {
+            "session_id": request.session_id,
+            "message": request.message,
+            "attachments": list(request.attachments or []),
+            "workspace": request.workspace,
+            "profile": request.profile,
+            "provider": request.provider,
+            "model": request.model,
+            "toolsets": list(request.toolsets or []),
+            "source": request.source,
+            "metadata": dict(request.metadata or {}),
+        })
+
+    def observe_run(self, run_id: str, *, cursor: str | None = None) -> dict[str, Any]:
+        query = ""
+        if cursor not in (None, ""):
+            query = "?cursor=" + urllib.parse.quote(str(cursor), safe="")
+        return self._get(f"/v1/runs/{urllib.parse.quote(str(run_id), safe='')}/events{query}")
+
+    def get_run(self, run_id: str) -> dict[str, Any]:
+        return self._get(f"/v1/runs/{urllib.parse.quote(str(run_id), safe='')}")
+
+    def cancel_run(self, run_id: str) -> dict[str, Any]:
+        return self._post(f"/v1/runs/{urllib.parse.quote(str(run_id), safe='')}/cancel", {})
+
+    def respond_approval(self, run_id: str, approval_id: str, choice: str) -> dict[str, Any]:
+        return self._post(
+            f"/v1/runs/{urllib.parse.quote(str(run_id), safe='')}/approvals/{urllib.parse.quote(str(approval_id), safe='')}/respond",
+            {"choice": choice},
+        )
+
+    def respond_clarify(self, run_id: str, clarify_id: str, response: str) -> dict[str, Any]:
+        return self._post(
+            f"/v1/runs/{urllib.parse.quote(str(run_id), safe='')}/clarifications/{urllib.parse.quote(str(clarify_id), safe='')}/respond",
+            {"response": response},
+        )
+
+    def queue_message(self, run_id: str, message: str, *, mode: str = "queue") -> dict[str, Any]:
+        return self._post(
+            f"/v1/runs/{urllib.parse.quote(str(run_id), safe='')}/messages",
+            {"message": message, "mode": mode},
+        )
+
+    def update_goal(self, session_id: str, action: str, text: str = "") -> dict[str, Any]:
+        return self._post(
+            f"/v1/sessions/{urllib.parse.quote(str(session_id), safe='')}/goal",
+            {"action": action, "text": text},
+        )
+
+    def _headers(self) -> dict[str, str]:
+        headers = {
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+            "User-Agent": "Hermes-WebUI-RunnerClient",
+        }
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        return headers
+
+    def _get(self, path: str) -> dict[str, Any]:
+        req = urllib.request.Request(self.base_url + path, headers=self._headers(), method="GET")
+        return self._request_json(req)
+
+    def _post(self, path: str, payload: dict[str, Any]) -> dict[str, Any]:
+        req = urllib.request.Request(
+            self.base_url + path,
+            data=json.dumps(payload).encode("utf-8"),
+            headers=self._headers(),
+            method="POST",
+        )
+        return self._request_json(req)
+
+    def _opener(self) -> urllib.request.OpenerDirector:
+        # Hardening: do NOT follow redirects. A misbehaving/compromised runner
+        # returning 3xx Location could otherwise smuggle the Bearer token to
+        # another host. Treat any redirect as an error instead.
+        class _NoRedirect(urllib.request.HTTPRedirectHandler):
+            def redirect_request(self, *args, **kwargs):
+                return None
+        return urllib.request.build_opener(_NoRedirect)
+
+    def _request_json(self, req: urllib.request.Request) -> dict[str, Any]:
+        try:
+            with self._opener().open(req, timeout=60) as resp:
+                raw = resp.read().decode("utf-8", errors="replace")
+        except urllib.error.HTTPError as exc:
+            try:
+                detail = exc.read(2048).decode("utf-8", errors="replace")
+            except Exception:
+                detail = ""
+            raise RunnerClientError(f"Runner returned HTTP {exc.code}: {detail[:500]}") from exc
+        except Exception as exc:
+            raise RunnerClientError(f"Runner request failed: {exc}") from exc
+        try:
+            payload = json.loads(raw or "{}")
+        except json.JSONDecodeError as exc:
+            raise RunnerClientError("Runner returned invalid JSON") from exc
+        if not isinstance(payload, dict):
+            raise RunnerClientError("Runner returned a non-object JSON payload")
+        return payload