mcp_liveness.py 8.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213
  1. """Application-backed MCP liveness parsing and user-facing status descriptions."""
  2. from __future__ import annotations
  3. import logging
  4. from dataclasses import dataclass, replace
  5. from typing import Any, Literal
  6. from hermes_platform import declaration
  7. from hermes_platform.host import facts
  8. from hermes_platform.resolver.app import AppDef, AppResolver
  9. from hermes_platform.resolver.availability import Availability, availability
  10. from hermes_platform.resolver.base import Effort
  11. from hermes_platform.resolver.core import CheckState
  12. logger = logging.getLogger(__name__)
  13. LivenessKind = Literal["static", "server_json", "interactive_session"]
  14. LivenessState = Literal[
  15. "app_not_running",
  16. "hermes_not_connected",
  17. "endpoint_unavailable",
  18. "no_interactive_session",
  19. "version_too_old",
  20. "missing_app",
  21. "unsupported_gpu",
  22. ]
  23. Retry = Literal["after_user_action", "never_here"]
  24. @dataclass(frozen=True)
  25. class Liveness:
  26. kind: LivenessKind
  27. path: str = ""
  28. url_field: str = "http"
  29. token_field: str = "token"
  30. pid_field: str = "pid"
  31. def app_definition(self, definition: AppDef) -> AppDef:
  32. if self.kind != "server_json":
  33. return definition
  34. return replace(
  35. definition,
  36. liveness_kind="server_json",
  37. liveness_path=self.path,
  38. liveness_pid_key=self.pid_field,
  39. liveness_url_key=self.url_field,
  40. liveness_token_key=self.token_field,
  41. )
  42. @dataclass(frozen=True)
  43. class Status:
  44. state: LivenessState
  45. availability: Availability
  46. liveness: Liveness
  47. user_action: str
  48. retry: Retry
  49. def parse_liveness(raw: Any) -> Liveness:
  50. """Parse one portable-plugin liveness declaration."""
  51. if not isinstance(raw, dict):
  52. raise ValueError("liveness must be an object")
  53. kind = raw.get("kind")
  54. if kind == "static":
  55. if set(raw) != {"kind"}:
  56. raise ValueError("static liveness only accepts 'kind'")
  57. return Liveness("static")
  58. if kind == "interactive_session":
  59. if set(raw) != {"kind"}:
  60. raise ValueError("interactive_session liveness only accepts 'kind'")
  61. return Liveness("interactive_session")
  62. if kind != "server_json":
  63. raise ValueError(f"unknown liveness kind: {kind!r}")
  64. if set(raw) - {"kind", "path", "fields"}:
  65. raise ValueError("server_json liveness has unknown fields")
  66. path = raw.get("path")
  67. fields = {"url": "http", "token": "token", "pid": "pid", **(raw.get("fields") or {})}
  68. if not isinstance(path, str) or not path.strip():
  69. raise ValueError("server_json liveness requires a non-empty path")
  70. if set(fields) != {"url", "token", "pid"}:
  71. raise ValueError("server_json liveness fields may only override url, token, and pid")
  72. if any(not isinstance(value, str) or not value.strip() for value in fields.values()):
  73. raise ValueError("server_json liveness field names must be non-empty strings")
  74. return Liveness(
  75. "server_json",
  76. path=path.strip(),
  77. url_field=fields["url"].strip(),
  78. token_field=fields["token"].strip(),
  79. pid_field=fields["pid"].strip(),
  80. )
  81. def liveness_for(server_name: str) -> Liveness:
  82. """Return a server's registered liveness declaration, defaulting to static."""
  83. try:
  84. from hermes_cli.agent_plugins import liveness_for as registered_liveness
  85. except ImportError:
  86. return Liveness("static")
  87. raw = registered_liveness(server_name)
  88. if raw is None:
  89. return Liveness("static")
  90. try:
  91. return parse_liveness(raw)
  92. except ValueError as exc:
  93. logger.warning("MCP server '%s' has an invalid liveness declaration (%s); treating it as static", server_name, exc)
  94. return Liveness("static")
  95. def _action(state: LivenessState, app_name: str, gpu_label: str) -> tuple[str, Retry]:
  96. actions: dict[LivenessState, tuple[str, Retry]] = {
  97. "app_not_running": (f"Start {app_name}, then try again.", "after_user_action"),
  98. "hermes_not_connected": (f"Reconnect {app_name} in Hermes, then try again.", "after_user_action"),
  99. "endpoint_unavailable": (f"Open {app_name} and enable its local connection, then try again.", "after_user_action"),
  100. "no_interactive_session": (f"Open an interactive desktop session and start {app_name}, then try again.", "never_here"),
  101. "version_too_old": (f"Update {app_name}, then try again.", "after_user_action"),
  102. "missing_app": (f"Install {app_name}, then try again.", "after_user_action"),
  103. "unsupported_gpu": (f"Use {app_name} on a machine with {gpu_label}.", "never_here"),
  104. }
  105. return actions[state]
  106. _AVAILABILITY_PROBLEMS: dict[str, LivenessState] = {
  107. "missing_app": "missing_app",
  108. "unsupported_os": "missing_app",
  109. "unsupported_gpu": "unsupported_gpu",
  110. "version_too_old": "version_too_old",
  111. }
  112. def availability_problem(available: Availability) -> LivenessState | None:
  113. """The unavailable state an install-time availability verdict maps to; None when it is not a problem."""
  114. return _AVAILABILITY_PROBLEMS.get(available.state)
  115. def status(server_name: str) -> Status | None:
  116. """Return the current unavailable state for a registered declaration."""
  117. decl = declaration.lookup(server_name)
  118. if decl is None:
  119. return None
  120. available = availability(decl)
  121. live = liveness_for(server_name)
  122. problem = availability_problem(available)
  123. if problem is not None:
  124. state: LivenessState = problem
  125. elif live.kind == "interactive_session" and not facts.interactive_session():
  126. state = "no_interactive_session"
  127. elif live.kind == "server_json":
  128. definition = decl.app_for(facts.os_family())
  129. if definition is None:
  130. state = "missing_app"
  131. else:
  132. probe = AppResolver(live.app_definition(definition)).probe(
  133. AppResolver(live.app_definition(definition)).locate(), effort=Effort.LOCAL
  134. )
  135. if probe.running.value is not True:
  136. state = "app_not_running"
  137. elif probe.endpoint.state is not CheckState.PRESENT:
  138. state = "endpoint_unavailable"
  139. else:
  140. # The app runs and its endpoint answers: the only thing missing is Hermes' own
  141. # MCP connection to it. Telling the user to "start" an app that IS running is
  142. # the wrong instruction (#119975).
  143. state = "hermes_not_connected"
  144. else:
  145. # static / unknown liveness kinds cannot observe the app, so they cannot conclude it
  146. # is not running; the honest answer is that Hermes is not connected (#119975).
  147. state = "hermes_not_connected"
  148. action, retry = _action(state, decl.name, declaration.gpu_label(decl.required_gpu))
  149. return Status(state, available, live, action, retry)
  150. def describe(decl: declaration.Declaration, available: Availability, liveness_state: LivenessState,
  151. display_name: str | None = None) -> str:
  152. """Compose one unavailable-state sentence with one user action.
  153. ``display_name`` overrides the declaration's slug when the caller knows the plugin's
  154. catalog/manifest title — the Plugins tab does, and a raw slug reads like an error code."""
  155. app_name = display_name or decl.name
  156. gpu = declaration.gpu_label(decl.required_gpu)
  157. action, _retry = _action(liveness_state, app_name, gpu)
  158. if liveness_state == "missing_app" and available.state == "unsupported_os":
  159. reason = f"{app_name} is not supported on this operating system."
  160. action = "Use a supported operating system."
  161. elif liveness_state == "missing_app":
  162. reason = f"{app_name} is not installed."
  163. if available.min_version:
  164. action = f"Install {app_name} {available.min_version} or newer, then try again."
  165. elif liveness_state == "unsupported_gpu":
  166. reason = f"{app_name} needs {gpu}; none was found on this machine."
  167. elif liveness_state == "version_too_old":
  168. found = f" version {available.version}" if available.version else ""
  169. minimum = f"; version {available.min_version} or newer is required" if available.min_version else ""
  170. reason = f"{app_name}{found} is too old{minimum}."
  171. elif liveness_state == "no_interactive_session":
  172. reason = f"{app_name} needs an interactive desktop session."
  173. elif liveness_state == "endpoint_unavailable":
  174. reason = f"{app_name}'s local endpoint is unavailable."
  175. elif liveness_state == "hermes_not_connected":
  176. reason = f"{app_name}'s MCP connection is missing."
  177. else:
  178. reason = f"{app_name} is not running."
  179. return f"{reason} {action}"
  180. def unavailable_details(server_name: str) -> tuple[declaration.Declaration, Status, str] | None:
  181. """Return declaration, structured state, and its composed sentence."""
  182. decl = declaration.lookup(server_name)
  183. current = status(server_name)
  184. if decl is None or current is None:
  185. return None
  186. return decl, current, describe(decl, current.availability, current.state)