The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
"""Plugin slash commands of the classic CLI on the shared gateway (``slash.exec``).
On main a plugin's ``/command`` ran in this process. Rewired, the plugin's hooks, tools and MCP servers
live in the gateway, so its command runs there too (``gateway/session_commands.py``, the messaging
gateway's own plugin dispatch): ``ctx.call_mcp`` reaches the servers the gateway connected, and this
process never imports the plugin to run it. The names come from the gateway's ``commands.catalog``,
read once per session and gateway life (``/new``, resume and a redial read again) and again once when
a typed name misses, so a plugin the gateway enabled since still dispatches; a cached name a plugin
reload dropped since is re-read once when the gateway refuses it, then dispatched again (:data:`GONE`).
A catalog whose ``plugin_discovery_error`` is set lists no plugins because the gateway could not load
them, not because there are none: it is treated as a failed read and never cached. Off the gateway
(tests, the TUI slash worker's shadow CLI) main's dispatch applies.
"""
from __future__ import annotations
import logging
import threading
from hermes_cli.gateway_client import GatewayClientError
logger = logging.getLogger(__name__)
_CATEGORY = "Plugin commands" # tui_gateway/command_discovery.py
GONE = object() # run(): the gateway no longer has the command; the caller dispatches the name again
STOPPED = object() # call_unbounded(): Ctrl+C stopped the wait (the stopped line is printed)
_GONE_LINE = " /{}: the gateway no longer has this plugin command; nothing was run."
_CHOICE_POLL_S = 0.1 # how often a running command's clarify requests are looked for
_STOPPED_LINE = " /{}: stopped waiting. The command keeps running in the gateway and its reply will not be shown."
class CatalogUnavailable(Exception):
"""The gateway's command list could not be read (already printed): run nothing for this input."""
def _boundary(cli, connection):
return connection, getattr(connection, "epoch", None), getattr(cli, "session_id", None)
def _read(cli, connection):
"""Fetch the catalog's plugin commands and cache them for the session and gateway life that served
them (raises GatewayClientError, also when the gateway reports its plugin discovery failed). The
result is published only if neither moved during the call: a reply from epoch E that arrives after
a concurrent redial is never relabelled E+1 (``call_tagged``)."""
session = getattr(cli, "session_id", None)
catalog, epoch = _catalog(cli, connection, session)
catalog = catalog or {}
if catalog.get("plugin_discovery_error"): # absent on older gateways: today's behaviour
raise GatewayClientError(f"plugin command discovery failed: {catalog['plugin_discovery_error']}")
listed = catalog.get("plugin_commands")
if isinstance(listed, dict): # every plugin command, also one a display row (Ink's /logs) hides
found = {str(name).lstrip("/"): str(desc or "") for name, desc in listed.items()}
else: # older gateways: the display category
found = {}
for category in catalog.get("categories") or []:
if isinstance(category, dict) and category.get("name") == _CATEGORY:
for row in category.get("pairs") or []:
if isinstance(row, (list, tuple)) and len(row) == 2 and isinstance(row[0], str):
found[row[0].lstrip("/")] = str(row[1] or "")
# The session's skill commands as the gateway resolved them (its plugin skills included): /help,
# completion and dispatch read these, so this process never scans plugin skills to list them.
descriptions = {row[0]: str(row[1] or "") for row in catalog.get("pairs") or []
if isinstance(row, (list, tuple)) and len(row) == 2 and isinstance(row[0], str)}
skills = {key: {"name": key.lstrip("/"), "description": descriptions.get(key) or "Skill"}
for key in catalog.get("skills") or {} if isinstance(key, str)}
served = (connection, epoch, session)
if _boundary(cli, connection) == served:
cli._gateway_plugin_commands = (served, found)
cli._gateway_skills = (served, skills, str(catalog.get("warning") or ""))
return found
def _catalog(cli, connection, session):
"""``(commands.catalog, epoch)`` for the open gateway session, so its skills come from the session's
folder (its trusted project skills), not the gateway's. A gateway older than this CLI refuses the
``session_id`` (``invalid_params``): it is asked again without it, as before."""
from hermes_cli.gateway_client import GatewayRPCError
if session and getattr(cli, "_gateway_session_open", False):
try:
return connection.call_tagged("commands.catalog", session_id=session)
except GatewayRPCError as exc:
if str(exc) != "invalid_params":
raise
return connection.call_tagged("commands.catalog")
def invalidate(cli):
"""Drop ``cli``'s copy of the gateway's catalog after a skill rescan (``/reload-skills``, ``/skills
install``): the next read asks the gateway again."""
cli._gateway_plugin_commands = cli._gateway_skills = None
def _hung_up(connection):
"""A closed connection keeps its epoch until the next call redials, maybe to another life: no
cache it labelled is served."""
return getattr(connection, "closed", False)
def _cached(cli, connection):
if _hung_up(connection):
return None
boundary, found = getattr(cli, "_gateway_plugin_commands", None) or (None, None)
return found if boundary == _boundary(cli, connection) else None
def skills(cli, *, notes=False):
"""``{"/key": {name, description}}`` of the session's skill commands from the gateway's catalog
(``notes``: its one-line notice instead, e.g. skills a built-in command shadows), or None off the
gateway. A failed read is printed once per input and lists none; nothing is scanned here."""
from hermes_cli.gateway_side import connection_for
connection = connection_for(cli)
if connection is None:
return None
boundary, found, warning = getattr(cli, "_gateway_skills", None) or (None, None, "")
if _hung_up(connection) or boundary != _boundary(cli, connection):
try:
_read(cli, connection)
except GatewayClientError as exc:
logger.debug("commands.catalog unavailable: %s", exc)
return "" if notes else {}
_seen, found, warning = getattr(cli, "_gateway_skills", None) or (None, {}, "")
return warning if notes else found
def skill_notes(cli):
"""``/help skills`` notes (skills a built-in command shadows): the gateway's notice on its session,
else this process's own scan."""
notice = skills(cli, notes=True)
if notice is not None:
return [notice] if notice else []
from agent.skill_commands import skill_command_collision_note
from tools.skills_tool import find_all_skills
return list(filter(None, (skill_command_collision_note(s["name"]) for s in find_all_skills())))
def run_skill(cli, base_cmd, rest):
"""``/skill ...`` on the gateway session: the gateway resolves and loads the skill (its plugin
skills and stacked skills too) and returns the message, which is queued as main queued it; True
when answered there (False off the gateway: main's local load)."""
from hermes_cli.gateway_side import connection_for
connection = connection_for(cli)
if connection is None:
return False
from agent.i18n import t
from cli import _cprint
command = base_cmd.lstrip("/") + (" " + rest if rest else "")
try:
reply = connection.call("slash.exec", session_id=cli.session_id, command=command) or {}
except GatewayClientError as exc:
_cprint(f" {base_cmd}: {exc}")
return True
if reply.get("type") == "skill" and reply.get("message"):
cli._queue_loaded_skills(reply["message"], t("cli.skills.loading_skill", name=reply.get("name") or command), None)
if reply.get("notice") or reply.get("output"):
_cprint(f" {reply.get('notice') or reply.get('output')}")
return True
def toolsets(cli):
"""``([(key, label, description)], {portable MCP server})`` the gateway's plugins provide for this
profile (``plugins.list``), or None off the gateway (this process's own registry applies). An older
gateway or a failed read gives none, never a local scan. Read once per gateway life."""
from hermes_cli.gateway_side import connection_for
connection = connection_for(cli)
if connection is None:
return None
boundary = (connection, getattr(connection, "epoch", None))
cached = getattr(cli, "_gateway_plugin_toolsets", None)
if cached and cached[0] == boundary and not _hung_up(connection):
return cached[1]
try:
reply = connection.call("plugins.list") or {}
except GatewayClientError as exc:
logger.debug("plugins.list unavailable: %s", exc)
return [], set()
rows = [(str(r.get("key")), str(r.get("label") or r.get("key")), str(r.get("description") or ""))
for r in reply.get("toolsets") or [] if isinstance(r, dict) and isinstance(r.get("key"), str)]
found = (rows, {str(n) for n in reply.get("portable_mcp_servers") or [] if isinstance(n, str)})
cli._gateway_plugin_toolsets = (boundary, found)
return found
def names(cli):
"""``{name: description}`` of the gateway's plugin commands for completion, or None off the
gateway. A failed read degrades quietly to none; dispatch uses :func:`lookup`."""
from hermes_cli.gateway_side import connection_for
connection = connection_for(cli)
if connection is None:
return None
found = _cached(cli, connection)
if found is None:
try:
found = _read(cli, connection)
except GatewayClientError:
return {} # not cached: the next read asks again
return found
def lookup(cli, name):
"""Whether ``/name`` is one of the gateway's plugin commands; None off the gateway. A name the
cached list lacks re-reads it once. A failed read is not evidence the name is no plugin: it is
printed and :class:`CatalogUnavailable` raised, so no skill, bundle or expansion stands in."""
from hermes_cli.gateway_side import connection_for
connection = connection_for(cli)
if connection is None:
return None
found = _cached(cli, connection)
if found is not None and name in found:
return True
try:
return name in _read(cli, connection)
except GatewayClientError as exc:
from cli import _cprint
_cprint(f" /{name}: the gateway's command list is unavailable ({exc}); nothing was run.")
raise CatalogUnavailable(name) from exc
def call_unbounded(cli, connection, name, command):
"""``slash.exec`` of *command* with no answer deadline, on a socket of its own so the session's prompts
and interrupts never queue behind it (GatewayConnection.call_until). Ctrl+C stops waiting: the stopped
line is printed and :data:`STOPPED` returned (a KeyboardInterrupt still propagates after it)."""
from cli import _cprint
from hermes_cli.gateway_connection import CallStopped
wake = cli._gateway_command_wait = threading.Event() # set by Ctrl+C (cli_tui_mixin)
from agent.memory_provider import spawn_context_thread
answering: list = [] # the clarify request id the panel is answering, while it is open
spawn_context_thread(_answer_choices, args=(cli, connection, wake, answering), name="hermes-command-choices").start()
try:
return connection.call_until("slash.exec", wake, session_id=cli.session_id, command=command)
except (CallStopped, KeyboardInterrupt) as exc:
_cprint(_STOPPED_LINE.format(name))
if isinstance(exc, KeyboardInterrupt):
raise
return STOPPED
finally:
cli._gateway_command_wait = None
if answering: # the command is over: its picker must not keep the input
cli._withdraw_gateway_modal("clarify")
def _answer_choices(cli, connection, wake, answering):
"""While the command runs, answer the ``clarify`` server requests its handler sends to this session
(``ctx.ask_choice``, ``gateway/plugin_command_choice.py``) with the CLI's clarify panel. No turn
pump reads the session's frames between turns, so they are taken here; every other frame stays
queued, in order, for the turn that owns it."""
from hermes_cli.gateway_agent import clarify_reply
events, state = connection.events, connection.state(cli.session_id)
def withdrawn(payload):
# ``request.cancel`` for the request the panel is answering (another viewer picked, or the gateway's
# wait ended): close the panel, as GatewayAgent does for a turn's modal.
if answering and payload.get("id") == answering[0]:
cli._withdraw_gateway_modal("clarify")
state.request_listeners.append(withdrawn)
try:
while not wake.wait(_CHOICE_POLL_S):
with events.mutex:
asks = [frame for frame in events.queue if isinstance(frame, dict) and frame.get("method") == "clarify"
and "id" in frame and (frame.get("params") or {}).get("session_id") == cli.session_id]
for frame in asks:
events.queue.remove(frame)
for frame in asks:
answering[:] = [frame["id"]]
try:
reply = clarify_reply(cli._clarify_callback, frame["params"])
finally:
answering.clear()
connection.reply(frame["id"], reply)
finally:
state.request_listeners.remove(withdrawn)
def run(cli, name, arg):
"""True when the gateway answered ``/name arg`` (the local handler must not run); :data:`GONE`
when it no longer has that plugin command and a fresh catalog read agrees (a plugin reload, e.g.
``hermes plugins disable``, dropped it in this session and gateway life, which no cache boundary
sees): nothing ran, and the caller dispatches the name again (bundle, skill, prefix)."""
from hermes_cli.gateway_side import connection_for
connection = connection_for(cli)
if connection is None:
return False
from cli import _cprint
from hermes_cli.gateway_client import GatewayRPCError
# No answer deadline: main's CLI waited for the handler, which may wait minutes (ctx.call_mcp).
try:
reply = call_unbounded(cli, connection, name, name + (" " + arg if arg else ""))
except GatewayRPCError as exc:
if str(exc) != "unsupported_command":
_cprint(f" /{name}: {exc}")
return True
reply = {"type": "unsupported"}
except GatewayClientError as exc:
_cprint(f" /{name}: {exc}")
return True
if reply is STOPPED:
return True
reply = reply or {}
if reply.get("type", "exec") != "exec": # it lost the plugin since lookup: a refusal or skill reply
if _dropped(cli, connection, name):
return GONE
_cprint(_GONE_LINE.format(name))
return True
output = str(reply.get("output") or "")
if output:
_cprint(output)
return True
def _dropped(cli, connection, name):
"""Whether the gateway's catalog, read again with the cached copy dropped, no longer lists
``name`` (a failed read: not known, so False)."""
cli._gateway_plugin_commands = None
try:
return name not in _read(cli, connection)
except GatewayClientError:
return False
def report_gone(name, *known):
"""Print that ``/name`` is no longer a plugin command, unless one of the built-in commands or a
``known`` skill or bundle name starts with it (then prefix expansion decides); True when printed."""
from hermes_cli.commands import COMMANDS
if any(key.startswith("/" + name) for group in (COMMANDS, *known) for key in group):
return False
from cli import _cprint
_cprint(_GONE_LINE.format(name))
return True
def observe(cli, name, arg, *, runs=True):
"""Tell the gateway about a recognized command this process runs itself (``command.observe``), so
``pre_command`` fires there, in the session's profile, and never here; False off the gateway (main's
in-process hook applies). A command that ``runs`` nothing here (a refusal) is not reported. The
gateway replies before any plugin runs. One older than this CLI (no such method) gets one printed
line, and is not asked again on that connection life: local commands then reach no ``pre_command``
observer, and this process still fires none itself."""
from hermes_cli.gateway_side import connection_for
connection = connection_for(cli)
if connection is None:
return False
if not runs:
return True
epoch = getattr(connection, "epoch", None)
if getattr(cli, "_observe_unsupported", None) == (connection, epoch):
return True
from hermes_cli.gateway_client import GatewayRPCError
try:
connection.call("command.observe", session_id=cli.session_id, name=name, arg=arg)
except GatewayRPCError as exc:
if exc.code != -32601 and str(exc) != "unknown_method":
logger.debug("command.observe /%s refused: %s", name, exc)
return True
cli._observe_unsupported = (connection, epoch)
if not getattr(cli, "_observe_notice_shown", False):
cli._observe_notice_shown = True
from cli import _cprint
_cprint(" This gateway predates this CLI: plugin pre_command hooks don't see the commands the CLI "
"runs itself until it restarts.")
except GatewayClientError as exc:
logger.debug("command.observe /%s not delivered: %s", name, exc)
return True
def loaded(cli):
"""``{name: row}`` of the plugins the gateway loaded (tool/hook/command counts, load error) for
``/plugins``, or None off the gateway. A gateway without ``plugins.list`` on this socket (older
than this CLI) or one that can't answer gets one printed line and ``{}``: the listing then shows
no load details, and this process never loads plugins to fill them in."""
from hermes_cli.gateway_side import connection_for
connection = connection_for(cli)
if connection is None:
return None
from cli import _cprint
from hermes_cli.gateway_client import GatewayRPCError
try:
rows = (connection.call("plugins.list") or {}).get("plugins") or []
except GatewayRPCError as exc:
older = exc.code == -32601 or str(exc) == "unknown_method"
_cprint(" This gateway doesn't report its loaded plugins (it predates this CLI); restart it for load details."
if older else f" The gateway's plugin list is unavailable ({exc}).")
return {}
except GatewayClientError as exc:
_cprint(f" The gateway's plugin list is unavailable ({exc}).")
return {}
return {row["name"]: row for row in rows if isinstance(row, dict) and isinstance(row.get("name"), str)}