prepared_compaction.py 30 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558
  1. """Opt-in prepared compaction (``compression.prepare_ahead``, default off).
  2. When the provider-reported prompt size comes within ``PREPARE_BAND_RATIO`` of
  3. the compaction trigger, the turn loop (before a tool batch runs, and at turn
  4. end) starts ONE background pass. The pass plans the same window
  5. ``ContextCompressor.compress`` would plan and runs the existing summariser on a
  6. copy of the compressor and of that window's messages. The live transcript and
  7. compressor are untouched, so the prompt cache is too.
  8. At the next automatic threshold compaction ``compress`` takes the completed
  9. summary if the messages it covers are still the same messages: same session,
  10. same head boundary, and the same message structure (roles, tool call and result ids) up to that boundary, each
  11. message vouched for by its durable ``message_uid``. The text of a persisted
  12. message is not compared: plugins rewrite text in place, and a summary written
  13. before such a rewrite still summarises the same messages. Only a message that
  14. has no uid on one side (caller-supplied history that is never persisted) is
  15. compared by text, since nothing else can tell it from a different message. On a hit the summary replaces
  16. ``messages[start:candidate_end]`` and every message after the candidate
  17. boundary, however many arrived since the pass started, stays verbatim in the
  18. tail. Where the fresh plan would cut does not matter, earlier or later: the
  19. summary is never redone over a moved cut, and the candidate boundary is the
  20. tail's start. On a miss compaction runs inline exactly as without the flag.
  21. When no completed summary exists but a running pass fits, compaction waits for
  22. that pass instead of starting the same summary over: the pass's streamed
  23. progress and local prompt reading feed the waiting compaction's hooks, so the
  24. host's idle watchdog and deadline extension see a live summary exactly as they
  25. would inline, and the wait ends at the host's deadline (the compression aux
  26. timeout without one), on cancellation, or when the pass is discarded. A pass
  27. that compaction or a session boundary supersedes is cancelled: its summary
  28. stream is closed instead of being billed to completion for nothing.
  29. State is per compressor and in memory only; every session boundary (reset,
  30. end, or a rebind to another session id) discards it. Manual, focus,
  31. overflow-recovery and memory-provider-context compactions always summarise
  32. fresh; the first compaction that needs provider context stops further passes
  33. for the agent, since every later one would need it too. A failed pass backs off
  34. further passes but never touches the live compressor's cooldown or failure
  35. state; a pass that recovered on the main model hands that fallback to the live
  36. compressor on a splice, as an inline summary would.
  37. """
  38. from __future__ import annotations
  39. import copy
  40. import hashlib
  41. import logging
  42. import threading
  43. import time
  44. from dataclasses import dataclass, field, replace
  45. from typing import Any, Callable, Optional
  46. logger = logging.getLogger(__name__)
  47. # Start a pass once the real prompt count is within this fraction of the
  48. # compaction trigger (a band below ``threshold_tokens``).
  49. PREPARE_BAND_RATIO = 0.12
  50. # Minimum pause after a failed pass (the summariser's own cooldown applies when longer).
  51. _FAILED_PASS_BACKOFF_SECONDS = 60.0
  52. # Background passes running across the process (a cancelled pass frees its slot as it unwinds; its
  53. # provider stream closes on the aux cancel path, normally within one chunk).
  54. _slots = threading.BoundedSemaphore(2)
  55. # How often a compaction waiting on a running pass re-checks cancellation and the deadline.
  56. _WAIT_POLL_SECONDS = 0.5
  57. # Compressor state a summary call leaves behind besides the summary: the main-model fallback after a
  58. # failed summary model and the warning it raises (the next compaction tries the summary model again,
  59. # inline or prepared alike). A splice adopts the pass's.
  60. _SUMMARY_CALL_STATE = (
  61. "summary_model", "_last_aux_model_failure_error", "_last_aux_model_failure_model", "_last_aux_resolved_model",
  62. )
  63. # Attempt telemetry the summary call fills; a splice copies the pass's values onto the attempt.
  64. _SUMMARY_CALL_TELEMETRY = (
  65. "aux_prompt_tokens", "aux_output_reservation", "aux_provider", "aux_model", "effective_aux_context", "fit_margin",
  66. "aux_call_duration_ms", "queue_wait_ms", "prompt_build_ms", "time_to_first_progress_ms", "summary_generation_ms",
  67. "summary_input_chars", "summary_input_sampled_chars", "summary_input_omitted_chars", "summary_input_record_count",
  68. "summary_input_sampled_record_count", "summary_input_elided_record_count", "fallback_used", "failure_class",
  69. )
  70. # Per message: (structure, durable uid or None, text digest).
  71. _Identity = tuple[str, Optional[str], str]
  72. # Why a compaction stopped waiting on a running pass; the pass then records it as its cancel reason.
  73. _WAIT_CANCEL_REASONS = frozenset({"wait_timeout", "host_cancelled"})
  74. class _Miss(str):
  75. """A splice-miss reason: the log text, plus the closed code opt-in shared metrics count."""
  76. code: str
  77. def __new__(cls, code: str, text: str) -> _Miss:
  78. miss = super().__new__(cls, text)
  79. miss.code = code
  80. return miss
  81. def _record(event: str, **dims: Any) -> None:
  82. """Count one event in opt-in shared metrics (a no-op when off; never raises)."""
  83. from hermes_cli.observability.shared_metrics_prepared_compaction import record_prepared_compaction
  84. record_prepared_compaction(event, **dims)
  85. @dataclass(frozen=True)
  86. class _Window:
  87. session_id: str
  88. compress_start: int
  89. compress_end: int
  90. identities: tuple[_Identity, ...] # one per message of ``messages[:compress_end]``
  91. @dataclass(frozen=True)
  92. class PreparedSummary(_Window):
  93. summary: str # prefixed handoff text, exactly as ``_generate_summary`` returns it
  94. body: str # bare body the next compaction extends iteratively
  95. call_state: dict[str, Any] = field(default_factory=dict, compare=False) # _SUMMARY_CALL_STATE after the pass
  96. telemetry: dict[str, Any] = field(default_factory=dict, compare=False) # _SUMMARY_CALL_TELEMETRY of the pass
  97. waited: Optional[float] = field(default=None, compare=False) # seconds the taking compaction waited on the pass
  98. class _PendingPass:
  99. """The one running pass allowed to publish: its planned window, completion and cancel events, and
  100. the progress and prompt-reading hooks of a compaction waiting on it."""
  101. def __init__(self, window: _Window) -> None:
  102. self.window = window
  103. self.done = threading.Event()
  104. # Set once nothing can use the pass any more; its summary stream is closed (the aux hard-cancel path).
  105. self.cancelled = threading.Event()
  106. self.cancel_reason = "superseded" # set by whoever cancels first; the pass records it
  107. self.on_progress: Optional[Callable[[], None]] = None
  108. self.on_reading: Optional[Callable[[float], None]] = None
  109. def cancel(self, reason: str) -> None:
  110. if not self.cancelled.is_set():
  111. self.cancel_reason = reason
  112. self.cancelled.set()
  113. def touch(self) -> None:
  114. hook = self.on_progress
  115. if hook is not None:
  116. hook()
  117. def read(self, seconds: float) -> None:
  118. hook = self.on_reading
  119. if hook is not None:
  120. hook(seconds)
  121. def _message_identity(msg: Any) -> _Identity:
  122. """Role, tool call ids/names and tool result ids; the durable ``message_uid`` when the message has
  123. been persisted; and a digest of its text for messages no uid vouches for. Tool arguments and result
  124. bodies are left out: the no-LLM prune rewrites them in place."""
  125. if not isinstance(msg, dict):
  126. return "?", None, ""
  127. from agent.memory_manager import sanitize_context
  128. from agent.message_content import flatten_message_text
  129. from agent.message_metadata import message_uid_or_none
  130. role = str(msg.get("role") or "")
  131. uid = message_uid_or_none(msg)
  132. if role == "tool":
  133. return f"tool\x1f{msg.get('tool_call_id') or ''}", uid, ""
  134. # Normalised the way a SessionDB round trip normalises it.
  135. text = sanitize_context(flatten_message_text(msg.get("content"))).strip()
  136. digest = hashlib.blake2b(text.encode("utf-8", errors="replace"), digest_size=8).hexdigest()
  137. parts = [role]
  138. for tc in msg.get("tool_calls") or []:
  139. if isinstance(tc, dict):
  140. fn = tc.get("function") or {}
  141. parts.append(f"{tc.get('id', '')}:{fn.get('name', '') if isinstance(fn, dict) else ''}")
  142. else:
  143. parts.append(f"{getattr(tc, 'id', '')}:{getattr(getattr(tc, 'function', None), 'name', '')}")
  144. return "\x1f".join(parts), uid, digest
  145. def prefix_identities(messages: list[dict[str, Any]], end: int) -> tuple[_Identity, ...]:
  146. """Identity of each message in ``messages[:end]``."""
  147. return tuple(_message_identity(msg) for msg in messages[:end])
  148. def _mismatch(window: _Window, messages: list[dict[str, Any]], session_id: str, start: int) -> Optional[_Miss]:
  149. """Why *window* cannot splice into ``messages`` with the head ending at ``start``, or None. The fresh tail
  150. cut is not consulted: the candidate's boundary is where the tail starts (one summary, never redone)."""
  151. if window.session_id != session_id:
  152. return _Miss("other_session", "another session")
  153. if window.compress_start != start:
  154. return _Miss("head_moved", f"head moved ({window.compress_start} -> {start})")
  155. if window.compress_end > len(messages):
  156. return _Miss("transcript_shorter", "transcript shorter than the prepared window")
  157. for idx, ((structure, uid, digest), msg) in enumerate(zip(window.identities, messages)):
  158. now_structure, now_uid, now_digest = _message_identity(msg)
  159. if now_structure != structure:
  160. return _Miss("shape_changed", f"message {idx} changed shape")
  161. if uid and now_uid:
  162. if uid != now_uid:
  163. return _Miss("rewound", f"message {idx} is a different message (rewound or branched)")
  164. elif digest != now_digest:
  165. return _Miss("text_changed", f"message {idx} changed and has no durable id to vouch for it")
  166. return None
  167. def _worker_copy(compressor: Any) -> Any:
  168. """A compressor copy whose writes stay off the live one: no durable row, private attempt
  169. telemetry, no host cancel consult (those belong to a foreground attempt), and the per-call
  170. fallback fields cleared as a compaction attempt clears them."""
  171. worker = copy.copy(compressor)
  172. worker._session_db = None
  173. worker._compression_cancelled_check = None
  174. worker._last_aux_model_failure_error = worker._last_aux_model_failure_model = None
  175. worker._begin_compression_telemetry(current_tokens=None)
  176. return worker
  177. def _blocked_for_platform(agent: Any, origin: str) -> bool:
  178. """A turn-end pass in a session that ends with its turn (a cron run, a delegated child, a one-shot) is never
  179. used."""
  180. if origin != "turn-end":
  181. return False
  182. if getattr(agent, "platform", None) in ("cron", "subagent") or getattr(agent, "_delegate_depth", 0) > 0:
  183. return True
  184. from agent.oneshot_footprint import agent_is_oneshot
  185. return agent_is_oneshot(agent) # ``chat -q``: the agent is released right after the reply
  186. class PreparedCompaction:
  187. """Prepared-summary state owned by one ``ContextCompressor``."""
  188. def __init__(self) -> None:
  189. self._lock = threading.Lock()
  190. self._entry: Optional[PreparedSummary] = None
  191. self._pending: Optional[_PendingPass] = None # the one pass allowed to publish
  192. self._retry_after = 0.0 # monotonic; set by a failed pass
  193. # Set by the first compaction that needed memory-provider context; such compactions summarise fresh.
  194. self._needs_provider_context = False
  195. self._busy_window: Optional[tuple[str, int, int]] = None # last window the slot cap refused (counted once)
  196. self._taken: Optional[PreparedSummary] = None # handed to compress(), not yet spliced by adopt()
  197. # The attempt that spliced the last summary. Lives here, not on the compressor, because a pre-commit
  198. # cancel restores the compressor's attempt telemetry (and its prepared_summary flag) before the
  199. # attempt record is emitted.
  200. self.spliced_attempt_id: Optional[str] = None
  201. self._boundaries = 0 # discard() calls that dropped something; a wait that spans one was discarded
  202. def _count_unspliced(self) -> None:
  203. """A summary take() handed out that adopt() never spliced (the compaction aborted or no-opped after
  204. taking it) is counted once, at the next touch, so every summary ends as used or discarded."""
  205. with self._lock:
  206. taken, self._taken = self._taken, None
  207. if taken is not None:
  208. _record("discarded", reason="compaction_aborted", wait_seconds=taken.waited)
  209. def discard(self, reason: str, code: str = "session_boundary") -> None:
  210. """Drop the candidate and cancel a running pass (it can no longer publish); ``code`` is the closed
  211. reason opt-in shared metrics count."""
  212. self._count_unspliced()
  213. with self._lock:
  214. entry, pending, self._entry, self._pending = self._entry, self._pending, None, None
  215. if pending is not None:
  216. pending.cancel(code) # under the lock: the pass reads its cancel reason after it
  217. if entry is not None or pending is not None:
  218. self._boundaries += 1
  219. if entry is not None or pending is not None:
  220. _record("discarded", reason=code)
  221. dropped = entry or (pending.window if pending is not None else None)
  222. if dropped is not None:
  223. logger.info(
  224. "prepared compaction: dropped session=%s window=%d-%d reason=%s%s", dropped.session_id,
  225. dropped.compress_start, dropped.compress_end, reason, "" if entry is not None else " (pass running)",
  226. )
  227. def stop_for_provider_context(self) -> None:
  228. """A memory provider supplied summary context: stop preparing summaries that would be discarded."""
  229. if not self._needs_provider_context:
  230. self._needs_provider_context = True
  231. logger.info("prepared compaction: off for this agent (memory provider supplies compaction context)")
  232. _record("auto_disabled", reason="provider_context")
  233. def take(
  234. self, messages: list[dict[str, Any]], session_id: str, start: int, *, eligible: bool,
  235. ) -> Optional[PreparedSummary]:
  236. """The completed candidate when it still covers the same messages after ``compress()``'s head, else
  237. what a running pass whose window does publishes while this compaction waits for it, else None. Either way the state is
  238. cleared and a running pass is cancelled: this compaction consumes or supersedes it."""
  239. self._count_unspliced()
  240. with self._lock:
  241. entry, pending = self._entry, self._pending
  242. self._entry = None
  243. boundaries = self._boundaries
  244. reason = None if eligible else _Miss(
  245. "provider_context" if self._needs_provider_context else "fresh_required", "fresh summary required",
  246. )
  247. if reason is None and entry is not None:
  248. reason = _mismatch(entry, messages, session_id, start)
  249. waited = None
  250. try:
  251. if eligible and (entry is None or reason is not None):
  252. if pending is not None and _mismatch(pending.window, messages, session_id, start) is None:
  253. wait_started = time.monotonic()
  254. entry, reason = self._await(pending)
  255. waited = time.monotonic() - wait_started
  256. if entry is None and self._boundaries != boundaries:
  257. # The pass published, then a boundary dropped it before this wait read it: a discard,
  258. # already counted by the boundary, not a failed pass.
  259. reason = _Miss("discarded_while_waiting", "running pass discarded")
  260. elif entry is None:
  261. reason = _Miss(
  262. "running_not_fit", "running pass does not fit",
  263. ) if pending is not None else _Miss("none", "no candidate")
  264. finally:
  265. with self._lock:
  266. if self._pending is pending:
  267. self._pending = None
  268. # A pass that published after the snapshot above planned on the pre-compaction transcript.
  269. self._entry = None
  270. if pending is not None:
  271. # Done already, or superseded: stop paying for it.
  272. code = getattr(reason, "code", None)
  273. pending.cancel(code if code in _WAIT_CANCEL_REASONS else "superseded")
  274. if reason is not None or entry is None:
  275. if entry is not None or pending is not None:
  276. logger.info("prepared compaction: splice miss session=%s reason=%s", session_id, reason)
  277. if reason.code != "discarded_while_waiting": # the discard() that woke the wait counted it
  278. _record("discarded", reason=reason.code, wait_seconds=waited)
  279. return None
  280. logger.info(
  281. "prepared compaction: splice hit session=%s window=%d-%d", session_id, entry.compress_start,
  282. entry.compress_end,
  283. )
  284. taken = replace(entry, waited=waited) # counted as used once adopt() splices it
  285. with self._lock:
  286. self._taken = taken
  287. return taken
  288. def _await(self, pending: _PendingPass) -> tuple[Optional[PreparedSummary], Optional[_Miss]]:
  289. """Wait on the compacting thread for *pending*: what it published, or None and why (the host's
  290. deadline, or the compression aux timeout without one; a host cancel; a discard; a failed pass).
  291. Meanwhile the pass's streamed progress and local prompt reading feed this thread's hooks, so the
  292. host's idle watchdog and deadline extension see a live summary exactly as they would inline; the
  293. deadline is re-read on every poll because prompt reading pushes it back."""
  294. from agent.auxiliary_client import (
  295. _aux_progress, _capture_aux_cancel_check, _captured_aux_cancel_requested, _current_aux_stream_deadline,
  296. _effective_aux_timeout,
  297. )
  298. from agent.local_prompt_progress import current_prompt_reading_hook
  299. # Hooks first: the pass may stream while the rest of the setup runs (the timeout loads config).
  300. pending.on_progress = getattr(_aux_progress, "hook", None)
  301. pending.on_reading = current_prompt_reading_hook()
  302. cancel_check = _capture_aux_cancel_check()
  303. fallback = time.monotonic() + float(_effective_aux_timeout("compression", None))
  304. logger.info(
  305. "prepared compaction: waiting for the running pass session=%s window=%d-%d",
  306. pending.window.session_id, pending.window.compress_start, pending.window.compress_end,
  307. )
  308. try:
  309. while not pending.done.wait(
  310. max(0.0, min(_WAIT_POLL_SECONDS, (_current_aux_stream_deadline() or fallback) - time.monotonic())),
  311. ):
  312. if pending.cancelled.is_set():
  313. return None, _Miss("discarded_while_waiting", "running pass discarded")
  314. if cancel_check is not None and _captured_aux_cancel_requested(cancel_check):
  315. return None, _Miss("host_cancelled", "host cancelled the wait")
  316. if time.monotonic() >= (_current_aux_stream_deadline() or fallback):
  317. return None, _Miss("wait_timeout", "running pass did not finish in time")
  318. finally:
  319. pending.on_progress = pending.on_reading = None
  320. with self._lock: # a discard() between the pass publishing and this wake took the entry and cancelled
  321. entry, self._entry = self._entry, None
  322. discarded = pending.cancelled.is_set()
  323. if discarded:
  324. return None, _Miss("discarded_while_waiting", "running pass discarded")
  325. if entry is None or entry.identities != pending.window.identities:
  326. return None, _Miss("pass_failed_while_waiting", "running pass failed")
  327. return entry, None
  328. def _blocked(self, agent: Any, compressor: Any, origin: str) -> bool:
  329. if not getattr(agent, "compression_enabled", False) or getattr(agent, "_persist_disabled", False):
  330. return True # compression off, or a background-review fork of the live session
  331. if (
  332. getattr(agent, "api_mode", None) == "codex_app_server"
  333. or getattr(agent, "codex_responses_native_compaction", False)
  334. or getattr(compressor, "_micro_compact_enabled", False)
  335. ):
  336. return True # another path owns compaction, or history is rewritten every turn
  337. if self._needs_provider_context or _blocked_for_platform(agent, origin):
  338. return True
  339. if compressor.awaiting_real_usage_after_compression or compressor._fallback_compression_streak >= 2:
  340. return True # no real usage yet, or the summary model is benched after repeated fallbacks
  341. tokens = compressor.last_prompt_tokens
  342. band_floor = int(compressor.threshold_tokens * (1 - PREPARE_BAND_RATIO))
  343. if tokens <= 0 or compressor.threshold_tokens <= 0 or tokens < band_floor:
  344. return True
  345. now = time.monotonic()
  346. return now < compressor._summary_failure_cooldown_until or now < self._retry_after
  347. def maybe_prepare(
  348. self, agent: Any, compressor: Any, messages: list[dict[str, Any]], origin: str,
  349. ) -> Optional[threading.Thread]:
  350. """Start the pass when the next compaction is near and none ran yet; returns the started thread.
  351. Never raises."""
  352. token: Optional[_PendingPass] = None
  353. try:
  354. self._count_unspliced()
  355. if self._blocked(agent, compressor, origin):
  356. return None
  357. with self._lock:
  358. if self._pending is not None or self._entry is not None:
  359. return None # one summary per compaction: later messages join the tail at the splice
  360. working, _, start, end = compressor._plan_compaction_window(messages)
  361. if start >= end:
  362. return None
  363. worker = _worker_copy(compressor)
  364. # Same handoff rehydration and window rows compress() uses (mutates only the worker).
  365. scan = worker._scan_window_handoffs(working, start, end, working[start:end])
  366. if scan.tail_start != end:
  367. return None # a handoff inside the protected tail: leave it to compress()
  368. turns = scan.turns_to_summarize
  369. if not turns:
  370. return None
  371. focus = worker._derive_auto_focus_topic(working)
  372. window = _Window(compressor._session_id, start, end, prefix_identities(working, end))
  373. # Never queue threads that retain transcripts while every slot is busy.
  374. if not _slots.acquire(blocking=False):
  375. if self._busy_window != (window.session_id, start, end): # count refused passes, not tool batches
  376. self._busy_window = (window.session_id, start, end)
  377. _record("skipped_busy", origin=origin)
  378. return None
  379. with self._lock:
  380. if self._pending is not None or self._entry is not None:
  381. _slots.release()
  382. return None
  383. token = self._pending = _PendingPass(window)
  384. from agent.memory_provider import spawn_context_thread
  385. # Profile and secret scope ride the contextvars into the pass.
  386. thread = spawn_context_thread(
  387. self._run_pass, name="compaction-prepare", args=(worker, copy.deepcopy(turns), focus, token, origin),
  388. )
  389. thread.start()
  390. _record("pass_started", origin=origin)
  391. return thread
  392. except Exception:
  393. if token is not None:
  394. with self._lock:
  395. if self._pending is token:
  396. self._pending = None
  397. token.done.set()
  398. _slots.release()
  399. logger.debug("prepared compaction: maybe_prepare failed", exc_info=True)
  400. _record("internal_error", origin=origin, failure_class="exception")
  401. return None
  402. def _run_pass(
  403. self, worker: Any, turns: list[dict[str, Any]], focus: Optional[str], token: _PendingPass, origin: str,
  404. ) -> None:
  405. from agent.auxiliary_client import AuxiliaryExplicitCancellation, aux_interrupt_protection, aux_progress_hook
  406. from agent.local_prompt_progress import prompt_reading_hook
  407. from agent.thread_scoped_output import thread_scoped_silence
  408. window = token.window
  409. entry: Optional[PreparedSummary] = None
  410. event, failure_class = "pass_cancelled", None # a published summary records pass_completed instead
  411. started = time.monotonic()
  412. try:
  413. logger.info(
  414. "prepared compaction: pass started session=%s origin=%s window=%d-%d turns=%d",
  415. window.session_id, origin, window.compress_start, window.compress_end, len(turns),
  416. )
  417. with (
  418. thread_scoped_silence(), aux_interrupt_protection(cancel_event=token.cancelled),
  419. aux_progress_hook(token.touch), prompt_reading_hook(token.read),
  420. ):
  421. summary = worker._generate_summary(turns, focus_topic=focus)
  422. if token.cancelled.is_set():
  423. logger.info("prepared compaction: pass cancelled session=%s after %.1fs (%s)", window.session_id,
  424. time.monotonic() - started, token.cancel_reason)
  425. elif summary:
  426. telemetry = worker._active_compression_telemetry or {}
  427. entry = PreparedSummary(
  428. window.session_id, window.compress_start, window.compress_end, window.identities,
  429. summary, worker._previous_summary,
  430. call_state={name: getattr(worker, name, None) for name in _SUMMARY_CALL_STATE},
  431. telemetry={key: telemetry.get(key) for key in _SUMMARY_CALL_TELEMETRY},
  432. )
  433. logger.info("prepared compaction: pass completed session=%s window=%d-%d in %.1fs",
  434. window.session_id, window.compress_start, window.compress_end, time.monotonic() - started)
  435. else:
  436. logger.warning("prepared compaction: pass failed session=%s after %.1fs: %s", window.session_id,
  437. time.monotonic() - started,
  438. worker._last_summary_error or "summariser returned nothing")
  439. event, failure_class = "pass_failed", _pass_failure_class(worker)
  440. except AuxiliaryExplicitCancellation:
  441. # The closed stream raises a BaseException; it must not reach the thread's excepthook (stderr).
  442. logger.info("prepared compaction: pass cancelled session=%s after %.1fs (%s)", window.session_id,
  443. time.monotonic() - started, token.cancel_reason)
  444. except Exception:
  445. logger.warning("prepared compaction: pass crashed session=%s", window.session_id, exc_info=True)
  446. event, failure_class = "internal_error", "exception"
  447. finally:
  448. with self._lock:
  449. if entry is not None and self._pending is token:
  450. event = "pass_completed"
  451. if self._pending is token:
  452. self._pending = None
  453. if entry is not None:
  454. self._entry = entry
  455. else:
  456. self._retry_after = max(
  457. worker._summary_failure_cooldown_until, time.monotonic() + _FAILED_PASS_BACKOFF_SECONDS,
  458. )
  459. token.done.set()
  460. _slots.release()
  461. _record(
  462. event, origin=origin, reason=token.cancel_reason if event == "pass_cancelled" else None,
  463. failure_class=failure_class,
  464. )
  465. def _pass_failure_class(worker: Any) -> str:
  466. """The class an inline attempt logs for this failed summary call: a terminal failure first."""
  467. from agent.context_compressor import _TERMINAL_SUMMARY_FAILURES
  468. terminal = next((cls for flag, cls, _ in _TERMINAL_SUMMARY_FAILURES if getattr(worker, flag, False)), None)
  469. return terminal or (worker._active_compression_telemetry or {}).get("failure_class") or "summary_generation_failed"
  470. def release_for_agent(agent: Any) -> None:
  471. """The agent is being released (cache eviction, rewind, close): no compaction of it can splice the summary,
  472. so stop paying for a running pass."""
  473. prepared = getattr(getattr(agent, "context_compressor", None), "prepared_compaction", None)
  474. if prepared is not None:
  475. prepared.discard("agent released", "agent_released")
  476. def adopt(compressor: Any, prepared: PreparedSummary) -> None:
  477. """Leave the live compressor as the inline summary call would have: the summary is the iterative base,
  478. failure state cleared, the pass's main-model fallback (if any) carried over, its call in the telemetry."""
  479. state = getattr(compressor, "prepared_compaction", None)
  480. telemetry = getattr(compressor, "_active_compression_telemetry", None)
  481. if state is not None:
  482. with state._lock:
  483. if state._taken is prepared:
  484. state._taken = None
  485. state.spliced_attempt_id = telemetry.get("attempt_id") if isinstance(telemetry, dict) else None
  486. compressor._record_summary_success(prepared.body)
  487. for name, value in prepared.call_state.items():
  488. setattr(compressor, name, value)
  489. if isinstance(telemetry, dict):
  490. telemetry.update({key: value for key, value in prepared.telemetry.items() if value is not None})
  491. telemetry["prepared_summary"] = True
  492. _record("used", reason="aux_fallback_main" if prepared.telemetry.get("fallback_used") else None,
  493. wait_seconds=prepared.waited)
  494. def maybe_prepare(agent: Any, messages: list[dict[str, Any]], *, origin: str) -> Optional[threading.Thread]:
  495. """Turn-loop hook; a no-op unless ``compression.prepare_ahead`` gave the compressor state."""
  496. compressor = getattr(agent, "context_compressor", None)
  497. state = getattr(compressor, "prepared_compaction", None)
  498. return state.maybe_prepare(agent, compressor, messages, origin) if state is not None else None