mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-11-16 02:46:38 +03:00
eef9a3e52c
Under plugins.isolation: host, discover_and_load(force=True) (reload-plugins, and every plugin install, enable or update) loads a plugin again into the same host process under the same plugin_key. A task the first load spawned kept running, and its emit_plugin_session_event was taken for the new load and published to the session's viewers. - Hermes numbers each load of a plugin in the host (load), sends it with the load request, and forgets it at unload. - The host binds that load, with the plugin, to each request it serves, so it follows the request's code onto the tasks it spawns; session_event carries it. - The gateway process publishes only when that load is the plugin's current one; otherwise it logs and returns False, as the hosted call did before this PR forwarded it. A category plugin's fresh instance keeps its key's load. - ctx.emit_to_session reads the manager's home_path directly: every manager sets it, as the other readers of the plugin's own profile assume. Suggested by @BearHuddleston in review. - The late-event test now covers a same-host reload and waits with tests.waiting.wait_until and Events instead of sleep loops. ctx.emit_to_session from such a task is unchanged (it reached viewers on main too). Refs #142005, #141982
122 lines
6.5 KiB
Python
122 lines
6.5 KiB
Python
"""Public event bridge for plugin backends (``plugin_api.py``, slash commands).
|
|
|
|
A plugin's backend runs inside the gateway process. To push an update to its
|
|
OWN desktop half it emits on the app's global event stream — the same stream
|
|
``host.onEvent`` subscribes to in the renderer::
|
|
|
|
from hermes_cli.plugin_events import broadcast_plugin_event
|
|
|
|
broadcast_plugin_event("rss-reader", "feed.updated", {"count": 3})
|
|
# event "plugin.rss-reader.feed.updated" reaches every connected desktop client
|
|
|
|
The desktop half filters for its own name::
|
|
|
|
host.onEvent('plugin.rss-reader.feed.updated', ({ payload }) => …)
|
|
|
|
This module is the sanctioned door for that: plugin backends must never import
|
|
``tui_gateway.server`` privates (``_broadcast_global_event``), whose signature
|
|
is core-internal. The ``plugin.`` prefix keeps plugin traffic out of core's own
|
|
event names (``skin.changed``, ``session.reclaimed``, …).
|
|
|
|
Delivery is per process: the frame goes to the clients of the gateway the
|
|
caller runs in. Under ``hermes serve`` (the Desktop backend, where plugin
|
|
routers, slash commands and the agent turn's tools/hooks run) that is every
|
|
connected window; a call from the ``dashboard.turn_isolation`` compute-host
|
|
child rides the host pipe to ``hermes serve`` and fans out there. A process
|
|
with no Desktop client at all (``hermes gateway run``, ``hermes chat``, cron)
|
|
has nobody to deliver to: the call is a logged no-op.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import json
|
|
import logging
|
|
import re
|
|
from typing import Any, Callable, Optional
|
|
|
|
logger = logging.getLogger(__name__)
|
|
|
|
#: Every plugin event name starts with this — core owns all other names.
|
|
PLUGIN_EVENT_PREFIX = "plugin."
|
|
|
|
# Plugin ids are the catalog names (``plugin_catalog._NAME_RE``): lowercase, digits, ``_``/``-``.
|
|
# No dot: ``plugin.<id>.`` must be an unambiguous prefix, so an id can never spell a neighbour's
|
|
# namespace (``other.x`` would read as plugin ``other``).
|
|
_PLUGIN_ID_RE = re.compile(r"^[a-z0-9_-]{1,64}$")
|
|
# Dotted hierarchy like core's own names (``display.install.done``): non-empty segments of
|
|
# [A-Za-z0-9_-], so ``../x``, ``a..b``, a leading/trailing dot, slashes and whitespace are refused.
|
|
_EVENT_RE = re.compile(r"^[A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+)*$")
|
|
|
|
# Set only inside a ``plugins.isolation: host`` process (``hermes_cli/plugin_host_child.py``): sessions
|
|
# live in the gateway process, so a session event crosses the host channel to it.
|
|
_session_event_forwarder: Optional[Callable[[str, str, str, dict], bool]] = None
|
|
|
|
|
|
def plugin_event_name(plugin_id: str, event: str, *, kind: str = "event") -> str:
|
|
"""The wire name for one plugin event (or RPC method, ``kind``): ``plugin.<plugin_id>.<event>``.
|
|
|
|
Raises ``ValueError`` for an id or event that cannot form one — a silently
|
|
mangled name would strand the desktop half waiting on a name nobody emits.
|
|
"""
|
|
if not isinstance(plugin_id, str) or not _PLUGIN_ID_RE.match(plugin_id):
|
|
raise ValueError(f"invalid plugin id {plugin_id!r}: expected [a-z0-9_-]{{1,64}}")
|
|
if not isinstance(event, str) or len(event) > 128 or not _EVENT_RE.match(event):
|
|
raise ValueError(
|
|
f"invalid plugin {kind} {event!r}: expected dot-separated segments of [A-Za-z0-9_-] "
|
|
"(the plugin id already namespaces the name)"
|
|
)
|
|
return f"{PLUGIN_EVENT_PREFIX}{plugin_id}.{event}"
|
|
|
|
|
|
def broadcast_plugin_event(plugin_id: str, event: str, payload: Optional[dict[str, Any]] = None) -> None:
|
|
"""Emit ``plugin.<plugin_id>.<event>`` to every connected client.
|
|
|
|
Fire-and-forget and safe to call from any request handler: delivery fans out
|
|
over the gateway's live transports, and a wedged peer is skipped rather than
|
|
stalling the caller. ``payload`` must be a dict (or ``None`` for ``{}``).
|
|
"""
|
|
if payload is not None and not isinstance(payload, dict):
|
|
raise TypeError(f"plugin event payload must be a dict or None, got {type(payload).__name__}")
|
|
name = plugin_event_name(plugin_id, event)
|
|
|
|
# Late import: plugin backends load before the gateway server is up in some
|
|
# hosts (CLI tooling imports plugin_api modules for route inspection), and
|
|
# tui_gateway.server pulls in the transport stack.
|
|
try:
|
|
from tui_gateway.server import _broadcast_global_event
|
|
except ImportError:
|
|
# A plugin-only process (``hermes plugins validate`` importing the backend, a trimmed
|
|
# install) has no gateway at all: nobody to deliver to, and the handler must not die for it.
|
|
logger.warning("plugin event %s dropped: no tui_gateway in this process", name, exc_info=True)
|
|
return
|
|
|
|
_broadcast_global_event(name, dict(payload or {}))
|
|
|
|
|
|
def emit_plugin_session_event(plugin_id: str, session_id: str, event: str,
|
|
payload: Optional[dict[str, Any]] = None) -> bool:
|
|
"""Emit ``plugin.<plugin_id>.<event>`` to the viewers of ``session_id`` only, on that session's
|
|
event stream (so a viewer that reconnects replays it). True when a live viewer took it; False when
|
|
none did, or when this process holds no session authority with that session.
|
|
|
|
Under ``plugins.isolation: host`` the call is forwarded to the gateway process and looked up in the
|
|
host's profile, sent as the plugin whose code is running in that host request: False, and nothing
|
|
sent, when ``plugin_id`` is not that loaded plugin's own, when that code is from a load since
|
|
unloaded (a task left running across a reload), and, usually, from a thread the plugin started (it
|
|
carries no request the host can attribute). In-process ``plugin_id`` is taken as given, and the session is looked
|
|
up in the caller's profile scope: from a thread the plugin started (no scope), use
|
|
``ctx.emit_to_session``, which knows the plugin's profile.
|
|
"""
|
|
if not isinstance(session_id, str) or not session_id:
|
|
raise ValueError("plugin session event needs a session_id")
|
|
if payload is not None and not isinstance(payload, dict):
|
|
raise TypeError(f"plugin event payload must be a dict or None, got {type(payload).__name__}")
|
|
name = plugin_event_name(plugin_id, event)
|
|
# Encoded here, at the caller: a frame the viewer's socket cannot encode would end that connection,
|
|
# and NaN/Infinity are not JSON (a client's JSON.parse would drop the frame and its replay).
|
|
body = json.loads(json.dumps(payload or {}, allow_nan=False))
|
|
if _session_event_forwarder is not None:
|
|
return bool(_session_event_forwarder(plugin_id, session_id, event, body))
|
|
from gateway.session_plugin_rpc import publish_session_event
|
|
return publish_session_event(session_id, name, body)
|