@bitseek/hermes-webui 0.1.0-beta.0

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

@@ -0,0 +1,238 @@
+"""Clarify prompt state for the WebUI.
+
+This mirrors the approval flow structure, but the response is a free-form
+clarification string instead of an approval decision.
+"""
+
+from __future__ import annotations
+
+import queue
+import threading
+import time
+import uuid
+from typing import Optional
+
+from api.session_events import publish_session_list_changed
+
+
+DEFAULT_TIMEOUT_SECONDS = 120
+_lock = threading.Lock()
+_pending: dict[str, dict] = {}
+_gateway_queues: dict[str, list] = {}
+_gateway_notify_cbs: dict[str, object] = {}
+
+# ── SSE subscriber registry ─────────────────────────────────────────────
+_clarify_sse_subscribers: dict[str, list[queue.Queue]] = {}
+
+
+class _ClarifyEntry:
+    """One pending clarify request inside a session."""
+
+    __slots__ = ("event", "data", "result", "clarify_id")
+
+    def __init__(self, data: dict):
+        self.event = threading.Event()
+        self.data = data
+        self.result: Optional[str] = None
+        self.clarify_id: str = data.get("clarify_id", "") or uuid.uuid4().hex[:12]
+
+
+def register_gateway_notify(session_key: str, cb) -> None:
+    """Register a per-session callback for sending clarify requests to the UI."""
+    with _lock:
+        _gateway_notify_cbs[session_key] = cb
+
+
+def _clear_queue_locked(session_key: str) -> list[_ClarifyEntry]:
+    entries = _gateway_queues.pop(session_key, [])
+    _pending.pop(session_key, None)
+    return entries
+
+
+def unregister_gateway_notify(session_key: str) -> None:
+    """Unregister the per-session callback and unblock any waiting clarify prompt."""
+    with _lock:
+        _gateway_notify_cbs.pop(session_key, None)
+        entries = _clear_queue_locked(session_key)
+    if entries:
+        publish_session_list_changed("attention_cleared")
+    for entry in entries:
+        entry.event.set()
+
+
+def clear_pending(session_key: str) -> int:
+    """Clear any pending clarify prompts for the session without removing the callback."""
+    with _lock:
+        entries = _clear_queue_locked(session_key)
+    if entries:
+        publish_session_list_changed("attention_cleared")
+    for entry in entries:
+        entry.event.set()
+    return len(entries)
+
+
+def _with_timeout_metadata(data: dict) -> dict:
+    item = dict(data or {})
+    requested_at = float(item.get("requested_at") or time.time())
+    timeout_seconds = int(item.get("timeout_seconds") or DEFAULT_TIMEOUT_SECONDS)
+    expires_at = float(item.get("expires_at") or requested_at + timeout_seconds)
+    item["requested_at"] = requested_at
+    item["timeout_seconds"] = timeout_seconds
+    item["expires_at"] = expires_at
+    return item
+
+
+def _clarify_sse_notify(session_id: str, head: dict | None, total: int) -> None:
+    """Push a clarify event to all SSE subscribers for a session."""
+    payload = {"pending": dict(head) if head else None, "pending_count": total}
+    for q in _clarify_sse_subscribers.get(session_id, ()):
+        try:
+            q.put_nowait(payload)
+        except queue.Full:
+            pass  # drop if subscriber is slow
+
+
+def sse_subscribe(session_id: str) -> queue.Queue:
+    """Register a bounded Queue for SSE push to a given session."""
+    q: queue.Queue = queue.Queue(maxsize=16)
+    with _lock:
+        _clarify_sse_subscribers.setdefault(session_id, []).append(q)
+    return q
+
+
+def sse_unsubscribe(session_id: str, q: queue.Queue) -> None:
+    """Remove a subscriber Queue; clean up empty session entries."""
+    with _lock:
+        subs = _clarify_sse_subscribers.get(session_id)
+        if subs:
+            try:
+                subs.remove(q)
+            except ValueError:
+                pass
+            if not subs:
+                _clarify_sse_subscribers.pop(session_id, None)
+
+
+def submit_pending(session_key: str, data: dict) -> _ClarifyEntry:
+    """Queue a pending clarify request and notify the UI callback if registered."""
+    data = _with_timeout_metadata(data)
+    with _lock:
+        gw_queue = _gateway_queues.setdefault(session_key, [])
+        # De-duplicate while unresolved: if the most recent pending clarify is
+        # semantically identical, reuse it instead of stacking duplicates.
+        if gw_queue:
+            last = gw_queue[-1]
+            if (
+                str(last.data.get("question", "")) == str(data.get("question", ""))
+                and list(last.data.get("choices_offered") or [])
+                == list(data.get("choices_offered") or [])
+            ):
+                entry = last
+                # Dedup re-uses the existing entry with its original clarify_id.
+                # If a future caller pre-populates clarify_id in data, it is
+                # silently discarded here — the original entry's id wins.
+                # Today no caller sets clarify_id (it's generated by __init__),
+                # so this is a non-issue.
+                cb = _gateway_notify_cbs.get(session_key)
+                # Keep _pending aligned to the oldest unresolved entry.
+                _pending[session_key] = gw_queue[0].data
+                if cb:
+                    try:
+                        cb(dict(entry.data))
+                    except Exception:
+                        pass
+                # Safe to call while holding _lock: publish() only takes the
+                # leaf _SESSION_EVENTS_LOCK and never re-acquires this lock.
+                publish_session_list_changed("attention_pending")
+                return entry
+
+        entry = _ClarifyEntry(data)
+        # Ensure clarify_id is present in the serialised data the frontend receives.
+        entry.data["clarify_id"] = entry.clarify_id
+        gw_queue.append(entry)
+        _pending[session_key] = gw_queue[0].data
+        cb = _gateway_notify_cbs.get(session_key)
+        # Notify SSE subscribers from inside _lock for ordering guarantees.
+        _clarify_sse_notify(session_key, dict(gw_queue[0].data), len(gw_queue))
+    publish_session_list_changed("attention_pending")
+    if cb:
+        try:
+            cb(data)
+        except Exception:
+            pass
+    return entry
+
+
+def get_pending(session_key: str) -> dict | None:
+    """Return the oldest pending clarify request for this session, if any."""
+    with _lock:
+        queue = _gateway_queues.get(session_key) or []
+        if queue:
+            return dict(queue[0].data)
+        pending = _pending.get(session_key)
+        return dict(pending) if pending else None
+
+
+def has_pending(session_key: str) -> bool:
+    with _lock:
+        return bool(_gateway_queues.get(session_key))
+
+
+def pending_count(session_key: str) -> int:
+    """Return the number of unresolved clarify prompts for a session."""
+    with _lock:
+        queue = _gateway_queues.get(session_key) or []
+        if queue:
+            return len(queue)
+        return 1 if _pending.get(session_key) else 0
+
+
+def resolve_clarify(session_key: str, response: str, resolve_all: bool = False) -> int:
+    """Resolve the oldest pending clarify request for a session."""
+    with _lock:
+        q = _gateway_queues.get(session_key)
+        if not q:
+            _pending.pop(session_key, None)
+            return 0
+        entries = list(q) if resolve_all else [q.pop(0)]
+        if q:
+            _pending[session_key] = q[0].data
+            _clarify_sse_notify(session_key, dict(q[0].data), len(q))
+        else:
+            _clear_queue_locked(session_key)
+            _clarify_sse_notify(session_key, None, 0)
+    publish_session_list_changed("attention_resolved")
+    count = 0
+    for entry in entries:
+        entry.result = response
+        entry.event.set()
+        count += 1
+    return count
+
+
+def resolve_clarify_by_id(session_key: str, clarify_id: str, response: str) -> bool:
+    """Resolve a specific pending clarify request by its stable id.
+
+    Returns True if the id was found and resolved, False otherwise.
+    """
+    with _lock:
+        q = _gateway_queues.get(session_key)
+        if not q:
+            _pending.pop(session_key, None)
+            return False
+        for i, entry in enumerate(q):
+            if entry.clarify_id == clarify_id:
+                q.pop(i)
+                if q:
+                    _pending[session_key] = q[0].data
+                    _clarify_sse_notify(session_key, dict(q[0].data), len(q))
+                else:
+                    _clear_queue_locked(session_key)
+                    _clarify_sse_notify(session_key, None, 0)
+                # Safe to call while holding _lock: publish() only takes the
+                # leaf _SESSION_EVENTS_LOCK and never re-acquires this lock.
+                publish_session_list_changed("attention_resolved")
+                entry.result = response
+                entry.event.set()
+                return True
+        return False

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

@@ -0,0 +1,124 @@
+"""Expose hermes-agent's COMMAND_REGISTRY to the webui frontend.
+
+This module is the single integration point with hermes_cli.commands.
+If hermes-agent is unavailable the endpoint degrades to an empty list
+so the frontend can still load with WEBUI_ONLY commands.
+"""
+from __future__ import annotations
+import logging
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+# Commands that are gateway_only in the agent registry -- webui never
+# wants to expose them (sethome, restart, update etc.) even if a future
+# agent version drops the gateway_only flag. /commands is the agent's
+# own command-listing command; webui has its own /help that calls
+# cmdHelp() locally, so /commands would be redundant and confusing.
+_NEVER_EXPOSE: frozenset[str] = frozenset({
+    'sethome', 'restart', 'update', 'commands',
+})
+
+
+def list_commands(_registry=None) -> list[dict[str, Any]]:
+    """Return COMMAND_REGISTRY entries as JSON-friendly dicts.
+
+    Returns empty list if hermes_cli is not installed (graceful
+    degradation -- the frontend has its own fallback minimum set).
+
+    Args:
+        _registry: Optional injected registry for testing. When None
+            (production), imports COMMAND_REGISTRY from hermes_cli.
+    """
+    if _registry is None:
+        try:
+            from hermes_cli.commands import COMMAND_REGISTRY as _registry
+        except ImportError:
+            logger.warning("hermes_cli.commands not importable -- /api/commands returns []")
+            return []
+
+    out: list[dict[str, Any]] = []
+    for cmd in _registry:
+        if cmd.gateway_only:
+            continue
+        if cmd.name in _NEVER_EXPOSE:
+            continue
+        out.append({
+            'name': cmd.name,
+            'description': cmd.description,
+            'category': cmd.category,
+            'aliases': list(cmd.aliases),
+            'args_hint': cmd.args_hint,
+            'subcommands': list(cmd.subcommands),
+            'cli_only': bool(cmd.cli_only),
+            'gateway_only': bool(cmd.gateway_only),
+        })
+
+    # Include plugin-registered slash commands
+    try:
+        from hermes_cli.plugins import get_plugin_commands
+        plugin_cmds = get_plugin_commands() or {}
+        existing_names = {c['name'] for c in out}
+        for cmd_name, cmd_info in plugin_cmds.items():
+            if cmd_name in existing_names or cmd_name in _NEVER_EXPOSE:
+                continue
+            out.append({
+                'name': cmd_name,
+                'description': str(cmd_info.get('description', 'Plugin command')),
+                'category': 'Plugin',
+                'aliases': [],
+                'args_hint': str(cmd_info.get('args_hint', '')),
+                'subcommands': [],
+                'cli_only': False,
+                'gateway_only': False,
+            })
+    except Exception:
+        pass
+
+    return out
+
+
+def execute_plugin_command(command: str) -> str:
+    """Execute a plugin-registered slash command and return printable output.
+
+    Unknown commands raise ``KeyError`` so the HTTP layer can return 404.
+    Plugin handler failures are returned as output text instead of surfacing as
+    transport errors, matching Hermes' existing slash-command UX.
+    """
+
+    raw = str(command or "").strip()
+    if not raw:
+        raise ValueError("command is required")
+
+    cmd_text = raw[1:] if raw.startswith("/") else raw
+    cmd_parts = cmd_text.split(maxsplit=1)
+    cmd_base = (cmd_parts[0] if cmd_parts else "").strip().lower()
+    cmd_arg = cmd_parts[1] if len(cmd_parts) > 1 else ""
+    if not cmd_base:
+        raise ValueError("command is required")
+
+    try:
+        from hermes_cli.plugins import (
+            get_plugin_command_handler,
+            resolve_plugin_command_result,
+        )
+    except ImportError as exc:
+        raise RuntimeError("plugin command runtime unavailable") from exc
+
+    try:
+        handler = get_plugin_command_handler(cmd_base)
+    except Exception as exc:
+        raise RuntimeError(f"plugin command lookup failed: {exc}") from exc
+
+    if not handler:
+        raise KeyError(cmd_base)
+
+    try:
+        result = resolve_plugin_command_result(handler(cmd_arg))
+        return str(result or "(no output)")
+    except Exception as exc:
+        # Don't leak raw exception str (paths, env, internal state) to the
+        # user-facing chat. Type name is enough for the user to know what
+        # class of failure occurred; full traceback lives in the server log.
+        logger.warning("Plugin command %r failed", cmd_base, exc_info=exc)
+        return f"Plugin command error: {type(exc).__name__}"

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

@@ -0,0 +1,134 @@
+"""
+Shared helpers for session compression anchor metadata.
+
+Manual compression anchoring versus automatic compression paths
+===============================================================
+
+When ``auto_compression=True`` is passed to ``visible_messages_for_anchor()``,
+the function accepts a broader set of message content types (including
+provider-style ``input_text`` / ``output_text`` parts) and metadata markers
+(``reasoning``, ``thinking``, etc.) from any non-tool role. This enables the
+streaming auto-compression path to determine which messages should anchor
+compression UI metadata without being limited to the legacy manual-compression
+rules.
+
+When ``auto_compression=False`` (the default), the function applies the
+historical manual-compression rules: only plain ``text`` content parts from
+non-assistant roles are counted.
+
+Why this module exists
+======================
+
+Compression anchoring needs to identify which messages in a session transcript
+are semantically significant enough to seed the compression UI metadata (e.g.,
+message count, token budget display). The original implementation hard-coded
+these rules in multiple places. This module consolidates the logic so that:
+
+1. Manual compression anchoring (CLI/legacy path) uses the stricter ruleset.
+2. Automatic compression (streaming/agent path) can leverage the relaxed ruleset
+   when it knows it is handling provider-style messages.
+
+Callers specify ``auto_compression=True`` when the messages may originate from
+an automatic/compression-aware pipeline, and ``False`` (default) for manual
+compression contexts.
+"""
+
+
+def _content_text(content, *, part_types):
+    if isinstance(content, list):
+        return "\n".join(
+            str(part.get("text") or part.get("content") or "")
+            for part in content
+            if isinstance(part, dict) and part.get("type") in part_types
+        ).strip()
+    return str(content or "").strip()
+
+
+def _content_has_part_type(content, part_types):
+    if not isinstance(content, list):
+        return False
+    return any(
+        isinstance(part, dict) and part.get("type") in part_types
+        for part in content
+    )
+
+
+def is_context_compression_marker(message):
+    """Return true for synthetic compression/reference cards, not user turns."""
+    if not isinstance(message, dict):
+        return False
+    role = message.get("role")
+    if not role or role == "tool":
+        return False
+    text = _content_text(
+        message.get("content", ""),
+        part_types={"text", "input_text", "output_text"},
+    ).lower().lstrip()
+    return (
+        text.startswith("[context compaction")
+        or text.startswith("context compaction")
+        or text.startswith("[your active task list was preserved across context compression]")
+        or text.startswith("[session arc summary")
+    )
+
+
+def _is_context_compression_marker(message):
+    """Backward-compatible alias for callers that have not switched yet."""
+    return is_context_compression_marker(message)
+
+
+def visible_messages_for_anchor(messages, *, auto_compression: bool = False):
+    """Return transcript messages that can anchor compression UI metadata.
+
+    Manual compression historically only counted plain ``text`` content parts
+    for non-assistant messages, while the streaming auto-compression path also
+    accepted provider-style ``input_text`` / ``output_text`` parts and metadata
+    markers on any non-tool role. Keep that difference explicit at the call site
+    instead of carrying two near-identical helper implementations.
+    """
+    out = []
+    text_part_types = {"text", "input_text", "output_text"} if auto_compression else {"text"}
+    for message in messages or []:
+        if not isinstance(message, dict):
+            continue
+        role = message.get("role")
+        if not role or role == "tool":
+            continue
+        if _is_context_compression_marker(message):
+            continue
+
+        content = message.get("content", "")
+        has_attachments = bool(message.get("attachments"))
+        text = _content_text(content, part_types=text_part_types)
+
+        if auto_compression:
+            has_tool_calls = bool(
+                isinstance(message.get("tool_calls"), list) and message.get("tool_calls")
+            )
+            has_tool_use = _content_has_part_type(content, {"tool_use"})
+            has_reasoning = bool(message.get("reasoning"))
+            if not text:
+                has_reasoning = has_reasoning or _content_has_part_type(
+                    content,
+                    {"thinking", "reasoning"},
+                )
+            if text or has_attachments or has_tool_calls or has_tool_use or has_reasoning:
+                out.append(message)
+            continue
+
+        if role == "assistant":
+            has_tool_calls = bool(
+                isinstance(message.get("tool_calls"), list) and message.get("tool_calls")
+            )
+            has_tool_use = _content_has_part_type(content, {"tool_use"})
+            has_reasoning = bool(message.get("reasoning")) or _content_has_part_type(
+                content,
+                {"thinking", "reasoning"},
+            )
+            if text or has_attachments or has_tool_calls or has_tool_use or has_reasoning:
+                out.append(message)
+            continue
+
+        if text or has_attachments:
+            out.append(message)
+    return out