actions.py 24 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503
  1. """Gateway restart/drain, Hermes update and background-action status dashboard routes.
  2. Extracted from ``hermes_cli.web_server``; helpers/state that tests monkeypatch on
  3. ``web_server`` stay there and are late-bound (cycle-safe).
  4. """
  5. import asyncio
  6. import contextlib
  7. import logging
  8. import re
  9. import secrets
  10. import subprocess
  11. import time
  12. from pathlib import Path
  13. from typing import Any, Dict, List, Optional
  14. from fastapi import APIRouter, HTTPException, Request
  15. from hermes_cli.config import format_docker_update_message, recommended_update_command_for_method
  16. from hermes_cli.update_contract import COMMIT_BUILD_UPDATE_MESSAGE, is_commit_build
  17. from hermes_cli.version_info import get_version_info
  18. from hermes_cli.web_deps import LateState, late
  19. from hermes_cli.web_server_gateway import _ACTION_LOG_FILES
  20. from hermes_cli.web_routers._common import http_failure
  21. _log = logging.getLogger("hermes_cli.web_server")
  22. router = APIRouter()
  23. status_router = APIRouter()
  24. # Late-bound so a test's monkeypatch on the owning module wins at call time.
  25. _dashboard_local_update_managed_externally = late("_dashboard_local_update_managed_externally", "hermes_cli.web_server_files")
  26. _spawn_gateway_restart = late("_spawn_gateway_restart")
  27. _spawn_hermes_action = late("_spawn_hermes_action", "hermes_cli.web_server_gateway")
  28. detect_install_method = late("detect_install_method", "hermes_cli.config")
  29. get_hermes_home = late("get_hermes_home", "hermes_cli.config")
  30. _config_profile_scope = late("_config_profile_scope", "hermes_cli.web_server_profiles")
  31. _ACTION_COMMANDS = LateState("_ACTION_COMMANDS", "hermes_cli.web_server_gateway")
  32. _ACTION_IDS = LateState("_ACTION_IDS", "hermes_cli.web_server_gateway")
  33. _ACTION_PROCS = LateState("_ACTION_PROCS", "hermes_cli.web_server_gateway")
  34. _ACTION_RESULTS = LateState("_ACTION_RESULTS", "hermes_cli.web_server_gateway")
  35. def _server_path(name: str) -> Path:
  36. """Live Path value (``_ACTION_LOG_DIR`` on web_server_gateway, ``PROJECT_ROOT`` on
  37. web_server; plain values are not proxied by LateState)."""
  38. import hermes_cli.web_server as ws
  39. import hermes_cli.web_server_gateway as gw
  40. return getattr(gw if name == "_ACTION_LOG_DIR" else ws, name)
  41. _ACTION_LOG_TAIL_MAX_BYTES = 256 * 1024
  42. _ACTION_LOG_TAIL_INITIAL_CHUNK_BYTES = 8 * 1024
  43. _ACTION_LOG_TAIL_MAX_CHUNK_BYTES = 64 * 1024
  44. _UPDATE_ACTION_COMPLETED_RE = re.compile(r"^=== hermes-update completed ([0-9a-f]{32}) ===$")
  45. _UPDATE_ACTION_STARTED_RE = re.compile(r"^=== hermes-update started .* ([0-9a-f]{32}) ===$")
  46. _MANAGED_EXTERNALLY_MESSAGE = "Hermes updates are managed outside this dashboard in containerized environments."
  47. # Per-kind dashboard error codes the UI keys on, by admission-refusal code.
  48. _UPDATE_REFUSAL_ERROR_CODES = {
  49. "docker": "docker_update_unsupported", "image-marker": "docker_update_unsupported",
  50. "image-marker-invalid": "docker_update_unsupported", "apt": "apt_update_required",
  51. "nix": "nix_update_unsupported",
  52. }
  53. def _finish_action(name: str, exit_code: Optional[int], pid: Optional[int]) -> None:
  54. """Record a terminal result and drop the live-process registries for ``name``."""
  55. _ACTION_RESULTS[name] = {"exit_code": exit_code, "pid": pid}
  56. for registry in (_ACTION_PROCS, _ACTION_COMMANDS, _ACTION_IDS):
  57. registry.pop(name, None)
  58. def _record_completed_action(name: str, message: str, exit_code: int = 1) -> None:
  59. """Record a non-spawned action result and write it to the action log."""
  60. log_dir = _server_path("_ACTION_LOG_DIR")
  61. log_dir.mkdir(parents=True, exist_ok=True)
  62. with open(log_dir / _ACTION_LOG_FILES[name], "ab", buffering=0) as log_file:
  63. log_file.write(f"\n=== {name} completed {time.strftime('%Y-%m-%d %H:%M:%S')} ===\n".encode())
  64. log_file.write(message.encode("utf-8", errors="replace"))
  65. if not message.endswith("\n"):
  66. log_file.write(b"\n")
  67. _finish_action(name, exit_code, None)
  68. def _tail_lines(path: Path, n: int) -> list[str]:
  69. """Return the last ``n`` lines of ``path`` without loading huge logs."""
  70. try:
  71. size = path.stat().st_size
  72. except OSError:
  73. return []
  74. if n <= 0 or size <= 0:
  75. return []
  76. min_offset = max(0, size - _ACTION_LOG_TAIL_MAX_BYTES)
  77. offset = size
  78. chunk_size = _ACTION_LOG_TAIL_INITIAL_CHUNK_BYTES
  79. newline_count = 0
  80. chunks: list[bytes] = []
  81. drop_partial_first_line = False
  82. try:
  83. with path.open("rb") as handle:
  84. while offset > min_offset and newline_count <= n:
  85. read_size = min(chunk_size, offset - min_offset)
  86. offset -= read_size
  87. handle.seek(offset)
  88. chunk = handle.read(read_size)
  89. chunks.append(chunk)
  90. newline_count += chunk.count(b"\n")
  91. chunk_size = min(chunk_size * 2, _ACTION_LOG_TAIL_MAX_CHUNK_BYTES)
  92. if offset > 0:
  93. handle.seek(offset - 1)
  94. drop_partial_first_line = handle.read(1) != b"\n"
  95. except OSError:
  96. return []
  97. lines = b"".join(reversed(chunks)).decode("utf-8", errors="replace").splitlines()
  98. if drop_partial_first_line and lines:
  99. lines = lines[1:]
  100. return lines[-n:]
  101. def _durable_completed_update_action_id(lines: list[str]) -> Optional[str]:
  102. """Latest successful update id from ``update.log`` — the durable record that survives
  103. the update restarting the dashboard (losing the in-memory ``Popen``/result registries).
  104. Only a completion marker after the latest start marker counts, so a stale success
  105. cannot mask a newer failed attempt."""
  106. last_start = last_completed = -1
  107. completed_action_id: Optional[str] = None
  108. for index, line in enumerate(lines):
  109. if line.startswith("=== hermes update started "):
  110. last_start = index
  111. match = _UPDATE_ACTION_COMPLETED_RE.fullmatch(line.strip())
  112. if match:
  113. last_completed = index
  114. completed_action_id = match.group(1)
  115. return completed_action_id if completed_action_id and last_completed > last_start else None
  116. def _latest_spawned_update_action_id(lines: list[str]) -> Optional[str]:
  117. """Action id named by the latest ``hermes-update started`` header of THIS dashboard's log."""
  118. for line in reversed(lines):
  119. if line.startswith("=== hermes-update started "):
  120. match = _UPDATE_ACTION_STARTED_RE.fullmatch(line.strip())
  121. return match.group(1) if match else None
  122. return None
  123. def _persisted_action_id(log_dir: Path, name: str) -> Optional[str]:
  124. """Action id of the latest spawn of ``name`` from its sidecar (survives the log's tail
  125. bound and rotation). A visible start header wins: a dashboard predating the sidecar wrote
  126. only the header, and the newest header IS the latest spawn."""
  127. with contextlib.suppress(OSError, UnicodeDecodeError):
  128. value = (log_dir / f"{name}.action_id").read_text(encoding="utf-8-sig").strip()
  129. return value if re.fullmatch(r"[0-9a-f]{32}", value) else None
  130. return None
  131. @router.post("/api/gateway/restart")
  132. async def restart_gateway(profile: Optional[str] = None):
  133. """Kick off a ``hermes gateway restart --interrupt`` in the background: the user-commanded force
  134. path that supersedes a drain (D6, 19b26244046), so live sessions do not refuse it."""
  135. with http_failure("Failed to spawn gateway restart", 500, "Failed to restart gateway"):
  136. proc, _reused = _spawn_gateway_restart(profile, interrupt=True)
  137. return {"ok": True, "pid": proc.pid, "name": "gateway-restart"}
  138. @router.get("/api/gateway/migrate/plan")
  139. async def gateway_migrate_plan():
  140. """Preflight for folding per-profile gateways into one multiplexer (same JSON as the CLI plan)."""
  141. from hermes_cli.gateway_migrate import build_migration_plan
  142. plan = await asyncio.to_thread(build_migration_plan)
  143. return plan.to_dict()
  144. @router.post("/api/gateway/migrate")
  145. async def gateway_migrate():
  146. """Run ``hermes gateway migrate --multiplex --yes`` detached; the CLI re-runs the preflight and
  147. refuses (exit 1 into the action log) when blocked, so the UI should gate on the plan first."""
  148. from hermes_cli.web_server_gateway import _spawn_hermes_action
  149. with http_failure("Failed to spawn gateway migrate", 500, "Failed to start gateway migration"):
  150. proc = _spawn_hermes_action(["gateway", "migrate", "--multiplex", "--yes"], "gateway-migrate")
  151. return {"ok": True, "pid": proc.pid, "name": "gateway-migrate"}
  152. @router.post("/api/gateway/drain")
  153. async def gateway_drain(request: Request):
  154. """Begin or cancel an external (NAS-driven) gateway drain.
  155. Authenticated by the non-interactive token-auth seam (the ``dashboard_auth/drain``
  156. plugin registers this path as a token route and verifies the bearer secret);
  157. without that plugin the cookie gate covers a gated bind and the legacy
  158. session-token gate a loopback bind — never unauthenticated on a network bind.
  159. Body ``{"action": "drain"|"cancel"}``. Only the ``.drain_request.json`` marker is
  160. written/removed here — the gateway's ``_drain_control_watcher`` owns the state
  161. transition (the marker IS the control channel). Idempotent on both sides;
  162. ``POST /api/gateway/restart`` is the force-override that supersedes a drain.
  163. """
  164. from gateway.drain_control import clear_drain_request, drain_requested, write_drain_request
  165. try:
  166. body = await request.json()
  167. except Exception:
  168. body = {}
  169. body = body or {}
  170. action = str(body.get("action", "drain")).strip().lower()
  171. # Attribute to the verified token principal when the token-auth seam attached one.
  172. principal = getattr(getattr(request.state, "token_principal", None), "principal", None) or "dashboard"
  173. if action == "cancel":
  174. existed = clear_drain_request()
  175. _log.info("Gateway drain CANCEL requested by %s (existed=%s)", principal, existed)
  176. return {"ok": True, "action": "cancel", "was_draining": existed}
  177. if action != "drain":
  178. raise HTTPException(status_code=400, detail=f"Unknown drain action {action!r}; expected 'drain' or 'cancel'")
  179. payload = write_drain_request(
  180. principal=str(principal), suppress_notification=bool(body.get("suppress_notification", False)),
  181. )
  182. _log.info(
  183. "Gateway drain BEGIN requested by %s (suppress_notification=%s)", principal, payload["suppress_notification"],
  184. )
  185. return {
  186. "ok": True, "action": "drain", "requested_at": payload["requested_at"],
  187. # Echo so a caller polling /api/status knows the marker is now set;
  188. # the gateway watcher flips gateway_state -> draining within ~1s.
  189. "draining": drain_requested(), "suppress_notification": payload["suppress_notification"],
  190. }
  191. def _update_refused(error: str, message: str, update_command: str) -> dict[str, Any]:
  192. _record_completed_action("hermes-update", message, exit_code=1)
  193. return {
  194. "ok": False, "pid": None, "name": "hermes-update", "error": error, "message": message,
  195. "update_command": update_command,
  196. }
  197. @router.post("/api/hermes/update")
  198. async def update_hermes():
  199. """Kick off ``hermes update`` in the background."""
  200. if is_commit_build(_server_path("PROJECT_ROOT")):
  201. return _update_refused("commit-build", COMMIT_BUILD_UPDATE_MESSAGE, "")
  202. if _dashboard_local_update_managed_externally():
  203. message = _MANAGED_EXTERNALLY_MESSAGE + " The built-in local updater is disabled here."
  204. # No runnable command exists here: the outer launcher/image owns updates.
  205. return _update_refused("dashboard_update_managed_externally", message, "")
  206. # Shared admission gate: marker-first, then the docker/nix/apt heuristics —
  207. # one decision with the CLI paths.
  208. from hermes_cli.update_contract import evaluate_update_admission, record_refusal_receipt
  209. refusal = evaluate_update_admission(_server_path("PROJECT_ROOT"))
  210. if refusal is not None:
  211. response = _update_refused(
  212. _UPDATE_REFUSAL_ERROR_CODES.get(refusal.code, "update_not_in_place"), refusal.message, refusal.update_command,
  213. )
  214. record_refusal_receipt(refusal)
  215. return response
  216. existing = _ACTION_PROCS.get("hermes-update")
  217. if existing is not None and existing.poll() is None:
  218. response = {"ok": True, "pid": existing.pid, "name": "hermes-update", "already_running": True}
  219. action_id = _ACTION_IDS.get("hermes-update")
  220. if action_id:
  221. response["action_id"] = action_id
  222. return response
  223. action_id = secrets.token_hex(16)
  224. with http_failure("Failed to spawn hermes update", 500, "Failed to start update"):
  225. proc = _spawn_hermes_action(["update"], "hermes-update", env_overrides={"HERMES_ACTION_ID": action_id})
  226. return {"ok": True, "pid": proc.pid, "name": "hermes-update", "action_id": action_id}
  227. _NON_APPLYABLE_MESSAGES = {
  228. "docker": format_docker_update_message,
  229. "apt": lambda: "Hermes is managed by Termux APT; run `pkg upgrade hermes-agent`.",
  230. }
  231. def _source_release_label(status: dict[str, Any]) -> str:
  232. version = status.get("sourceVersion")
  233. return f"{status.get('channel') or 'stable'} release" + (f" v{version}" if version else "")
  234. @router.get("/api/hermes/update/check")
  235. async def check_hermes_update(force: bool = False, profile: Optional[str] = None):
  236. """Report whether a Hermes update is available, without applying it.
  237. Returns install_method ('apt'|'git'|'docker'|'nix'|'nixos'|'unknown'),
  238. current_version, behind (commits behind, 0 = up to date, -1 = unknown count,
  239. null = check could not run), update_available, can_apply (git only — the
  240. dashboard button can apply in place), update_command, message (guidance for
  241. non-applyable methods) and, for git installs that are behind, commits
  242. [{sha, summary, author, at}] (additive; existing consumers ignore it).
  243. """
  244. if is_commit_build(_server_path("PROJECT_ROOT")):
  245. return {
  246. "install_method": "desktop-app",
  247. "current_version": get_version_info().derived_version,
  248. "behind": None, "update_available": False, "can_apply": False,
  249. "update_command": "", "message": COMMIT_BUILD_UPDATE_MESSAGE,
  250. }
  251. if _dashboard_local_update_managed_externally():
  252. return {
  253. "install_method": "managed-runtime",
  254. "current_version": get_version_info().derived_version,
  255. "behind": None,
  256. "update_available": False, "can_apply": False,
  257. "update_command": "", "message": _MANAGED_EXTERNALLY_MESSAGE,
  258. }
  259. install_method = detect_install_method(_server_path("PROJECT_ROOT"))
  260. payload: dict[str, Any] = {
  261. "install_method": install_method,
  262. "current_version": get_version_info().derived_version,
  263. "behind": None,
  264. "update_available": False, "can_apply": install_method == "git",
  265. "update_command": recommended_update_command_for_method(install_method), "message": None,
  266. }
  267. non_applyable = _NON_APPLYABLE_MESSAGES.get(install_method)
  268. if non_applyable is not None:
  269. payload["message"] = non_applyable()
  270. return payload
  271. # source_check.check_for_updates() handles git / nix-revision paths through the GitHub API and
  272. # caches the result for 24h. ``force`` busts the cache so "Check now" reflects reality.
  273. status: dict[str, Any] = {}
  274. try:
  275. from hermes_cli.source_check import check_for_updates
  276. with _config_profile_scope(profile):
  277. status = await asyncio.to_thread(check_for_updates, force=force)
  278. behind = status.get("behind")
  279. except Exception:
  280. _log.exception("Update check failed")
  281. behind = None
  282. payload["behind"] = behind
  283. if behind is None:
  284. payload["message"] = "Couldn't reach the update source — try again later."
  285. elif behind == 0 and status.get("held"):
  286. version = status.get("sourceVersion")
  287. payload.update(held=status["held"], source_version=version,
  288. message=f"This build is newer than {_source_release_label(status)}, which predates the gateway "
  289. "runtime its sessions use. It stays on this build until a newer release ships.")
  290. elif behind == 0:
  291. payload["message"] = "You're on the latest version."
  292. else:
  293. payload["update_available"] = True
  294. if status.get("rollback"):
  295. # A stable release this build already contains: applying it moves back.
  296. payload.update(rollback_to=status.get("sourceVersion"),
  297. message=f"This build is newer than {_source_release_label(status)}. "
  298. "Updating moves it back to that release.")
  299. # "What's changed" for the desktop's remote update overlay; best-effort
  300. # (empty list on any failure). Channel + release name pick its notes source.
  301. payload.update(channel=status.get("channel"), branch=status.get("branch"),
  302. source_version=status.get("sourceVersion"))
  303. payload["commits"] = [{**row, "sha": row["sha"][:7], "at": row["at"] // 1000}
  304. for row in status.get("commits", [])[:20]]
  305. return payload
  306. def _completed_exit_code(
  307. result: Optional[dict[str, Any]], durable_action_id: Optional[str], receipt: Optional[dict[str, Any]],
  308. ) -> Optional[int]:
  309. """Exit code for an action with no live process: in-memory result, else durable evidence."""
  310. if result is not None:
  311. return result.get("exit_code")
  312. if durable_action_id:
  313. return 0
  314. if receipt is not None and receipt.get("outcome") in ("success", "partial"):
  315. # No in-memory result and no log marker (e.g. log rotated), but THIS
  316. # action's receipt proves a completed run: report its outcome rather than
  317. # a null clients time out on. ``partial`` maps to exit 1 like the CLI.
  318. return 0 if receipt["outcome"] == "success" else 1
  319. return None
  320. @status_router.get("/api/actions/{name}/status")
  321. async def get_action_status(name: str, lines: int = 200):
  322. """Tail an action log and report whether the process is still running."""
  323. log_file_name = _ACTION_LOG_FILES.get(name)
  324. if log_file_name is None:
  325. raise HTTPException(status_code=404, detail=f"Unknown action: {name}")
  326. log_dir = _server_path("_ACTION_LOG_DIR")
  327. requested_lines = min(max(lines, 1), 2000)
  328. tail = _tail_lines(log_dir / log_file_name, requested_lines)
  329. durable_update_action_id = None
  330. update_receipt_summary = action_receipt_summary = None
  331. if name == "hermes-update":
  332. # ``hermes update`` mirrors to the ROOT home's update.log (main_dashboard), never this
  333. # dashboard's profile home: read it where it is written.
  334. from hermes_cli.logs import log_file_path
  335. durable_update_action_id = _durable_completed_update_action_id(_tail_lines(log_file_path("update"), 2000))
  336. spawned_action_id = (_latest_spawned_update_action_id(_tail_lines(log_dir / log_file_name, 2000))
  337. or _persisted_action_id(log_dir, name) or _ACTION_IDS.get(name))
  338. if durable_update_action_id != spawned_action_id:
  339. # The root log is shared by every profile: another profile's (or an older) run's
  340. # completion never certifies the action this dashboard started.
  341. durable_update_action_id = None
  342. if durable_update_action_id:
  343. marker = f"=== hermes-update completed {durable_update_action_id} ==="
  344. if marker not in tail:
  345. tail = [*tail, marker][-requested_lines:]
  346. # The update receipt is the durable, structured truth about the last
  347. # update (written by every run, incl. refused/failed; survives the
  348. # dashboard restarting itself mid-action). Surface it so clients READ
  349. # the outcome instead of inferring it from liveness probes.
  350. # See #81193, #87359, #91277.
  351. # The store is root-wide (every profile's runs): show THIS action's receipt when one exists.
  352. update_receipt_summary = _latest_update_receipt_summary(spawned_action_id)
  353. if spawned_action_id and (update_receipt_summary or {}).get("action_id") == spawned_action_id:
  354. action_receipt_summary = update_receipt_summary
  355. proc = _ACTION_PROCS.get(name)
  356. if proc is None:
  357. result = _ACTION_RESULTS.get(name)
  358. running = False
  359. pid = result.get("pid") if result else None
  360. exit_code = _completed_exit_code(result, durable_update_action_id, action_receipt_summary)
  361. else:
  362. exit_code = proc.poll()
  363. running = exit_code is None
  364. pid = proc.pid
  365. if exit_code is not None:
  366. with contextlib.suppress(Exception):
  367. proc.wait(timeout=1)
  368. _finish_action(name, exit_code, pid)
  369. response = {"name": name, "running": running, "exit_code": exit_code, "pid": pid, "lines": tail}
  370. if durable_update_action_id:
  371. response["action_id"] = durable_update_action_id
  372. if update_receipt_summary is not None:
  373. response["receipt"] = update_receipt_summary
  374. return response
  375. def _read_latest_receipt() -> Optional[dict[str, Any]]:
  376. """Latest update receipt, or None on any failure (never raises)."""
  377. try:
  378. from hermes_cli.update_receipt import read_latest_receipt
  379. return read_latest_receipt() or None
  380. except Exception:
  381. return None
  382. def _latest_update_receipt_summary(action_id: Optional[str] = None) -> Optional[dict[str, Any]]:
  383. """Compact summary of dashboard action ``action_id``'s receipt when one exists, else of the
  384. latest receipt (written by EVERY ``hermes update`` run, incl. refused/failed), or None; never
  385. raises. Steps/skips stay in the full endpoint. ``action_id`` names the writer so a client
  386. never credits another action's run.
  387. Phase-1 bullet 3 (#91277): the receipt (written by EVERY ``hermes update`` run since #91283, including
  388. refused and failed ones, with a ``latest.json`` pointer) is the durable success signal the Desktop and
  389. dashboard should read instead of inferring outcomes from liveness probes across the update's stop/start
  390. gap (#81193, #87359).
  391. """
  392. receipt = None
  393. if action_id:
  394. from hermes_cli.update_receipt import read_receipt_for_action
  395. receipt = read_receipt_for_action(action_id)
  396. receipt = receipt or _read_latest_receipt()
  397. if not receipt:
  398. return None
  399. try:
  400. post = receipt.get("post_update") or {}
  401. return {
  402. **{k: receipt.get(k) for k in ("outcome", "started_at", "finished_at", "action_id")},
  403. "pre_sha": (receipt.get("pre_update") or {}).get("sha"),
  404. "post_sha": post.get("sha"), "post_version": post.get("version"),
  405. "fleet_states": sorted({str(e.get("state")) for e in receipt.get("fleet") or [] if isinstance(e, dict)}),
  406. # C3: a committed run is ``success`` even while post-commit steps are owed; carry them
  407. # so a client reports the owed step and its remedy instead of plain success.
  408. "followups": [{"step": str(f.get("step")), "reason": str(f.get("reason") or "")}
  409. for f in receipt.get("followups") or [] if isinstance(f, dict)],
  410. "user_action": receipt.get("user_action") if isinstance(receipt.get("user_action"), dict) else None,
  411. }
  412. except Exception:
  413. return None
  414. @status_router.get("/api/hermes/update/receipt")
  415. async def get_update_receipt():
  416. """The FULL latest update receipt (steps, skips, gateway restart outcome, fleet
  417. matrix) plus a compact ``summary``; 404 when no update has run since receipts landed.
  418. Clients read this instead of inferring success from backend liveness, which misread
  419. the update's own restart gap as a failed update/boot.
  420. See #81193, #87359, #91277.
  421. """
  422. receipt = _read_latest_receipt()
  423. if not receipt:
  424. raise HTTPException(status_code=404, detail="No update receipt found (no `hermes update` run recorded).")
  425. return {"receipt": receipt, "summary": _latest_update_receipt_summary()}