hermes-webui/api/runtime_adapter.py

"""RuntimeAdapter seam for WebUI-owned run execution.

This is the #1925 Slice 2 seam only.  The default WebUI chat path remains the
legacy direct route; enabling ``HERMES_WEBUI_RUNTIME_ADAPTER=legacy-journal``
routes through this protocol-translator facade over the same legacy execution
path plus the Slice 1 run journal.  This module intentionally does not own
AIAgent instances, cancellation flags, approval callbacks, clarify callbacks, or
new long-lived queues.
"""
from __future__ import annotations

from dataclasses import dataclass, field
import os
from pathlib import Path
from typing import Any, Callable, Iterable, Protocol

_RUNTIME_ADAPTER_ENV = "HERMES_WEBUI_RUNTIME_ADAPTER"
_RUNTIME_ADAPTER_DIRECT = "legacy-direct"
_RUNTIME_ADAPTER_JOURNAL = "legacy-journal"
_VALID_RUNTIME_ADAPTER_MODES = {_RUNTIME_ADAPTER_DIRECT, _RUNTIME_ADAPTER_JOURNAL}


@dataclass(frozen=True)
class StartRunRequest:
    session_id: str
    message: str
    attachments: list[dict[str, Any]] = field(default_factory=list)
    workspace: str | None = None
    profile: str | None = None
    provider: str | None = None
    model: str | None = None
    toolsets: list[str] = field(default_factory=list)
    source: str = "webui"
    metadata: dict[str, Any] = field(default_factory=dict)


@dataclass(frozen=True)
class RunStartResult:
    run_id: str
    session_id: str
    stream_id: str
    status: str = "started"
    started_at: float | None = None
    cursor: str | None = None
    active_controls: list[str] = field(default_factory=list)
    payload: dict[str, Any] = field(default_factory=dict)


@dataclass(frozen=True)
class RunEventStream:
    run_id: str
    events: list[dict[str, Any]] = field(default_factory=list)
    cursor: str | None = None
    last_event_id: str | None = None


@dataclass(frozen=True)
class RunStatus:
    run_id: str
    session_id: str | None = None
    status: str = "unknown"
    last_event_id: str | None = None
    terminal_state: str | None = None
    active_controls: list[str] = field(default_factory=list)
    pending_approval_id: str | None = None
    pending_clarify_id: str | None = None


@dataclass(frozen=True)
class ControlResult:
    accepted: bool
    status: str = "accepted"
    event_id: str | None = None
    safe_message: str | None = None


class RuntimeAdapter(Protocol):
    def start_run(self, request: StartRunRequest) -> RunStartResult: ...
    def observe_run(self, run_id: str, *, cursor: str | None = None) -> RunEventStream: ...
    def get_run(self, run_id: str) -> RunStatus: ...
    def cancel_run(self, run_id: str) -> ControlResult: ...
    def respond_approval(self, run_id: str, approval_id: str, choice: str) -> ControlResult: ...
    def respond_clarify(self, run_id: str, clarify_id: str, response: str) -> ControlResult: ...


def runtime_adapter_mode(environ: dict[str, str] | None = None) -> str:
    """Return the configured adapter mode, defaulting safely to legacy-direct."""
    source = os.environ if environ is None else environ
    raw = str(source.get(_RUNTIME_ADAPTER_ENV, _RUNTIME_ADAPTER_DIRECT) or "").strip().lower()
    return raw if raw in _VALID_RUNTIME_ADAPTER_MODES else _RUNTIME_ADAPTER_DIRECT


def runtime_adapter_enabled(environ: dict[str, str] | None = None) -> bool:
    return runtime_adapter_mode(environ) == _RUNTIME_ADAPTER_JOURNAL


def _cursor_to_after_seq(cursor: str | None) -> int | None:
    if cursor in (None, ""):
        return None
    try:
        text = str(cursor)
        if ":" in text:
            text = text.rsplit(":", 1)[-1]
        return max(0, int(text))
    except (TypeError, ValueError):
        return 0


def _active_control_result(value: Any) -> ControlResult:
    accepted = bool(value)
    return ControlResult(
        accepted=accepted,
        status="accepted" if accepted else "not-active",
        safe_message=None if accepted else "Legacy control did not accept the request.",
    )


class LegacyJournalRuntimeAdapter:
    """Protocol-translator facade over the current legacy streaming path.

    Delegates keep Slice 2 honest: this adapter has no worker thread, AIAgent
    cache, cancellation registry, approval queue, or clarify queue of its own.
    """

    def __init__(
        self,
        *,
        start_run_delegate: Callable[[StartRunRequest], dict[str, Any]] | None = None,
        cancel_delegate: Callable[[str], Any] | None = None,
        approval_delegate: Callable[[str, str, str], Any] | None = None,
        clarify_delegate: Callable[[str, str, str], Any] | None = None,
        live_stream_lookup: Callable[[str], bool] | None = None,
        session_dir: Path | None = None,
    ):
        self._start_run_delegate = start_run_delegate
        self._cancel_delegate = cancel_delegate
        self._approval_delegate = approval_delegate
        self._clarify_delegate = clarify_delegate
        self._live_stream_lookup = live_stream_lookup or (lambda _run_id: False)
        self._session_dir = Path(session_dir) if session_dir is not None else None

    def start_run(self, request: StartRunRequest) -> RunStartResult:
        if self._start_run_delegate is None:
            raise NotImplementedError("LegacyJournalRuntimeAdapter.start_run requires a legacy delegate")
        payload = dict(self._start_run_delegate(request) or {})
        stream_id = str(payload.get("stream_id") or payload.get("run_id") or "")
        run_id = str(payload.get("run_id") or stream_id)
        session_id = str(payload.get("session_id") or request.session_id)
        active_controls = payload.get("active_controls")
        if not isinstance(active_controls, list):
            active_controls = ["cancel"] if stream_id else []
        return RunStartResult(
            run_id=run_id,
            session_id=session_id,
            stream_id=stream_id,
            status=str(payload.get("status") or "started"),
            started_at=payload.get("started_at"),
            cursor=payload.get("cursor"),
            active_controls=active_controls,
            payload=payload,
        )

    def observe_run(self, run_id: str, *, cursor: str | None = None) -> RunEventStream:
        from api.run_journal import find_run_summary, read_run_events

        summary = find_run_summary(run_id, session_dir=self._session_dir)
        if not summary:
            return RunEventStream(run_id=run_id, events=[], cursor=cursor, last_event_id=None)
        journal = read_run_events(
            str(summary.get("session_id") or ""),
            run_id,
            after_seq=_cursor_to_after_seq(cursor),
            session_dir=self._session_dir,
        )
        events = list(journal.get("events") or [])
        last_event_id = events[-1].get("event_id") if events else summary.get("last_event_id")
        return RunEventStream(
            run_id=run_id,
            events=events,
            cursor=str(events[-1].get("seq")) if events else cursor,
            last_event_id=last_event_id,
        )

    def get_run(self, run_id: str) -> RunStatus:
        from api.run_journal import find_run_summary

        live = bool(self._live_stream_lookup(run_id))
        summary = find_run_summary(run_id, session_dir=self._session_dir)
        if live:
            return RunStatus(
                run_id=run_id,
                session_id=str((summary or {}).get("session_id") or "") or None,
                status="running",
                last_event_id=(summary or {}).get("last_event_id"),
                terminal_state=None,
                active_controls=["cancel"],
            )
        if summary:
            terminal_state = summary.get("terminal_state")
            return RunStatus(
                run_id=run_id,
                session_id=str(summary.get("session_id") or "") or None,
                status=str(terminal_state or "unknown"),
                last_event_id=summary.get("last_event_id"),
                terminal_state=terminal_state,
                active_controls=[],
            )
        return RunStatus(run_id=run_id)

    def cancel_run(self, run_id: str) -> ControlResult:
        if self._cancel_delegate is None:
            return ControlResult(False, status="unsupported", safe_message="Cancel is not wired for this adapter.")
        return _active_control_result(self._cancel_delegate(run_id))

    def respond_approval(self, run_id: str, approval_id: str, choice: str) -> ControlResult:
        if self._approval_delegate is None:
            return ControlResult(False, status="unsupported", safe_message="Approval is delegated to the legacy path.")
        return _active_control_result(self._approval_delegate(run_id, approval_id, choice))

    def respond_clarify(self, run_id: str, clarify_id: str, response: str) -> ControlResult:
        if self._clarify_delegate is None:
            return ControlResult(False, status="unsupported", safe_message="Clarify is delegated to the legacy path.")
        return _active_control_result(self._clarify_delegate(run_id, clarify_id, response))