compaction_events.py 18 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344
  1. """Content-free ``hermes.compaction`` v1 records for every history rewrite, and their fan-out.
  2. One record per ``compress_context`` attempt (built from the attempt telemetry seam), per
  3. micro-compaction pass, per committed proactive tool-result prune, and per Codex-native thread
  4. compaction Hermes observes. A persistence-detached fork (background review) shares the live session id
  5. but rewrites only its own throwaway transcript, so it publishes nothing. The payload is flat because OpenTelemetry exporters flatten only top-level
  6. keys; every categorical field except the free-form ``summarizer_provider`` / ``summarizer_model`` identifiers
  7. comes from a closed set with an ``other`` fallback; no field carries message, summary, focus-topic, error or
  8. path text. Publishing never raises into compaction. A committed record also fires the ``post_compaction`` plugin
  9. hook, so plugins learn about every compaction the model will see without inferring it from history shrinkage.
  10. """
  11. from __future__ import annotations
  12. import functools
  13. import logging
  14. import threading
  15. import uuid
  16. from typing import Any
  17. from agent.model_metadata import estimate_messages_tokens_rough
  18. logger = logging.getLogger(__name__)
  19. SCHEMA_NAME = "hermes.compaction"
  20. SCHEMA_VERSION = "1"
  21. # Relay's reserved mark name: it resets the owning agent scope's LLM-history freshness, so it is used only
  22. # for a committed rewrite of what the model will see next. Everything else is an ordinary attempt mark.
  23. COMPACTION_MARK = "compaction"
  24. ATTEMPT_MARK = "compaction.attempt"
  25. # The v1 sets list only values this module emits. Later versions may add request-scope truncation kinds.
  26. _KINDS = frozenset({"summarize", "micro_summarize", "prune_tool_results", "provider_native"})
  27. _SCOPES = frozenset({"history", "provider"})
  28. _METHODS = frozenset({
  29. "llm_summary", "aux_fallback_main", "deterministic_fallback", "deterministic_prune", "provider", "none",
  30. })
  31. _TRIGGERS = frozenset({
  32. "manual", "turn_start_threshold", "pre_api", "post_tool", "idle", "engine_preflight", "overflow",
  33. "gateway_hygiene", "between_turns", "proactive_prune", "provider", "unknown",
  34. })
  35. # Every other known trigger is automatic; an unknown or unlisted one asserts nothing.
  36. _TRIGGER_CLASSES = {
  37. "manual": "manual", "overflow": "overflow", "provider": "provider", "unknown": "unknown", "other": "unknown",
  38. }
  39. _TRIGGER_CLASS_VALUES = frozenset({"auto", "manual", "overflow", "provider", "unknown"})
  40. # The error-classifier reasons whose recovery compresses with ``trigger="overflow"``.
  41. _OVERFLOW_REASONS = frozenset({"context_overflow", "payload_too_large", "long_context_tier"})
  42. _OUTCOMES = frozenset({"committed", "aborted", "failed", "skipped", "blocked"})
  43. _SPLIT_STATUSES = frozenset({
  44. "not_applicable", "in_place_committed", "rotated_committed", "failed_not_indexed", "aborted",
  45. })
  46. _TOKEN_COUNT_METHODS = frozenset({"estimate_rough"})
  47. # Attempt classes beyond the shared-metrics closed set: guards, Codex route exits, lease races, an engine's
  48. # empty transcript, and the micro-compaction pass outcomes.
  49. _EXTRA_FAILURE_CLASSES = frozenset({
  50. "blocked:cooldown", "blocked:structural_backoff", "blocked:ineffective", "blocked:unknown",
  51. "codex_auto_native", "codex_auto_off", "codex_no_thread", "codex_compaction_failed",
  52. "session_ownership_lost", "session_ownership_unreadable", "cooldown_state_unreadable", "empty_transcript",
  53. "summary_model_benched",
  54. "summarize_failed", "exchange_skipped", "defrag_failed", "stale_generation", "watermark_unavailable",
  55. })
  56. # An aborted attempt the compressor ran but deliberately did not commit; other aborts are failures.
  57. _ABORTED_CLASSES = frozenset({"would_grow", "no_progress", "commit_fence_cancelled"})
  58. _COMMIT_MODES = frozenset({"in_place_committed", "rotated_committed"})
  59. _MICRO_OUTCOMES = {
  60. "absorbed": "committed", "defrag": "committed", "stale_generation": "skipped", "watermark_unavailable": "skipped",
  61. }
  62. # Every v1 key, so consumers see a stable shape; unknown values stay null.
  63. _FIELDS = (
  64. "harness", "kind", "scope", "official", "method", "trigger", "trigger_class", "overflow_reason", "outcome",
  65. "failure_class", "attempt_id", "session_id", "tokens_before", "tokens_after", "tokens_reclaimed",
  66. "token_count_method", "messages_before", "messages_after", "items_dropped", "context_limit", "threshold_tokens",
  67. "protected_head_tokens", "middle_window_tokens", "protected_tail_tokens", "duration_ms",
  68. "summary_generation_ms", "aux_call_duration_ms", "queue_wait_ms", "commit_ms", "summarizer_provider",
  69. "summarizer_model", "tool_results_pruned", "reasoning_items_pruned", "summary_input_omitted_chars",
  70. "compression_count", "in_place", "session_rotated", "split_status", "cache_break", "has_focus_topic",
  71. )
  72. # Integer fields copied as-is from the attempt record (record key -> payload key).
  73. _ATTEMPT_INTS = {
  74. "tokens_before": "tokens_before", "tokens_after": "tokens_after", "tokens_reclaimed": "tokens_reclaimed",
  75. "messages_before": "messages_before", "messages_after": "messages_after", "items_dropped": "items_dropped",
  76. "main_context_limit": "context_limit", "effective_threshold": "threshold_tokens",
  77. "protected_head_tokens": "protected_head_tokens", "middle_window_tokens": "middle_window_tokens",
  78. "protected_tail_tokens": "protected_tail_tokens", "total_duration_ms": "duration_ms",
  79. "summary_generation_ms": "summary_generation_ms", "aux_call_duration_ms": "aux_call_duration_ms",
  80. "queue_wait_ms": "queue_wait_ms", "commit_ms": "commit_ms", "tool_results_pruned": "tool_results_pruned",
  81. "reasoning_items_pruned": "reasoning_items_pruned", "summary_input_omitted_chars": "summary_input_omitted_chars",
  82. }
  83. _warned_lock = threading.Lock()
  84. _warned = False
  85. @functools.cache
  86. def _failure_classes() -> frozenset[str]:
  87. from hermes_cli.observability.shared_metrics_contract import COMPRESSION_FAILURE_CLASSES
  88. return COMPRESSION_FAILURE_CLASSES | _EXTRA_FAILURE_CLASSES
  89. @functools.cache
  90. def _skip_classes() -> frozenset[str]:
  91. from hermes_cli.observability.shared_metrics_contract import COMPRESSION_SKIP_CLASSES
  92. return COMPRESSION_SKIP_CLASSES
  93. def _closed(value: Any, allowed: frozenset[str], default: str | None = "other") -> str | None:
  94. if not isinstance(value, str) or not value:
  95. return None
  96. return value if value in allowed else default
  97. def _int(value: Any) -> int | None:
  98. return value if isinstance(value, int) and not isinstance(value, bool) else None
  99. def failure_class(value: Any) -> str:
  100. """Closed failure class: ``exception:<Type>`` / ``rollback:<Type>`` keep only the prefix (the type name
  101. may be a plugin's); a missing class reads ``none``."""
  102. if not isinstance(value, str) or not value:
  103. return "none"
  104. if value.startswith(("exception:", "rollback:")):
  105. value = value.split(":", 1)[0]
  106. return value if value in _failure_classes() else "other"
  107. def event_name(payload: dict[str, Any]) -> str:
  108. """``compaction`` only for a committed history or provider rewrite; ``compaction.attempt`` otherwise."""
  109. committed = payload.get("outcome") == "committed" and payload.get("scope") in {"history", "provider"}
  110. return COMPACTION_MARK if committed else ATTEMPT_MARK
  111. def _payload(**values: Any) -> dict[str, Any]:
  112. payload = dict.fromkeys(_FIELDS)
  113. payload.update(values, harness="hermes")
  114. payload["kind"] = _closed(payload["kind"], _KINDS)
  115. payload["scope"] = _closed(payload["scope"], _SCOPES)
  116. payload["method"] = _closed(payload["method"], _METHODS) or "none"
  117. payload["trigger"] = _closed(payload["trigger"], _TRIGGERS) or "unknown"
  118. payload["trigger_class"] = (
  119. _closed(payload["trigger_class"], _TRIGGER_CLASS_VALUES, None) or _TRIGGER_CLASSES.get(payload["trigger"], "auto")
  120. )
  121. payload["outcome"] = _closed(payload["outcome"], _OUTCOMES) or "other"
  122. payload["token_count_method"] = _closed(payload["token_count_method"], _TOKEN_COUNT_METHODS)
  123. payload["attempt_id"] = payload["attempt_id"] or uuid.uuid4().hex
  124. payload["session_id"] = payload["session_id"] or ""
  125. if payload["cache_break"] is None and payload["scope"] == "history":
  126. payload["cache_break"] = payload["outcome"] == "committed"
  127. return payload
  128. def _attempt_outcome(commit_status: Any, failure: str, history_rewritten: Any) -> str:
  129. # A split that failed after publishing the compacted history still rewrote what the model sees next: it is
  130. # a committed compaction whose failure_class records the failure.
  131. if history_rewritten is True:
  132. return "committed"
  133. if commit_status != "aborted":
  134. return commit_status if commit_status in _OUTCOMES else "other"
  135. if failure in _skip_classes():
  136. return "skipped"
  137. return "aborted" if failure in _ABORTED_CLASSES else "failed"
  138. def _attempt_trigger(trigger_source: Any) -> tuple[Any, str | None]:
  139. """``(trigger, trigger_class)``. ``auto`` is what an unlabelled automatic caller records: the reason is
  140. unknown, but the attempt is still known to be automatic."""
  141. if trigger_source == "auto":
  142. return "unknown", "auto"
  143. return trigger_source or "unknown", None
  144. def attempt_payload(record: dict[str, Any], *, compression_count: Any = None) -> dict[str, Any]:
  145. """Map one attempt telemetry record (the attempt log line's dict) onto the v1 schema."""
  146. codex = record.get("route") == "codex_app_server"
  147. failure = failure_class(record.get("failure_class"))
  148. split_status = _closed(record.get("split_status"), _SPLIT_STATUSES)
  149. outcome = _attempt_outcome(record.get("commit_status"), failure, record.get("history_rewritten"))
  150. trigger, trigger_class = _attempt_trigger(record.get("trigger_source"))
  151. values: dict[str, Any] = {key: _int(record.get(src)) for src, key in _ATTEMPT_INTS.items()}
  152. values.update(
  153. kind="provider_native" if codex else "summarize", scope="provider" if codex else "history", official=True,
  154. method=record.get("method"), trigger=trigger, trigger_class=trigger_class,
  155. overflow_reason=_closed(record.get("overflow_reason"), _OVERFLOW_REASONS), outcome=outcome,
  156. failure_class=failure,
  157. attempt_id=record.get("attempt_id"), session_id=record.get("session_id"),
  158. token_count_method=record.get("token_count_method"),
  159. summarizer_provider=record.get("aux_provider") or None, summarizer_model=record.get("aux_model") or None,
  160. compression_count=_int(compression_count), split_status=split_status,
  161. # Commit mode is known only for a fully committed split; anything else leaves both null.
  162. in_place=split_status == "in_place_committed" if split_status in _COMMIT_MODES else None,
  163. session_rotated=split_status == "rotated_committed" if split_status in _COMMIT_MODES else None,
  164. has_focus_topic=record.get("has_focus_topic") if isinstance(record.get("has_focus_topic"), bool) else None,
  165. )
  166. if codex:
  167. values["cache_break"] = None # the Codex thread's provider cache is not Hermes's prompt cache
  168. return _payload(**values)
  169. def micro_payload(record: dict[str, Any]) -> dict[str, Any]:
  170. """Map one micro-compaction telemetry record onto the v1 schema."""
  171. outcome = _MICRO_OUTCOMES.get(record.get("outcome"), "failed")
  172. before, after = _int(record.get("tokens_before")), _int(record.get("tokens_after"))
  173. return _payload(
  174. kind="micro_summarize", scope="history", official=False, trigger="between_turns", outcome=outcome,
  175. method="llm_summary" if outcome == "committed" else "none",
  176. failure_class="none" if outcome == "committed" else failure_class(record.get("outcome")),
  177. session_id=record.get("session_id"), tokens_before=before, tokens_after=after,
  178. tokens_reclaimed=before - after if before is not None and after is not None else None,
  179. token_count_method="estimate_rough", messages_before=_int(record.get("messages_before")),
  180. messages_after=_int(record.get("messages_after")), duration_ms=_int(record.get("duration_ms")),
  181. threshold_tokens=_int(record.get("threshold_tokens")), context_limit=_int(record.get("context_limit")),
  182. summarizer_model=record.get("aux_model") or None,
  183. )
  184. def prune_payload(
  185. *, session_id: str, tokens_before: int, tokens_after: int, messages: int, tool_results_pruned: int,
  186. ) -> dict[str, Any]:
  187. """A committed proactive tool-result prune: deterministic, no LLM, message count unchanged."""
  188. return _payload(
  189. kind="prune_tool_results", scope="history", official=False, trigger="proactive_prune", outcome="committed",
  190. method="deterministic_prune", failure_class="none", session_id=session_id, tokens_before=tokens_before,
  191. tokens_after=tokens_after, tokens_reclaimed=tokens_before - tokens_after, token_count_method="estimate_rough",
  192. messages_before=messages, messages_after=messages, tool_results_pruned=tool_results_pruned,
  193. )
  194. def provider_native_payload(*, session_id: str, compression_count: Any = None) -> dict[str, Any]:
  195. """A compaction the provider ran on its own thread and Hermes only observed."""
  196. return _payload(
  197. kind="provider_native", scope="provider", official=False, trigger="provider", outcome="committed",
  198. method="provider", failure_class="none", session_id=session_id, compression_count=_int(compression_count),
  199. )
  200. def fire_post_compaction(
  201. *, session_id: str, old_session_id: str = "", kind: str | None, reason: str | None,
  202. before_tokens: int | None, after_tokens: int | None, messages_removed: int | None,
  203. ) -> None:
  204. """The ``post_compaction`` plugin hook, gated on a listener. Callbacks are isolated by the dispatcher."""
  205. from hermes_cli.lifecycle import has_hook, invoke_hook
  206. if has_hook("post_compaction"):
  207. invoke_hook(
  208. "post_compaction", session_id=session_id, old_session_id=old_session_id, kind=kind, reason=reason,
  209. before_tokens=before_tokens, after_tokens=after_tokens, messages_removed=messages_removed,
  210. )
  211. def _fire_for(payload: dict[str, Any], session_id: str) -> None:
  212. before, after = payload["messages_before"], payload["messages_after"]
  213. fire_post_compaction(
  214. session_id=session_id, old_session_id=payload["session_id"] if payload["session_id"] != session_id else "",
  215. kind=payload["kind"], reason=payload["trigger"], before_tokens=payload["tokens_before"],
  216. after_tokens=payload["tokens_after"],
  217. messages_removed=before - after if before is not None and after is not None else None,
  218. )
  219. def _publish(
  220. build: Any, *args: Any, turn_session_id: str | None = None, require_target_session_id: str | None = None,
  221. live_session_id: str | None = None, **kwargs: Any,
  222. ) -> None:
  223. """Build one record, fire ``post_compaction`` for a committed one, and fan it out to the built-in Relay
  224. integration. ``live_session_id`` is the session holding the compacted transcript now (a rotating commit
  225. moved it off the record's session). Never raises into compaction: the first failure logs at WARNING with
  226. its traceback, later ones at DEBUG."""
  227. global _warned
  228. try:
  229. relay = True
  230. if require_target_session_id is not None:
  231. from agent.relay_compaction import compaction_target_available
  232. relay = compaction_target_available(require_target_session_id, turn_session_id=turn_session_id)
  233. from hermes_cli.lifecycle import has_hook
  234. hook = has_hook("post_compaction")
  235. if not (relay or hook):
  236. return
  237. payload = build(*args, **kwargs)
  238. name = event_name(payload)
  239. if hook and name == COMPACTION_MARK:
  240. _fire_for(payload, live_session_id or payload["session_id"])
  241. if not relay:
  242. return
  243. from agent.relay_compaction import emit_compaction_mark
  244. emit_compaction_mark(payload["session_id"], name, payload, turn_session_id=turn_session_id)
  245. except Exception:
  246. with _warned_lock:
  247. first, _warned = not _warned, True
  248. logger.log(logging.WARNING if first else logging.DEBUG, "compaction event publish failed", exc_info=True)
  249. def _publishes_for(agent: Any) -> bool:
  250. """A persistence-detached fork (background review) rewrites only its own throwaway transcript."""
  251. return not getattr(agent, "_persist_disabled", False)
  252. def _turn_session_id(agent: Any) -> str | None:
  253. """The session the agent's current turn started in; a rotating commit moves ``agent.session_id`` off it
  254. mid-turn. ``None`` outside a turn."""
  255. value = getattr(agent, "_inflight_turn_session_id", None)
  256. return value if isinstance(value, str) and value else None
  257. def publish_attempt(agent: Any, record: dict[str, Any]) -> None:
  258. """Publish one ``compress_context`` attempt record (the attempt telemetry seam calls this)."""
  259. if _publishes_for(agent):
  260. _publish(lambda: attempt_payload(
  261. record, compression_count=getattr(getattr(agent, "context_compressor", None), "compression_count", None),
  262. ), turn_session_id=_turn_session_id(agent), live_session_id=getattr(agent, "session_id", None))
  263. def publish_micro(record: dict[str, Any], *, turn_session_id: str | None = None) -> None:
  264. """Publish one micro-compaction pass record. The finalizer never runs micro-compaction for a fork, and passes
  265. the session its turn started in (``_turn_session_id``) because the pass may run in a rotated child."""
  266. _publish(micro_payload, record, turn_session_id=turn_session_id)
  267. def publish_prune(agent: Any, messages: list, pruned: list, tool_results_pruned: int) -> None:
  268. """Publish one committed proactive tool-result prune, measured like the attempt record (rough estimate of
  269. the message list the model sees next)."""
  270. session_id = getattr(agent, "session_id", None) or ""
  271. turn_session_id = _turn_session_id(agent)
  272. if _publishes_for(agent):
  273. _publish(lambda: prune_payload(
  274. session_id=session_id, tokens_before=estimate_messages_tokens_rough(messages),
  275. tokens_after=estimate_messages_tokens_rough(pruned), messages=len(pruned),
  276. tool_results_pruned=tool_results_pruned,
  277. ), turn_session_id=turn_session_id, require_target_session_id=session_id)
  278. def publish_provider_native(agent: Any) -> None:
  279. """Publish one provider-native compaction Hermes observed but did not run."""
  280. if _publishes_for(agent):
  281. _publish(
  282. provider_native_payload, session_id=getattr(agent, "session_id", None) or "",
  283. compression_count=getattr(getattr(agent, "context_compressor", None), "compression_count", None),
  284. turn_session_id=_turn_session_id(agent),
  285. )