heartbeat.py 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291
  1. """Session heartbeats — recurring re-entry prompts for the current session.
  2. Session-scoped and in-process (CLI or gateway must be running); durable cross-process scheduling stays
  3. ``hermes cron``. Invariants (mirrors goals.py): injection is a plain user message — no system-prompt
  4. mutation or toolset swap, so prompt caching stays intact — and a real user message always wins:
  5. heartbeats only fire into an idle session with an empty input queue."""
  6. from __future__ import annotations
  7. import json
  8. import logging
  9. import re
  10. import threading
  11. import time
  12. from dataclasses import asdict, dataclass
  13. from typing import Any, Optional
  14. logger = logging.getLogger(__name__)
  15. MIN_INTERVAL_SECONDS = 60 # floor: re-entering more often than once a minute is a busy-loop, not a heartbeat
  16. POLL_SECONDS = 5.0 # how often drivers poll for due heartbeats; not user-facing
  17. HEARTBEAT_PROMPT_TEMPLATE = (
  18. "[Heartbeat — recurring instruction, fires every {interval}]\n{prompt}\n\n"
  19. "If there is nothing meaningful to do or report for this instruction "
  20. "right now, reply briefly that nothing has changed and stop — do not invent work."
  21. )
  22. _INTERVAL_RE = re.compile(
  23. r"^\s*(?:every\s+)?(\d+(?:\.\d+)?)\s*(s|sec|secs|seconds?|m|min|mins|minutes?|h|hr|hrs|hours?|d|days?)\s*$", re.IGNORECASE)
  24. _UNIT_SECONDS = {
  25. **dict.fromkeys(("s", "sec", "secs", "second", "seconds"), 1),
  26. **dict.fromkeys(("m", "min", "mins", "minute", "minutes"), 60),
  27. **dict.fromkeys(("h", "hr", "hrs", "hour", "hours"), 3600),
  28. **dict.fromkeys(("d", "day", "days"), 86400),
  29. }
  30. # field -> (coercer, default used when the stored value is missing/falsy)
  31. _STATE_FIELDS = {
  32. "prompt": (str, ""), "interval_seconds": (int, 0), "status": (str, "active"),
  33. "created_at": (float, 0.0), "last_fired_at": (float, 0.0), "fire_count": (int, 0),
  34. }
  35. def parse_interval(text: str) -> Optional[int]:
  36. """Parse ``10m`` / ``every 2h`` / ``every 90 minutes`` into seconds.
  37. None when not an interval; below ``MIN_INTERVAL_SECONDS`` returns -1 so callers can tell "too small" apart.
  38. """
  39. m = _INTERVAL_RE.match(text) if text else None
  40. if not m:
  41. return None
  42. seconds = int(float(m.group(1)) * _UNIT_SECONDS[m.group(2).lower()])
  43. return -1 if seconds < MIN_INTERVAL_SECONDS else seconds
  44. def format_interval(seconds: int) -> str:
  45. """Human-readable interval (``600`` → ``10m``)."""
  46. seconds = int(seconds)
  47. units = ((86400, "d"), (3600, "h"), (60, "m"))
  48. return next((f"{seconds // unit}{suffix}" for unit, suffix in units if seconds % unit == 0), f"{seconds}s")
  49. @dataclass
  50. class HeartbeatState:
  51. """Serializable per-session heartbeat."""
  52. prompt: str
  53. interval_seconds: int
  54. status: str = "active" # active | paused | cleared
  55. created_at: float = 0.0
  56. last_fired_at: float = 0.0
  57. fire_count: int = 0
  58. def to_json(self) -> str:
  59. return json.dumps(asdict(self), ensure_ascii=False)
  60. @classmethod
  61. def from_json(cls, raw: str) -> HeartbeatState:
  62. data = json.loads(raw)
  63. return cls(**{name: coerce(data.get(name) or default) for name, (coerce, default) in _STATE_FIELDS.items()})
  64. def is_due(self, now: Optional[float] = None) -> bool:
  65. if self.status != "active" or not self.prompt or self.interval_seconds <= 0:
  66. return False
  67. return (time.time() if now is None else now) - (self.last_fired_at or self.created_at) >= self.interval_seconds
  68. def render_prompt(self) -> str:
  69. return HEARTBEAT_PROMPT_TEMPLATE.format(interval=format_interval(self.interval_seconds), prompt=self.prompt)
  70. def _get_session_db() -> Optional[Any]:
  71. """Persistence goes through the goals module's per-HERMES_HOME cached SessionDB (one shared connection)."""
  72. try:
  73. from hermes_cli.goals import _get_session_db as _goals_db
  74. return _goals_db()
  75. except Exception as exc: # pragma: no cover
  76. logger.debug("HeartbeatManager: SessionDB bootstrap failed (%s)", exc)
  77. return None
  78. _META_PREFIX = "heartbeat:"
  79. _CLAIM_LOCK = threading.Lock() # every driver of a session's heartbeat runs in its owning gateway process
  80. def load_heartbeat(session_id: str) -> Optional[HeartbeatState]:
  81. db = _get_session_db() if session_id else None
  82. if db is None:
  83. return None
  84. try:
  85. raw = db.get_meta(_META_PREFIX + session_id)
  86. except Exception as exc:
  87. logger.debug("HeartbeatManager: get_meta failed: %s", exc)
  88. return None
  89. try:
  90. state = HeartbeatState.from_json(raw) if raw else None
  91. except Exception as exc:
  92. logger.warning("HeartbeatManager: could not parse stored heartbeat for %s: %s", session_id, exc)
  93. return None
  94. return None if state is None or state.status == "cleared" else state
  95. def store_has_active_heartbeat(db: Any) -> bool:
  96. """True when *db* holds an ACTIVE ``heartbeat:*`` row — or one that cannot be parsed (unknown, so
  97. the caller keeps its full sweep). ``clear``/``pause`` keep their rows (status ``cleared``/``paused``),
  98. so key existence alone is not "active". Read errors propagate: "unavailable" is the caller's call."""
  99. for _key, raw in db.list_meta_prefix(_META_PREFIX):
  100. try:
  101. if HeartbeatState.from_json(raw).status == "active":
  102. return True
  103. except Exception:
  104. return True
  105. return False
  106. def save_heartbeat(session_id: str, state: HeartbeatState) -> None:
  107. if not session_id:
  108. return
  109. db = _get_session_db()
  110. if db is None:
  111. from hermes_cli.goals import _warn_dropped_write
  112. _warn_dropped_write("HeartbeatManager", "heartbeat", session_id)
  113. return
  114. try:
  115. db.set_meta(_META_PREFIX + session_id, state.to_json())
  116. except Exception as exc:
  117. logger.debug("HeartbeatManager: set_meta failed: %s", exc)
  118. class HeartbeatManager:
  119. """Per-session heartbeat state + due-tick decisions; the surface CLI + gateway talk to.
  120. Drivers (CLI thread / gateway task) call :meth:`due_prompt` on a poll cadence while the session is
  121. idle; a non-None return is the user-role message to inject.
  122. """
  123. def __init__(self, session_id: str):
  124. self.session_id = session_id
  125. self._state: Optional[HeartbeatState] = load_heartbeat(session_id)
  126. self._last_claim: Optional[tuple[float, int]] = None # (last_fired_at, fire_count) before the last due_prompt
  127. @property
  128. def state(self) -> Optional[HeartbeatState]:
  129. return self._state
  130. def has_heartbeat(self) -> bool:
  131. return self._state is not None and self._state.status in {"active", "paused"}
  132. def is_active(self) -> bool:
  133. return self._state is not None and self._state.status == "active"
  134. def status_line(self) -> str:
  135. s = self._state
  136. if s is None:
  137. return "No heartbeat. Set one with /heartbeat every <interval> <prompt>."
  138. every = format_interval(s.interval_seconds)
  139. fired = f", fired {s.fire_count}×" if s.fire_count else ""
  140. if s.status == "active":
  141. next_in = max(0, int((s.last_fired_at or s.created_at) + s.interval_seconds - time.time()))
  142. return f"♥ Heartbeat (every {every}, next in ~{next_in}s{fired}): {s.prompt}"
  143. icon = "⏸ " if s.status == "paused" else ""
  144. return f"{icon}Heartbeat ({s.status}, every {every}{fired}): {s.prompt}"
  145. def set(self, prompt: str, interval_seconds: int) -> HeartbeatState:
  146. prompt = (prompt or "").strip()
  147. if not prompt:
  148. raise ValueError("heartbeat prompt is empty")
  149. interval_seconds = int(interval_seconds)
  150. if interval_seconds < MIN_INTERVAL_SECONDS:
  151. raise ValueError(f"interval must be at least {MIN_INTERVAL_SECONDS}s")
  152. self._state = HeartbeatState(prompt=prompt, interval_seconds=interval_seconds, status="active",
  153. created_at=time.time())
  154. save_heartbeat(self.session_id, self._state)
  155. return self._state
  156. def _set_status(self, status: str, *, reanchor: bool = False) -> Optional[HeartbeatState]:
  157. if not self._state:
  158. return None
  159. with _CLAIM_LOCK: # a stop landing inside a claim's reread-then-write would be overwritten by it
  160. self._state.status = status
  161. if reanchor:
  162. self._state.last_fired_at = time.time()
  163. save_heartbeat(self.session_id, self._state)
  164. return self._state
  165. def pause(self) -> Optional[HeartbeatState]:
  166. return self._set_status("paused")
  167. def resume(self) -> Optional[HeartbeatState]:
  168. # Re-anchor so resuming doesn't instantly fire a stale tick.
  169. return self._set_status("active", reanchor=True)
  170. def clear(self) -> bool:
  171. cleared = self._set_status("cleared") is not None
  172. self._state = None
  173. return cleared
  174. def due_prompt(self, now: Optional[float] = None) -> Optional[str]:
  175. """Return the injection prompt if the heartbeat is due, else None.
  176. The fire is recorded immediately (before the turn runs) so overlapping polls or a long turn can never
  177. double-fire the same tick. Missed ticks coalesce: the anchor resets to NOW, not the theoretical
  178. schedule.
  179. """
  180. with _CLAIM_LOCK:
  181. s = self._state
  182. if s is None or not s.is_due(now):
  183. return None
  184. # Compare-and-set on the stored row: the gateway poller and a viewer's due_prompt RPC each hold
  185. # their own manager over it, and only one may take the tick. A row cleared or paused since is lost too.
  186. stored = load_heartbeat(self.session_id)
  187. if stored is None or stored.status != "active" or (
  188. stored.last_fired_at, stored.fire_count) != (s.last_fired_at, s.fire_count):
  189. self._state = stored
  190. return None
  191. self._last_claim = (s.last_fired_at, s.fire_count)
  192. s.last_fired_at = now if now is not None else time.time()
  193. s.fire_count += 1
  194. save_heartbeat(self.session_id, s)
  195. return s.render_prompt()
  196. def abandon_fire(self) -> bool:
  197. """Rewind the fire recorded by the last :meth:`due_prompt` whose turn never started, so the tick stays
  198. due for the next poll instead of being silently consumed. Mirrors ``LoopManager.abandon_tick``. Skipped
  199. (False) when the persisted state moved on — a pause/resume/clear that landed in between wins."""
  200. claim, s = self._last_claim, self._state
  201. if claim is None or s is None:
  202. return False
  203. current = load_heartbeat(self.session_id)
  204. if current is None or current.status != "active" or (current.last_fired_at, current.fire_count) != (
  205. s.last_fired_at, s.fire_count):
  206. return False
  207. s.last_fired_at, s.fire_count = claim
  208. self._last_claim = None
  209. save_heartbeat(self.session_id, s)
  210. return True
  211. def migrate_heartbeat_to_session(old_session_id: str, new_session_id: str) -> bool:
  212. """Carry a heartbeat across a compression session rotation (copy to child, archive parent, never raise).
  213. Same shape as ``goals.migrate_goal_to_session``.
  214. """
  215. if not old_session_id or not new_session_id or old_session_id == new_session_id:
  216. return False
  217. try:
  218. state = load_heartbeat(old_session_id)
  219. if state is None or load_heartbeat(new_session_id) is not None:
  220. return False
  221. save_heartbeat(new_session_id, state)
  222. state.status = "cleared"
  223. save_heartbeat(old_session_id, state)
  224. return True
  225. except Exception as exc: # pragma: no cover - defensive
  226. logger.debug("HeartbeatManager: migration failed: %s", exc)
  227. return False
  228. __all__ = [
  229. "HEARTBEAT_PROMPT_TEMPLATE",
  230. "MIN_INTERVAL_SECONDS",
  231. "POLL_SECONDS",
  232. "HeartbeatManager",
  233. "HeartbeatState",
  234. "format_interval",
  235. "load_heartbeat",
  236. "migrate_heartbeat_to_session",
  237. "parse_interval",
  238. "save_heartbeat",
  239. ]