@bitseek/hermes-webui 0.1.0-beta.0 → 0.1.0-beta.1

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

@@ -637,18 +637,6 @@ class Session:
     def path(self):
         return SESSION_DIR / f'{self.session_id}.json'
 
-    def _maybe_clear_truncation_watermark(self) -> None:
-        watermark = _message_timestamp_as_float({"timestamp": self.truncation_watermark})
-        if watermark is None:
-            return
-        max_message_timestamp = None
-        for msg in self.messages or []:
-            timestamp = _message_timestamp_as_float(msg)
-            if timestamp is not None:
-                max_message_timestamp = timestamp if max_message_timestamp is None else max(max_message_timestamp, timestamp)
-        if max_message_timestamp is not None and max_message_timestamp > watermark:
-            self.truncation_watermark = None
-
     def save(self, touch_updated_at: bool = True, skip_index: bool = False) -> None:
         if not is_safe_session_id(self.session_id):
             raise ValueError(f"Unsafe session_id {self.session_id!r}; refusing to write outside session store")
@@ -671,7 +659,6 @@ class Session:
             )
         if touch_updated_at:
             self.updated_at = time.time()
-        self._maybe_clear_truncation_watermark()
         # Write metadata fields first so load_metadata_only() can read them
         # without parsing the full messages array (which may be 400KB+).
         # Fields are listed in the order they should appear in the JSON file.
@@ -2655,6 +2642,68 @@ def _refresh_index_rows_from_sidecar_metadata(sessions: list[dict]) -> list[dict
     return out
 
 
+def state_db_has_session(sid: str) -> bool:
+    """Return True when ``sid`` exists in the active state.db sessions table.
+
+    Used by file-manager handlers to fall back to a state.db lookup when
+    ``get_session`` raises ``KeyError`` because the session was created by
+    Telegram/CLI (external) rather than the WebUI (issue #3280). The state.db
+    schema stores only metadata (id/title/model/source/...), not a workspace
+    path — the workspace is shared across session storage backends and is
+    resolved separately via ``get_last_workspace()``.
+    """
+    if not sid:
+        return False
+    try:
+        import sqlite3
+    except ImportError:
+        return False
+    db_path = _active_state_db_path()
+    if not db_path.exists():
+        return False
+    try:
+        with closing(sqlite3.connect(str(db_path))) as conn:
+            cur = conn.cursor()
+            cur.execute("SELECT 1 FROM sessions WHERE id = ? LIMIT 1", (str(sid),))
+            return cur.fetchone() is not None
+    except Exception:
+        return False
+
+
+class _ExternalSessionView:
+    """Minimal session-shaped view for external (Telegram/CLI) sessions.
+
+    Only exposes the fields file-manager handlers need (``session_id`` and
+    ``workspace``). The workspace falls back to the WebUI's last-used
+    workspace because state.db does not persist a per-session workspace path
+    and the file browser is intentionally workspace-scoped, not
+    session-storage-scoped (issue #3280).
+    """
+
+    __slots__ = ("session_id", "workspace")
+
+    def __init__(self, session_id: str, workspace: str):
+        self.session_id = session_id
+        self.workspace = workspace
+
+
+def get_session_for_file_ops(sid: str):
+    """Return a session-like object for file-manager handlers.
+
+    Tries ``get_session`` first (preserves all existing behavior for WebUI
+    sessions). If that raises ``KeyError``, checks state.db; when the session
+    exists there, returns an ``_ExternalSessionView`` whose ``workspace`` is
+    the active WebUI workspace. If neither has the session, re-raises
+    ``KeyError`` so callers continue to return their existing 404.
+    """
+    try:
+        return get_session(sid, metadata_only=True)
+    except KeyError:
+        if state_db_has_session(sid):
+            return _ExternalSessionView(str(sid), str(get_last_workspace()))
+        raise
+
+
 def _active_state_db_path() -> Path:
     """Return state.db for the active Hermes profile, degrading to HERMES_HOME."""
     try:
@@ -2665,6 +2714,49 @@ def _active_state_db_path() -> Path:
     return hermes_home / 'state.db'
 
 
+def agent_session_row_exists(session_id: str, *, profile=None) -> bool:
+    """Return True if ``session_id`` still has a backing row in the agent state.db.
+
+    Used to detect orphaned imported-CLI sidecars (#3238): the WebUI sidebar
+    must NOT rely on the session's presence in ``get_cli_sessions()`` to decide
+    whether its backing CLI row still exists, because that helper caps at
+    ``CLI_VISIBLE_SESSION_LIMIT`` (20) rows — a still-existing session can fall
+    out of the recent window and look "deleted." This is an exact, uncapped
+    existence probe against the ``sessions`` table.
+
+    Degrades safely to ``True`` (assume present) on any error or when the DB is
+    unreadable, so a transient failure never causes a stale-pruning data loss.
+    """
+    sid = str(session_id or "").strip()
+    if not sid:
+        return False
+    try:
+        import sqlite3
+    except ImportError:
+        return True
+    if isinstance(profile, str) and profile:
+        db_path = _get_profile_home(profile) / 'state.db'
+        if not db_path.exists():
+            db_path = _active_state_db_path()
+    else:
+        db_path = _active_state_db_path()
+    if not db_path.exists():
+        # No agent DB at all on this instance — can't claim the row is gone.
+        return True
+    try:
+        with closing(sqlite3.connect(str(db_path))) as conn:
+            cur = conn.cursor()
+            cur.execute("PRAGMA table_info(sessions)")
+            cols = {str(row[1]) for row in cur.fetchall()}
+            if 'id' not in cols:
+                return True
+            cur.execute("SELECT 1 FROM sessions WHERE id = ? LIMIT 1", (sid,))
+            return cur.fetchone() is not None
+    except Exception:
+        logger.debug("agent_session_row_exists probe failed for %s", sid, exc_info=True)
+        return True
+
+
 def _sidebar_title_is_generic_webui(title: str | None) -> bool:
     text = ' '.join(str(title or '').split())
     if text == 'Hermes WebUI':
@@ -2858,6 +2950,10 @@ def all_sessions(diag=None):
     return result
 
 
+def _strip_attached_files_marker(text: str) -> str:
+    return re.sub(r"\n\n\[Attached files: [^\]]+\]$", "", str(text or "")).strip()
+
+
 def title_from(messages, fallback: str='Untitled'):
     """Derive a session title from the first user message."""
     for m in messages:
@@ -2865,7 +2961,7 @@ def title_from(messages, fallback: str='Untitled'):
             c = m.get('content', '')
             if isinstance(c, list):
                 c = ' '.join(p.get('text', '') for p in c if isinstance(p, dict) and p.get('type') == 'text')
-            text = str(c).strip()
+            text = _strip_attached_files_marker(str(c))
             if text:
                 return text[:64]
     return fallback
@@ -3810,6 +3906,29 @@ def _session_message_merge_key(msg: dict):
     )
 
 
+def _session_message_dedup_key(msg: dict):
+    """Like _session_message_merge_key but preserves full-precision timestamp.
+
+    Two messages are true duplicates only if role, content, AND exact
+    timestamp all match.  Sub-second timestamp differences indicate
+    legitimately distinct messages (e.g. two assistant turns within the
+    same wall-clock second).
+    """
+    if not isinstance(msg, dict):
+        return ("non_dict", repr(msg))
+    message_identity = msg.get("id") or msg.get("message_id")
+    if message_identity:
+        return ("message_id", str(message_identity))
+    return (
+        "legacy",
+        str(msg.get("role") or ""),
+        str(msg.get("content") or ""),
+        str(msg.get("timestamp") or ""),
+        str(msg.get("tool_call_id") or ""),
+        str(msg.get("tool_name") or msg.get("name") or ""),
+    )
+
+
 def _normalized_session_message_content(msg: dict) -> str:
     if not isinstance(msg, dict):
         return repr(msg)
@@ -3947,17 +4066,34 @@ def merge_session_messages_append_only(
         return sidecar_messages
     if not sidecar_messages:
         if watermark_timestamp is not None:
-            return [
+            filtered = [
                 msg for msg in state_messages
                 if (
                     (timestamp := _message_timestamp_as_float(msg)) is not None
                     and timestamp <= watermark_timestamp
                 )
             ]
-        return state_messages
+        else:
+            filtered = state_messages
+        # Deduplicate true duplicates (same role, content, exact timestamp)
+        # without collapsing legitimately-repeated identical turns (#3346).
+        # Note: rows whose timestamps were mutated by compaction/recovery to
+        # microsecond-different values will not be folded — only byte-identical
+        # timestamps are treated as the same message.  This is intentional;
+        # collapsing same-second distinct turns would be worse than retaining
+        # a compaction-restamped duplicate.
+        seen = set()
+        deduped = []
+        for msg in filtered:
+            key = _session_message_dedup_key(msg)
+            if key not in seen:
+                seen.add(key)
+                deduped.append(msg)
+        return deduped
 
     merged_messages = []
     seen_message_keys = set()
+    seen_dedup_keys = set()
     seen_content_keys = set()
     seen_visible_keys = set()
     sidecar_visible_sequence = []
@@ -3970,6 +4106,7 @@ def merge_session_messages_append_only(
             max_sidecar_timestamp = timestamp if max_sidecar_timestamp is None else max(max_sidecar_timestamp, timestamp)
         key = _session_message_merge_key(msg)
         seen_message_keys.add(key)
+        seen_dedup_keys.add(_session_message_dedup_key(msg))
         seen_content_keys.add(_session_message_content_key(msg))
         visible_key = _session_message_visible_key(msg)
         seen_visible_keys.add(visible_key)
@@ -4002,20 +4139,65 @@ def merge_session_messages_append_only(
                 skipped_state_visible_counts[matched_visible_key] = (
                     skipped_state_visible_counts.get(matched_visible_key, 0) + 1
                 )
+            # Record dedup key so later duplicates of this replayed message
+            # are caught by the dedup guard (#3346).
+            seen_dedup_keys.add(_session_message_dedup_key(msg))
             continue
+        # Skip rows ABOVE the watermark only while the sidecar has NOT advanced
+        # past the watermark. Because Session.save() no longer auto-clears the
+        # watermark, an unconditional `timestamp > watermark` skip would become
+        # permanent and silently drop legitimate future state.db-only recovery
+        # rows once the session moves forward past the edit boundary. Once the
+        # sidecar's own max timestamp is beyond the watermark (the session has
+        # advanced), allow state rows newer than the sidecar tail to merge.
+        sidecar_advanced_past_watermark = (
+            watermark_timestamp is not None
+            and max_sidecar_timestamp is not None
+            and max_sidecar_timestamp > watermark_timestamp
+        )
         if (
             watermark_timestamp is not None
             and timestamp is not None
             and timestamp > watermark_timestamp
             and key not in seen_message_keys
+            and (
+                not sidecar_advanced_past_watermark
+                or (max_sidecar_timestamp is not None and timestamp <= max_sidecar_timestamp)
+            )
+        ):
+            continue
+        # When a truncation watermark is active, state.db may contain original
+        # messages that were replaced by Edit (old content with old timestamp).
+        # The timestamp-based filter above catches messages AFTER the watermark,
+        # but messages BEFORE it (like the original pre-edit content) slip through.
+        # If a state.db message's content is not present in the sidecar and its
+        # timestamp is before the watermark, it's a replaced/stale row — skip it.
+        if (
+            watermark_timestamp is not None
+            and timestamp is not None
+            and timestamp < watermark_timestamp
+            and key not in seen_message_keys
+            and _session_message_content_key(msg) not in seen_content_keys
         ):
             continue
+        # Check for true duplicates using full-precision timestamp (#3346).
+        # Must run before the merge-key guards so that legitimately distinct
+        # sub-second messages with the same second-level merge key are not
+        # collapsed.  The merge key truncates to seconds; the dedup key does
+        # not.
+        dedup_key = _session_message_dedup_key(msg)
+        if dedup_key in seen_dedup_keys:
+            continue
         if max_sidecar_timestamp is not None and timestamp is not None and timestamp <= max_sidecar_timestamp:
-            if key in seen_message_keys:
+            # For message_id keys the merge key is authoritative — skip if
+            # already seen.  For legacy keys the dedup check above already
+            # handled true duplicates; same-second distinct messages must
+            # fall through.
+            if key in seen_message_keys and key[0] == "message_id":
                 continue
             if not (isinstance(key, tuple) and key[:1] == ("message_id",)):
                 continue
-        if key in seen_message_keys:
+        if key in seen_message_keys and key[0] == "message_id":
             continue
         matched_visible_key = _matching_visible_duplicate(
             visible_key,
@@ -4045,8 +4227,8 @@ def merge_session_messages_append_only(
             and timestamp <= max_sidecar_timestamp
         ):
             continue
-        if key[0] == "message_id":
-            seen_message_keys.add(key)
+        seen_message_keys.add(key)
+        seen_dedup_keys.add(dedup_key)
         seen_content_keys.add(_session_message_content_key(msg))
         seen_visible_keys.add(visible_key)
         merged_messages.append(msg)

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

@@ -0,0 +1,77 @@
+"""Shared path helpers for Hermes WebUI.
+
+Keep low-level filesystem defaults here instead of in ``api.config`` so modules
+that need the default Hermes home can import them without triggering config's
+larger startup side effects.
+"""
+
+import os
+from pathlib import Path
+
+HOME = Path.home()
+
+
+def _hermes_home_has_webui_state(base: Path) -> bool:
+    """Return True when *base* holds real WebUI state under its ``webui/`` dir.
+
+    Used only on Windows to detect a pre-v0.51.134 install at the legacy
+    ``%USERPROFILE%\\.hermes`` location so we don't strand the user's existing
+    sessions/pins/settings when the default moved to ``%LOCALAPPDATA%\\hermes``
+    (#2905).
+
+    We intentionally check ONLY WebUI-owned artifacts (the ``webui/`` subtree),
+    NOT agent-owned files like ``config.yaml`` / ``auth.json``.  The agent has
+    defaulted to ``%LOCALAPPDATA%\\hermes`` on Windows since before #2897, so a
+    long-time agent user who never ran WebUI at the legacy location would have a
+    stray ``auth.json`` there — keying on that would wrongly divert a *fresh*
+    WebUI install to the legacy dir.  Only ``webui/`` state is what actually
+    gets stranded by the move, so it is the correct and narrow signal.
+    Cheap stat-only checks; never raises.
+    """
+    try:
+        if not base.is_dir():
+            return False
+        markers = (
+            base / "webui" / "sessions",        # WebUI session store
+            base / "webui" / "settings.json",   # WebUI UI settings + pins
+            base / "webui",                     # WebUI state dir at all
+        )
+        return any(m.exists() for m in markers)
+    except OSError:
+        return False
+
+
+def _platform_default_hermes_home() -> Path:
+    """Return the platform-aware default Hermes home when HERMES_HOME is unset.
+
+    Native Windows Hermes Agent installs default to %LOCALAPPDATA%\\hermes,
+    while POSIX installs use ~/.hermes.
+
+    Windows migration safety (#2905): v0.51.134 moved the Windows default from
+    ``%USERPROFILE%\\.hermes`` to ``%LOCALAPPDATA%\\hermes`` to match the agent.
+    Upgrading users whose WebUI state still lives at the old location saw an
+    empty app (sessions/pins/settings "lost" — actually just at an address the
+    new build no longer reads).  To avoid stranding that data, prefer the
+    legacy ``%USERPROFILE%\\.hermes`` ONLY when it is populated AND the new
+    ``%LOCALAPPDATA%\\hermes`` location is not yet established.  This is a
+    non-destructive, self-healing fallback: no files are moved, and once the
+    new location has state (fresh installs, or users who set HERMES_HOME) the
+    legacy path is never preferred.  Explicit HERMES_HOME / HERMES_WEBUI_STATE_DIR
+    overrides take precedence upstream and are unaffected.
+    """
+    if os.name == "nt":
+        local_app_data = os.getenv("LOCALAPPDATA", "").strip()
+        if local_app_data:
+            new_home = Path(local_app_data) / "hermes"
+            legacy_home = HOME / ".hermes"
+            # Only fall back to the legacy home if it actually holds state and
+            # the new location has not been established yet — the exact
+            # post-upgrade fingerprint from #2905.
+            if (
+                legacy_home != new_home
+                and not _hermes_home_has_webui_state(new_home)
+                and _hermes_home_has_webui_state(legacy_home)
+            ):
+                return legacy_home
+            return new_home
+    return HOME / ".hermes"

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

@@ -0,0 +1,185 @@
+"""
+Plugin discovery and static serving for Hermes Web UI.
+
+Scans ~/.hermes/plugins/<name>/dashboard/ for manifest.json files,
+matching the official Hermes dashboard plugin format.
+
+Each plugin may have:
+  dashboard/
+    manifest.json   -- tab definition and entry point
+    dist/
+      index.js      -- plugin JS bundle (IIFE)
+      style.css     -- optional plugin stylesheet
+    plugin_api.py   -- optional backend API (not used in WebUI MVP)
+"""
+import json
+import logging
+import os
+import re
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+# Valid dashboard-plugin name: a safe slug (it becomes a URL path component and
+# a settings key). Lowercase alnum + - / _, 1-64 chars, must start with a letter.
+_VALID_PLUGIN_NAME = re.compile(r"^[a-z][a-z0-9_-]{0,63}$")
+
+# Valid tab.path: a clean same-origin absolute path. Must start with a single
+# '/' (NOT '//' — a leading '//' is a protocol-relative URL that would resolve
+# to a remote origin when assigned to iframe.src), then only safe path chars —
+# no quotes, whitespace, control chars, query ('?') or fragment ('#').
+_VALID_PLUGIN_TAB_PATH = re.compile(r"^/(?!/)[A-Za-z0-9._~/-]{0,255}$")
+
+# plugin_name -> manifest dict (as loaded from manifest.json)
+PLUGIN_MANIFESTS: dict[str, dict] = {}
+
+# plugin_name -> resolved static root dir
+_PLUGIN_STATIC_ROOTS: dict[str, Path] = {}
+
+
+def _get_plugin_base() -> Path:
+    return Path(os.environ.get("HERMES_WEBUI_PLUGINS_DIR", str(Path.home() / ".hermes" / "plugins")))
+
+
+def load_plugins() -> None:
+    """Scan plugin directories and load manifest.json for each dashboard plugin."""
+    plugin_base = _get_plugin_base()
+    if not plugin_base.is_dir():
+        logger.debug("No plugins directory at %s", plugin_base)
+        return
+
+    for entry in sorted(plugin_base.iterdir()):
+        if not entry.is_dir():
+            continue
+        manifest_path = entry / "dashboard" / "manifest.json"
+        if not manifest_path.is_file():
+            continue
+
+        try:
+            manifest = json.loads(manifest_path.read_text())
+        except Exception:
+            logger.exception("Failed to parse manifest for plugin %s", entry.name)
+            continue
+
+        name = manifest.get("name") or entry.name
+
+        # Validate the plugin name: it becomes a URL path component
+        # (/dashboard-plugins/<name>/...) and a settings key. Restrict to a safe
+        # slug so a manifest like name:"../foo" can't make the URL-space ambiguous.
+        if not _VALID_PLUGIN_NAME.match(str(name)):
+            logger.warning("Skipping plugin with invalid name %r (must match %s)", name, _VALID_PLUGIN_NAME.pattern)
+            continue
+
+        tab = manifest.get("tab", {})
+        tab_path = tab.get("path", f"/{name}")
+
+        # Validate tab.path: it's a same-origin route the plugin page is served
+        # at AND a value passed into client-side navigation. Require a clean
+        # absolute path — no quotes/control chars/query/fragment — so a hostile
+        # manifest can't shadow odd routes or inject via the path.
+        if not _VALID_PLUGIN_TAB_PATH.match(str(tab_path)):
+            logger.warning("Skipping plugin %s with invalid tab.path %r (must match %s)", name, tab_path, _VALID_PLUGIN_TAB_PATH.pattern)
+            continue
+
+        if name in PLUGIN_MANIFESTS:
+            logger.warning("Duplicate plugin name skipped: %s (already loaded)", name)
+            continue
+        if tab_path in (m.get("tab", {}).get("path") for m in PLUGIN_MANIFESTS.values()):
+            logger.warning("Plugin %s tab.path %r conflicts with another plugin; skipped", name, tab_path)
+            continue
+
+        PLUGIN_MANIFESTS[name] = manifest
+        logger.info("Loaded dashboard plugin: %s (label=%s)", name, manifest.get("label", ""))
+
+        # Pre-compute static root for fast serving (points to dashboard/)
+        dashboard_dir = entry / "dashboard"
+        if dashboard_dir.is_dir():
+            _PLUGIN_STATIC_ROOTS[name] = dashboard_dir.resolve()
+
+
+def serve_plugin_static(plugin_name: str, rel_path: str) -> tuple[bytes, str] | None:
+    """
+    Serve a built static asset from a plugin's dashboard/dist/ (or static/) dir.
+
+    Returns (file_bytes, content_type) on success, None on not found.
+
+    Security: _PLUGIN_STATIC_ROOTS points at the plugin's whole dashboard/ dir
+    (the page route needs that), but the asset route must NOT expose plugin
+    source/config — e.g. dashboard/plugin_api.py, manifest.json, .env. So we
+    constrain served files to the built-asset subtrees (dist/ or static/), reject
+    dotfiles, and require a known static extension.
+    """
+    root = _PLUGIN_STATIC_ROOTS.get(plugin_name)
+    if not root:
+        return None
+
+    safe = (root / rel_path.lstrip("/")).resolve()
+    try:
+        safe.relative_to(root)
+    except ValueError:
+        return None  # path traversal attempt
+
+    # Only built-asset subtrees are servable (not the dashboard root itself,
+    # which holds plugin_api.py / manifest.json / config).
+    rel = safe.relative_to(root)
+    if not rel.parts or rel.parts[0] not in ("dist", "static"):
+        return None
+    # No dotfiles (.env, .git, etc.) anywhere in the path.
+    if any(part.startswith(".") for part in rel.parts):
+        return None
+
+    if not safe.is_file():
+        return None
+
+    # Allowlist of static asset extensions — refuse source/config (.py, .json,
+    # .toml, .env, .sh, ...) even if somehow placed under dist/.
+    ext = os.path.splitext(rel_path.lower())[1]
+    _STATIC_EXTS = {
+        ".js", ".css", ".html", ".png", ".jpg", ".jpeg", ".gif", ".svg",
+        ".ico", ".webp", ".woff", ".woff2", ".ttf", ".otf", ".map", ".txt",
+    }
+    if ext not in _STATIC_EXTS:
+        return None
+
+    data = safe.read_bytes()
+    content_type = {
+        ".js": "application/javascript; charset=utf-8",
+        ".css": "text/css; charset=utf-8",
+        ".html": "text/html; charset=utf-8",
+        ".json": "application/json; charset=utf-8",
+        ".png": "image/png",
+        ".svg": "image/svg+xml",
+        ".ico": "image/x-icon",
+    }.get(ext, "application/octet-stream")
+
+    return data, content_type
+
+
+def get_plugin_metadata() -> list[dict]:
+    """
+    Return a list of plugin metadata suitable for the Settings → Plugins tab.
+    Each entry includes name, key, version, description, and tab info for linking.
+
+    Per-plugin enabled state is stored in settings.json under `dashboard_plugins`.
+    A plugin is enabled only if the user has explicitly toggled it on (default off).
+    """
+    from api.config import load_settings
+
+    plugin_settings = load_settings().get("dashboard_plugins", {})
+    plugins = []
+    for name, manifest in sorted(PLUGIN_MANIFESTS.items()):
+        tab = manifest.get("tab", {})
+        path = tab.get("path", f"/{name}")
+        plugins.append({
+            "name": manifest.get("label") or manifest.get("name") or name,
+            "key": name,
+            "version": manifest.get("version", "0.0.0"),
+            "description": manifest.get("description", ""),
+            "tab": {
+                "path": path,
+                "label": tab.get("label") or manifest.get("label") or name,
+            },
+            "enabled": bool(plugin_settings.get(name, False)),
+            "hooks": [],
+        })
+    return plugins