hermes_state_rewind.py 10 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169
  1. """Carrier-aware user-turn rewind (``/undo``, ``/retry``) — the ONE implementation behind the CLI, the
  2. gateway and the TUI. Rewind is a persisted-history operation: the durable transcript is the authority,
  3. the warm (in-memory) history only has to agree with it. A composite compaction carrier (retained
  4. summary + live human ask in one row) keeps its hidden handoff scaffold as the new head."""
  5. from __future__ import annotations
  6. from dataclasses import dataclass
  7. from typing import Any, Dict, List, Optional
  8. _HISTORY_CHANGED = "session history changed before the rewind could be persisted"
  9. class RewindTargetUnavailableError(ValueError):
  10. """The requested user turn is not a rewindable target of the active transcript: no user turns, an
  11. ordinal past the newest one, a row that is not user-originated, or a plain turn where the caller
  12. required a compaction carrier. Surfaces map this to their own "nothing to undo" message."""
  13. @dataclass
  14. class RewindPlan:
  15. target_row_id: int
  16. expected_active_ids: list[int]
  17. expected_target_content: Any
  18. scaffold: Optional[dict[str, Any]]
  19. prefix: list[dict[str, Any]]
  20. durable_prefix: list[dict[str, Any]]
  21. live_view: dict[str, Any]
  22. live_text: Optional[str]
  23. durable_user: list[int]
  24. user_ordinal: int
  25. @dataclass
  26. class RewindOutcome:
  27. prefix: list[dict[str, Any]] # history to install: the warm prefix when ``warm_history`` was given, else durable
  28. live_view: dict[str, Any] # canonical live projection of the rewound turn (prefill / retry source)
  29. live_text: str # lossless retry text when ``require_retryable``, else the display flattening (prefill)
  30. rewound_count: int
  31. turns_undone: int
  32. def _user_indices(messages: list[dict[str, Any]]) -> list[int]:
  33. from agent.context_compressor import user_originated_turn_view
  34. return [i for i, m in enumerate(messages) if user_originated_turn_view(m) is not None]
  35. def _comparison_content(message: dict[str, Any]) -> Any:
  36. """Project content the way the durable row stores it (flush projection, then the read-side sanitize) so a
  37. warm row and its durable twin compare equal."""
  38. from agent.session_persistence import _durable_content
  39. from hermes_state_messages import SessionMessagesMixin
  40. return SessionMessagesMixin._loaded_view_content(message.get("role"), _durable_content(message.get("content")))
  41. class SessionRewindMixin:
  42. """``SessionDB`` mixin: soft-delete from one user turn onward, validated against the warm history."""
  43. def rewind_user_turn(
  44. self, session_id: str, user_ordinal: int, *, warm_history: Optional[list[dict[str, Any]]] = None,
  45. require_retryable: bool = False, require_composite: bool = False, adopt_row_ids: bool = False,
  46. ) -> RewindOutcome:
  47. """Rewind the active transcript to just before user turn ``user_ordinal`` (0 = oldest; negative counts
  48. back from the newest and clamps to the oldest, so ``-n`` is ``/undo n``). ``warm_history`` (CLI/TUI):
  49. the in-memory view must have the same user turns and the same live target text as the durable
  50. transcript, else ``RuntimeError`` and nothing changes; its (richer) prefix is what gets installed.
  51. ``require_retryable``: the live payload must be losslessly replayable as text (``ValueError`` from
  52. :func:`retryable_user_text` before any write). ``require_composite``: the target must be a compaction
  53. carrier. ``adopt_row_ids`` (TUI): copy durable ``_row_id`` identities onto the installed warm prefix so
  54. clients can address follow-ups by row; the CLI leaves its history shape alone. Out-of-range /
  55. wrong-shape targets raise :class:`RewindTargetUnavailableError`."""
  56. from agent.context_compressor import _DB_PERSISTED_MARKER
  57. from agent.message_content import flatten_message_text
  58. from agent.message_metadata import MESSAGE_UID, message_uid_or_none
  59. plan = self.plan_user_turn_rewind(session_id, user_ordinal, warm_history=warm_history,
  60. require_retryable=require_retryable, require_composite=require_composite)
  61. (prefix, durable_prefix, live_view, live_text, scaffold, durable_user,
  62. user_ordinal) = (plan.prefix, plan.durable_prefix, plan.live_view, plan.live_text, plan.scaffold,
  63. plan.durable_user, plan.user_ordinal)
  64. try:
  65. result = self.rewind_to_message(
  66. session_id, plan.target_row_id, preserve_compaction_handoff=scaffold is not None,
  67. expected_active_ids=plan.expected_active_ids, expected_target_content=plan.expected_target_content)
  68. except ValueError as exc: # target vanished / changed role under us: same class of failure as out-of-range
  69. raise RewindTargetUnavailableError(str(exc)) from exc
  70. if scaffold is not None:
  71. replacement_id = result.get("replacement_message_id")
  72. if not isinstance(replacement_id, int) or not durable_prefix:
  73. raise RuntimeError("rewind did not retain its compaction handoff")
  74. # The installed scaffold IS the replacement row: carry its identity, not just its row id.
  75. durable_prefix[-1].update({"_row_id": replacement_id, _DB_PERSISTED_MARKER: True})
  76. if replacement_uid := result.get("replacement_message_uid"):
  77. durable_prefix[-1][MESSAGE_UID] = replacement_uid
  78. prefix[-1] = durable_prefix[-1]
  79. if adopt_row_ids and prefix is not durable_prefix and len(prefix) == len(durable_prefix) and all(
  80. warm.get("role") == durable_message.get("role")
  81. and bool(warm.get("display_kind")) == bool(durable_message.get("display_kind"))
  82. and _comparison_content(warm) == _comparison_content(durable_message)
  83. for warm, durable_message in zip(prefix, durable_prefix)
  84. ):
  85. # Clients address follow-ups by durable row id: keep the richer warm content, adopt the identities.
  86. for warm, durable_message in zip(prefix, durable_prefix):
  87. if isinstance(row_id := durable_message.get("_row_id"), int):
  88. warm["_row_id"] = row_id
  89. if uid := message_uid_or_none(durable_message):
  90. warm[MESSAGE_UID] = uid
  91. return RewindOutcome(
  92. prefix=prefix, live_view=live_view,
  93. live_text=live_text if live_text is not None else flatten_message_text(live_view.get("content")),
  94. rewound_count=int(result.get("rewound_count", 0)), turns_undone=len(durable_user) - user_ordinal)
  95. def plan_user_turn_rewind(
  96. self, session_id: str, user_ordinal: int, *, warm_history: Optional[list[dict[str, Any]]] = None,
  97. require_retryable: bool = False, require_composite: bool = False,
  98. ) -> RewindPlan:
  99. """Every read and check :meth:`rewind_user_turn` makes before its write, with no write: the
  100. gateway ``/retry`` commits the planned rewind inside its re-send's admission transaction
  101. (``rewind_in_transaction`` with the plan's pins), so a refused re-send leaves it unapplied."""
  102. from agent.context_compressor import (
  103. history_before_user_originated_turn, retryable_user_text,
  104. split_user_originated_turn, user_originated_turn_view)
  105. from agent.session_persistence import _is_ephemeral_scaffolding
  106. expected_active_ids = self.get_active_message_ids(session_id)
  107. stored = self.get_messages_as_conversation(session_id, include_row_ids=True)
  108. # Live replay (the pre-request repair, a resume) merges a stored ``user;user`` pair — an ask whose turn
  109. # ended with no reply, then the next ask — into ONE turn while both rows stay stored. Address turns on
  110. # that same repaired projection or the warm history is a turn short of the transcript forever
  111. # (#115493); the merged turn keeps the first row's identity, so the rewind starts at that row.
  112. durable = self.get_messages_as_conversation(session_id, include_row_ids=True, repair_alternation=True)
  113. durable_user = _user_indices(durable)
  114. if user_ordinal < 0:
  115. user_ordinal = max(len(durable_user) + user_ordinal, 0)
  116. if user_ordinal >= len(durable_user):
  117. raise RewindTargetUnavailableError("target user message is no longer in session history")
  118. target_index = durable_user[user_ordinal]
  119. target = durable[target_index]
  120. durable_prefix, live_view = history_before_user_originated_turn(durable, target_index)
  121. scaffold, _ = split_user_originated_turn(target)
  122. if require_composite and scaffold is None:
  123. raise RewindTargetUnavailableError("target user message is not a compaction carrier")
  124. prefix = durable_prefix
  125. if warm_history is not None:
  126. warm = [m for m in warm_history if not _is_ephemeral_scaffolding(m)]
  127. warm_user = _user_indices(warm)
  128. if len(warm_user) != len(durable_user):
  129. raise RuntimeError(_HISTORY_CHANGED)
  130. prefix, warm_live_view = history_before_user_originated_turn(warm, warm_user[user_ordinal])
  131. if _comparison_content(live_view) != _comparison_content(warm_live_view):
  132. raise RuntimeError(_HISTORY_CHANGED)
  133. # Retry re-sends the stored bytes: ``"".join`` of the text parts, never the "\n"-joined display
  134. # flattening (wire bytes == stored bytes; ``"ab"`` must not come back as ``"a\nb"``).
  135. live_text = retryable_user_text(live_view.get("content")) if require_retryable else None
  136. target_row_id = target.get("_row_id")
  137. if not isinstance(target_row_id, int):
  138. raise RuntimeError("rewind target has no durable row identity")
  139. # The in-txn payload pin compares against the STORED row, which for a merged turn holds only the
  140. # first ask, never the merged text the live views carry.
  141. stored_view = next(
  142. (user_originated_turn_view(m) for m in stored if m.get("_row_id") == target_row_id), None)
  143. if stored_view is None:
  144. raise RuntimeError(_HISTORY_CHANGED)
  145. return RewindPlan(
  146. target_row_id=target_row_id, expected_active_ids=expected_active_ids,
  147. expected_target_content=stored_view.get("content"), scaffold=scaffold, prefix=prefix,
  148. durable_prefix=durable_prefix, live_view=live_view, live_text=live_text, durable_user=durable_user,
  149. user_ordinal=user_ordinal)