| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213 |
- """Application-backed MCP liveness parsing and user-facing status descriptions."""
- from __future__ import annotations
- import logging
- from dataclasses import dataclass, replace
- from typing import Any, Literal
- from hermes_platform import declaration
- from hermes_platform.host import facts
- from hermes_platform.resolver.app import AppDef, AppResolver
- from hermes_platform.resolver.availability import Availability, availability
- from hermes_platform.resolver.base import Effort
- from hermes_platform.resolver.core import CheckState
- logger = logging.getLogger(__name__)
- LivenessKind = Literal["static", "server_json", "interactive_session"]
- LivenessState = Literal[
- "app_not_running",
- "hermes_not_connected",
- "endpoint_unavailable",
- "no_interactive_session",
- "version_too_old",
- "missing_app",
- "unsupported_gpu",
- ]
- Retry = Literal["after_user_action", "never_here"]
- @dataclass(frozen=True)
- class Liveness:
- kind: LivenessKind
- path: str = ""
- url_field: str = "http"
- token_field: str = "token"
- pid_field: str = "pid"
- def app_definition(self, definition: AppDef) -> AppDef:
- if self.kind != "server_json":
- return definition
- return replace(
- definition,
- liveness_kind="server_json",
- liveness_path=self.path,
- liveness_pid_key=self.pid_field,
- liveness_url_key=self.url_field,
- liveness_token_key=self.token_field,
- )
- @dataclass(frozen=True)
- class Status:
- state: LivenessState
- availability: Availability
- liveness: Liveness
- user_action: str
- retry: Retry
- def parse_liveness(raw: Any) -> Liveness:
- """Parse one portable-plugin liveness declaration."""
- if not isinstance(raw, dict):
- raise ValueError("liveness must be an object")
- kind = raw.get("kind")
- if kind == "static":
- if set(raw) != {"kind"}:
- raise ValueError("static liveness only accepts 'kind'")
- return Liveness("static")
- if kind == "interactive_session":
- if set(raw) != {"kind"}:
- raise ValueError("interactive_session liveness only accepts 'kind'")
- return Liveness("interactive_session")
- if kind != "server_json":
- raise ValueError(f"unknown liveness kind: {kind!r}")
- if set(raw) - {"kind", "path", "fields"}:
- raise ValueError("server_json liveness has unknown fields")
- path = raw.get("path")
- fields = {"url": "http", "token": "token", "pid": "pid", **(raw.get("fields") or {})}
- if not isinstance(path, str) or not path.strip():
- raise ValueError("server_json liveness requires a non-empty path")
- if set(fields) != {"url", "token", "pid"}:
- raise ValueError("server_json liveness fields may only override url, token, and pid")
- if any(not isinstance(value, str) or not value.strip() for value in fields.values()):
- raise ValueError("server_json liveness field names must be non-empty strings")
- return Liveness(
- "server_json",
- path=path.strip(),
- url_field=fields["url"].strip(),
- token_field=fields["token"].strip(),
- pid_field=fields["pid"].strip(),
- )
- def liveness_for(server_name: str) -> Liveness:
- """Return a server's registered liveness declaration, defaulting to static."""
- try:
- from hermes_cli.agent_plugins import liveness_for as registered_liveness
- except ImportError:
- return Liveness("static")
- raw = registered_liveness(server_name)
- if raw is None:
- return Liveness("static")
- try:
- return parse_liveness(raw)
- except ValueError as exc:
- logger.warning("MCP server '%s' has an invalid liveness declaration (%s); treating it as static", server_name, exc)
- return Liveness("static")
- def _action(state: LivenessState, app_name: str, gpu_label: str) -> tuple[str, Retry]:
- actions: dict[LivenessState, tuple[str, Retry]] = {
- "app_not_running": (f"Start {app_name}, then try again.", "after_user_action"),
- "hermes_not_connected": (f"Reconnect {app_name} in Hermes, then try again.", "after_user_action"),
- "endpoint_unavailable": (f"Open {app_name} and enable its local connection, then try again.", "after_user_action"),
- "no_interactive_session": (f"Open an interactive desktop session and start {app_name}, then try again.", "never_here"),
- "version_too_old": (f"Update {app_name}, then try again.", "after_user_action"),
- "missing_app": (f"Install {app_name}, then try again.", "after_user_action"),
- "unsupported_gpu": (f"Use {app_name} on a machine with {gpu_label}.", "never_here"),
- }
- return actions[state]
- _AVAILABILITY_PROBLEMS: dict[str, LivenessState] = {
- "missing_app": "missing_app",
- "unsupported_os": "missing_app",
- "unsupported_gpu": "unsupported_gpu",
- "version_too_old": "version_too_old",
- }
- def availability_problem(available: Availability) -> LivenessState | None:
- """The unavailable state an install-time availability verdict maps to; None when it is not a problem."""
- return _AVAILABILITY_PROBLEMS.get(available.state)
- def status(server_name: str) -> Status | None:
- """Return the current unavailable state for a registered declaration."""
- decl = declaration.lookup(server_name)
- if decl is None:
- return None
- available = availability(decl)
- live = liveness_for(server_name)
- problem = availability_problem(available)
- if problem is not None:
- state: LivenessState = problem
- elif live.kind == "interactive_session" and not facts.interactive_session():
- state = "no_interactive_session"
- elif live.kind == "server_json":
- definition = decl.app_for(facts.os_family())
- if definition is None:
- state = "missing_app"
- else:
- probe = AppResolver(live.app_definition(definition)).probe(
- AppResolver(live.app_definition(definition)).locate(), effort=Effort.LOCAL
- )
- if probe.running.value is not True:
- state = "app_not_running"
- elif probe.endpoint.state is not CheckState.PRESENT:
- state = "endpoint_unavailable"
- else:
- # The app runs and its endpoint answers: the only thing missing is Hermes' own
- # MCP connection to it. Telling the user to "start" an app that IS running is
- # the wrong instruction (#119975).
- state = "hermes_not_connected"
- else:
- # static / unknown liveness kinds cannot observe the app, so they cannot conclude it
- # is not running; the honest answer is that Hermes is not connected (#119975).
- state = "hermes_not_connected"
- action, retry = _action(state, decl.name, declaration.gpu_label(decl.required_gpu))
- return Status(state, available, live, action, retry)
- def describe(decl: declaration.Declaration, available: Availability, liveness_state: LivenessState,
- display_name: str | None = None) -> str:
- """Compose one unavailable-state sentence with one user action.
- ``display_name`` overrides the declaration's slug when the caller knows the plugin's
- catalog/manifest title — the Plugins tab does, and a raw slug reads like an error code."""
- app_name = display_name or decl.name
- gpu = declaration.gpu_label(decl.required_gpu)
- action, _retry = _action(liveness_state, app_name, gpu)
- if liveness_state == "missing_app" and available.state == "unsupported_os":
- reason = f"{app_name} is not supported on this operating system."
- action = "Use a supported operating system."
- elif liveness_state == "missing_app":
- reason = f"{app_name} is not installed."
- if available.min_version:
- action = f"Install {app_name} {available.min_version} or newer, then try again."
- elif liveness_state == "unsupported_gpu":
- reason = f"{app_name} needs {gpu}; none was found on this machine."
- elif liveness_state == "version_too_old":
- found = f" version {available.version}" if available.version else ""
- minimum = f"; version {available.min_version} or newer is required" if available.min_version else ""
- reason = f"{app_name}{found} is too old{minimum}."
- elif liveness_state == "no_interactive_session":
- reason = f"{app_name} needs an interactive desktop session."
- elif liveness_state == "endpoint_unavailable":
- reason = f"{app_name}'s local endpoint is unavailable."
- elif liveness_state == "hermes_not_connected":
- reason = f"{app_name}'s MCP connection is missing."
- else:
- reason = f"{app_name} is not running."
- return f"{reason} {action}"
- def unavailable_details(server_name: str) -> tuple[declaration.Declaration, Status, str] | None:
- """Return declaration, structured state, and its composed sentence."""
- decl = declaration.lookup(server_name)
- current = status(server_name)
- if decl is None or current is None:
- return None
- return decl, current, describe(decl, current.availability, current.state)
|