fix(compression): defer local preflight after native checkpoint

A native Responses compaction checkpoint is opaque ciphertext; the rough
preflight estimator counts it as text (5.17M chars -> ~1.29M tokens against
a 204K trigger) and fires local compression on a request whose real prompt is
~116K. Arm the existing one-response real-usage latch when a replayable
checkpoint is captured (build_assistant_message) or restored into a fresh
agent (_hydrate_from_history), honor it in the post-tool gate and idle
compaction, and require non-empty encrypted_content for a checkpoint.

Squash of the author's source commits from #100642 (0e3c234ea0, 771e1b3365,
bb1505a119) plus the fdf140c81d test refresh, re-based onto current main by
patch application. Source delta is byte-identical to the PR head d6ce3e236d.

Fixes #100611
This commit is contained in:
Benjamin Brumbaugh
2026-09-06 09:00:00 +00:00
committed by Teknium
parent 66f1668850
commit cd71ee0708
11 changed files with 387 additions and 17 deletions
+13
View File
@@ -1729,6 +1729,19 @@ def build_assistant_message(agent, assistant_message, finish_reason: str) -> dic
value = getattr(assistant_message, attr, None)
if value:
msg[attr] = value
if attr == "codex_reasoning_items":
from agent.codex_responses_adapter import (
has_replayable_native_compaction_checkpoint,
)
note_checkpoint = getattr(
agent.context_compressor, "note_native_compaction_checkpoint", None
)
if (
callable(note_checkpoint)
and has_replayable_native_compaction_checkpoint(agent, [msg])
):
note_checkpoint()
if assistant_tool_calls:
msg["tool_calls"] = [_assistant_tool_call_dict(agent, tc, i) for i, tc in enumerate(assistant_tool_calls)]
+35 -11
View File
@@ -541,16 +541,10 @@ def classify_responses_route(agent: Any) -> ResponsesRouteFlags:
)
def estimate_native_responses_preflight_tokens(
agent: Any, messages: List[Dict[str, Any]], *, system_prompt: str = "", tools: Optional[List[Dict[str, Any]]] = None,
) -> Optional[int]:
"""Estimate tokens for the checkpoint-pruned Responses payload (the full transcript overstates a natively compacted
session and fires local compression needlessly). None when native compaction is not proven eligible or conversion fails.
Automatic preflight previously counted the full durable transcript. On a natively compacted Codex
session that overstates the wire by several times and fires local compression against history the main
request will never send (#96155).
"""
def _native_responses_replay_items(
agent: Any, messages: List[Dict[str, Any]]
) -> Optional[List[Dict[str, Any]]]:
"""Build the native-compaction-eligible wire items, or ``None`` when ineligible."""
if getattr(agent, "api_mode", None) != "codex_responses" or not isinstance(messages, list):
return None
route = classify_responses_route(agent)._asdict()
@@ -565,7 +559,37 @@ def estimate_native_responses_preflight_tokens(
native_compaction_eligible=True,
)
except Exception:
logger.debug("native Responses preflight conversion failed; falling back to generic estimate", exc_info=True)
logger.debug(
"native Responses replay conversion failed; using the generic fallback",
exc_info=True,
)
return None
return items
def has_replayable_native_compaction_checkpoint(
agent: Any, messages: List[Dict[str, Any]]
) -> bool:
"""Whether the current route would replay a persisted native checkpoint."""
items = _native_responses_replay_items(agent, messages)
if items is None:
return False
from agent.native_compaction import has_compaction_checkpoint
return has_compaction_checkpoint(items)
def estimate_native_responses_preflight_tokens(
agent: Any, messages: List[Dict[str, Any]], *, system_prompt: str = "", tools: Optional[List[Dict[str, Any]]] = None,
) -> Optional[int]:
"""Estimate tokens for the checkpoint-pruned Responses payload (the full transcript overstates a natively compacted
session and fires local compression needlessly). None when native compaction is not proven eligible or conversion fails.
Automatic preflight previously counted the full durable transcript. On a natively compacted Codex
session that overstates the wire by several times and fires local compression against history the main
request will never send (#96155).
"""
items = _native_responses_replay_items(agent, messages)
if items is None:
return None
from agent.model_metadata import estimate_request_tokens_rough
return estimate_request_tokens_rough(items, system_prompt=system_prompt or "", tools=tools)
+16 -1
View File
@@ -2416,6 +2416,20 @@ class ContextCompressor(MicroCompactionMixin, ContextEngine):
except (TypeError, ValueError):
self._pending_request_rough_tokens = 0
def note_native_compaction_checkpoint(self) -> None:
"""Wait for real usage before trusting a newly checkpointed request.
Native Responses compaction replaces durable history with an opaque
encrypted checkpoint. Its serialized size is unrelated to the token
count billed by the provider, so the first rough estimate after capture
can jump by more than the whole context window. Reuse the one-response
compaction latch and discard any stale local-compression baseline; the
next provider response then pairs its real usage with the rough estimate
for the checkpointed request.
"""
self.awaiting_real_usage_after_compression = True
self.last_compression_rough_tokens = 0
def should_defer_preflight_to_real_usage(self, rough_tokens: int) -> bool:
"""Return True when a high rough preflight estimate is known-noisy.
Projects real usage as ``last_real + (rough_now - rough_at_last_real)`` and fires only when the
@@ -2426,7 +2440,8 @@ class ContextCompressor(MicroCompactionMixin, ContextEngine):
re-runs with the aligned basis."""
if rough_tokens < self.threshold_tokens:
return False
# After compaction last_real_prompt_tokens is STALE (above threshold); defer one turn until real usage arrives.
# After local or native compaction, last_real_prompt_tokens is STALE
# (above threshold); defer one turn until real usage arrives.
if self.awaiting_real_usage_after_compression:
return True
if self.last_real_prompt_tokens <= 0 or self.last_real_prompt_tokens >= self.threshold_tokens:
+6 -1
View File
@@ -328,7 +328,12 @@ def is_native_compaction_rejection(error: Any, status_code: Any = None) -> bool:
def has_compaction_checkpoint(items: Any) -> bool:
"""Does this ``codex_reasoning_items`` sidecar carry a compaction checkpoint? A checkpoint is
cumulative context living in exactly one place: rewrite/discard the sidecar only after asking."""
return isinstance(items, list) and any(_is_compaction_item(item) for item in items)
return isinstance(items, list) and any(
_is_compaction_item(item)
and isinstance(item.get("encrypted_content"), str)
and bool(item["encrypted_content"].strip())
for item in items
)
def merge_interim_reasoning_items(prior_items: Any, new_items: Any) -> List[Dict[str, Any]]:
+26 -2
View File
@@ -525,13 +525,37 @@ def _stage_turn_user_message(
def _hydrate_from_history(agent: Any, conversation_history: Optional[List[Any]]) -> None:
"""Hydrate the todo store and per-session nudge counters from persisted history."""
"""Hydrate process-local state from persisted history on the first resumed turn."""
if not conversation_history:
return
if not agent._todo_store.has_items():
agent._hydrate_todo_store(conversation_history)
# Hydrate per-session nudge counters from persisted history.
# A live native checkpoint arms this latch while its response is captured. A
# restarted agent must recover the same one-response deferral before turn-start
# compression can rewrite the restored opaque checkpoint. Reuse the adapter's
# exact route/issuer/replay filtering and tolerate plugin compressors without the
# optional hook.
if agent._user_turn_count == 0:
note_checkpoint = getattr(
getattr(agent, "context_compressor", None),
"note_native_compaction_checkpoint",
None,
)
if callable(note_checkpoint):
try:
from agent.codex_responses_adapter import (
has_replayable_native_compaction_checkpoint,
)
if has_replayable_native_compaction_checkpoint(
agent, conversation_history
):
note_checkpoint()
except Exception:
logger.debug(
"restored native checkpoint hydration skipped", exc_info=True
)
# Hydrate per-session nudge counters from persisted history.
prior_user_turns = sum(1 for m in conversation_history if m.get("role") == "user")
if prior_user_turns > 0:
agent._user_turn_count = prior_user_turns
+5
View File
@@ -156,6 +156,11 @@ def _idle_compaction(
if _idle_gap < _idle_after:
return
_compressor = agent.context_compressor
# A live or restored native checkpoint must reach its issuer once so real usage,
# rather than an opaque ciphertext estimate, decides whether local compression is
# still needed. Threshold and post-tool preflight honor the same latch.
if bool(getattr(_compressor, "awaiting_real_usage_after_compression", False)):
return
# Route-aware pressure: on compacted native-Codex sessions the durable figure
# overstates the wire, so reuse the preflight estimator.
_idle_tokens = _tc._preflight_request_tokens(
+3
View File
@@ -297,6 +297,9 @@ def compress_after_tool_results(
if (
agent.compression_enabled
and compression_attempts < max_compression_attempts
and not bool(
getattr(_compressor, "awaiting_real_usage_after_compression", False)
)
and _compressor.should_compress(_real_tokens)
):
compression_attempts += 1
+34
View File
@@ -366,6 +366,40 @@ class TestPreflightDeferral:
compressor.awaiting_real_usage_after_compression = True
assert compressor.should_defer_preflight_to_real_usage(95_000) is True
def test_native_checkpoint_defers_until_provider_usage_reanchors(self, compressor):
"""A newly captured native checkpoint is opaque ciphertext, not text.
Its serialized size can add more than a million rough tokens even when
the provider reports that the checkpoint-pruned request fits. Defer the
local compressor for one request so real usage can establish the new
rough/real calibration instead of immediately summarizing again.
"""
compressor.threshold_tokens = 85_000
compressor.last_real_prompt_tokens = 60_000
compressor.last_rough_tokens_when_real_prompt_fit = 70_000
compressor.last_compression_rough_tokens = 40_000
compressor.note_native_compaction_checkpoint()
encrypted_checkpoint_rough = 1_300_000
assert compressor.awaiting_real_usage_after_compression is True
assert compressor.last_compression_rough_tokens == 0
assert (
compressor.should_defer_preflight_to_real_usage(
encrypted_checkpoint_rough
)
is True
)
compressor.note_request_rough_estimate(encrypted_checkpoint_rough)
compressor.update_from_response({"prompt_tokens": 65_000})
assert compressor.awaiting_real_usage_after_compression is False
assert (
compressor.last_rough_tokens_when_real_prompt_fit
== encrypted_checkpoint_rough
)
+166 -2
View File
@@ -12,11 +12,13 @@ import pytest
from types import SimpleNamespace
from typing import Any
from unittest.mock import MagicMock, patch
from agent.context_compressor import SUMMARY_PREFIX, _DB_PERSISTED_MARKER
from agent.conversation_compression import COMPACTION_DONE_STATUS, COMPACTION_STATUS
from hermes_state import SessionDB
from run_agent import AIAgent
import run_agent
@@ -78,8 +80,7 @@ def _make_413_error(*, use_status_code=True, message="Request entity too large")
return err
@pytest.fixture()
def agent():
def _new_test_agent():
with (
patch("model_tools.get_tool_definitions", return_value=_make_tool_defs("web_search")),
patch("model_tools.check_toolset_requirements", return_value={}),
@@ -104,6 +105,11 @@ def agent():
return a
@pytest.fixture()
def agent():
return _new_test_agent()
# ---------------------------------------------------------------------------
# Tests
# ---------------------------------------------------------------------------
@@ -1209,6 +1215,164 @@ class TestPreflightCompression:
assert agent.context_compressor._ineffective_compression_count == 2
assert agent.context_compressor._last_compression_savings_pct == 0.0
@pytest.mark.parametrize(
("failure_kind", "expected_provider_calls"),
[("interrupt", 0), ("provider_error", 3)],
)
def test_pending_native_checkpoint_recovers_after_failed_turn(
self, agent, failure_kind, expected_provider_calls
):
"""A failed turn preserves the latch only until a response arrives.
Clearing it on interrupt/error would expose the next turn to the same
ciphertext-driven false preflight compaction. Keeping it armed does not
park the compressor: the next request bypasses local preflight, reaches
the provider, and real usage consumes the latch.
"""
agent.compression_enabled = True
agent.context_compressor.context_length = 200_000
agent.context_compressor.threshold_tokens = 130_000
agent.context_compressor.note_native_compaction_checkpoint()
if failure_kind == "interrupt":
agent._interrupt_requested = True
else:
agent.client.chat.completions.create.side_effect = RuntimeError(
"provider died"
)
with (
patch("agent.turn_context.estimate_request_tokens_rough", return_value=1_300_000),
patch.object(agent, "_persist_session"),
patch.object(agent, "_save_trajectory"),
patch.object(agent, "_cleanup_task_resources"),
):
failed = agent.run_conversation("first request")
if failure_kind == "interrupt":
assert failed["interrupted"] is True
agent._interrupt_requested = False
else:
assert failed["failed"] is True
assert (
agent.client.chat.completions.create.call_count
== expected_provider_calls
)
assert agent.context_compressor.awaiting_real_usage_after_compression is True
agent.client.chat.completions.create.reset_mock()
agent.client.chat.completions.create.side_effect = None
agent.client.chat.completions.create.return_value = _mock_response(
content="Recovered",
usage={
"prompt_tokens": 65_000,
"completion_tokens": 100,
"total_tokens": 65_100,
},
)
with (
patch("agent.turn_context.estimate_request_tokens_rough", return_value=1_300_000),
patch.object(agent, "_compress_context") as mock_compress,
patch.object(agent, "_persist_session"),
patch.object(agent, "_save_trajectory"),
patch.object(agent, "_cleanup_task_resources"),
):
recovered = agent.run_conversation("retry after failure")
assert recovered["completed"] is True
assert recovered["final_response"] == "Recovered"
mock_compress.assert_not_called()
assert agent.client.chat.completions.create.call_count == 1
assert agent.context_compressor.awaiting_real_usage_after_compression is False
assert agent.context_compressor.last_prompt_tokens == 65_000
def test_restored_native_checkpoint_defers_first_local_compaction(self, tmp_path):
"""A checkpoint restored into a new agent instance must reach its issuer once.
The in-memory native-checkpoint latch is lost when the process restarts. Rehydrate
it in an agent constructed after the durable history is reopened, before either
idle or threshold preflight can summarize the opaque checkpoint using its
ciphertext-sized rough estimate.
"""
db_path = tmp_path / "state.db"
session_id = "restored-native-checkpoint"
checkpoint = {
"type": "compaction",
"encrypted_content": "opaque-checkpoint",
"_issuer_kind": "codex_backend",
}
db = SessionDB(db_path=db_path)
db.create_session(session_id, source="test")
db.append_message(session_id, "user", "before restart")
db.append_message(
session_id,
"assistant",
"checkpoint captured",
codex_reasoning_items=[checkpoint],
)
db.close()
reopened = SessionDB(db_path=db_path)
history = reopened.get_messages_as_conversation(session_id)
reopened.close()
assert history[-1]["codex_reasoning_items"] == [checkpoint]
agent: Any = _new_test_agent()
assert agent.context_compressor.awaiting_real_usage_after_compression is False
agent.api_mode = "codex_responses"
agent.provider = "openai-codex"
agent.model = "gpt-5.6-sol"
agent.base_url = "https://chatgpt.com/backend-api/codex"
agent._base_url_hostname = "chatgpt.com"
agent._base_url_lower = agent.base_url
agent.codex_responses_native_compaction = True
agent.runtime_capabilities = {"native_compaction": True}
agent.context_compressor.context_length = 200_000
agent.context_compressor.threshold_tokens = 130_000
# Exercise the idle pass too: it runs before threshold preflight and must honor
# the same one-response checkpoint latch on a long-idle restored session.
agent.compression_idle_compact_after_seconds = 1
agent._last_activity_ts = 0
response = SimpleNamespace(
output=[
SimpleNamespace(
type="message",
status="completed",
content=[SimpleNamespace(type="output_text", text="Resumed")],
)
],
usage=SimpleNamespace(
input_tokens=65_000,
output_tokens=100,
total_tokens=65_100,
),
status="completed",
incomplete_details=None,
model="gpt-5.6-sol",
)
with (
patch(
"agent.codex_responses_adapter.estimate_native_responses_preflight_tokens",
return_value=1_300_000,
),
patch.object(agent, "_run_codex_stream", return_value=response) as provider,
patch.object(agent, "_compress_context") as local_compress,
patch.object(agent, "_persist_session"),
patch.object(agent, "_save_trajectory"),
patch.object(agent, "_cleanup_task_resources"),
):
resumed = agent.run_conversation(
"after restart", conversation_history=history
)
assert resumed["completed"] is True
assert resumed["final_response"] == "Resumed"
local_compress.assert_not_called()
provider.assert_called_once()
assert agent.context_compressor.awaiting_real_usage_after_compression is False
assert agent.context_compressor.last_prompt_tokens == 65_000
class TestToolResultPreflightCompression:
"""Compression should trigger when tool results push context past the threshold."""
@@ -86,6 +86,7 @@ def _pressured_compressor() -> MagicMock:
compressor.threshold_tokens = 10_000
compressor.context_length = 200_000
compressor.last_prompt_tokens = 150_000
compressor.awaiting_real_usage_after_compression = False
compressor.should_compress.return_value = True
compressor.should_defer_preflight_to_real_usage.return_value = True
compressor.get_active_compression_failure_cooldown.return_value = None
@@ -151,6 +152,14 @@ def _run_tool_loop(agent, n_tool_iterations: int):
class TestPostToolCompressionAttemptCap:
def test_post_tool_gate_waits_for_usage_after_native_checkpoint(self, agent):
agent.context_compressor.awaiting_real_usage_after_compression = True
result, compress_calls = _run_tool_loop(agent, n_tool_iterations=1)
assert result["completed"] is True
assert compress_calls == []
def test_post_tool_compression_capped_at_default_three(self, agent):
"""7 tool iterations under constant pressure → exactly 3 compactions.
+74
View File
@@ -1632,6 +1632,18 @@ class TestBuildApiKwargs:
class TestBuildAssistantMessage:
@staticmethod
def _enable_native_compaction(agent):
agent.api_mode = "codex_responses"
agent.provider = "openai-codex"
agent.model = "gpt-5.6-sol"
agent.base_url = "https://chatgpt.com/backend-api/codex"
agent._base_url_hostname = "chatgpt.com"
agent._base_url_lower = agent.base_url
agent.codex_responses_native_compaction = True
agent.compression_enabled = True
agent.runtime_capabilities = {"native_compaction": True}
def test_basic_message(self, agent):
msg = _mock_assistant_msg(content="Hello!")
result = agent._build_assistant_message(msg, "stop")
@@ -1639,6 +1651,68 @@ class TestBuildAssistantMessage:
assert result["content"] == "Hello!"
assert result["finish_reason"] == "stop"
def test_native_checkpoint_arms_real_usage_preflight_deferral(self, agent):
checkpoint = {
"type": "compaction",
"encrypted_content": "opaque-checkpoint",
"_issuer_kind": "codex_backend",
}
msg = _mock_assistant_msg(content="Compacted")
msg.codex_reasoning_items = [checkpoint]
agent.context_compressor.note_native_compaction_checkpoint = MagicMock()
self._enable_native_compaction(agent)
result = agent._build_assistant_message(msg, "stop")
assert result["codex_reasoning_items"] == [checkpoint]
agent.context_compressor.note_native_compaction_checkpoint.assert_called_once_with()
def test_native_checkpoint_remains_compatible_with_plugin_context_engine(self, agent):
checkpoint = {
"type": "compaction",
"encrypted_content": "opaque-checkpoint",
"_issuer_kind": "codex_backend",
}
msg = _mock_assistant_msg(content="Compacted")
msg.codex_reasoning_items = [checkpoint]
agent.context_compressor = SimpleNamespace(threshold_tokens=204_000)
self._enable_native_compaction(agent)
result = agent._build_assistant_message(msg, "stop")
assert result["codex_reasoning_items"] == [checkpoint]
@pytest.mark.parametrize("encrypted_content", ["", " "])
def test_malformed_checkpoint_does_not_arm_deferral(
self, agent, encrypted_content
):
note_checkpoint = MagicMock()
agent.context_compressor.note_native_compaction_checkpoint = note_checkpoint
malformed = {
"type": "compaction",
"encrypted_content": encrypted_content,
}
msg = _mock_assistant_msg(content="Compacted")
msg.codex_reasoning_items = [malformed]
self._enable_native_compaction(agent)
result = agent._build_assistant_message(msg, "stop")
assert result["codex_reasoning_items"] == [malformed]
note_checkpoint.assert_not_called()
def test_ineligible_route_checkpoint_does_not_arm_deferral(self, agent):
note_checkpoint = MagicMock()
agent.context_compressor.note_native_compaction_checkpoint = note_checkpoint
checkpoint = {"type": "compaction", "encrypted_content": "opaque-checkpoint"}
msg = _mock_assistant_msg(content="Compacted")
msg.codex_reasoning_items = [checkpoint]
result = agent._build_assistant_message(msg, "stop")
assert result["codex_reasoning_items"] == [checkpoint]
note_checkpoint.assert_not_called()