profile_identity.py 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255
  1. """Rekey a renamed profile's durable identity (#111926), and purge a deleted profile's (#112727).
  2. ``rename_profile`` moves ``profiles/<old>/`` to ``profiles/<new>/`` so row DATA travels with the
  3. directory, but several identities are derived from the old name or absolute path and do not:
  4. ``agent:<old>:*`` session-key namespaces (routing index + the profile's own ``sessions`` rows),
  5. ``sessions.profile_name``, ``gateway_heartbeats.profile``, ``delivery_obligations``, and checkpoint
  6. project refs/metadata/ledgers keyed by the absolute workdir path. Left alone, routing resolves to a
  7. profile that no longer exists and profile-local `/rollback` history disappears under the new path.
  8. The same identity has to be *purged* when a profile is deleted — the mirror image of the rekey,
  9. and ``delete_profile`` calls :func:`purge_profile_identity` for it.
  10. Ownership decides who rewrites: a live multiplexer holds the routing index in memory
  11. (``SessionStore._entries``) and writes it back periodically, so a CLI-side DB rewrite would be
  12. clobbered on its next save — the CLI delegates the rename to the ``migrate-profile-identity``
  13. control verb and the delete to the delete-only ``purge-profile-identity`` verb. Neither runs inside
  14. ``_unserve_profile()``: that hook fires for every name leaving the served set, and a rename's old
  15. name leaves it exactly like a deleted one, so identity must survive it for the rekey that follows.
  16. With no live multiplexer nothing else holds the store and the durable rewrite is safe here.
  17. Checkpoint project state has no live in-memory owner and is rekeyed locally after the directory move.
  18. """
  19. from __future__ import annotations
  20. import contextlib
  21. import sys
  22. from pathlib import Path
  23. def migrate_profile_identity(old_name: str, new_name: str) -> bool:
  24. """Retry the durable identity migration of a rename that already completed.
  25. ``rename_profile`` runs the migration itself; this is the standalone retry behind
  26. ``hermes profile migrate-identity <old> <new>`` for when that attempt failed. The rename
  27. cannot simply be repeated — ``profiles/<old>`` is gone — and the identity to migrate is read
  28. from rows/metadata that still name the old profile or old absolute workdir, so only the new
  29. profile has to exist here.
  30. A live multiplexer holds the routing index in memory and therefore stays the owner of that
  31. portion of the migration (the CLI delegates to its control verb); checkpoint identity and,
  32. with no live multiplexer, session identity are durable-only and safe to rewrite here.
  33. Idempotent: re-running a completed migration succeeds with nothing left to rekey. Returns True
  34. when all applicable identity was migrated, False when any durable migration failed or a live
  35. gateway would not accept the routing migration.
  36. """
  37. from hermes_cli.profiles import _canon_valid, _live_default_multiplexer, _unknown_profile_error, get_profile_dir
  38. old_canon = _canon_valid(old_name)
  39. new_canon = _canon_valid(new_name)
  40. if "default" in (old_canon, new_canon):
  41. raise ValueError("Identity migration applies to named profiles only.")
  42. if not get_profile_dir(new_canon).is_dir():
  43. raise _unknown_profile_error(new_canon)
  44. return _migrate_profile_identity(old_canon, new_canon, _live_default_multiplexer())
  45. def purge_profile_identity(profile: str) -> bool:
  46. """Purge a deleted profile's session/routing identity from the durable stores (#111926).
  47. The mirror of :func:`migrate_profile_identity`: a rename must rekey a profile's identity, a
  48. delete must purge it. ``agent:<name>:*`` routing keys, ``gateway_heartbeats.profile`` and
  49. ``delivery_obligations`` rows are bookkeeping for a profile that no longer exists; left behind,
  50. every inbound event on a chat keyed to the deleted name enters the routing index, resolves a
  51. profile whose directory is gone, and logs ``Profile '<name>' does not exist`` on each event.
  52. A live multiplexer holds that index in memory and writes it back periodically, so it owns the
  53. purge exactly as it owns the rename migration: the delete path asks it through the
  54. ``purge-profile-identity`` control verb and treats the answer as the settlement — a gateway that
  55. times out, predates the verb, or fails the purge is reported with a retry command instead of
  56. being silently assumed. With no live multiplexer nothing else holds the store and the durable
  57. delete happens here. Session history rows are not part of this purge — it settles identity only.
  58. Refuses a name that is a live profile again: the purge keys off the name alone, so a same-name
  59. profile created after the delete (the very case a failed settlement leaves behind) would
  60. otherwise have the new incarnation's routing/heartbeat identity deleted from under it. The
  61. delete path tombstones the directory before calling this, so the guard never blocks it.
  62. Idempotent: purging an already-purged profile succeeds. Returns False only when the identity was
  63. not settled — by this process or by the live gateway.
  64. """
  65. from hermes_cli.profiles import _canon_valid, _live_default_multiplexer, profile_exists
  66. canon = _canon_valid(profile)
  67. if canon == "default":
  68. raise ValueError("Identity purge applies to named profiles only.")
  69. if profile_exists(canon):
  70. raise ValueError(
  71. f"Profile '{canon}' exists; purge-identity only settles the identity of a delete that "
  72. "has already completed.")
  73. return _purge_profile_identity(canon, _live_default_multiplexer())
  74. def _purge_profile_identity(canon: str, live_mux: bool) -> bool:
  75. """Purge deleted-profile identity without racing a live gateway's in-memory routing index.
  76. Returns True when the identity was purged — by the gateway's control verb, or by this process's
  77. durable delete when no gateway holds the store — and False when a live gateway did not accept
  78. it. Never fatal to the delete, which has already happened by this point.
  79. """
  80. if live_mux:
  81. from hermes_constants import get_default_hermes_root
  82. root = get_default_hermes_root()
  83. try:
  84. from gateway.control_socket import purge_gateway_profile_identity
  85. answer = purge_gateway_profile_identity(root, canon)
  86. except Exception as exc:
  87. reason = f"{type(exc).__name__}: {exc}"
  88. else:
  89. if isinstance(answer, dict) and answer.get("ok") is True:
  90. return True
  91. reason = _control_answer_failure(answer)
  92. if answer is None and _gateway_accepts_profile_identity_verb(root):
  93. reason += (" — the gateway is running but does not implement "
  94. "'purge-profile-identity' (an older process than this CLI)")
  95. print(
  96. "⚠ Profile was deleted, but the live gateway could not purge its session identity"
  97. f" ({reason}). Restart the gateway, then run:\n"
  98. f" hermes profile purge-identity {canon}",
  99. file=sys.stderr)
  100. return False
  101. from hermes_cli.profiles import get_profile_dir
  102. from hermes_constants import get_default_hermes_root
  103. from hermes_state_registry import acquire, release_or_close
  104. root = get_default_hermes_root()
  105. purged = True
  106. for db_path in (root / "state.db", get_profile_dir(canon) / "state.db"):
  107. if not db_path.exists():
  108. continue
  109. db = None
  110. try:
  111. db = acquire(db_path)
  112. db.purge_profile_state(canon)
  113. except Exception as exc:
  114. purged = False
  115. print(
  116. f"⚠ Profile was deleted, but identity purge failed for {db_path}: "
  117. f"{type(exc).__name__}: {exc}",
  118. file=sys.stderr)
  119. finally:
  120. if db is not None:
  121. with contextlib.suppress(Exception):
  122. release_or_close(db)
  123. return purged
  124. def _control_answer_failure(answer) -> str:
  125. """Why a control-socket answer is not a success. Keeps the raw answer when the payload carries
  126. no reason field, so a malformed or old-gateway response stays diagnosable instead of
  127. collapsing into a generic warning."""
  128. if isinstance(answer, dict):
  129. failure = answer.get("error") or answer.get("message") or answer.get("detail")
  130. return str(failure) if failure else repr(answer)
  131. if answer is not None:
  132. return repr(answer)
  133. return "no response from gateway control socket"
  134. def _gateway_accepts_profile_identity_verb(root: Path) -> bool:
  135. """True when the gateway at *root* answers a verb it has always had. Distinguishes a failed
  136. migration verb caused by an older gateway process from one caused by no gateway at all."""
  137. try:
  138. from gateway.control_socket import identify_gateway
  139. return identify_gateway(root) is not None
  140. except Exception:
  141. return False
  142. def _migrate_checkpoint_identity(old_canon: str, new_canon: str) -> bool:
  143. """Rekey checkpoint projects whose absolute workdirs moved with the profile directory."""
  144. from hermes_cli.profiles import get_profile_dir
  145. from tools.checkpoint_manager_profile_rename import migrate_profile_checkpoint_projects
  146. old_dir = get_profile_dir(old_canon)
  147. new_dir = get_profile_dir(new_canon)
  148. result = migrate_profile_checkpoint_projects(old_dir, new_dir)
  149. if result["migrated"]:
  150. print(f"✓ Checkpoint identity updated: {result['migrated']} project(s)")
  151. if not result["errors"]:
  152. return True
  153. print(
  154. "⚠ Profile was renamed, but checkpoint identity migration failed for "
  155. f"{result['errors']} project(s). Retry with:\n"
  156. f" hermes profile migrate-identity {old_canon} {new_canon}",
  157. file=sys.stderr,
  158. )
  159. return False
  160. def _migrate_profile_identity(old_canon: str, new_canon: str, live_mux: bool) -> bool:
  161. """Rekey renamed-profile identity without racing a live gateway's in-memory routing index.
  162. Returns True when every applicable identity was migrated. Session/routing identity is handled
  163. by the gateway's control verb when it owns the live store, otherwise by this process; checkpoint
  164. project identity is always durable-only. Never fatal to the rename, which has already happened
  165. by this point.
  166. """
  167. checkpoint_migrated = _migrate_checkpoint_identity(old_canon, new_canon)
  168. if live_mux:
  169. from hermes_constants import get_default_hermes_root
  170. root = get_default_hermes_root()
  171. try:
  172. from gateway.control_socket import migrate_gateway_profile_identity
  173. answer = migrate_gateway_profile_identity(root, old_canon, new_canon)
  174. except Exception as exc:
  175. reason = f"{type(exc).__name__}: {exc}"
  176. else:
  177. if isinstance(answer, dict) and answer.get("ok") is True:
  178. return checkpoint_migrated
  179. reason = _control_answer_failure(answer)
  180. if answer is None and _gateway_accepts_profile_identity_verb(root):
  181. reason += (" — the gateway is running but does not implement "
  182. "'migrate-profile-identity' (an older process than this CLI)")
  183. print(
  184. "⚠ Profile was renamed, but the live gateway could not migrate session identity"
  185. f" ({reason}). Restart the gateway, then run:\n"
  186. f" hermes profile migrate-identity {old_canon} {new_canon}",
  187. file=sys.stderr)
  188. return False
  189. from hermes_cli.profiles import get_profile_dir
  190. from hermes_state_registry import acquire, release_or_close
  191. from hermes_constants import get_default_hermes_root
  192. root = get_default_hermes_root()
  193. migrated = checkpoint_migrated
  194. for db_path in (root / "state.db", get_profile_dir(new_canon) / "state.db"):
  195. if not db_path.exists():
  196. continue
  197. db = None
  198. try:
  199. db = acquire(db_path)
  200. db.rekey_profile_state(old_canon, new_canon)
  201. except Exception as exc:
  202. migrated = False
  203. print(
  204. f"⚠ Profile was renamed, but identity migration failed for {db_path}: "
  205. f"{type(exc).__name__}: {exc}",
  206. file=sys.stderr)
  207. finally:
  208. if db is not None:
  209. with contextlib.suppress(Exception):
  210. release_or_close(db)
  211. return migrated
  212. def _record_profile_rename(new_dir: Path, old_canon: str) -> None:
  213. """Append ``old_canon`` to the renamed profile's ``previous_names`` history.
  214. Best-effort: never raises, so a metadata write failure cannot fail the rename.
  215. Only reached for a real slug change — ``rename_profile`` returns early for the
  216. default profile (display-name only) and refuses ``old == new`` (target exists)."""
  217. from hermes_cli import profiles as _profiles
  218. try:
  219. history = _profiles.read_profile_meta(new_dir).get("previous_names") or []
  220. if old_canon not in history:
  221. history = [*history, old_canon]
  222. _profiles.write_profile_meta(new_dir, previous_names=history)
  223. except Exception as exc: # unwritable / corrupt profile.yaml — history is advisory
  224. _profiles.logger.debug("profile rename: could not record previous name %r in %s: %s", old_canon, new_dir, exc)