| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385 |
- """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)}
|