gateway_plugin_commands.py 19 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385
  1. """Plugin slash commands of the classic CLI on the shared gateway (``slash.exec``).
  2. On main a plugin's ``/command`` ran in this process. Rewired, the plugin's hooks, tools and MCP servers
  3. live in the gateway, so its command runs there too (``gateway/session_commands.py``, the messaging
  4. gateway's own plugin dispatch): ``ctx.call_mcp`` reaches the servers the gateway connected, and this
  5. process never imports the plugin to run it. The names come from the gateway's ``commands.catalog``,
  6. read once per session and gateway life (``/new``, resume and a redial read again) and again once when
  7. a typed name misses, so a plugin the gateway enabled since still dispatches; a cached name a plugin
  8. reload dropped since is re-read once when the gateway refuses it, then dispatched again (:data:`GONE`).
  9. A catalog whose ``plugin_discovery_error`` is set lists no plugins because the gateway could not load
  10. them, not because there are none: it is treated as a failed read and never cached. Off the gateway
  11. (tests, the TUI slash worker's shadow CLI) main's dispatch applies.
  12. """
  13. from __future__ import annotations
  14. import logging
  15. import threading
  16. from hermes_cli.gateway_client import GatewayClientError
  17. logger = logging.getLogger(__name__)
  18. _CATEGORY = "Plugin commands" # tui_gateway/command_discovery.py
  19. GONE = object() # run(): the gateway no longer has the command; the caller dispatches the name again
  20. STOPPED = object() # call_unbounded(): Ctrl+C stopped the wait (the stopped line is printed)
  21. _GONE_LINE = " /{}: the gateway no longer has this plugin command; nothing was run."
  22. _CHOICE_POLL_S = 0.1 # how often a running command's clarify requests are looked for
  23. _STOPPED_LINE = " /{}: stopped waiting. The command keeps running in the gateway and its reply will not be shown."
  24. class CatalogUnavailable(Exception):
  25. """The gateway's command list could not be read (already printed): run nothing for this input."""
  26. def _boundary(cli, connection):
  27. return connection, getattr(connection, "epoch", None), getattr(cli, "session_id", None)
  28. def _read(cli, connection):
  29. """Fetch the catalog's plugin commands and cache them for the session and gateway life that served
  30. them (raises GatewayClientError, also when the gateway reports its plugin discovery failed). The
  31. result is published only if neither moved during the call: a reply from epoch E that arrives after
  32. a concurrent redial is never relabelled E+1 (``call_tagged``)."""
  33. session = getattr(cli, "session_id", None)
  34. catalog, epoch = _catalog(cli, connection, session)
  35. catalog = catalog or {}
  36. if catalog.get("plugin_discovery_error"): # absent on older gateways: today's behaviour
  37. raise GatewayClientError(f"plugin command discovery failed: {catalog['plugin_discovery_error']}")
  38. listed = catalog.get("plugin_commands")
  39. if isinstance(listed, dict): # every plugin command, also one a display row (Ink's /logs) hides
  40. found = {str(name).lstrip("/"): str(desc or "") for name, desc in listed.items()}
  41. else: # older gateways: the display category
  42. found = {}
  43. for category in catalog.get("categories") or []:
  44. if isinstance(category, dict) and category.get("name") == _CATEGORY:
  45. for row in category.get("pairs") or []:
  46. if isinstance(row, (list, tuple)) and len(row) == 2 and isinstance(row[0], str):
  47. found[row[0].lstrip("/")] = str(row[1] or "")
  48. # The session's skill commands as the gateway resolved them (its plugin skills included): /help,
  49. # completion and dispatch read these, so this process never scans plugin skills to list them.
  50. descriptions = {row[0]: str(row[1] or "") for row in catalog.get("pairs") or []
  51. if isinstance(row, (list, tuple)) and len(row) == 2 and isinstance(row[0], str)}
  52. skills = {key: {"name": key.lstrip("/"), "description": descriptions.get(key) or "Skill"}
  53. for key in catalog.get("skills") or {} if isinstance(key, str)}
  54. served = (connection, epoch, session)
  55. if _boundary(cli, connection) == served:
  56. cli._gateway_plugin_commands = (served, found)
  57. cli._gateway_skills = (served, skills, str(catalog.get("warning") or ""))
  58. return found
  59. def _catalog(cli, connection, session):
  60. """``(commands.catalog, epoch)`` for the open gateway session, so its skills come from the session's
  61. folder (its trusted project skills), not the gateway's. A gateway older than this CLI refuses the
  62. ``session_id`` (``invalid_params``): it is asked again without it, as before."""
  63. from hermes_cli.gateway_client import GatewayRPCError
  64. if session and getattr(cli, "_gateway_session_open", False):
  65. try:
  66. return connection.call_tagged("commands.catalog", session_id=session)
  67. except GatewayRPCError as exc:
  68. if str(exc) != "invalid_params":
  69. raise
  70. return connection.call_tagged("commands.catalog")
  71. def invalidate(cli):
  72. """Drop ``cli``'s copy of the gateway's catalog after a skill rescan (``/reload-skills``, ``/skills
  73. install``): the next read asks the gateway again."""
  74. cli._gateway_plugin_commands = cli._gateway_skills = None
  75. def _hung_up(connection):
  76. """A closed connection keeps its epoch until the next call redials, maybe to another life: no
  77. cache it labelled is served."""
  78. return getattr(connection, "closed", False)
  79. def _cached(cli, connection):
  80. if _hung_up(connection):
  81. return None
  82. boundary, found = getattr(cli, "_gateway_plugin_commands", None) or (None, None)
  83. return found if boundary == _boundary(cli, connection) else None
  84. def skills(cli, *, notes=False):
  85. """``{"/key": {name, description}}`` of the session's skill commands from the gateway's catalog
  86. (``notes``: its one-line notice instead, e.g. skills a built-in command shadows), or None off the
  87. gateway. A failed read is printed once per input and lists none; nothing is scanned here."""
  88. from hermes_cli.gateway_side import connection_for
  89. connection = connection_for(cli)
  90. if connection is None:
  91. return None
  92. boundary, found, warning = getattr(cli, "_gateway_skills", None) or (None, None, "")
  93. if _hung_up(connection) or boundary != _boundary(cli, connection):
  94. try:
  95. _read(cli, connection)
  96. except GatewayClientError as exc:
  97. logger.debug("commands.catalog unavailable: %s", exc)
  98. return "" if notes else {}
  99. _seen, found, warning = getattr(cli, "_gateway_skills", None) or (None, {}, "")
  100. return warning if notes else found
  101. def skill_notes(cli):
  102. """``/help skills`` notes (skills a built-in command shadows): the gateway's notice on its session,
  103. else this process's own scan."""
  104. notice = skills(cli, notes=True)
  105. if notice is not None:
  106. return [notice] if notice else []
  107. from agent.skill_commands import skill_command_collision_note
  108. from tools.skills_tool import find_all_skills
  109. return list(filter(None, (skill_command_collision_note(s["name"]) for s in find_all_skills())))
  110. def run_skill(cli, base_cmd, rest):
  111. """``/skill ...`` on the gateway session: the gateway resolves and loads the skill (its plugin
  112. skills and stacked skills too) and returns the message, which is queued as main queued it; True
  113. when answered there (False off the gateway: main's local load)."""
  114. from hermes_cli.gateway_side import connection_for
  115. connection = connection_for(cli)
  116. if connection is None:
  117. return False
  118. from agent.i18n import t
  119. from cli import _cprint
  120. command = base_cmd.lstrip("/") + (" " + rest if rest else "")
  121. try:
  122. reply = connection.call("slash.exec", session_id=cli.session_id, command=command) or {}
  123. except GatewayClientError as exc:
  124. _cprint(f" {base_cmd}: {exc}")
  125. return True
  126. if reply.get("type") == "skill" and reply.get("message"):
  127. cli._queue_loaded_skills(reply["message"], t("cli.skills.loading_skill", name=reply.get("name") or command), None)
  128. if reply.get("notice") or reply.get("output"):
  129. _cprint(f" {reply.get('notice') or reply.get('output')}")
  130. return True
  131. def toolsets(cli):
  132. """``([(key, label, description)], {portable MCP server})`` the gateway's plugins provide for this
  133. profile (``plugins.list``), or None off the gateway (this process's own registry applies). An older
  134. gateway or a failed read gives none, never a local scan. Read once per gateway life."""
  135. from hermes_cli.gateway_side import connection_for
  136. connection = connection_for(cli)
  137. if connection is None:
  138. return None
  139. boundary = (connection, getattr(connection, "epoch", None))
  140. cached = getattr(cli, "_gateway_plugin_toolsets", None)
  141. if cached and cached[0] == boundary and not _hung_up(connection):
  142. return cached[1]
  143. try:
  144. reply = connection.call("plugins.list") or {}
  145. except GatewayClientError as exc:
  146. logger.debug("plugins.list unavailable: %s", exc)
  147. return [], set()
  148. rows = [(str(r.get("key")), str(r.get("label") or r.get("key")), str(r.get("description") or ""))
  149. for r in reply.get("toolsets") or [] if isinstance(r, dict) and isinstance(r.get("key"), str)]
  150. found = (rows, {str(n) for n in reply.get("portable_mcp_servers") or [] if isinstance(n, str)})
  151. cli._gateway_plugin_toolsets = (boundary, found)
  152. return found
  153. def names(cli):
  154. """``{name: description}`` of the gateway's plugin commands for completion, or None off the
  155. gateway. A failed read degrades quietly to none; dispatch uses :func:`lookup`."""
  156. from hermes_cli.gateway_side import connection_for
  157. connection = connection_for(cli)
  158. if connection is None:
  159. return None
  160. found = _cached(cli, connection)
  161. if found is None:
  162. try:
  163. found = _read(cli, connection)
  164. except GatewayClientError:
  165. return {} # not cached: the next read asks again
  166. return found
  167. def lookup(cli, name):
  168. """Whether ``/name`` is one of the gateway's plugin commands; None off the gateway. A name the
  169. cached list lacks re-reads it once. A failed read is not evidence the name is no plugin: it is
  170. printed and :class:`CatalogUnavailable` raised, so no skill, bundle or expansion stands in."""
  171. from hermes_cli.gateway_side import connection_for
  172. connection = connection_for(cli)
  173. if connection is None:
  174. return None
  175. found = _cached(cli, connection)
  176. if found is not None and name in found:
  177. return True
  178. try:
  179. return name in _read(cli, connection)
  180. except GatewayClientError as exc:
  181. from cli import _cprint
  182. _cprint(f" /{name}: the gateway's command list is unavailable ({exc}); nothing was run.")
  183. raise CatalogUnavailable(name) from exc
  184. def call_unbounded(cli, connection, name, command):
  185. """``slash.exec`` of *command* with no answer deadline, on a socket of its own so the session's prompts
  186. and interrupts never queue behind it (GatewayConnection.call_until). Ctrl+C stops waiting: the stopped
  187. line is printed and :data:`STOPPED` returned (a KeyboardInterrupt still propagates after it)."""
  188. from cli import _cprint
  189. from hermes_cli.gateway_connection import CallStopped
  190. wake = cli._gateway_command_wait = threading.Event() # set by Ctrl+C (cli_tui_mixin)
  191. from agent.memory_provider import spawn_context_thread
  192. answering: list = [] # the clarify request id the panel is answering, while it is open
  193. spawn_context_thread(_answer_choices, args=(cli, connection, wake, answering), name="hermes-command-choices").start()
  194. try:
  195. return connection.call_until("slash.exec", wake, session_id=cli.session_id, command=command)
  196. except (CallStopped, KeyboardInterrupt) as exc:
  197. _cprint(_STOPPED_LINE.format(name))
  198. if isinstance(exc, KeyboardInterrupt):
  199. raise
  200. return STOPPED
  201. finally:
  202. cli._gateway_command_wait = None
  203. if answering: # the command is over: its picker must not keep the input
  204. cli._withdraw_gateway_modal("clarify")
  205. def _answer_choices(cli, connection, wake, answering):
  206. """While the command runs, answer the ``clarify`` server requests its handler sends to this session
  207. (``ctx.ask_choice``, ``gateway/plugin_command_choice.py``) with the CLI's clarify panel. No turn
  208. pump reads the session's frames between turns, so they are taken here; every other frame stays
  209. queued, in order, for the turn that owns it."""
  210. from hermes_cli.gateway_agent import clarify_reply
  211. events, state = connection.events, connection.state(cli.session_id)
  212. def withdrawn(payload):
  213. # ``request.cancel`` for the request the panel is answering (another viewer picked, or the gateway's
  214. # wait ended): close the panel, as GatewayAgent does for a turn's modal.
  215. if answering and payload.get("id") == answering[0]:
  216. cli._withdraw_gateway_modal("clarify")
  217. state.request_listeners.append(withdrawn)
  218. try:
  219. while not wake.wait(_CHOICE_POLL_S):
  220. with events.mutex:
  221. asks = [frame for frame in events.queue if isinstance(frame, dict) and frame.get("method") == "clarify"
  222. and "id" in frame and (frame.get("params") or {}).get("session_id") == cli.session_id]
  223. for frame in asks:
  224. events.queue.remove(frame)
  225. for frame in asks:
  226. answering[:] = [frame["id"]]
  227. try:
  228. reply = clarify_reply(cli._clarify_callback, frame["params"])
  229. finally:
  230. answering.clear()
  231. connection.reply(frame["id"], reply)
  232. finally:
  233. state.request_listeners.remove(withdrawn)
  234. def run(cli, name, arg):
  235. """True when the gateway answered ``/name arg`` (the local handler must not run); :data:`GONE`
  236. when it no longer has that plugin command and a fresh catalog read agrees (a plugin reload, e.g.
  237. ``hermes plugins disable``, dropped it in this session and gateway life, which no cache boundary
  238. sees): nothing ran, and the caller dispatches the name again (bundle, skill, prefix)."""
  239. from hermes_cli.gateway_side import connection_for
  240. connection = connection_for(cli)
  241. if connection is None:
  242. return False
  243. from cli import _cprint
  244. from hermes_cli.gateway_client import GatewayRPCError
  245. # No answer deadline: main's CLI waited for the handler, which may wait minutes (ctx.call_mcp).
  246. try:
  247. reply = call_unbounded(cli, connection, name, name + (" " + arg if arg else ""))
  248. except GatewayRPCError as exc:
  249. if str(exc) != "unsupported_command":
  250. _cprint(f" /{name}: {exc}")
  251. return True
  252. reply = {"type": "unsupported"}
  253. except GatewayClientError as exc:
  254. _cprint(f" /{name}: {exc}")
  255. return True
  256. if reply is STOPPED:
  257. return True
  258. reply = reply or {}
  259. if reply.get("type", "exec") != "exec": # it lost the plugin since lookup: a refusal or skill reply
  260. if _dropped(cli, connection, name):
  261. return GONE
  262. _cprint(_GONE_LINE.format(name))
  263. return True
  264. output = str(reply.get("output") or "")
  265. if output:
  266. _cprint(output)
  267. return True
  268. def _dropped(cli, connection, name):
  269. """Whether the gateway's catalog, read again with the cached copy dropped, no longer lists
  270. ``name`` (a failed read: not known, so False)."""
  271. cli._gateway_plugin_commands = None
  272. try:
  273. return name not in _read(cli, connection)
  274. except GatewayClientError:
  275. return False
  276. def report_gone(name, *known):
  277. """Print that ``/name`` is no longer a plugin command, unless one of the built-in commands or a
  278. ``known`` skill or bundle name starts with it (then prefix expansion decides); True when printed."""
  279. from hermes_cli.commands import COMMANDS
  280. if any(key.startswith("/" + name) for group in (COMMANDS, *known) for key in group):
  281. return False
  282. from cli import _cprint
  283. _cprint(_GONE_LINE.format(name))
  284. return True
  285. def observe(cli, name, arg, *, runs=True):
  286. """Tell the gateway about a recognized command this process runs itself (``command.observe``), so
  287. ``pre_command`` fires there, in the session's profile, and never here; False off the gateway (main's
  288. in-process hook applies). A command that ``runs`` nothing here (a refusal) is not reported. The
  289. gateway replies before any plugin runs. One older than this CLI (no such method) gets one printed
  290. line, and is not asked again on that connection life: local commands then reach no ``pre_command``
  291. observer, and this process still fires none itself."""
  292. from hermes_cli.gateway_side import connection_for
  293. connection = connection_for(cli)
  294. if connection is None:
  295. return False
  296. if not runs:
  297. return True
  298. epoch = getattr(connection, "epoch", None)
  299. if getattr(cli, "_observe_unsupported", None) == (connection, epoch):
  300. return True
  301. from hermes_cli.gateway_client import GatewayRPCError
  302. try:
  303. connection.call("command.observe", session_id=cli.session_id, name=name, arg=arg)
  304. except GatewayRPCError as exc:
  305. if exc.code != -32601 and str(exc) != "unknown_method":
  306. logger.debug("command.observe /%s refused: %s", name, exc)
  307. return True
  308. cli._observe_unsupported = (connection, epoch)
  309. if not getattr(cli, "_observe_notice_shown", False):
  310. cli._observe_notice_shown = True
  311. from cli import _cprint
  312. _cprint(" This gateway predates this CLI: plugin pre_command hooks don't see the commands the CLI "
  313. "runs itself until it restarts.")
  314. except GatewayClientError as exc:
  315. logger.debug("command.observe /%s not delivered: %s", name, exc)
  316. return True
  317. def loaded(cli):
  318. """``{name: row}`` of the plugins the gateway loaded (tool/hook/command counts, load error) for
  319. ``/plugins``, or None off the gateway. A gateway without ``plugins.list`` on this socket (older
  320. than this CLI) or one that can't answer gets one printed line and ``{}``: the listing then shows
  321. no load details, and this process never loads plugins to fill them in."""
  322. from hermes_cli.gateway_side import connection_for
  323. connection = connection_for(cli)
  324. if connection is None:
  325. return None
  326. from cli import _cprint
  327. from hermes_cli.gateway_client import GatewayRPCError
  328. try:
  329. rows = (connection.call("plugins.list") or {}).get("plugins") or []
  330. except GatewayRPCError as exc:
  331. older = exc.code == -32601 or str(exc) == "unknown_method"
  332. _cprint(" This gateway doesn't report its loaded plugins (it predates this CLI); restart it for load details."
  333. if older else f" The gateway's plugin list is unavailable ({exc}).")
  334. return {}
  335. except GatewayClientError as exc:
  336. _cprint(f" The gateway's plugin list is unavailable ({exc}).")
  337. return {}
  338. return {row["name"]: row for row in rows if isinstance(row, dict) and isinstance(row.get("name"), str)}