prune_advisor.py 19 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428
  1. """Low-disk prompt for ``sessions.auto_prune`` (off by default).
  2. Auto-prune deletes history, so it is opt-in. Users who never decided still need to hear about it
  3. when the disk holding ``state.db`` runs low: every surface asks once the disk is low, and the
  4. question stops forever as soon as ``sessions.auto_prune`` is written to the user's config.yaml
  5. (either answer). "Later" snoozes for :data:`SNOOZE_SECONDS`.
  6. The hot-path check is two syscalls (``os.stat`` + ``shutil.disk_usage``, microseconds), so it can
  7. run at every session start. Only when it fires does :func:`advise` open the database read-only to
  8. estimate what a prune would actually free, so the prompt can say plainly when pruning will not
  9. fix the disk (nothing old enough to delete, or the store is a small share of the full disk).
  10. """
  11. from __future__ import annotations
  12. import json
  13. import logging
  14. import os
  15. import shutil
  16. import sqlite3
  17. import time
  18. from dataclasses import dataclass
  19. from pathlib import Path
  20. from typing import Optional
  21. logger = logging.getLogger(__name__)
  22. GIB = 1024 ** 3
  23. # Low = under 2 GiB free, or under 10% free while also under 20 GiB (a 10%-free 4 TB disk is fine).
  24. LOW_FREE_FLOOR = 2 * GIB
  25. LOW_FREE_PERCENT = 10.0
  26. LOW_FREE_HEADROOM = 20 * GIB
  27. SNOOZE_SECONDS = 7 * 86400
  28. _SNOOZE_FILE = ".auto_prune_prompt.json"
  29. # The all-rows byte total is a full scan of ``messages`` (seconds, up to tens on a cold multi-GB
  30. # store), so one measurement is reused for a week, scaled by how much state.db has grown since.
  31. # The prunable share is read fresh each time through the session index.
  32. _ESTIMATE_FILE = ".auto_prune_estimate.json"
  33. TOTAL_BYTES_TTL = 7 * 86400
  34. # The classic CLI asks from a stored estimate only: it never reads the store at startup. One older
  35. # than this still asks (scaled to the current file) and is refreshed in the background meanwhile.
  36. CLI_ADVICE_TTL = 86400
  37. @dataclass(frozen=True)
  38. class DiskSnapshot:
  39. db_bytes: int
  40. free_bytes: int
  41. total_bytes: int
  42. @property
  43. def low(self) -> bool:
  44. if self.total_bytes <= 0:
  45. return False
  46. free_pct = self.free_bytes * 100.0 / self.total_bytes
  47. return self.free_bytes < LOW_FREE_FLOOR or (
  48. free_pct < LOW_FREE_PERCENT and self.free_bytes < LOW_FREE_HEADROOM)
  49. @dataclass(frozen=True)
  50. class Advice:
  51. disk: DiskSnapshot
  52. retention_days: int
  53. prunable_sessions: int
  54. total_sessions: int
  55. reclaim_bytes: int # estimate: the prunable share of stored message bytes times the file size
  56. estimate_ok: bool = True # False when state.db could not be read (counts are unknown, not zero)
  57. vacuum_after_prune: bool = True
  58. @property
  59. def helps(self) -> bool:
  60. """Whether a prune would free a meaningful amount: at least 1 GiB, or enough to lift the
  61. disk back out of the low band."""
  62. if self.prunable_sessions == 0:
  63. return False
  64. lifted = DiskSnapshot(self.disk.db_bytes - self.reclaim_bytes,
  65. self.disk.free_bytes + self.reclaim_bytes, self.disk.total_bytes)
  66. return self.reclaim_bytes >= GIB or not lifted.low
  67. def _home(home: Optional[Path]) -> Path:
  68. if home is not None:
  69. return Path(home)
  70. from hermes_constants import get_hermes_home
  71. return get_hermes_home()
  72. def disk_snapshot(home: Optional[Path] = None) -> Optional[DiskSnapshot]:
  73. """``state.db`` size plus free/total bytes of its filesystem; None when either is unreadable."""
  74. db = _home(home) / "state.db"
  75. try:
  76. size = os.stat(db).st_size
  77. usage = shutil.disk_usage(db.parent)
  78. except OSError:
  79. return None
  80. return DiskSnapshot(size, usage.free, usage.total)
  81. def _effective_sessions(home: Optional[Path]) -> Optional[dict]:
  82. """*home*'s ``sessions:`` block as maintenance sees it (user file, ``${VAR}`` expansion, managed
  83. overlay; no defaults merged) or None when the file cannot be read. Read through *home*'s own
  84. config path, so gateway housekeeping gets each served profile's values, not the caller's."""
  85. from hermes_cli.config_effective import load_user_config_effective
  86. try:
  87. sessions = load_user_config_effective(_home(home) / "config.yaml", fail_closed=True).get("sessions")
  88. except Exception as exc: # health: allow BLE001 -- any parse/read failure means "unreadable": never ask on it
  89. logger.debug("auto-prune advice: config unreadable: %s", exc, exc_info=True)
  90. return None
  91. return sessions if isinstance(sessions, dict) else {}
  92. def _retention_days(sessions: dict) -> int:
  93. """Same coercion maintenance applies (``int(...)``); an unusable value reads as the default."""
  94. try:
  95. days = int(sessions.get("retention_days", 90))
  96. except (TypeError, ValueError):
  97. return 90
  98. return days if days >= 0 else 90
  99. def undecided(home: Optional[Path] = None) -> bool:
  100. """True while neither the user's config nor an administrator's managed layer sets
  101. ``sessions.auto_prune``. A managed value is already decided: asking would promise a choice the
  102. user cannot make."""
  103. sessions = _effective_sessions(home)
  104. return sessions is not None and "auto_prune" not in sessions
  105. def _snooze_path(home: Optional[Path]) -> Path:
  106. return _home(home) / _SNOOZE_FILE
  107. def snoozed(home: Optional[Path] = None, *, now: Optional[float] = None) -> bool:
  108. try:
  109. until = float(json.loads(_snooze_path(home).read_text(encoding="utf-8-sig")).get("snoozed_until", 0))
  110. except (OSError, ValueError, TypeError, AttributeError):
  111. return False
  112. return (now or time.time()) < until
  113. def snooze(home: Optional[Path] = None, seconds: float = SNOOZE_SECONDS) -> None:
  114. from utils import atomic_json_write
  115. atomic_json_write(_snooze_path(home), {"snoozed_until": time.time() + seconds})
  116. def should_ask(home: Optional[Path] = None) -> Optional[DiskSnapshot]:
  117. """The cheap gate every surface runs at session start: the snapshot when the disk is low and
  118. the user has neither decided nor snoozed, else None. Two syscalls plus one small YAML read."""
  119. snap = disk_snapshot(home)
  120. if snap is None or not snap.low:
  121. return None
  122. if not undecided(home) or snoozed(home):
  123. return None
  124. return snap
  125. def advise(home: Optional[Path] = None) -> Optional[Advice]:
  126. """:func:`should_ask` plus the reclaim estimate. Opens state.db read-only (a second or two on
  127. a multi-GB store), so callers run it only after the cheap gate fires or off the prompt thread."""
  128. snap = should_ask(home)
  129. if snap is None:
  130. return None
  131. # Read the settings from THIS home's config: gateway housekeeping calls this for every served
  132. # profile without entering its scope. Only an explicit key differs from the defaults here.
  133. sessions = _effective_sessions(home) or {}
  134. retention = _retention_days(sessions)
  135. prunable = total = prunable_bytes = total_bytes = 0
  136. estimate_ok = True
  137. try:
  138. from hermes_state import SessionDB
  139. db = SessionDB(db_path=_home(home) / "state.db", read_only=True)
  140. try:
  141. where, params = db._prune_where(retention, None, {}, whole_lineages=True)
  142. prunable, total = tuple(db._read_one(
  143. f"SELECT (SELECT COUNT(*) FROM sessions s WHERE {where}), (SELECT COUNT(*) FROM sessions)",
  144. params) or (0, 0))
  145. if prunable:
  146. # Weight by stored bytes, not message_count: old messages are far smaller than recent
  147. # ones, and message_count skips the soft-archived rows a prune also deletes.
  148. row_bytes = _row_bytes_sql(db)
  149. prunable_bytes = (db._read_one(
  150. f"SELECT COALESCE(SUM({row_bytes}), 0) FROM messages m WHERE m.session_id IN "
  151. f"(SELECT s.id FROM sessions s WHERE {where})", params) or (0,))[0]
  152. total_bytes = _cached_total_bytes(home, snap.db_bytes)
  153. if total_bytes is None:
  154. total_bytes = (db._read_one(
  155. f"SELECT COALESCE(SUM({row_bytes}), 0) FROM messages m", []) or (0,))[0]
  156. _store_estimate(home, total_bytes=total_bytes, total_at_db_bytes=snap.db_bytes)
  157. total_bytes = max(total_bytes, prunable_bytes) # a stale scaled total never under-counts
  158. finally:
  159. db.close()
  160. except (sqlite3.Error, OSError, RuntimeError, ValueError) as exc: # a busy/damaged store: no estimate
  161. logger.debug("auto-prune advice: reclaim estimate unavailable: %s", exc)
  162. estimate_ok = False
  163. reclaim = int(snap.db_bytes * prunable_bytes / total_bytes) if total_bytes else 0
  164. advice = Advice(snap, retention, int(prunable), int(total), reclaim, estimate_ok,
  165. bool(sessions.get("vacuum_after_prune", True)))
  166. if estimate_ok:
  167. _store_estimate(home, advice={"retention_days": retention, "prunable": advice.prunable_sessions,
  168. "total": advice.total_sessions, "db_bytes": snap.db_bytes,
  169. "reclaim_bytes": reclaim})
  170. return advice
  171. def _read_estimate(home: Optional[Path]) -> dict:
  172. try:
  173. data = json.loads((_home(home) / _ESTIMATE_FILE).read_text(encoding="utf-8-sig"))
  174. except (OSError, ValueError):
  175. return {}
  176. return data if isinstance(data, dict) else {}
  177. def _store_estimate(home: Optional[Path], **fields) -> None:
  178. """Merge *fields* (each stamped with the time) into the estimate sidecar; a full disk that
  179. cannot take the write just means the next estimate measures again."""
  180. from utils import atomic_json_write
  181. data = _read_estimate(home)
  182. now = time.time()
  183. for key, value in fields.items():
  184. data[key] = value
  185. data[f"{key}_at"] = now
  186. try:
  187. atomic_json_write(_home(home) / _ESTIMATE_FILE, data)
  188. except OSError as exc:
  189. logger.debug("auto-prune advice: estimate not cached: %s", exc)
  190. def _cached_total_bytes(home: Optional[Path], db_bytes: int) -> Optional[int]:
  191. """The week-old all-rows byte total scaled to the current file size, or None to re-measure."""
  192. data = _read_estimate(home)
  193. try:
  194. total, at, base = int(data["total_bytes"]), float(data["total_bytes_at"]), int(data["total_at_db_bytes"])
  195. except (KeyError, TypeError, ValueError):
  196. return None
  197. if time.time() - at > TOTAL_BYTES_TTL or base <= 0 or total <= 0:
  198. return None
  199. return int(total * db_bytes / base)
  200. def cached_advice(home: Optional[Path] = None) -> tuple[Optional[Advice], bool]:
  201. """``(advice, stale)`` from the last stored estimate for the same retention, scaled to the
  202. live file and disk; ``(None, True)`` when nothing usable is stored. No DB read. A stale one
  203. (over :data:`CLI_ADVICE_TTL`) still answers: refusing it would let a user who launches less
  204. often than the TTL miss the question forever."""
  205. snap = should_ask(home)
  206. if snap is None:
  207. return None, False
  208. sessions = _effective_sessions(home) or {}
  209. retention = _retention_days(sessions)
  210. stored = _read_estimate(home)
  211. est = stored.get("advice")
  212. try:
  213. if not (isinstance(est, dict) and int(est["retention_days"]) == retention):
  214. return None, True
  215. stale = time.time() - float(stored["advice_at"]) > CLI_ADVICE_TTL
  216. reclaim = int(est["reclaim_bytes"]) * snap.db_bytes // max(int(est["db_bytes"]), 1)
  217. return Advice(snap, retention, int(est["prunable"]), int(est["total"]), min(reclaim, snap.db_bytes),
  218. True, bool(sessions.get("vacuum_after_prune", True))), stale
  219. except (KeyError, TypeError, ValueError):
  220. return None, True
  221. def _row_bytes_sql(db) -> str:
  222. """Stored size of one ``messages`` row: the byte length of every text/blob column (read from
  223. the live schema, so a column added later is counted without touching this)."""
  224. cols = [r[1] for r in db._read_all("PRAGMA table_info(messages)", [])
  225. if str(r[2]).upper() in {"TEXT", "BLOB", ""}]
  226. return " + ".join(f'COALESCE(LENGTH(CAST(m."{c}" AS BLOB)), 0)' for c in cols) or "0"
  227. def _gb(n: int) -> str:
  228. """Human size: GB at or above 1 GiB, MB below (a 26 MB store must not read "0.0 GB")."""
  229. return f"{n / GIB:.1f} GB" if n >= GIB else f"{max(n, 0) / 1024 ** 2:.0f} MB"
  230. def _sessions(n: int) -> str:
  231. return f"{n} session" + ("" if n == 1 else "s")
  232. def advice_lines(advice: Advice, *, command_prefix: str = "/") -> list[str]:
  233. """Plain-text prompt shared by every surface (no markup); the last line names the commands."""
  234. d = advice.disk
  235. lines = [
  236. f"Low disk space: {_gb(d.free_bytes)} free of {_gb(d.total_bytes)}. "
  237. f"Your session history (state.db) uses {_gb(d.db_bytes)}.",
  238. f"Auto-prune is off. Turning it on deletes ended sessions inactive for more than "
  239. f"{advice.retention_days} days, once a day (pinned and open sessions are kept).",
  240. ]
  241. if not advice.estimate_ok:
  242. lines.append("Could not read state.db to estimate how much pruning would free.")
  243. elif advice.prunable_sessions == 0:
  244. held = (f"none of your {_sessions(advice.total_sessions)} is older than {advice.retention_days} days"
  245. if advice.total_sessions else "there is no session history to delete")
  246. lines.append(f"Pruning will not help right now: {held}. Something else is filling this disk.")
  247. elif not advice.helps:
  248. lines.append(f"Pruning would remove only about {_gb(advice.reclaim_bytes)} of history "
  249. f"({_sessions(advice.prunable_sessions)}), which will not fix this disk on its own.")
  250. else:
  251. lines.append(f"Pruning would remove about {_gb(advice.reclaim_bytes)} of history "
  252. f"({advice.prunable_sessions} of {_sessions(advice.total_sessions)}).")
  253. if advice.estimate_ok and advice.prunable_sessions:
  254. # Automatic compaction runs only past a free-page threshold most prunes never reach, so the
  255. # disk gets the space back reliably only from an explicit VACUUM.
  256. lines.append("Deleted history frees space inside state.db; to give it back to the disk, run "
  257. "`hermes sessions optimize` with other Hermes windows closed.")
  258. p = command_prefix
  259. lines.append(f"{p}autoprune on to enable, {p}autoprune off to keep everything (never asked again), "
  260. f"{p}autoprune later to be reminded in a week.")
  261. return lines
  262. NOTICE_KEY = "sessions.auto_prune"
  263. def notice_payload(advice: Advice) -> dict:
  264. """``notification.show`` payload for TUI/Desktop: a short status-line ``text`` plus the full
  265. question in ``detail`` (Desktop's expandable toast body; Ink prints it into the transcript)."""
  266. d = advice.disk
  267. return {"text": f"⚠ Low disk ({_gb(d.free_bytes)} free) · /autoprune on|off|later",
  268. "detail": "\n".join(advice_lines(advice)), "level": "warn", "kind": "sticky", "ttl_ms": None,
  269. "key": NOTICE_KEY, "id": NOTICE_KEY}
  270. def answered(home: Optional[Path] = None) -> bool:
  271. """True once the question is settled for now (a saved on/off, or a live ``later`` snooze):
  272. the only state in which a shown notice may be withdrawn."""
  273. return not undecided(home) or snoozed(home)
  274. def notice_due(home: Optional[Path], shown: dict) -> bool:
  275. """Per-process dedup that re-arms: a home already noticed is due again once the gate passes
  276. and a full snooze window has gone by since (so ``later`` really asks again in a week)."""
  277. if should_ask(home) is None:
  278. return False
  279. last = shown.get(str(_home(home)))
  280. return last is None or time.time() - last >= SNOOZE_SECONDS
  281. def managed() -> bool:
  282. """True when an administrator pins ``sessions.auto_prune`` (the user cannot change it)."""
  283. from hermes_cli import managed_scope
  284. return managed_scope.is_key_managed("sessions.auto_prune")
  285. def decide(enable: bool, home: Optional[Path] = None) -> bool:
  286. """Persist the user's answer as an explicit ``sessions.auto_prune``; ends the prompt for good.
  287. False when the save failed or did not take effect (an administrator-managed value wins)."""
  288. import hermes_yaml as yaml
  289. from hermes_cli.config_backend import ConfigWriteError, write_config_key
  290. from hermes_constants import mkdir_under_hermes_home
  291. if managed():
  292. return False
  293. path = _home(home) / "config.yaml"
  294. try:
  295. mkdir_under_hermes_home(path.parent)
  296. write_config_key(path, "sessions.auto_prune", bool(enable))
  297. except (OSError, ValueError, yaml.YAMLError, ConfigWriteError) as exc:
  298. logger.warning("Could not save sessions.auto_prune: %s", exc)
  299. return False
  300. try:
  301. _snooze_path(home).unlink(missing_ok=True)
  302. except OSError:
  303. pass
  304. return bool((_effective_sessions(home) or {}).get("auto_prune")) == bool(enable)
  305. _SAVE_FAILED = "Could not save sessions.auto_prune; check disk space and config.yaml permissions."
  306. def run_command(args: str, home: Optional[Path] = None) -> str:
  307. """``/autoprune [on|off|later|status]`` — the one handler behind the CLI, TUI, Desktop and
  308. messaging surfaces."""
  309. arg = (args or "").strip().lower()
  310. sessions = _effective_sessions(home) or {}
  311. state = "on" if sessions.get("auto_prune") else "off"
  312. if arg in {"on", "off", "enable", "disable", "yes", "no", "later", "snooze"} and managed():
  313. return f"Auto-prune is {state}, set by your administrator; it cannot be changed here."
  314. if arg in {"on", "enable", "yes"}:
  315. return ("Auto-prune is on: ended sessions inactive past retention_days are deleted once a day."
  316. if decide(True, home) else _SAVE_FAILED)
  317. if arg in {"off", "disable", "no"}:
  318. return ("Auto-prune is off and you will not be asked again. `hermes sessions prune` still works any time."
  319. if decide(False, home) else _SAVE_FAILED)
  320. if arg in {"later", "snooze"}:
  321. snooze(home)
  322. return "OK, I'll ask again in a week if the disk is still low."
  323. chosen = ("set by your administrator" if managed() else
  324. "default" if "auto_prune" not in sessions else "your setting")
  325. snap = disk_snapshot(home)
  326. disk = (f" state.db {_gb(snap.db_bytes)}; {_gb(snap.free_bytes)} free of {_gb(snap.total_bytes)}"
  327. f"{' (low)' if snap.low else ''}.") if snap else ""
  328. return (f"Auto-prune is {state} ({chosen}), retention {_retention_days(sessions)} days.{disk} "
  329. "Usage: /autoprune on | off | later")
  330. def offer_interactive(*, cprint, ask=input) -> Optional[bool]:
  331. """Classic-CLI startup offer (TTY only). Returns the decision, or None when nothing was asked
  332. or the user chose later."""
  333. if should_ask() is None:
  334. return None
  335. advice, stale = cached_advice()
  336. if stale:
  337. # Never read the store on the startup path: (re)measure in the background for next launch.
  338. from agent.memory_provider import spawn_context_thread
  339. spawn_context_thread(advise, name="auto-prune-estimate").start()
  340. if advice is None:
  341. return None
  342. cprint("")
  343. cprint("☤ " + advice_lines(advice)[0])
  344. for line in advice_lines(advice)[1:-1]:
  345. cprint(f" {line}")
  346. try:
  347. answer = ask(" Enable auto-prune? [y = enable / n = never prune, don't ask again / Enter = remind me later]: ")
  348. except (KeyboardInterrupt, EOFError):
  349. print()
  350. return None
  351. answer = answer.strip().lower()
  352. if answer in {"y", "yes", "n", "no"}:
  353. enable = answer.startswith("y")
  354. if not decide(enable):
  355. cprint(f" {_SAVE_FAILED}")
  356. return None
  357. cprint(" ✓ sessions.auto_prune: true" if enable else
  358. " ✓ sessions.auto_prune: false. You won't be asked again.")
  359. return enable
  360. snooze()
  361. cprint(" Later. /autoprune on|off decides it any time.")
  362. return None