"""Prepared compaction (``compression.prepare_ahead``): adoption and every way a prepared pass is wasted. The daily snapshot carries ``compression_prepare_ahead`` (``on``/``off``), read with the agent's own truthiness, so "active installs with the feature on" needs no join. ``hermes.prepared_compaction.count`` counts each pass and splice outcome from ``agent/prepared_compaction.py`` (and a spliced compaction that then failed, from ``agent/conversation_compression_telemetry.py``) over closed sets only: the event, the hook that started the pass, a reason code (never the free-text miss reason), the compression failure class, and how long a compaction waited on a running pass, bucketed. The contract imports this module at load time, so it never imports the contract at module level. """ from __future__ import annotations from typing import Any PREPARED_COMPACTION_MARK = PREPARED_COMPACTION_METRIC = "hermes.prepared_compaction.count" PREPARED_COMPACTION_EVENTS = frozenset({ "auto_disabled", "compaction_failed", "discarded", "internal_error", "pass_cancelled", "pass_completed", "pass_failed", "pass_started", "skipped_busy", "used", }) PREPARED_COMPACTION_ORIGINS = frozenset({"none", "tool_batch", "turn_end"}) PREPARED_COMPACTION_REASONS = frozenset({ "agent_released", "aux_fallback_main", "compaction_aborted", "fresh_required", "head_moved", "host_cancelled", "none", "other_session", "pass_failed_while_waiting", "provider_context", "rewound", "running_not_fit", "session_boundary", "shape_changed", "superseded", "text_changed", "transcript_shorter", "wait_timeout", }) PREPARED_COMPACTION_WAIT_BUCKETS = frozenset({"none", "lt_1s", "1s_to_5s", "5s_to_30s", "30s_to_120s", "gte_120s"}) _WAIT_THRESHOLDS = ((1, "lt_1s"), (5, "1s_to_5s"), (30, "5s_to_30s"), (120, "30s_to_120s")) # failure_class (the compression vocabulary) is added by the contract, which owns that set. PREPARED_COMPACTION_DIMENSIONS = { "event": PREPARED_COMPACTION_EVENTS, "origin": PREPARED_COMPACTION_ORIGINS, "reason": PREPARED_COMPACTION_REASONS, "wait_bucket": PREPARED_COMPACTION_WAIT_BUCKETS, } PREPARED_COMPACTION_SNAPSHOT_DIMENSIONS = {"compression_prepare_ahead": frozenset({"off", "on"})} def prepare_ahead_state(config: Any) -> str: """``on`` when the profile config turns ``compression.prepare_ahead`` on, read as the agent reads it.""" from utils import is_truthy_value compression = config.get("compression") if isinstance(config, dict) else None value = compression.get("prepare_ahead") if isinstance(compression, dict) else None return "on" if is_truthy_value(value, default=False) else "off" def wait_bucket(seconds: Any) -> str: if isinstance(seconds, bool) or not isinstance(seconds, (int, float)) or seconds < 0: return "none" return next((label for limit, label in _WAIT_THRESHOLDS if seconds < limit), "gte_120s") def _closed(value: Any, allowed: frozenset[str], fallback: str) -> str: text = str(value or "").strip().lower().replace("-", "_") return text if text in allowed else fallback def prepared_compaction_fields( *, event: Any, origin: Any, reason: Any, failure_class: Any, wait_seconds: Any, ) -> dict[str, str] | None: """Closed dimensions for one event; ``None`` for an event outside the set (never recorded).""" from .shared_metrics_fields import compression_failure_class name = _closed(event, PREPARED_COMPACTION_EVENTS, "") if not name: return None return { "event": name, "failure_class": "none" if failure_class is None else compression_failure_class("failed", failure_class), "origin": _closed(origin, PREPARED_COMPACTION_ORIGINS, "none"), "reason": _closed(reason, PREPARED_COMPACTION_REASONS, "none"), "wait_bucket": wait_bucket(wait_seconds), } def record_prepared_compaction( event: str, *, origin: str | None = None, reason: str | None = None, failure_class: str | None = None, wait_seconds: float | None = None, ) -> None: """Count one prepared-compaction event (no-op unless shared metrics are on; never raises).""" from .shared_metrics_events import _emit _emit( PREPARED_COMPACTION_MARK, prepared_compaction_fields, event=event, origin=origin, reason=reason, failure_class=failure_class, wait_seconds=wait_seconds, )