@bitseek/hermes-webui 0.1.0-beta.0

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

@@ -0,0 +1,208 @@
+"""
+Hermes WebUI memory-provider session lifecycle.
+
+Batch-extraction memory providers (OpenViking, Holographic) only extract memories
+when AIAgent.commit_memory_session() invokes provider on_session_end(). WebUI
+sessions can be reopened and continued many times, so the lifecycle must guarantee:
+
+1. Only completed, non-ephemeral turns are committable.
+2. A commit finishing late must not erase work completed while it was in flight.
+3. A failed commit preserves the uncommitted generation and owning agent handle.
+4. Replacement/reopened agents cannot steal older dirty generations.
+5. Overlapping commits are serialised via a per-session in-flight guard.
+
+CLI-parity semantics — post-turn marking, boundary extraction/commit:
+
+- Completed turn: Hermes core still mirrors the exchange through
+  run_agent.py::_sync_external_memory_for_turn(), MemoryManager sync_all(), and
+  provider sync_turn() WITHOUT triggering extraction.  WebUI then calls
+  mark_turn_completed() after the saved/completed-turn boundary so later drains
+  know the synced session has uncommitted work and which agent owns it.
+
+- Session boundary: commit_session_memory() triggers
+  AIAgent.commit_memory_session(), which calls provider on_session_end(),
+  posting /api/v1/sessions/<sid>/commit and triggering extraction. This is
+  called only at boundaries — /api/session/new with prev_session_id, explicit
+  agent eviction, LRU cache eviction, and shutdown drain — matching the CLI's
+  AIAgent.commit_memory_session()/shutdown_memory_provider() boundary.
+
+The design uses a monotonic generation counter per session plus per-generation
+agent ownership segments. mark_turn_completed() records which agent owns the new
+generation. commit_session_memory() commits the earliest uncommitted segment and
+compare-and-clears only that captured segment after success.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+import time
+
+logger = logging.getLogger(__name__)
+
+_lock = threading.Lock()
+_condition = threading.Condition(_lock)
+
+_sessions: dict[str, dict] = {}
+
+
+def _new_entry() -> dict:
+    return {
+        "generation": 0,
+        "committed_generation": 0,
+        "agent": None,
+        "in_flight": False,
+        "segments": [],
+    }
+
+
+def _reset_for_tests() -> None:
+    with _condition:
+        _sessions.clear()
+        _condition.notify_all()
+
+
+def register_agent(session_id: str, agent) -> None:
+    """Register the current agent handle for future completed generations.
+
+    Existing dirty generations keep their original segment owner. This prevents
+    a rebuilt/reopened agent from overwriting the handle needed to retry older
+    failed memory-provider work.
+    """
+    if not session_id:
+        return
+    with _condition:
+        entry = _sessions.setdefault(session_id, _new_entry())
+        entry["agent"] = agent
+        _condition.notify_all()
+
+
+def unregister_agent(session_id: str) -> None:
+    """Clear the current future-generation agent handle.
+
+    Dirty segment owners are intentionally preserved so failed work remains
+    retryable even if the cache drops the current agent reference.
+    """
+    if not session_id:
+        return
+    with _condition:
+        entry = _sessions.get(session_id)
+        if entry is not None:
+            entry["agent"] = None
+        _condition.notify_all()
+
+
+def mark_turn_completed(session_id: str, *, agent=None) -> int:
+    if not session_id:
+        return 0
+    with _condition:
+        entry = _sessions.setdefault(session_id, _new_entry())
+        if agent is not None:
+            entry["agent"] = agent
+        owner = agent if agent is not None else entry.get("agent")
+        entry["generation"] += 1
+        generation = entry["generation"]
+        segments = entry["segments"]
+        if segments and not entry["in_flight"] and segments[-1].get("agent") is owner:
+            segments[-1]["end"] = generation
+        else:
+            segments.append({"start": generation, "end": generation, "agent": owner})
+        _condition.notify_all()
+        return generation
+
+
+def has_uncommitted_work(session_id: str) -> bool:
+    if not session_id:
+        return False
+    with _lock:
+        entry = _sessions.get(session_id)
+        if entry is None:
+            return False
+        return entry["generation"] > entry["committed_generation"]
+
+
+def _first_uncommitted_segment(entry: dict) -> dict | None:
+    committed = entry["committed_generation"]
+    for segment in entry["segments"]:
+        if segment["end"] > committed:
+            return segment
+    return None
+
+
+def commit_session_memory(session_id: str, agent=None, *, wait: bool = False, timeout: float | None = None) -> bool:
+    if not session_id:
+        return False
+    deadline = time.monotonic() + timeout if timeout is not None else None
+    with _condition:
+        entry = _sessions.get(session_id)
+        if entry is None:
+            return False
+        while entry["in_flight"]:
+            if not wait:
+                return False
+            if deadline is None:
+                _condition.wait()
+            else:
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    return False
+                _condition.wait(remaining)
+            entry = _sessions.get(session_id)
+            if entry is None:
+                return False
+        if entry["generation"] <= entry["committed_generation"]:
+            return False
+        segment = _first_uncommitted_segment(entry)
+        if segment is None:
+            return False
+        effective_agent = segment.get("agent")
+        if effective_agent is None:
+            effective_agent = agent if agent is not None else entry.get("agent")
+            if effective_agent is not None:
+                segment["agent"] = effective_agent
+        if effective_agent is None:
+            return False
+        captured_generation = segment["end"]
+        entry["in_flight"] = True
+
+    try:
+        effective_agent.commit_memory_session()
+    except Exception:
+        logger.exception("commit_memory_session() failed for session %s", session_id)
+        with _condition:
+            re_entry = _sessions.get(session_id)
+            if re_entry is not None:
+                re_entry["in_flight"] = False
+            _condition.notify_all()
+        return False
+
+    with _condition:
+        re_entry = _sessions.get(session_id)
+        if re_entry is not None:
+            re_entry["in_flight"] = False
+            if captured_generation > re_entry["committed_generation"]:
+                re_entry["committed_generation"] = captured_generation
+            committed = re_entry["committed_generation"]
+            segments = re_entry["segments"]
+            while segments and segments[0]["end"] <= committed:
+                segments.pop(0)
+            if segments and segments[0]["start"] <= committed:
+                segments[0]["start"] = committed + 1
+        _condition.notify_all()
+    return True
+
+
+def drain_all_on_shutdown() -> None:
+    while True:
+        with _lock:
+            snapshot = [sid for sid, entry in _sessions.items() if entry["generation"] > entry["committed_generation"]]
+        if not snapshot:
+            return
+
+        made_progress = False
+        for sid in snapshot:
+            if commit_session_memory(sid, wait=True):
+                made_progress = True
+        if not made_progress:
+            logger.debug("drain_all_on_shutdown: stopped with uncommitted sessions: %s", sorted(snapshot))
+            return

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

@@ -0,0 +1,207 @@
+"""Session-mutation operations for slash commands (/retry, /undo) and
+read-only aggregators (/status, /usage). Operates on the webui's own
+JSON Session store (api/models.py), not on hermes-agent's SQLite.
+
+Behavior parity reference: gateway/run.py:_handle_*_command in
+the hermes-agent repo.
+"""
+from __future__ import annotations
+import logging
+from typing import Any
+
+from api.config import LOCK, _get_session_agent_lock
+from api.models import get_session, SESSIONS
+
+logger = logging.getLogger(__name__)
+
+
+def _truncate_at_last_user(messages):
+    history = messages or []
+    last_user_idx = None
+    for i in range(len(history) - 1, -1, -1):
+        if isinstance(history[i], dict) and history[i].get('role') == 'user':
+            last_user_idx = i
+            break
+    if last_user_idx is None:
+        return None
+    return history[:last_user_idx]
+
+
+def _truncation_watermark_for(messages):
+    history = list(messages or [])
+    if not history:
+        return 0.0
+    try:
+        return float(history[-1].get('timestamp') or 0)
+    except (AttributeError, TypeError, ValueError):
+        return 0.0
+
+
+def retry_last(session_id: str) -> dict[str, Any]:
+    """Truncate the session to before the last user message, return its text.
+
+    Mirrors gateway/run.py:_handle_retry_command. Caller (webui frontend)
+    is expected to put the returned text back in the composer and call
+    send() to resume the conversation -- the agent's gateway calls its own
+    _handle_message; the webui has no equivalent in-process pipeline.
+
+    Raises:
+        KeyError: session not found
+        ValueError: no user message in transcript
+    """
+    # Acquire the per-session agent lock as the outermost lock so that the
+    # read-modify-write of s.messages is serialised with the periodic
+    # checkpoint thread, cancel_stream, and all other session writers.
+    # Lock ordering: _agent_lock → LOCK → _write_session_index (LOCK).
+    with _get_session_agent_lock(session_id):
+        # get_session() and Session.save() both acquire the module-level LOCK
+        # internally (the latter via _write_session_index()), and LOCK is a
+        # non-reentrant threading.Lock — so they MUST be called outside our
+        # own `with LOCK:` block to avoid self-deadlocking.
+        #
+        # The race we close is the read-modify-write of s.messages: two
+        # concurrent /api/session/retry calls could otherwise both compute the
+        # same last_user_idx from the same history and double-truncate. We
+        # serialize just the in-memory mutation; persistence happens inside
+        # the per-session lock so the checkpoint thread cannot race us.
+        #
+        # Stale-object guard: on a cache miss, two concurrent get_session()
+        # calls can each load and cache a *different* Session instance for the
+        # same session_id (the second store clobbers the first). Re-bind to
+        # the canonical cached instance inside the lock so the mutation lands
+        # on the object the next reader will see, not a stale parallel copy.
+        s = get_session(session_id)  # raises KeyError if missing
+        with LOCK:
+            s = SESSIONS.get(session_id, s)
+            history = s.messages or []
+            last_user_idx = None
+            for i in range(len(history) - 1, -1, -1):
+                if history[i].get('role') == 'user':
+                    last_user_idx = i
+                    break
+            if last_user_idx is None:
+                raise ValueError('No previous message to retry.')
+
+            last_user_text = _extract_text(history[last_user_idx].get('content', ''))
+            removed_count = len(history) - last_user_idx
+            s.messages = history[:last_user_idx]
+            s.truncation_watermark = _truncation_watermark_for(s.messages)
+            if isinstance(getattr(s, 'context_messages', None), list) and s.context_messages:
+                truncated_context = _truncate_at_last_user(s.context_messages)
+                if truncated_context is not None:
+                    s.context_messages = truncated_context
+        s.save()
+    return {'last_user_text': last_user_text, 'removed_count': removed_count}
+
+
+def undo_last(session_id: str) -> dict[str, Any]:
+    """Remove the most recent user message and everything after it.
+
+    Mirrors gateway/run.py:_handle_undo_command. Returns a preview of the
+    removed text so the UI can confirm to the user.
+
+    Raises:
+        KeyError: session not found
+        ValueError: no user message in transcript
+    """
+    # Acquire the per-session agent lock as the outermost lock so that the
+    # read-modify-write of s.messages is serialised with the periodic
+    # checkpoint thread, cancel_stream, and all other session writers.
+    # Lock ordering: _agent_lock → LOCK → _write_session_index (LOCK).
+    with _get_session_agent_lock(session_id):
+        s = get_session(session_id)  # acquires LOCK transiently
+        with LOCK:
+            # Stale-object guard — see retry_last for the rationale.
+            s = SESSIONS.get(session_id, s)
+            history = s.messages or []
+            last_user_idx = None
+            for i in range(len(history) - 1, -1, -1):
+                if history[i].get('role') == 'user':
+                    last_user_idx = i
+                    break
+            if last_user_idx is None:
+                raise ValueError('Nothing to undo.')
+
+            removed_text = _extract_text(history[last_user_idx].get('content', ''))
+            removed_count = len(history) - last_user_idx
+            s.messages = history[:last_user_idx]
+            s.truncation_watermark = _truncation_watermark_for(s.messages)
+            if isinstance(getattr(s, 'context_messages', None), list) and s.context_messages:
+                truncated_context = _truncate_at_last_user(s.context_messages)
+                if truncated_context is not None:
+                    s.context_messages = truncated_context
+        s.save()  # outside LOCK -- save() re-acquires LOCK via _write_session_index()
+    preview = (removed_text[:40] + '...') if len(removed_text) > 40 else removed_text
+    return {
+        'removed_count': removed_count,
+        'removed_preview': preview,
+    }
+
+
+def session_status(session_id: str) -> dict[str, Any]:
+    """Return a snapshot of session state for /status.
+
+    Webui equivalent of gateway/run.py:_handle_status_command. The agent's
+    "agent_running" comes from `session_key in self._running_agents`; the
+    webui equivalent is whether the session has an active stream
+    (active_stream_id is set).
+    """
+    s = get_session(session_id)
+    inp = int(s.input_tokens or 0)
+    out = int(s.output_tokens or 0)
+    profile = getattr(s, 'profile', None) or 'default'
+    try:
+        from api.profiles import get_hermes_home_for_profile
+        hermes_home = str(get_hermes_home_for_profile(profile))
+    except Exception:
+        hermes_home = ''
+    return {
+        'session_id': s.session_id,
+        'title': s.title,
+        'model': s.model,
+        'profile': profile,
+        'hermes_home': hermes_home,
+        'workspace': s.workspace,
+        'personality': s.personality,
+        'message_count': len(s.messages or []),
+        'created_at': s.created_at,
+        'updated_at': s.updated_at,
+        'agent_running': bool(getattr(s, 'active_stream_id', None)),
+        'input_tokens': inp,
+        'output_tokens': out,
+        'total_tokens': inp + out,
+        'estimated_cost': s.estimated_cost,
+    }
+
+
+def session_usage(session_id: str) -> dict[str, Any]:
+    """Return token usage and cost for /usage.
+
+    Mirrors gateway/run.py:_handle_usage_command's basic counters. The
+    agent shows additional fields (rate-limit headroom etc.) that depend
+    on provider API responses we don't have in webui -- those are deferred.
+    """
+    s = get_session(session_id)
+    inp = int(s.input_tokens or 0)
+    out = int(s.output_tokens or 0)
+    return {
+        'input_tokens': inp,
+        'output_tokens': out,
+        'total_tokens': inp + out,
+        'estimated_cost': s.estimated_cost,
+        'model': s.model,
+    }
+
+
+def _extract_text(content: Any) -> str:
+    """Flatten message content to plain text. Agent stores either a string
+    or a list of {type, text|...} parts; webui needs the user-typed text."""
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        parts = []
+        for p in content:
+            if isinstance(p, dict) and p.get('type') == 'text':
+                parts.append(p.get('text', ''))
+        return ' '.join(parts)
+    return str(content)