geny-executor 2.4.1__tar.gz → 2.5.0__tar.gz

{geny_executor-2.4.1 → geny_executor-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: geny-executor
-Version: 2.4.1
+Version: 2.5.0
 Summary: Harness-engineered agent pipeline library with 21-stage dual-abstraction architecture, built on the Anthropic API
 Project-URL: Homepage, https://github.com/CocoRoF/geny-executor
 Project-URL: Repository, https://github.com/CocoRoF/geny-executor

{geny_executor-2.4.1 → geny_executor-2.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "geny-executor"
-version = "2.4.1"
+version = "2.5.0"
 description = "Harness-engineered agent pipeline library with 21-stage dual-abstraction architecture, built on the Anthropic API"
 readme = "README.md"
 license = "MIT"

{geny_executor-2.4.1 → geny_executor-2.5.0}/src/geny_executor/__init__.py

@@ -126,7 +126,6 @@ from geny_executor.stages.s12_agent.subagent_type import (
 # Single source of truth: read the installed distribution version so
 # ``__version__`` can never drift from ``pyproject.toml`` again.
 try:
-    from importlib.metadata import PackageNotFoundError as _PkgNotFound
     from importlib.metadata import version as _pkg_version
 
     __version__ = _pkg_version("geny-executor")

geny_executor-2.5.0/src/geny_executor/core/compaction.py

@@ -0,0 +1,120 @@
+"""Shared compaction runner — one place that runs a compactor, emits a
+uniform event, and persists the snapshot to a memory provider.
+
+Both the Stage 2 proactive trigger (context near 80%) and the Stage 4
+reactive token-budget guard (context near the hard ceiling) compact the
+SAME ``state.messages`` with the SAME compactor instance. Centralising
+"compact + record" here guarantees they log and persist identically, and
+that the snapshot is never written twice (a host wrapper that records its
+own snapshot sets ``compactor.persists_own_compaction = True``).
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Optional
+
+from geny_executor.core.state import PipelineState
+from geny_executor.core.token_estimate import estimate_prompt_tokens
+
+logger = logging.getLogger(__name__)
+
+
+def _compactor_name(compactor: Any) -> str:
+    return str(getattr(compactor, "name", None) or type(compactor).__name__)
+
+
+def _summary_text(state: PipelineState) -> str:
+    """Best-effort extraction of the summary a compactor placed at the head."""
+    msgs = state.messages or []
+    if not msgs:
+        return ""
+    head = msgs[0]
+    if not isinstance(head, dict):
+        return ""
+    content = head.get("content", "")
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        parts = [
+            b.get("text", "") for b in content if isinstance(b, dict) and b.get("type") == "text"
+        ]
+        return "\n".join(p for p in parts if p)
+    return ""
+
+
+async def run_compaction(
+    state: PipelineState,
+    compactor: Any,
+    *,
+    trigger: str,
+    provider: Optional[Any] = None,
+) -> dict:
+    """Run ``compactor`` against ``state`` and return a result summary dict.
+
+    Emits a ``context.compacted`` event carrying ``trigger`` ("proactive"
+    from Stage 2, "guard" from Stage 4) and, when a provider exposes
+    ``record_compaction`` and the compactor does not persist its own
+    snapshot, records the snapshot to the provider's "compactions"
+    category. Never raises — compaction is best-effort relief, not a
+    correctness gate; failures are logged as events and swallowed.
+    """
+    before_msgs = len(state.messages or [])
+    before_tokens = estimate_prompt_tokens(state)
+
+    try:
+        await compactor.compact(state)
+    except Exception as exc:  # noqa: BLE001 — best effort
+        state.add_event(
+            "context.compaction_failed",
+            {"compactor": _compactor_name(compactor), "trigger": trigger, "error": str(exc)},
+        )
+        logger.warning("Compaction (%s) failed: %s", trigger, exc)
+        return {"ok": False, "before_messages": before_msgs, "after_messages": before_msgs}
+
+    after_msgs = len(state.messages or [])
+    after_tokens = estimate_prompt_tokens(state)
+    replaced = max(0, before_msgs - after_msgs)
+    saved_tokens = max(0, before_tokens - after_tokens)
+
+    state.add_event(
+        "context.compacted",
+        {
+            "strategy": _compactor_name(compactor),
+            "trigger": trigger,
+            "messages_before": before_msgs,
+            "messages_after": after_msgs,
+            "saved_tokens_estimate": saved_tokens,
+        },
+    )
+
+    # Persist the snapshot unless the compactor already does it itself.
+    if (
+        replaced > 0
+        and provider is not None
+        and not getattr(compactor, "persists_own_compaction", False)
+        and hasattr(provider, "record_compaction")
+    ):
+        try:
+            await provider.record_compaction(
+                _summary_text(state),
+                replaced_count=replaced,
+                strategy=_compactor_name(compactor),
+                saved_tokens=saved_tokens,
+                session_id=getattr(state, "session_id", "") or "",
+                trigger=trigger,
+            )
+        except Exception as exc:  # noqa: BLE001 — best effort
+            state.add_event(
+                "context.compaction_record_failed",
+                {"compactor": _compactor_name(compactor), "error": str(exc)},
+            )
+            logger.debug("record_compaction failed: %s", exc)
+
+    return {
+        "ok": True,
+        "before_messages": before_msgs,
+        "after_messages": after_msgs,
+        "replaced": replaced,
+        "saved_tokens_estimate": saved_tokens,
+    }

{geny_executor-2.4.1 → geny_executor-2.5.0}/src/geny_executor/core/manifest_factory.py

@@ -798,14 +798,10 @@ def build_manifest_for(
             if not provider:
                 raise ValueError(f"preset {key!r} requires an explicit provider=")
             return build_manifest(key, provider=provider, **kwargs)
-        raise ValueError(
-            f"unknown preset key {key!r}. Catalog: {[d.key for d in _PRESET_CATALOG]}"
-        )
+        raise ValueError(f"unknown preset key {key!r}. Catalog: {[d.key for d in _PRESET_CATALOG]}")
     eff_provider = provider or desc.provider
     if not eff_provider:
-        raise ValueError(
-            f"preset {key!r} has no recommended provider; pass provider= explicitly."
-        )
+        raise ValueError(f"preset {key!r} has no recommended provider; pass provider= explicitly.")
     kwargs.setdefault("name", desc.name)
     kwargs.setdefault("description", desc.description)
     return build_manifest(desc.base_preset, provider=eff_provider, **kwargs)

{geny_executor-2.4.1 → geny_executor-2.5.0}/src/geny_executor/core/pipeline.py

@@ -2672,6 +2672,26 @@ class Pipeline:
         else:
             state.tool_dispatcher = None
 
+        # Budget-recovery auto-wire (2.5.0): give the Guard stage the same
+        # compactor the Context stage uses so a ``compact`` guard signal
+        # (token-budget pressure) can shrink history and re-check instead
+        # of hard-rejecting. Re-synced each turn so a host that swaps the
+        # Context compactor (e.g. an LLM-backed one) is picked up — unless
+        # the host wired recovery explicitly via attach_budget_recovery.
+        guard_stage = self._stages.get(4)
+        context_stage = self._stages.get(2)
+        if (
+            guard_stage is not None
+            and context_stage is not None
+            and hasattr(guard_stage, "attach_budget_recovery")
+            and not getattr(guard_stage, "_budget_recovery_explicit", False)
+        ):
+            compactor = getattr(context_stage, "_compactor", None)
+            provider = getattr(context_stage, "_provider", None)
+            if compactor is not None:
+                guard_stage._budget_compactor = compactor
+                guard_stage._memory_provider = provider
+
         self._has_started = True
         return state
 

geny_executor-2.5.0/src/geny_executor/core/token_estimate.py

@@ -0,0 +1,87 @@
+"""Cheap, single-source token estimation for context-budget decisions.
+
+The Stage 2 *proactive* compaction trigger and the Stage 4 *reactive*
+token-budget guard must share ONE notion of "how big is the next API
+call" — otherwise compaction (which shrinks ``state.messages``) cannot
+relieve a guard that measures something else. Before 2.5.0 the guard
+read ``state.token_usage`` (session/turn-cumulative usage, which
+compaction never lowers) and compared it against the per-call context
+window, so a long tool-loop turn could trip the guard with no way for
+compaction to help. This module is the shared estimator both stages now
+use against ``state.context_window_budget``.
+
+The estimate is deliberately rough (≈4 chars/token, the heuristic Stage 2
+has always used) — it *gates compaction*, it does not bill. Image blocks
+are counted at a flat per-image estimate rather than their base64 length:
+a single 1568px screenshot is ~1.6k vision tokens but tens of thousands
+of base64 characters, and counting the characters would trip compaction
+on the first image.
+"""
+
+from __future__ import annotations
+
+from typing import Any, List, Union
+
+# Anthropic vision tokens land roughly here for a typical full-size image.
+# A flat estimate beats counting base64 characters (which over-counts by
+# ~50x and would trip compaction on a single screenshot).
+_IMAGE_TOKEN_ESTIMATE = 1_600
+_CHARS_PER_TOKEN = 4
+
+
+def _estimate_text(text: str) -> int:
+    return len(text) // _CHARS_PER_TOKEN
+
+
+def _estimate_block(block: Any) -> int:
+    """Estimate one content block (text / image / tool_use / tool_result)."""
+    if not isinstance(block, dict):
+        return _estimate_text(str(block))
+    btype = block.get("type")
+    if btype == "image" or "source" in block:
+        return _IMAGE_TOKEN_ESTIMATE
+    total = 0
+    for key in ("text", "content", "input", "thinking"):
+        val = block.get(key)
+        if isinstance(val, str):
+            total += _estimate_text(val)
+        elif isinstance(val, list):
+            total += sum(_estimate_block(sub) for sub in val)
+        elif val is not None:
+            total += _estimate_text(str(val))
+    return total or _estimate_text(str(block))
+
+
+def _estimate_content(content: Union[str, List[Any], Any]) -> int:
+    if isinstance(content, str):
+        return _estimate_text(content)
+    if isinstance(content, list):
+        return sum(_estimate_block(b) for b in content)
+    if content is None:
+        return 0
+    return _estimate_text(str(content))
+
+
+def estimate_message_tokens(messages: List[Any]) -> int:
+    """Rough token estimate of a message list (content only)."""
+    return sum(
+        _estimate_content(m.get("content", "")) for m in (messages or []) if isinstance(m, dict)
+    )
+
+
+def estimate_prompt_tokens(state: Any) -> int:
+    """Rough INPUT-token estimate for the next API call.
+
+    Sums the system prompt, the message list, and the tool schemas —
+    everything that travels in the request and therefore counts against
+    ``state.context_window_budget``. Used identically by the Stage 2
+    compaction trigger and the Stage 4 token-budget guard so that
+    compacting ``state.messages`` measurably lowers the same number the
+    guard checks.
+    """
+    total = _estimate_content(getattr(state, "system", "") or "")
+    total += estimate_message_tokens(getattr(state, "messages", []) or [])
+    tools = getattr(state, "tools", None)
+    if tools:
+        total += sum(_estimate_text(str(tool)) for tool in tools)
+    return total

{geny_executor-2.4.1 → geny_executor-2.5.0}/src/geny_executor/events/catalog.py

@@ -93,6 +93,8 @@ class EventTypes(str, Enum):
     # ── Stage 2: Context ──
     CONTEXT_BUILT = "context.built"
     CONTEXT_COMPACTED = "context.compacted"
+    CONTEXT_COMPACTION_FAILED = "context.compaction_failed"
+    CONTEXT_COMPACTION_RECORD_FAILED = "context.compaction_record_failed"
     MEMORY_COMPACTION_SUMMARIZED = "memory.compaction.summarized"
     MEMORY_COMPACTION_LLM_FAILED = "memory.compaction.llm_failed"
 
@@ -102,6 +104,7 @@ class EventTypes(str, Enum):
     # ── Stage 4: Guard ──
     GUARD_CHECK = "guard.check"
     GUARD_WARN = "guard.warn"
+    GUARD_COMPACTING = "guard.compacting"
 
     # ── Stage 5: Cache ──
     CACHE_APPLIED = "cache.applied"
@@ -317,7 +320,20 @@ PAYLOADS: Dict[EventTypes, Dict[str, str]] = {
         "chunks": "int? — RetrievalResult.to_event form (provider-driven path)",
     },
     EventTypes.CONTEXT_COMPACTED: {
-        "strategy": "str — compactor class name",
+        "strategy": "str — compactor name/class",
+        "trigger": "str? — 'proactive' (Stage 2) | 'guard' (Stage 4)",
+        "messages_before": "int?",
+        "messages_after": "int?",
+        "saved_tokens_estimate": "int?",
+    },
+    EventTypes.CONTEXT_COMPACTION_FAILED: {
+        "compactor": "str",
+        "trigger": "str — 'proactive' | 'guard'",
+        "error": "str",
+    },
+    EventTypes.CONTEXT_COMPACTION_RECORD_FAILED: {
+        "compactor": "str",
+        "error": "str",
     },
     EventTypes.MEMORY_COMPACTION_SUMMARIZED: {
         "model": "str",
@@ -342,6 +358,10 @@ PAYLOADS: Dict[EventTypes, Dict[str, str]] = {
     EventTypes.GUARD_WARN: {
         "message": "str",
     },
+    EventTypes.GUARD_COMPACTING: {
+        "guard_name": "str — guard that signalled compaction (token_budget)",
+        "reason": "str — the guard message",
+    },
     EventTypes.CACHE_APPLIED: {
         "strategy": "str — cache strategy class name",
         "system_is_blocks": "bool",

{geny_executor-2.4.1 → geny_executor-2.5.0}/src/geny_executor/memory/providers/file/provider.py

@@ -12,7 +12,7 @@ from __future__ import annotations
 
 import logging
 from pathlib import Path
-from typing import Dict, List, Optional, Sequence
+from typing import Any, Dict, List, Optional, Sequence
 
 from geny_executor.memory.provider import (
     BackendInfo,
@@ -252,6 +252,53 @@ class FileMemoryProvider(MemoryProvider):
         )
         return receipt
 
+    async def record_compaction(
+        self,
+        summary: str,
+        *,
+        replaced_count: int = 0,
+        strategy: str = "",
+        saved_tokens: Optional[int] = None,
+        session_id: str = "",
+        trigger: str = "",
+    ) -> Optional[str]:
+        """Persist a history-compaction snapshot to the "compactions" category.
+
+        Called by :func:`geny_executor.core.compaction.run_compaction` when
+        Stage 2 (proactive) or Stage 4 (token-budget guard) compacts the
+        conversation. Best-effort and standalone-friendly: returns the
+        written note filename, or ``None`` when there is nothing to record.
+        Hosts that maintain a richer compaction archive set
+        ``compactor.persists_own_compaction = True`` so this is skipped.
+        """
+        body = (summary or "").strip()
+        if not body and replaced_count <= 0:
+            return None
+
+        frontmatter: Dict[str, Any] = {
+            "replaced_count": int(replaced_count),
+            "strategy": strategy or "",
+            "trigger": trigger or "",
+            "session_id": session_id or self._session_id,
+        }
+        if saved_tokens is not None:
+            frontmatter["saved_tokens"] = int(saved_tokens)
+
+        title = f"Compaction · {replaced_count} messages" if replaced_count else "Compaction"
+        note_meta = await self._notes.write(
+            NoteDraft(
+                title=title,
+                body=body or f"[{replaced_count} messages compacted.]",
+                importance=Importance.MEDIUM,
+                tags=["compaction", "system-artifact"],
+                category="compactions",
+                scope=self._scope,
+                frontmatter=frontmatter,
+            )
+        )
+        await self._index.rebuild()
+        return note_meta.ref.filename
+
     async def reflect(self, ctx: ReflectionContext) -> Sequence[Insight]:
         # File provider has no LLM; reflection wires in via MemoryHooks
         # / the orchestrating stage. Default is "no insights".

{geny_executor-2.4.1 → geny_executor-2.5.0}/src/geny_executor/stages/s02_context/artifact/default/stage.py

@@ -4,10 +4,12 @@ from __future__ import annotations
 
 from typing import Any, Dict, Optional
 
+from geny_executor.core.compaction import run_compaction
 from geny_executor.core.schema import ConfigField, ConfigSchema
 from geny_executor.core.slot import StrategySlot
 from geny_executor.core.stage import Stage
 from geny_executor.core.state import PipelineState
+from geny_executor.core.token_estimate import estimate_prompt_tokens
 from geny_executor.memory.provider import (
     MemoryEvent,
     MemoryProvider,
@@ -24,6 +26,7 @@ from geny_executor.stages.s02_context.artifact.default.strategies import (
     SimpleLoadStrategy,
 )
 from geny_executor.stages.s02_context.artifact.default.compactors import (
+    LLMSummaryCompactor,
     SlidingWindowCompactor,
     SummaryCompactor,
     TruncateCompactor,
@@ -76,6 +79,7 @@ class ContextStage(Stage[Any, Any]):
                 registry={
                     "truncate": TruncateCompactor,
                     "summary": SummaryCompactor,
+                    "llm_summary": LLMSummaryCompactor,
                     "sliding_window": SlidingWindowCompactor,
                 },
                 description="History compaction strategy",
@@ -224,15 +228,15 @@ class ContextStage(Stage[Any, Any]):
                     )
                     state.metadata["memory_context"] = memory_text
 
-        # Compact if needed (rough estimate: 4 chars per token)
-        estimated_tokens = sum(len(str(m.get("content", ""))) // 4 for m in state.messages)
+        # Proactive compaction: when the projected next-call context
+        # (system + messages + tools) crosses 80% of the window, compact
+        # now so the Stage 4 token-budget guard's 95% safety net rarely
+        # has to. Both stages use ``estimate_prompt_tokens`` so compaction
+        # measurably lowers the same number the guard checks.
+        estimated_tokens = estimate_prompt_tokens(state)
         if estimated_tokens > state.context_window_budget * 0.8:
-            await self._compactor.compact(state)
-            state.add_event(
-                "context.compacted",
-                {
-                    "strategy": type(self._compactor).__name__,
-                },
+            await run_compaction(
+                state, self._compactor, trigger="proactive", provider=self._provider
             )
 
         state.add_event(

{geny_executor-2.4.1 → geny_executor-2.5.0}/src/geny_executor/stages/s02_context/interface.py

@@ -21,6 +21,14 @@ class ContextStrategy(Strategy):
 class HistoryCompactor(Strategy):
     """Base interface for compacting conversation history when budget is exceeded."""
 
+    # Set True by compactors that write their own compaction snapshot to a
+    # memory provider (e.g. a host wrapper that records to a vault). When
+    # True, the centralised :func:`geny_executor.core.compaction.run_compaction`
+    # helper skips its own ``provider.record_compaction`` call so the
+    # snapshot is not persisted twice. Plain in-library compactors leave
+    # this False and rely on the helper for persistence.
+    persists_own_compaction: bool = False
+
     @abstractmethod
     async def compact(self, state: PipelineState) -> None:
         """Compact history in state.messages to fit within budget."""

{geny_executor-2.4.1 → geny_executor-2.5.0}/src/geny_executor/stages/s04_guard/artifact/default/guards.py

@@ -6,12 +6,27 @@ from typing import Any, Dict, Optional, Set
 
 from geny_executor.core.schema import ConfigField, ConfigSchema
 from geny_executor.core.state import PipelineState
+from geny_executor.core.token_estimate import estimate_prompt_tokens
 from geny_executor.stages.s04_guard.interface import Guard
 from geny_executor.stages.s04_guard.types import GuardResult
 
 
 class TokenBudgetGuard(Guard):
-    """Check if token budget allows another API call."""
+    """Ensure the NEXT API call still fits in the context window.
+
+    Measures the *projected* input size of the next request (system +
+    messages + tools, via :func:`estimate_prompt_tokens`) against
+    ``state.context_window_budget``, reserving ``min_remaining_tokens``
+    of headroom for the model's response. When the projection leaves too
+    little headroom the guard returns ``action="compact"`` — a *recoverable*
+    signal: :class:`GuardStage` compacts ``state.messages`` and re-checks
+    once, hard-rejecting only if the context still does not fit.
+
+    Before 2.5.0 this guard read session/turn-cumulative ``token_usage``
+    and hard-rejected — a measure compaction could never lower, so a long
+    tool-loop turn died with no recovery. Cumulative *spend* caps remain
+    the job of ``cost_budget`` and the Stage 16 loop's token dimension.
+    """
 
     def __init__(self, min_remaining_tokens: int = 10_000):
         self._min_remaining = min_remaining_tokens
@@ -22,7 +37,10 @@ class TokenBudgetGuard(Guard):
 
     @property
     def description(self) -> str:
-        return f"Ensures at least {self._min_remaining} tokens remaining"
+        return (
+            f"Ensures the next request leaves >= {self._min_remaining} tokens "
+            "of context headroom (compacts history first)"
+        )
 
     @classmethod
     def config_schema(cls) -> ConfigSchema:
@@ -33,7 +51,12 @@ class TokenBudgetGuard(Guard):
                     name="min_remaining_tokens",
                     type="integer",
                     label="Min remaining tokens",
-                    description="Reject the turn if this many tokens aren't free in the context window.",
+                    description=(
+                        "Headroom (for the response) the next request must leave "
+                        "free in the context window. When the projected request "
+                        "would leave less, history is compacted and re-checked "
+                        "before the turn is rejected."
+                    ),
                     default=10_000,
                     min_value=0,
                 ),
@@ -49,14 +72,18 @@ class TokenBudgetGuard(Guard):
         return {"min_remaining_tokens": self._min_remaining}
 
     def check(self, state: PipelineState) -> GuardResult:
-        used = state.token_usage.input_tokens + state.token_usage.output_tokens
-        remaining = state.context_window_budget - used
+        projected = estimate_prompt_tokens(state)
+        remaining = state.context_window_budget - projected
         if remaining < self._min_remaining:
             return GuardResult(
                 passed=False,
                 guard_name=self.name,
-                message=f"Token budget low: {remaining} remaining (min {self._min_remaining})",
-                action="reject",
+                message=(
+                    f"Context near limit: ~{projected} of "
+                    f"{state.context_window_budget} tokens projected, "
+                    f"{remaining} free (need {self._min_remaining})"
+                ),
+                action="compact",
             )
         return GuardResult(passed=True, guard_name=self.name)
 

{geny_executor-2.4.1 → geny_executor-2.5.0}/src/geny_executor/stages/s04_guard/artifact/default/stage.py

@@ -11,6 +11,7 @@ from geny_executor.core.slot import SlotChain
 from geny_executor.core.stage import Stage
 from geny_executor.core.state import PipelineState
 from geny_executor.stages.s04_guard.interface import Guard, GuardChain
+from geny_executor.stages.s04_guard.types import GuardResult
 from geny_executor.stages.s04_guard.artifact.default.guards import (
     CostBudgetGuard,
     IterationGuard,
@@ -48,6 +49,29 @@ class GuardStage(Stage[Any, Any]):
         }
         self._max_chain_length = int(max_chain_length)
         self._fail_fast = bool(fail_fast)
+        # Budget-recovery wiring (2.5.0). A guard may return
+        # ``action="compact"`` (the token-budget guard does when the
+        # projected request is too large). When a compactor is wired,
+        # ``execute`` compacts ``state.messages`` and re-checks once
+        # before rejecting. Auto-wired from the Context stage's compactor
+        # by ``Pipeline._init_state`` each turn; a host may override via
+        # :meth:`attach_budget_recovery`. ``None`` → "compact" degrades
+        # to a hard reject (pre-2.5.0 behaviour).
+        self._budget_compactor: Optional[Any] = None
+        self._memory_provider: Optional[Any] = None
+        # True once a host explicitly wired recovery — stops the
+        # per-turn auto-wire (Pipeline._init_state) from clobbering it.
+        self._budget_recovery_explicit = False
+
+    def attach_budget_recovery(
+        self, compactor: Optional[Any], provider: Optional[Any] = None
+    ) -> "GuardStage":
+        """Wire the compactor (and optional memory provider) used to recover
+        from a ``compact`` guard signal. See class/__init__ notes."""
+        self._budget_compactor = compactor
+        self._memory_provider = provider
+        self._budget_recovery_explicit = True
+        return self
 
     @property
     def guards(self) -> SlotChain:
@@ -153,22 +177,52 @@ class GuardStage(Stage[Any, Any]):
                 },
             )
 
-            if not result.passed:
+            if result.passed:
+                return input
+
+            if result.action == "warn":
+                state.add_event("guard.warn", {"message": result.message})
+                return input
+
+            # Recoverable budget pressure: compact history and re-check
+            # once before giving up. Only the first compact-actionable
+            # failure triggers recovery; a recovered chain re-runs clean.
+            if result.action == "compact" and await self._recover_budget(state, result):
+                result = GuardChain(guards).check_all(state)
+                state.add_event(
+                    "guard.check",
+                    {
+                        "passed": result.passed,
+                        "guard_name": result.guard_name,
+                        "message": result.message,
+                        "recheck": True,
+                    },
+                )
+                if result.passed:
+                    return input
                 if result.action == "warn":
                     state.add_event("guard.warn", {"message": result.message})
                     return input
-                raise GuardRejectError(
-                    result.message,
-                    guard_name=result.guard_name,
-                )
 
-            return input
+            raise GuardRejectError(
+                result.message,
+                guard_name=result.guard_name,
+            )
 
         # fail_fast=False — run EVERY guard and aggregate. Operators use
         # this to see the full violation picture in one turn instead of
         # fixing guards one rejection at a time.
         failures = [r for r in (guard.check(state) for guard in guards) if not r.passed]
-        rejects = [r for r in failures if r.action != "warn"]
+
+        # Recoverable budget pressure: if any failure asked to compact,
+        # compact once and re-evaluate the whole chain before aggregating
+        # rejects (a recovered token_budget guard drops out of the list).
+        if any(r.action == "compact" for r in failures):
+            compact_result = next(r for r in failures if r.action == "compact")
+            if await self._recover_budget(state, compact_result):
+                failures = [r for r in (guard.check(state) for guard in guards) if not r.passed]
+
+        rejects = [r for r in failures if r.action not in ("warn",)]
 
         state.add_event(
             "guard.check",
@@ -194,3 +248,29 @@ class GuardStage(Stage[Any, Any]):
             )
 
         return input
+
+    async def _recover_budget(self, state: PipelineState, result: GuardResult) -> bool:
+        """Compact history in response to a ``compact`` guard signal.
+
+        Returns True iff a compactor was wired and ran (so the caller
+        should re-check the chain). With no compactor wired the signal
+        degrades to a hard reject — the pre-2.5.0 behaviour.
+        """
+        if self._budget_compactor is None:
+            return False
+
+        state.add_event(
+            "guard.compacting",
+            {"guard_name": result.guard_name, "reason": result.message},
+        )
+        # Lazy import: keeps the guard stage import-light and avoids a
+        # core→stage cycle at module load.
+        from geny_executor.core.compaction import run_compaction
+
+        outcome = await run_compaction(
+            state,
+            self._budget_compactor,
+            trigger="guard",
+            provider=self._memory_provider,
+        )
+        return bool(outcome.get("ok"))