Skip to content

Hermes Agent context engine: the main model writes the compaction handoff on its cached prompt prefix

Tell the user when the warm path keeps failing

Elevatormusic3d3cf383f998
diff --git a/CHANGELOG.md b/CHANGELOG.md
index ccb48fc..86f8bd2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,13 @@
All notable changes are listed here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the versions follow [Semantic Versioning](https://semver.org/).
+## [Unreleased]
+
+### Added
+
+- A WARNING for each compaction that does not use the warm path, with its reason (Hermes copies it to `errors.log`).
+- After 3 compactions in a row without the warm path, one notice with the reasons and the likely cause, in the logs and in the status of the next automatic compaction.
+
## [0.2.0] - 2026-10-06
First public release.
diff --git a/README.md b/README.md
index d6716d9..fb5ff6a 100644
--- a/README.md
+++ b/README.md
@@ -167,6 +167,20 @@ warm_compaction: path=warm reason=accepted elapsed_s=10.656 prompt_tokens=108021
The engine status (`get_status()`) has the same values in `warm_last`. The log never contains message text, request bodies, or keys.
+### When the warm path keeps failing
+
+The plugin never stops a compaction: when the warm request cannot run, the fallback summary does the work. So that this does not go unseen:
+
+- Each compaction without the warm path also writes a WARNING with its reason. Hermes copies warnings to `logs/errors.log`.
+- After 3 compactions in a row without the warm path, the plugin writes one WARNING that names the reasons and the likely cause. Hermes shows the same notice with the status of the next automatic compaction, also when the compaction status is turned off. For example:
+
+ ```text
+ warm_compaction: the last 3 compactions did not use the warm cache (provider_error). Compaction still works with the fallback summary, but it is slower. Likely cause: the server refused the warm request (a provider error, or a gateway that needs a cookie). Details: the warm_compaction lines in logs/agent.log.
+ ```
+
+- A warm compaction ends the streak, and the notice can show again after the next 3 failures. A cancelled attempt does not count, and `warm: false` is not a failure.
+- Manual `/compress` has no status line from the engine: after manual compactions only, the notice is in the logs.
+
## Results
All runs used synthetic conversations of 100,000 or more prompt tokens on unpatched Hermes `45871e10`, one session at a time. The records have metadata only. "DGX" is an OpenAI-compatible server on an NVIDIA DGX that reports cached tokens. "LM Studio 4B" is LM Studio with a Qwen3.5 4B model; it reports no cached-token counter.
diff --git a/evidence/plugin-integration.json b/evidence/plugin-integration.json
index 64c6706..fafe47d 100644
--- a/evidence/plugin-integration.json
+++ b/evidence/plugin-integration.json
@@ -1,22 +1,22 @@
{
"check": "standalone warm_compaction plugin on unpatched Hermes Agent",
- "started_utc": "2026-10-06T18:52:13Z",
+ "started_utc": "2026-10-07T02:34:54Z",
"hermes": {
"commit": "45871e100feceb89769536c88e5e6e265226a409",
"clean": true
},
"python": "3.11.14",
- "script_sha256": "08a2bedce89ede3a05576013351c1397e00bef0d50a24e28c9b6c0168d86c8ae",
+ "script_sha256": "3f14b3f48f0d9dff5928ebdb1cf4570a1ebcb90b417eec8aaa263d265937cd6f",
"plugin_files_sha256": {
"warm_compaction/__init__.py": "11e038f05813627b2d1d8b82b3b775ecfe41015746c8e90ed6d452cfdaec65a6",
- "warm_compaction/capture.py": "971abfe0751437701c030be8c23a1c33b5380e06db87cb696bc951ea080007cc",
- "warm_compaction/engine.py": "198ea6567059c8e2700c142e3b5f27705aab9a4472b8cbb6d6e0686279b96e5f",
- "warm_compaction/fallback.py": "3561af9eda01601574bc000155e5fb1e56d38c9a52c46c9bc756cb8686fce2f2",
- "warm_compaction/handoff.py": "9afea62ec2f8ef46cbeefd70b1071bb6c7111fa6fd1cd073e1fb2c7eae30f3c2",
- "warm_compaction/layout.py": "41787f75a1044bade37f01f5f1e9f5329726b15145b9c9b2bdd51c14bda45080",
+ "warm_compaction/capture.py": "3158562b9b4d4ab50c0ec7a6524bbc1b1c364b137c6d8d27c5801220959021c8",
+ "warm_compaction/engine.py": "10ec684e79e13765bcd7984a0fea6f1fc1138a2d0cb1ffed41c9914e04c2df0e",
+ "warm_compaction/fallback.py": "fcd385298c295a019af52381f90effc38417aec02e0415b28e6cb3b242afd7d1",
+ "warm_compaction/handoff.py": "fcab51def8fbcc2b1928957930c9a5c58a4ad202c949fd9f870a77f3b30276ae",
+ "warm_compaction/layout.py": "b49314c5236268247c337d9fae939135c97b47384300dcdfd00b0da0c040db93",
"warm_compaction/plugin.yaml": "d67560fd4625ec80d9e26f3e6d712763e77474f68d469c7e48f09fd3506ccc71",
"warm_compaction/rows.py": "f2ca69a7361affc4fd84388ab9ac718a0e9affa609c87d75efd6e0c25fa860cf",
- "warm_compaction/warm.py": "febc739af4757392f63b2c8daa343b2daf32aeab6864b5f33d63d5cb7e8ceb3a"
+ "warm_compaction/warm.py": "95bc01d954d30e37de7a74a2f0ad7e643b50048c7cb37ea9443748160f020fed"
},
"privacy": "metadata only: names, counts, codes, booleans, and times; no message text",
"scenarios": [
@@ -76,11 +76,11 @@
"threshold_tokens": 100000,
"context_length": 200000
},
- "compress_seconds": 0.101,
+ "compress_seconds": 0.144,
"warm_last": {
"path": "warm",
"reason": "accepted",
- "elapsed_s": 0.024,
+ "elapsed_s": 0.038,
"prompt_tokens": 33892,
"cached_tokens": 16946
},
@@ -189,7 +189,7 @@
"install",
"run"
],
- "process_seconds": 53.442
+ "process_seconds": 80.092
},
{
"scenario": "manual_fallback",
@@ -248,11 +248,11 @@
"threshold_tokens": 100000,
"context_length": 200000
},
- "compress_seconds": 0.238,
+ "compress_seconds": 0.345,
"warm_last": {
"path": "fallback",
"reason": "provider_error",
- "elapsed_s": 0.109,
+ "elapsed_s": 0.172,
"prompt_tokens": null,
"cached_tokens": null
},
@@ -260,11 +260,10 @@
"final_session_id": "wc-manual_fallback",
"continuation_keeps_custom_system_text": false,
"fence_denied": {
- "child_process_blocked": 4,
- "network_host_blocked": 1
+ "network_host_blocked": 1,
+ "child_process_blocked": 3
},
"fence_blocked_programs": [
- "git",
"pip",
"python",
"python3"
@@ -273,7 +272,6 @@
"hermes-assets.nousresearch.com"
],
"fence_blocked_callers": [
- "child_process_blocked from hermes_cli/source_check.py:_git_run < hermes_cli/source_check.py:_git_stdout < hermes_cli/source_check.py:_read_checkout",
"child_process_blocked from tools/env_probe.py:_run < tools/env_probe.py:_py_out < tools/env_probe.py:_pip_python_version",
"child_process_blocked from tools/env_probe.py:_run < tools/env_probe.py:_py_out < tools/env_probe.py:_python_version_of",
"network_host_blocked from hermes_cli/release_channels.py:read < hermes_cli/release_channels.py:read_bytes < hermes_cli/release_channels.py:read_record"
@@ -361,7 +359,7 @@
"install",
"run"
],
- "process_seconds": 33.695
+ "process_seconds": 47.001
},
{
"scenario": "manual_fixed",
@@ -419,11 +417,11 @@
"threshold_tokens": 100000,
"context_length": 200000
},
- "compress_seconds": 0.28,
+ "compress_seconds": 0.276,
"warm_last": {
"path": "fixed",
"reason": "provider_error",
- "elapsed_s": 0.141,
+ "elapsed_s": 0.125,
"prompt_tokens": null,
"cached_tokens": null
},
@@ -532,7 +530,7 @@
"install",
"run"
],
- "process_seconds": 31.52
+ "process_seconds": 38.423
},
{
"scenario": "auto_tool_loop",
@@ -736,7 +734,274 @@
"install",
"run"
],
- "process_seconds": 34.084
+ "process_seconds": 38.631
+ },
+ {
+ "scenario": "auto_warm_failures",
+ "python": "3.11.14",
+ "status": "passed",
+ "checks": {
+ "listed_in_engine_picker": true,
+ "engine_selected": true,
+ "turn1_final": true,
+ "turn2_final": true,
+ "turn3_final": true,
+ "turn4_final": true,
+ "three_fallbacks_then_warm": true,
+ "one_notice": true,
+ "notice_before_the_fourth_compaction": true,
+ "notice_names_the_reason": true,
+ "each_refusal_in_agent_log": true,
+ "each_refusal_in_errors_log": true,
+ "notice_in_errors_log": true,
+ "plugin_made_no_blocked_call": true
+ },
+ "requests": [
+ {
+ "seq": 0,
+ "kind": "main",
+ "status": 200,
+ "stream": true,
+ "message_count": 62
+ },
+ {
+ "seq": 1,
+ "kind": "warm",
+ "status": 500,
+ "stream": false,
+ "message_count": 65
+ },
+ {
+ "seq": 2,
+ "kind": "fallback",
+ "status": 200,
+ "stream": true,
+ "message_count": 2
+ },
+ {
+ "seq": 3,
+ "kind": "main",
+ "status": 200,
+ "stream": true,
+ "message_count": 24
+ },
+ {
+ "seq": 4,
+ "kind": "main",
+ "status": 200,
+ "stream": true,
+ "message_count": 26
+ },
+ {
+ "seq": 5,
+ "kind": "warm",
+ "status": 500,
+ "stream": false,
+ "message_count": 29
+ },
+ {
+ "seq": 6,
+ "kind": "fallback",
+ "status": 200,
+ "stream": true,
+ "message_count": 2
+ },
+ {
+ "seq": 7,
+ "kind": "main",
+ "status": 200,
+ "stream": true,
+ "message_count": 28
+ },
+ {
+ "seq": 8,
+ "kind": "main",
+ "status": 200,
+ "stream": true,
+ "message_count": 30
+ },
+ {
+ "seq": 9,
+ "kind": "warm",
+ "status": 500,
+ "stream": false,
+ "message_count": 33
+ },
+ {
+ "seq": 10,
+ "kind": "fallback",
+ "status": 200,
+ "stream": true,
+ "message_count": 2
+ },
+ {
+ "seq": 11,
+ "kind": "main",
+ "status": 200,
+ "stream": true,
+ "message_count": 32
+ },
+ {
+ "seq": 12,
+ "kind": "main",
+ "status": 200,
+ "stream": true,
+ "message_count": 34
+ },
+ {
+ "seq": 13,
+ "kind": "warm",
+ "status": 200,
+ "stream": false,
+ "message_count": 37
+ },
+ {
+ "seq": 14,
+ "kind": "main",
+ "status": 200,
+ "stream": true,
+ "message_count": 36
+ }
+ ],
+ "error": null,
+ "engine": {
+ "name": "warm_compaction",
+ "threshold_tokens": 80000,
+ "context_length": 200000
+ },
+ "outcomes": [
+ [
+ "fallback",
+ "provider_error"
+ ],
+ [
+ "fallback",
+ "provider_error"
+ ],
+ [
+ "fallback",
+ "provider_error"
+ ],
+ [
+ "warm",
+ "accepted"
+ ]
+ ],
+ "notices": [
+ "🗜️ Compacting context — summarizing earlier conversation so I can continue...\nwarm_compaction: the last 3 compactions did not use the warm cache (provider_error). Compaction still works with the fallback summary, but it is slower. Likely cause: the server refused the warm request (a provider error, or a gateway that needs a cookie). Details: the warm_compaction lines in logs/agent.log."
+ ],
+ "status_count": 13,
+ "log_counts": {
+ "agent_refusals": 3,
+ "errors_refusals": 3,
+ "errors_notice": 1
+ },
+ "fence_denied": {
+ "child_process_blocked": 8,
+ "network_host_blocked": 1
+ },
+ "fence_blocked_programs": [
+ "git",
+ "pip",
+ "python",
+ "python3"
+ ],
+ "fence_blocked_hosts": [
+ "hermes-assets.nousresearch.com"
+ ],
+ "fence_blocked_callers": [
+ "child_process_blocked from hermes_cli/local_runtime/processes.py:spawn_server < hermes_cli/_subprocess_compat.py:bounded_probe_run < hermes_cli/_subprocess_compat.py:bounded_git_probe",
+ "child_process_blocked from hermes_cli/local_runtime/processes.py:spawn_server < hermes_cli/_subprocess_compat.py:bounded_probe_run < hermes_cli/_subprocess_compat.py:noninteractive_repo_git_env",
+ "child_process_blocked from hermes_cli/source_check.py:_git_run < hermes_cli/source_check.py:_git_stdout < hermes_cli/source_check.py:_read_checkout",
+ "child_process_blocked from tools/env_probe.py:_run < tools/env_probe.py:_py_out < tools/env_probe.py:_pip_python_version",
+ "child_process_blocked from tools/env_probe.py:_run < tools/env_probe.py:_py_out < tools/env_probe.py:_python_version_of",
+ "network_host_blocked from hermes_cli/release_channels.py:read < hermes_cli/release_channels.py:read_bytes < hermes_cli/release_channels.py:read_record"
+ ],
+ "fence_socketpairs": 0,
+ "install": {
+ "python": "3.11.14",
+ "enable_path": "plugins.enabled in config",
+ "enabled_keys": [
+ "warm_compaction",
+ "wc_test_tools"
+ ],
+ "validate": [
+ [
+ "manifest",
+ true
+ ],
+ [
+ "manifest fields",
+ true
+ ],
+ [
+ "requires_hermes",
+ true
+ ],
+ [
+ "config schema",
+ true
+ ],
+ [
+ "requires_env",
+ true
+ ],
+ [
+ "loadable",
+ true
+ ],
+ [
+ "python dependencies",
+ true
+ ],
+ [
+ "capability probe",
+ true
+ ],
+ [
+ "declared tools",
+ true
+ ],
+ [
+ "declared hooks",
+ true
+ ],
+ [
+ "declared middleware",
+ true
+ ],
+ [
+ "built-in tool collisions",
+ true
+ ],
+ [
+ "security scan",
+ true
+ ],
+ [
+ "no core override",
+ true
+ ]
+ ],
+ "checks": {
+ "enabled_in_config": true,
+ "installed": true,
+ "validate_ok": true,
+ "security_scan_passed": true,
+ "no_core_override_passed": true
+ },
+ "error": null
+ },
+ "run_interpreter": "launch_python",
+ "exit": [
+ 0,
+ 0
+ ],
+ "phases": [
+ "install",
+ "run"
+ ],
+ "process_seconds": 38.35
},
{
"scenario": "rollback",
@@ -786,11 +1051,11 @@
"threshold_tokens": 100000,
"context_length": 200000
},
- "compress_seconds": 0.149,
+ "compress_seconds": 0.187,
"warm_last": {
"path": "warm",
"reason": "accepted",
- "elapsed_s": 0.016,
+ "elapsed_s": 0.015,
"prompt_tokens": 33882,
"cached_tokens": 16941
},
@@ -798,7 +1063,7 @@
"final_session_id": "wc-rollback",
"continuation_keeps_custom_system_text": false,
"fence_denied": {
- "child_process_blocked": 5,
+ "child_process_blocked": 4,
"network_host_blocked": 1
},
"fence_blocked_programs": [
@@ -949,7 +1214,8 @@
"stored": 30
},
"fence_denied": {
- "child_process_blocked": 5
+ "child_process_blocked": 5,
+ "network_host_blocked": 1
},
"fence_blocked_programs": [
"git",
@@ -957,7 +1223,9 @@
"python",
"python3"
],
- "fence_blocked_hosts": []
+ "fence_blocked_hosts": [
+ "hermes-assets.nousresearch.com"
+ ]
},
"exit": [
0,
@@ -969,10 +1237,10 @@
"run",
"rollback"
],
- "process_seconds": 38.551
+ "process_seconds": 44.95
}
],
- "finished_utc": "2026-10-06T18:55:25Z",
+ "finished_utc": "2026-10-07T02:39:42Z",
"passed": true,
"run_folder": "outside repository"
}
diff --git a/scripts/check_plugin_hermes.py b/scripts/check_plugin_hermes.py
index ed679a7..f469ad2 100644
--- a/scripts/check_plugin_hermes.py
+++ b/scripts/check_plugin_hermes.py
@@ -63,7 +63,11 @@ TOOL_PLUGIN = {
' "parameters": {"type": "object", "properties": {}, "required": []}})\n'
),
}
-SCENARIOS = ("enable_manual_warm", "manual_fallback", "manual_fixed", "auto_tool_loop", "rollback")
+SCENARIOS = ("enable_manual_warm", "manual_fallback", "manual_fixed", "auto_tool_loop", "auto_warm_failures",
+ "rollback")
+# The scenarios with automatic compaction in a tool loop.
+AUTO_SCENARIOS = ("auto_tool_loop", "auto_warm_failures")
+NOTICE_MARK = "did not use the warm cache"
# The rollback scenario has a third process: a new Hermes process with the built-in compressor.
PHASES = {"rollback": ("install", "run", "rollback")}
DEFAULT_PHASES = ("install", "run")
@@ -191,7 +195,10 @@ class FakeServer:
entry = {"seq": len(self.requests), "kind": kind, "body": body, "status": 200}
self.requests.append(entry)
if kind == "warm":
- entry["status"] = self.plan.get("warm_status", 200)
+ # The first warm_fail_first warm requests fail; the later ones use warm_status.
+ warm_seen = sum(1 for request in self.requests if request["kind"] == "warm")
+ failing = warm_seen <= self.plan.get("warm_fail_first", 0)
+ entry["status"] = 500 if failing else self.plan.get("warm_status", 200)
payload = completion(HANDOFF, prompt_tokens=size, cached_tokens=self.plan.get("cached", size // 2))
elif kind == "fallback":
entry["status"] = self.plan.get("fallback_status", 200)
@@ -355,6 +362,13 @@ def plan_for(scenario):
if scenario == "manual_fixed":
return {"warm_status": 500, "fallback_status": 500,
"main": [{"content": "The code word is BLUE-7."}, {"content": "Next."}]}
+ if scenario == "auto_warm_failures":
+ # Four automatic compactions; the server refuses the first three warm requests.
+ main = []
+ for index in range(4):
+ main += [{"tool": {"id": f"call_{index + 1}", "name": "wc_note"}, "prompt_tokens": 150_000},
+ {"content": f"Done {index + 1}.", "prompt_tokens": 20_000}]
+ return {"warm_fail_first": 3, "main": main}
if scenario == "auto_tool_loop":
return {"main": [
{"tool": {"id": "call_1", "name": "wc_note"}, "prompt_tokens": 150_000},
@@ -367,7 +381,7 @@ def plan_for(scenario):
def base_config(scenario):
"""The run phase replaces the placeholder URL with the URL of its fake server."""
- settings = {"threshold": 0.4} if scenario == "auto_tool_loop" else {}
+ settings = {"threshold": 0.4} if scenario in AUTO_SCENARIOS else {}
return {
"model": {"default": MODEL, "provider": "custom", "base_url": PLACEHOLDER_URL,
"context_length": CONTEXT_LENGTH},
@@ -433,7 +447,7 @@ def install_phase(spec, session_dir):
documented = scenario == "enable_manual_warm"
cmd_install(spec["plugin_url"], enable=documented)
names = ["warm_compaction"]
- if scenario == "auto_tool_loop":
+ if scenario in AUTO_SCENARIOS:
cmd_install(spec["tool_plugin_url"], enable=False)
names.append("wc_test_tools")
if not documented:
@@ -499,15 +513,18 @@ def run_phase(spec, session_dir):
sys.addaudithook(fence)
db = SessionDB(home / "state.db")
+ # The status lines that Hermes shows the user (CLI print and the gateway status callback).
+ statuses = []
sid = f"wc-{scenario}"
db.create_session(sid, "cli")
db.append_messages_batch(sid, synthetic_history())
agent = AIAgent(base_url=server.base_url, api_key="no-key-required", provider="custom",
api_mode="chat_completions", model=MODEL,
- enabled_toolsets=["wc_test"] if scenario == "auto_tool_loop" else [],
+ enabled_toolsets=["wc_test"] if scenario in AUTO_SCENARIOS else [],
disabled_toolsets=[], quiet_mode=True, skip_context_files=True, skip_memory=True,
skip_background_review=True, capabilities={"vision": False}, session_id=sid,
- session_db=db, max_tokens=1024, platform="cli", cwd=str(session_dir))
+ session_db=db, max_tokens=1024, platform="cli", cwd=str(session_dir),
+ status_callback=lambda kind, message: statuses.append([kind, str(message)]))
engine = agent.context_compressor
checks["engine_selected"] = getattr(engine, "name", None) == "warm_compaction"
result["engine"] = {"name": getattr(engine, "name", None), "threshold_tokens": engine.threshold_tokens,
@@ -515,6 +532,8 @@ def run_phase(spec, session_dir):
history = db.get_messages_as_conversation(sid)
if scenario == "auto_tool_loop":
run_auto(agent, engine, history, server, result, checks)
+ elif scenario == "auto_warm_failures":
+ run_auto_failures(agent, engine, history, server, result, checks, statuses, home)
else:
run_manual(agent, engine, db, history, server, result, checks, scenario,
_compress_session_history, finalize_context_engine_compression_notification)
@@ -765,6 +784,43 @@ def run_auto(agent, engine, history, server, result, checks):
result["compression_count"] = engine.compression_count
+def run_auto_failures(agent, engine, history, server, result, checks, statuses, home):
+ """Repeated warm refusals: each one is a WARNING in agent.log and errors.log, and after the third one the
+ next automatic compaction status shows one notice to the user. A warm compaction ends the streak."""
+ questions = (TOOL_QUESTION, TOOL_AGAIN_QUESTION)
+ outcomes, notice_turn = [], None
+ messages = history
+ for turn in range(4):
+ before = len(statuses)
+ reply = agent.run_conversation(questions[turn % 2], system_message=SYSTEM, conversation_history=messages)
+ messages = list(reply.get("messages") or [])
+ checks[f"turn{turn + 1}_final"] = reply.get("final_response") == f"Done {turn + 1}."
+ last = dict(engine.warm_last or {})
+ outcomes.append([last.get("path"), last.get("reason")])
+ if any(NOTICE_MARK in message for _kind, message in statuses[before:]):
+ notice_turn = turn + 1
+ result["outcomes"] = outcomes
+ notices = [message for _kind, message in statuses if NOTICE_MARK in message]
+ # Metadata only: the notice has no conversation text, so its text goes into the report.
+ result["notices"] = notices
+ result["status_count"] = len(statuses)
+ checks["three_fallbacks_then_warm"] = outcomes == [["fallback", "provider_error"]] * 3 + [["warm", "accepted"]]
+ checks["one_notice"] = len(notices) == 1
+ checks["notice_before_the_fourth_compaction"] = notice_turn == 4
+ checks["notice_names_the_reason"] = bool(notices) and "(provider_error)" in notices[0]
+ logs = home / "logs"
+ def read_log(name):
+ path = logs / name
+ return path.read_text(encoding="utf-8", errors="replace") if path.is_file() else ""
+ agent_log, errors_log = read_log("agent.log"), read_log("errors.log")
+ refusal = "warm request was not used (provider_error)"
+ result["log_counts"] = {"agent_refusals": agent_log.count(refusal), "errors_refusals": errors_log.count(refusal),
+ "errors_notice": errors_log.count(NOTICE_MARK)}
+ checks["each_refusal_in_agent_log"] = agent_log.count(refusal) == 3
+ checks["each_refusal_in_errors_log"] = errors_log.count(refusal) == 3
+ checks["notice_in_errors_log"] = errors_log.count(NOTICE_MARK) == 1
+
+
# ---------------------------------------------------------------------------------------------------------
# Parent
# ---------------------------------------------------------------------------------------------------------
diff --git a/tests/test_wc_engine.py b/tests/test_wc_engine.py
index 845014a..adb0321 100644
--- a/tests/test_wc_engine.py
+++ b/tests/test_wc_engine.py
@@ -585,6 +585,71 @@ class EngineTest(unittest.TestCase):
engine = self.make(tail_tokens=500_000)
self.assertEqual(engine._tail_cap(0, None, 0) - engine._tail_cap(2_000, None, 0, 1_000), 3_000)
+ def test_three_compactions_without_the_warm_path_tell_the_user_one_time(self):
+ # No capture: each compaction uses the fallback. Each refusal is a WARNING; the third one adds one notice
+ # to the next automatic compaction status that Hermes shows.
+ engine = self.make()
+ history = [*old_turns(), assistant("done")]
+ with self.assertLogs("warm_compaction.engine", level="WARNING") as logs:
+ for _ in range(3):
+ engine.compress(history)
+ self.assertEqual((engine.warm_last["path"], engine.warm_last["reason"]), ("fallback", "no_capture"))
+ self.assertEqual(sum("warm request was not used (no_capture)" in line for line in logs.output), 3)
+ self.assertEqual(sum("last 3 compactions did not use the warm cache" in line for line in logs.output), 1)
+ message = engine.get_automatic_compaction_status_message(phase="compress", default_message="Compacting")
+ self.assertTrue(message.startswith("Compacting\n"))
+ self.assertIn("last 3 compactions did not use the warm cache (no_capture)", message)
+ self.assertIn("no main-model request completed", message)
+ # One time only.
+ self.assertEqual(engine.get_automatic_compaction_status_message(phase="compress",
+ default_message="Compacting"), "Compacting")
+
+ def test_a_warm_compaction_ends_the_failure_streak(self):
+ engine = self.make()
+ rows, reply = old_turns(), assistant("final")
+ for _ in range(2):
+ engine.compress([*rows, reply])
+ self.seed(rows, reply)
+ engine.compress([*rows, reply])
+ self.assertEqual(engine.warm_last["path"], "warm")
+ self.store.forget(session_id="s1")
+ for _ in range(2):
+ engine.compress([*rows, reply])
+ self.assertEqual(engine.get_automatic_compaction_status_message(phase="compress",
+ default_message="Compacting"), "Compacting")
+
+ def test_a_cancelled_attempt_does_not_end_the_failure_streak(self):
+ engine = self.make()
+ history = [*old_turns(), assistant("done")]
+ engine.compress(history)
+ engine._compression_cancelled_check = lambda: True
+ engine.compress(history)
+ self.assertEqual(engine.warm_last["path"], "cancelled")
+ engine._compression_cancelled_check = lambda: False
+ for _ in range(2):
+ engine.compress(history)
+ self.assertIn("did not use the warm cache",
+ engine.get_automatic_compaction_status_message(phase="compress", default_message="Compacting"))
+
+ def test_the_warm_setting_off_is_not_a_failure(self):
+ engine = self.make(warm=False)
+ history = [*old_turns(), assistant("done")]
+ with self.assertNoLogs("warm_compaction.engine", level="WARNING"):
+ for _ in range(4):
+ engine.compress(history)
+ self.assertEqual(engine.get_automatic_compaction_status_message(phase="compress",
+ default_message="Compacting"), "Compacting")
+
+ def test_the_notice_shows_when_the_host_status_is_turned_off(self):
+ # A user who turned the compaction status off still gets the notice: it is a warning, not progress.
+ engine = self.make()
+ history = [*old_turns(), assistant("done")]
+ for _ in range(3):
+ engine.compress(history)
+ engine.emit_automatic_compaction_status = False
+ message = engine.get_automatic_compaction_status_message(phase="compress", default_message="Compacting")
+ self.assertTrue(message.startswith("warm_compaction: the last 3 compactions"))
+
def test_an_unusable_capture_does_not_set_the_reasoning_rule(self):
# The capture is of this route, but its rows are not the stored rows: it does not show what the next
# request replays. The stored rows with reasoning_content do.
diff --git a/tests/wc_hermes_stub.py b/tests/wc_hermes_stub.py
index c770619..755d895 100644
--- a/tests/wc_hermes_stub.py
+++ b/tests/wc_hermes_stub.py
@@ -62,6 +62,12 @@ class StubContextEngine(abc.ABC):
def clone_for_agent(self):
return copy.deepcopy(self)
+ # Hermes 45871e10 (agent.context_engine): the automatic compaction status that the host shows, or None.
+ emit_automatic_compaction_status = True
+
+ def get_automatic_compaction_status_message(self, *, phase, default_message, **context):
+ return default_message if self.emit_automatic_compaction_status else None
+
def update_model(self, model, context_length, base_url="", api_key="", provider="", api_mode=""):
self.context_length = context_length
from agent.context_compressor import resolve_model_threshold
diff --git a/warm_compaction/engine.py b/warm_compaction/engine.py
index eecb4cd..1ce410b 100644
--- a/warm_compaction/engine.py
+++ b/warm_compaction/engine.py
@@ -32,6 +32,25 @@ FIXED_ROUNDS = 10
SUMMARY_RESERVE = 2 * fallback.MAX_TOKENS
# The largest reply reserve for an unknown reply limit: the Hermes output reserve of a native Gemini route.
UNKNOWN_RESERVE_MAX = 65_536
+# After this many compactions in a row without the warm path, the user gets one notice.
+WARM_FAILURE_STREAK = 3
+# What a user can do about the common reasons. Other reasons point to the README Limits.
+FAILURE_HINTS = {
+ "no_capture": "no main-model request completed in this Hermes process before the compaction",
+ "provider_error": "the server refused the warm request (a provider error, or a gateway that needs a cookie)",
+ "timeout": "the warm request took longer than its time limit",
+ "api_mode_unsupported": "this API mode has no warm path; only chat_completions has one",
+ "settings_unsupported": "the main request uses a setting that the warm request cannot keep",
+ "request_options_unsupported": "the main request uses extra headers or query options",
+ "credential_changed": "the API key changed after the last main request",
+ "capacity": "the warm request does not fit in the context window",
+ "summary_too_large": "the handoff did not fit in the free room of the context window",
+ "headers_unknown": "the route headers could not be read",
+ "tls_unknown": "the TLS settings of the route could not be read",
+ "middleware_after_capture": "another plugin middleware runs after the capture and can change the request",
+ "middleware_order_unknown": "the order of the plugin middleware could not be read",
+ "source_transform_unsupported": "a hook or middleware changed the stored rows in the request",
+}
HERMES_END_MARKER = "--- END OF CONTEXT SUMMARY — respond to the message below, not the summary above ---"
HERMES_DB_MARKER = "_db_persisted"
@@ -144,6 +163,10 @@ class WarmCompactionEngine(ContextEngine):
self._wc_provider: str = ""
# True after the first update_model: an empty provider and key are an identity too.
self._wc_identity_set = False
+ # Compactions in a row without the warm path, their reasons, and the notice for the next status.
+ self._warm_failures = 0
+ self._warm_failure_reasons: list[str] = []
+ self._warm_notice: str | None = None
@property
def name(self) -> str:
@@ -624,3 +647,41 @@ class WarmCompactionEngine(ContextEngine):
logger.info("warm_compaction: path=%s reason=%s elapsed_s=%s prompt_tokens=%s cached_tokens=%s",
record["path"], record["reason"], record["elapsed_s"], record["prompt_tokens"],
record["cached_tokens"])
+ self._note_warm_result(record)
+
+ def _note_warm_result(self, record: dict[str, Any]) -> None:
+ """Count the compactions in a row without the warm path. Each one is a WARNING (errors.log has it too).
+ After WARM_FAILURE_STREAK of them, one WARNING names the reasons and the cause, and the next automatic
+ compaction status shows it to the user. A warm compaction ends the streak. A cancelled attempt is not a
+ result, and the warm setting off is the user's choice: neither counts."""
+ path, reason = record["path"], str(record["reason"])
+ if path == "warm":
+ if self._warm_failures >= WARM_FAILURE_STREAK:
+ logger.info("warm_compaction: the warm path works again after %d compactions without it",
+ self._warm_failures)
+ self._warm_failures, self._warm_failure_reasons, self._warm_notice = 0, [], None
+ return
+ if path not in ("fallback", "fixed") or reason == "disabled":
+ return
+ logger.warning("warm_compaction: the warm request was not used (%s); the %s summary was used", reason, path)
+ self._warm_failures += 1
+ self._warm_failure_reasons.append(reason)
+ if self._warm_failures == WARM_FAILURE_STREAK:
+ reasons = ", ".join(dict.fromkeys(self._warm_failure_reasons))
+ hint = FAILURE_HINTS.get(reason.split(":", 1)[0], "see the Limits section of the plugin README")
+ self._warm_notice = (
+ f"warm_compaction: the last {self._warm_failures} compactions did not use the warm cache ({reasons}). "
+ f"Compaction still works with the fallback summary, but it is slower. Likely cause: {hint}. "
+ "Details: the warm_compaction lines in logs/agent.log.")
+ logger.warning(self._warm_notice)
+
+ def get_automatic_compaction_status_message(self, *, phase: str, default_message: str,
+ **context: Any) -> str | None:
+ """The Hermes status for an automatic compaction, with the warm failure notice one time after a streak.
+ The notice shows also when the user turned the compaction status off: it is a warning, not progress."""
+ message = super().get_automatic_compaction_status_message(phase=phase, default_message=default_message,
+ **context)
+ notice, self._warm_notice = self._warm_notice, None
+ if notice is None:
+ return message
+ return f"{message}\n{notice}" if message else notice