conversation_compression_checkpoint.py 3.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293
  1. """Fail-closed pre-compress checkpoint gate for ``agent.conversation_compression``.
  2. The refusal type, its remediation text and the startup warning for
  3. ``compression.checkpoint_required``; ``conversation_compression`` re-exports every name.
  4. """
  5. from __future__ import annotations
  6. import logging
  7. from typing import Any
  8. from agent.memory_provider import PRE_COMPRESS_CHECKPOINT_API_VERSION
  9. # Log-record parity with the origin module.
  10. logger = logging.getLogger("agent.conversation_compression")
  11. class CompressionCheckpointUnavailable(RuntimeError):
  12. """Raised when required durable pre-compress checkpointing is unavailable."""
  13. # Shared by the startup warning and compress-time block so operators see the
  14. # same recovery path: disable the fail-closed flag, or switch providers.
  15. _CHECKPOINT_REQUIRED_REMEDIATION = (
  16. "set compression.checkpoint_required: false, or switch to a memory "
  17. "provider that implements checkpoint API v2"
  18. )
  19. def _active_memory_provider_label(agent: Any) -> str:
  20. """Human-readable active provider name, or an explicit none sentinel."""
  21. memory_manager = getattr(agent, "_memory_manager", None)
  22. if memory_manager is None:
  23. return "no active provider"
  24. providers = getattr(memory_manager, "providers", None)
  25. names: list[str] = []
  26. if providers is not None:
  27. try:
  28. iterable = list(providers)
  29. except TypeError:
  30. iterable = []
  31. for provider in iterable:
  32. name = getattr(provider, "name", None)
  33. if isinstance(name, str) and name.strip():
  34. names.append(name.strip())
  35. return ", ".join(names) if names else "no active provider"
  36. def _checkpoint_blocked(reason: str) -> CompressionCheckpointUnavailable:
  37. return CompressionCheckpointUnavailable(
  38. f"BLOCKED_MISSING_PREREQUISITE: required pre-compress checkpoint unavailable: {reason}"
  39. )
  40. def _checkpoint_incapable(reason: str) -> CompressionCheckpointUnavailable:
  41. """Capability refusal: the gate can never pass with this provider set, so the
  42. message carries the config-level way out. Transient checkpoint failures keep
  43. the plain form — there the provider is capable and the right move is a retry."""
  44. return _checkpoint_blocked(f"{reason}. Recover by {_CHECKPOINT_REQUIRED_REMEDIATION}")
  45. def _warn_checkpoint_required_without_capable_provider(agent: Any) -> None:
  46. """Startup warning when fail-closed compress will block (init itself must not refuse).
  47. Capability-probe exceptions are suppressed so a broken provider cannot crash
  48. agent construction — same fail-open style as the micro-compact warning.
  49. Probe failures log at DEBUG so a flaky probe can be diagnosed without
  50. refusing init or emitting the incapable-provider WARNING.
  51. """
  52. if getattr(agent, "compression_checkpoint_required", False) is not True:
  53. return
  54. memory_manager = getattr(agent, "_memory_manager", None)
  55. if memory_manager is not None:
  56. supports_checkpoint = getattr(memory_manager, "supports_pre_compress_checkpoint", None)
  57. if callable(supports_checkpoint):
  58. try:
  59. if bool(supports_checkpoint(PRE_COMPRESS_CHECKPOINT_API_VERSION)):
  60. return
  61. except Exception as exc:
  62. logger.debug(
  63. "checkpoint-required capability probe failed; init continues: %s",
  64. exc,
  65. exc_info=True,
  66. )
  67. return
  68. logger.warning(
  69. "compression.checkpoint_required is enabled but the active memory "
  70. "provider (%s) does not implement checkpoint API v%s. Compress will "
  71. "fail closed. Recover by %s.",
  72. _active_memory_provider_label(agent),
  73. PRE_COMPRESS_CHECKPOINT_API_VERSION,
  74. _CHECKPOINT_REQUIRED_REMEDIATION,
  75. )