hermes_state_user_copy.py 4.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113
  1. """Plain-language copy for "session storage is unavailable / could not be written" notices.
  2. One table keyed by ``classify_persistence_error``'s cause bucket feeds every surface (CLI banner,
  3. gateway home-channel warning, TUI/Desktop RPC errors) so they agree on what happened, what to do,
  4. and a machine-readable ``code`` a GUI can attach a "Run doctor" button to.
  5. """
  6. from __future__ import annotations
  7. from dataclasses import dataclass
  8. from hermes_state_errors import STORAGE_RECOVERY_DOCS_URL, classify_persistence_error, is_disk_full_error
  9. @dataclass(frozen=True)
  10. class StorageFailure:
  11. cause: str # classify_persistence_error bucket
  12. code: str # machine-readable, stable: storage_locked | storage_readonly | storage_corrupt | disk_full | ...
  13. gloss: str # what happened, one clause, lowercase start
  14. action: str # what to do, one sentence naming the exact command
  15. _DOCTOR = "Run `hermes {profile_arg}doctor --fix` to diagnose and repair."
  16. # cause -> (code, gloss, action). "disk" is split by is_disk_full_error at lookup time.
  17. _STORAGE_FAILURES: dict[str, tuple[str, str, str]] = {
  18. "locked": (
  19. "storage_locked",
  20. "the session database is locked by another Hermes process",
  21. "Wait a moment and try again; if it persists, stop the other Hermes process "
  22. "(`hermes {profile_arg}gateway stop`).",
  23. ),
  24. "disk_full": (
  25. "disk_full",
  26. "the disk is full",
  27. "Free some disk space, then try again.",
  28. ),
  29. "disk": (
  30. "storage_readonly",
  31. "the session database file is read-only or not writable",
  32. _DOCTOR,
  33. ),
  34. "corrupt": (
  35. "storage_corrupt",
  36. "the session database file is damaged",
  37. _DOCTOR + " Recovery: `hermes {profile_arg}sessions recover --source <state.db> --inspect-only`.",
  38. ),
  39. "session_row_missing": (
  40. "storage_session_missing",
  41. "this session's database row was deleted while the chat was still open and could not be recreated",
  42. "Try again; if it persists, run `hermes {profile_arg}doctor`.",
  43. ),
  44. "fts_index": (
  45. "storage_index_corrupt",
  46. "the session search index is damaged (the messages themselves are intact)",
  47. "Run `hermes {profile_arg}doctor --fix` (or `hermes {profile_arg}sessions repair`) to rebuild it.",
  48. ),
  49. "replaced": (
  50. "storage_replaced",
  51. "the session database file was replaced while Hermes was running",
  52. "Stop Hermes (`hermes {profile_arg}gateway stop`), run `hermes {profile_arg}doctor`, then start it again.",
  53. ),
  54. # Code stays `storage_replaced` (GUI clients key on it); the copy names the real remedy: every writer
  55. # on the profile must stop, doctor names the ones still holding the retired log (#110054).
  56. "deleted_wal": (
  57. "storage_replaced",
  58. "another Hermes process still holds an old copy of the session database's write-ahead log, "
  59. "so Hermes stopped writing to keep the file safe",
  60. "Nothing is lost. Quit every Hermes process on this profile (Desktop app, "
  61. "`hermes {profile_arg}gateway stop`, dashboard, cron), run `hermes {profile_arg}doctor` — it names "
  62. "any process still holding the log — then start Hermes again. Do not run `doctor --fix` or delete "
  63. "any state.db files while they run. Guide: " + STORAGE_RECOVERY_DOCS_URL,
  64. ),
  65. "compression": (
  66. "storage_busy",
  67. "another process is compressing this session",
  68. "Send your message again once compression finishes.",
  69. ),
  70. "compression_closed": (
  71. "storage_session_rotated",
  72. "this session was rotated by context compression",
  73. "Refresh the client (or start a new turn) and send your message again.",
  74. ),
  75. "turn_lease": (
  76. "storage_busy",
  77. "another Hermes process took over this session",
  78. "Wait for it to finish, then send your message again.",
  79. ),
  80. "unknown": (
  81. "storage_unavailable",
  82. "the session database could not be opened",
  83. _DOCTOR,
  84. ),
  85. }
  86. def describe_storage_failure(exc_or_str) -> StorageFailure:
  87. """Plain-language description of a persistence failure (never raises)."""
  88. cause = classify_persistence_error(exc_or_str)
  89. key = "disk_full" if cause == "disk" and is_disk_full_error(exc_or_str) else cause
  90. code, gloss, action = _STORAGE_FAILURES.get(key, _STORAGE_FAILURES["unknown"])
  91. # Pin the copy-pasteable command to the failing profile — see profile_cli_selector.
  92. from hermes_constants import profile_cli_selector
  93. return StorageFailure(
  94. cause=cause, code=code, gloss=gloss, action=action.replace("{profile_arg}", profile_cli_selector())
  95. )
  96. def storage_failure_details(exc_or_str, limit: int = 200) -> str:
  97. """Raw cause for a trailing, secondary "Details:" line (never the lead sentence)."""
  98. text = " ".join(str(exc_or_str or "").split())
  99. return text if len(text) <= limit else text[: limit - 3].rstrip() + "..."