Hermes Agent context engine: the main model writes the compaction handoff on its cached prompt prefix
Quote the cut middle of the prepended row in the fixed summary, and forget the capture on a key switch
Elevatormusicbfdf0f85b52f
diff --git a/README.md b/README.mdindex 14f78fe..4c5ef81 100644--- a/README.md+++ b/README.md@@ -198,9 +198,10 @@ The plugin was faster than both other engines in 10 of 10 cases. hermes-lcm and- The warm path needs a captured main-model request in the current Hermes process. After a restart or a resume, the first compaction uses the fallback summary if no main-model request completed before it (`no_capture`).- The warm request uses its own HTTP connection. It sends the route URL (with its query, for example an Azure `api-version`), the route headers, and the TLS settings, but not the cookies of the Hermes client. A gateway that needs a cookie from an earlier response refuses the warm request, and the fallback summary runs (`provider_error`).- A model or session switch, or a host timeout, during the attempt stops it, also while the warm request is on the network: the history stays unchanged (`route_changed` or `cancelled`).+- A provider or API key switch forgets the capture of the session: the next compaction uses the fallback summary (`no_capture`) until a main request on the new configuration completes.- A captured row with a field that Hermes does not send for the stored row (other than the prompt caching marker `cache_control`) refuses the warm path (`source_transform_unsupported`).- The handoff must start with `## Goal`: text before the first heading is refused (`gate:heading_preamble`).-- The verbatim tail keeps the newest rows that fit in `tail_tokens`. It stops at the first older row that does not fit, and that row goes into the summary. When the newest unit alone is larger than the tail or the free room, its largest sent payloads keep only their start and end: message text, tool call arguments (kept as a JSON object), and reasoning text. A large image or other media part is replaced by a short text. If the cuts are not enough, the payloads are dropped, largest first; only the row structure stays. Signed `reasoning_details` stay as they are. The fallback summary gets the cut middles, and the fixed summary quotes them (at most 8,000 characters). Without a usable capture (after a restart, after a model change, or when a middleware changed the captured rows), the request overhead is unknown: the summary has no copied user messages, the tail takes at most half of the free room, the check before a request compacts when the history estimate reaches half of the window less the reply reserve, and the reply reserve is a quarter of the window (at most 65,536 and at least 4,096 tokens). The host token count is not used for the overhead: it does not use the plugin tokenizer.+- The verbatim tail keeps the newest rows that fit in `tail_tokens`. It stops at the first older row that does not fit, and that row goes into the summary. When the newest unit alone is larger than the tail or the free room, its largest sent payloads keep only their start and end: message text, tool call arguments (kept as a JSON object), and reasoning text. A large image or other media part is replaced by a short text. If the cuts are not enough, the payloads are dropped, largest first; only the row structure stays. Signed `reasoning_details` stay as they are. The fallback summary gets the cut middles, and the fixed summary quotes them (at most 8,000 characters), also the cut middle of a long latest user message that goes in front of the tail. Without a usable capture (after a restart, after a model change, or when a middleware changed the captured rows), the request overhead is unknown: the summary has no copied user messages, the tail takes at most half of the free room, the check before a request compacts when the history estimate reaches half of the window less the reply reserve, and the reply reserve is a quarter of the window (at most 65,536 and at least 4,096 tokens). The host token count is not used for the overhead: it does not use the plugin tokenizer.- The warm request is not streamed and not retried. Its time limit is 120 seconds. The fallback request also has a 120-second limit.- A request with `extra_headers` or `extra_query`, `n` above 1, a forced `tool_choice`, `response_format`, or audio settings uses the fallback (`settings_unsupported`).- After `/compress`, Hermes builds the system prompt again from its configuration. A system message that a host gave in code is not kept. This is Hermes behavior, and it is the same for the built-in compressor.diff --git a/evidence/plugin-integration.json b/evidence/plugin-integration.jsonindex 10f81ac..3f57786 100644--- a/evidence/plugin-integration.json+++ b/evidence/plugin-integration.json@@ -1,6 +1,6 @@{"check": "standalone warm_compaction plugin on unpatched Hermes Agent",- "started_utc": "2026-10-06T14:23:16Z",+ "started_utc": "2026-10-06T14:39:33Z","hermes": {"commit": "45871e100feceb89769536c88e5e6e265226a409","clean": true@@ -10,10 +10,10 @@"plugin_files_sha256": {"warm_compaction/__init__.py": "11e038f05813627b2d1d8b82b3b775ecfe41015746c8e90ed6d452cfdaec65a6","warm_compaction/capture.py": "387a5bda2c97530c6e9114e810ac062199e3731c12a582d75598d2bdb95e8c57",- "warm_compaction/engine.py": "9723eb19203be4df6341197b9a6d5b622f99e2844063cd9f345100de4d9b3bb6",+ "warm_compaction/engine.py": "ba58072c5508c987bc4095b9a9c30c6aedffa998b07562c70071fa0845088106","warm_compaction/fallback.py": "f4cf08186f38fc9a46f47af2bedf22584b6ede4f11de1c3abd0fd598aec2f8a4","warm_compaction/handoff.py": "9afea62ec2f8ef46cbeefd70b1071bb6c7111fa6fd1cd073e1fb2c7eae30f3c2",- "warm_compaction/layout.py": "2ade107c1b6fc4f4d1bc35e0118c17184d8fe241484aad4b36d03800acb965c7",+ "warm_compaction/layout.py": "a45b12d53b7fcaf8ca61a57000cf29329d68fc4ea47526c9919ce46e8bb8146b","warm_compaction/plugin.yaml": "d67560fd4625ec80d9e26f3e6d712763e77474f68d469c7e48f09fd3506ccc71","warm_compaction/rows.py": "d2ca064205e4d2c021240efcf64bb85c70e144c424dabafdbae085a0855f0836","warm_compaction/warm.py": "f76aa64c739f8db7e228c25f9f3ee0c7d890c48eea8215f75577a2d6e5f4736b"@@ -76,11 +76,11 @@"threshold_tokens": 100000,"context_length": 200000},- "compress_seconds": 0.106,+ "compress_seconds": 0.099,"warm_last": {"path": "warm","reason": "accepted",- "elapsed_s": 0.025,+ "elapsed_s": 0.023,"prompt_tokens": 33892,"cached_tokens": 16946},@@ -88,11 +88,10 @@"final_session_id": "wc-enable_manual_warm","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"@@ -101,7 +100,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"@@ -189,7 +187,7 @@"install","run"],- "process_seconds": 53.734+ "process_seconds": 53.942},{"scenario": "manual_fallback",@@ -248,11 +246,11 @@"threshold_tokens": 100000,"context_length": 200000},- "compress_seconds": 0.244,+ "compress_seconds": 0.239,"warm_last": {"path": "fallback","reason": "provider_error",- "elapsed_s": 0.125,+ "elapsed_s": 0.109,"prompt_tokens": null,"cached_tokens": null},@@ -361,7 +359,7 @@"install","run"],- "process_seconds": 33.806+ "process_seconds": 32.634},{"scenario": "manual_fixed",@@ -419,11 +417,11 @@"threshold_tokens": 100000,"context_length": 200000},- "compress_seconds": 0.259,+ "compress_seconds": 0.228,"warm_last": {"path": "fixed","reason": "provider_error",- "elapsed_s": 0.125,+ "elapsed_s": 0.109,"prompt_tokens": null,"cached_tokens": null},@@ -532,7 +530,7 @@"install","run"],- "process_seconds": 30.941+ "process_seconds": 30.224},{"scenario": "auto_tool_loop",@@ -620,21 +618,21 @@"warm_last_1": {"path": "warm","reason": "accepted",- "elapsed_s": 0.031,+ "elapsed_s": 0.015,"prompt_tokens": 35209,"cached_tokens": 17604},"warm_last_2": {"path": "warm","reason": "accepted",- "elapsed_s": 0.0,+ "elapsed_s": 0.015,"prompt_tokens": 18436,"cached_tokens": 9218},"compression_count": 2,"fence_denied": {- "network_host_blocked": 1,- "child_process_blocked": 7+ "child_process_blocked": 8,+ "network_host_blocked": 1},"fence_blocked_programs": ["git",@@ -648,6 +646,7 @@"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"@@ -736,7 +735,7 @@"install","run"],- "process_seconds": 35.27+ "process_seconds": 33.729},{"scenario": "rollback",@@ -786,11 +785,11 @@"threshold_tokens": 100000,"context_length": 200000},- "compress_seconds": 0.156,+ "compress_seconds": 0.143,"warm_last": {"path": "warm","reason": "accepted",- "elapsed_s": 0.015,+ "elapsed_s": 0.0,"prompt_tokens": 33882,"cached_tokens": 16941},@@ -949,7 +948,8 @@"stored": 30},"fence_denied": {- "child_process_blocked": 4+ "child_process_blocked": 5,+ "network_host_blocked": 1},"fence_blocked_programs": ["git",@@ -957,7 +957,9 @@"python","python3"],- "fence_blocked_hosts": []+ "fence_blocked_hosts": [+ "hermes-assets.nousresearch.com"+ ]},"exit": [0,@@ -969,10 +971,10 @@"run","rollback"],- "process_seconds": 39.944+ "process_seconds": 39.267}],- "finished_utc": "2026-10-06T14:26:30Z",+ "finished_utc": "2026-10-06T14:42:43Z","passed": true,"run_folder": "outside repository"}diff --git a/tests/test_wc_engine.py b/tests/test_wc_engine.pyindex e711af9..c0e3954 100644--- a/tests/test_wc_engine.py+++ b/tests/test_wc_engine.py@@ -639,6 +639,41 @@ class EngineTest(unittest.TestCase):self.assertIs(self.engine.compress(messages), messages)self.assertIsNone(self.engine.warm_last)+ def test_the_fixed_summary_quotes_the_cut_middle_of_the_prepended_row(self):+ # The prepended row is the latest user message; it is not copied, so its cut middle must stay in the+ # summary when no model summary is available.+ from warm_compaction.layout import MIN_COPY_CHARS+ from warm_compaction.rows import estimate_tokens+ from warm_compaction.warm import DEFAULT_RESERVE+ self.llm.error = RuntimeError("down")+ rows = [*old_turns(4), user("BIG start " + "q" * 1_000 + " MID-REQ " + "q" * 40_000 + " big end"),+ assistant("", [("c1", "read", "{}")]), tool("c1", "r1"), assistant("done")]+ engine = self.make(threshold=0.95, tail_tokens=2_000, warm=False)+ engine.update_model(model=ROUTE[0], context_length=64_000, base_url=ROUTE[1], api_key="k",+ provider="custom", api_mode=ROUTE[2])+ new = engine.compress(rows)+ self.assertEqual(engine.warm_last["path"], "fixed")+ prepended = next(row for row in new if str(row.get("content")).startswith("BIG start"))+ self.assertLessEqual(len(prepended["content"]), MIN_COPY_CHARS)+ self.assertNotIn("MID-REQ", prepended["content"])+ self.assertTrue(any("MID-REQ" in str(row.get("content")) for row in new if row.get("_compressed_summary")))+ self.assertLessEqual(estimate_tokens(new), min(engine.threshold_tokens, 64_000 - DEFAULT_RESERVE))++ def test_a_provider_or_key_switch_forgets_the_capture(self):+ # Two configurations can share the model, the base URL, and the API mode; the old body must not go out+ # with the new key and headers.+ rows = old_turns(1)+ self.seed(rows, assistant("x"))+ self.engine.update_model(model=ROUTE[0], context_length=200_000, base_url=ROUTE[1], api_key="k",+ provider="custom", api_mode=ROUTE[2])+ self.assertIsNotNone(self.store.latest("s1"))+ for change in ({"api_key": "k2", "provider": "custom"}, {"api_key": "k2", "provider": "other"}):+ self.seed(rows, assistant("x"))+ with self.subTest(change=change):+ self.engine.update_model(model=ROUTE[0], context_length=200_000, base_url=ROUTE[1],+ api_mode=ROUTE[2], **change)+ self.assertIsNone(self.store.latest("s1"))+def test_clone_keeps_the_model_thresholds(self):self.engine.model_thresholds = {"fake": 0.25}clone = self.engine.clone_for_agent()diff --git a/warm_compaction/engine.py b/warm_compaction/engine.pyindex 44a0e75..19771dd 100644--- a/warm_compaction/engine.py+++ b/warm_compaction/engine.py@@ -160,6 +160,11 @@ class WarmCompactionEngine(ContextEngine):provider: str = "", api_mode: str = "") -> None:super().update_model(model, context_length, base_url=base_url, api_key=api_key, provider=provider,api_mode=api_mode)+ # A capture belongs to the provider and key that sent it: two configurations can share the model, the base+ # URL, and the API mode, and the old body must not go out with the new key and headers. The first call (no+ # identity yet) is not a switch.+ if (self._wc_provider or self._wc_api_key) and (provider, api_key) != (self._wc_provider, self._wc_api_key):+ self._store.forget(session_id=self._wc_session_id)self._wc_route = (model, base_url, api_mode)self._wc_api_key = api_keyself._wc_provider = provider@@ -255,14 +260,22 @@ class WarmCompactionEngine(ContextEngine):if summary is None:summary = fallback.fixed_summary([*messages[:start], *removed], prefixes)record["path"] = "fixed"- copy_tokens = 0 if overhead is None else self._copy_tokens(messages[start:], summary, overhead, reserve)# The prepended user row must be in the tail: when it does not fit in the room, keep its start and end.# With an unknown overhead, the room is unknown too: the row keeps only its minimum.room = self._room(messages[start:], summary, overhead or 0, reserve)if prepend is not None and room is not None:allowed = room if overhead is not None else 0if estimate_tokens(prepend) > allowed:- prepend = layout.fit_user_row(prepend, allowed)+ if record["path"] != "fixed":+ # A model summary had the whole row (in the warm request, or in the fallback transcript).+ prepend = layout.fit_user_row(prepend, allowed)+ else:+ # The row is not copied and the fixed summary does not have it: its cut middle goes into the+ # summary as a quote. The room keeps space for that quote.+ cut: list = []+ prepend = layout.fit_user_row(prepend, allowed - fallback.CUT_QUOTE_CHARS // 4, cut)+ summary = fallback.fixed_summary([*messages[:start], *removed, *cut], prefixes)+ copy_tokens = 0 if overhead is None else self._copy_tokens(messages[start:], summary, overhead, reserve)tail_tokens = self._tail_cap(estimate_tokens(summary), overhead, reserve,estimate_tokens(prepend) if prepend is not None else 0)new = layout.build(diff --git a/warm_compaction/layout.py b/warm_compaction/layout.pyindex 24f3f99..979e4f8 100644--- a/warm_compaction/layout.py+++ b/warm_compaction/layout.py@@ -184,9 +184,10 @@ def _fit_copy(text: str, chars: int, tokens: int | None) -> str | None:return None-def fit_user_row(row: dict[str, Any], tokens: int) -> dict[str, Any]:+def fit_user_row(row: dict[str, Any], tokens: int, removed: list | None = None) -> dict[str, Any]:"""Return the user row cut to its start and end, at most tokens estimated tokens (the text that Hermes- sent; an attachment becomes a mark). At least MIN_COPY_CHARS characters stay: the tail starts with it."""+ sent; an attachment becomes a mark). At least MIN_COPY_CHARS characters stay: the tail starts with it. With a+ removed list, a cut adds one user row to it: the removed middle after CUT_NOTE."""text = visible_text(api_content(row)).strip()limit = len(text)while True:@@ -195,6 +196,9 @@ def fit_user_row(row: dict[str, Any], tokens: int) -> dict[str, Any]:out["name"] = attr(row, "name")cost = estimate_tokens(out)if cost <= tokens or limit <= MIN_COPY_CHARS:+ if removed is not None and limit < len(text):+ first, second = cut_bounds(text, limit)+ removed.append({"role": "user", "content": CUT_NOTE + text[first:second]})return outlimit = max(MIN_COPY_CHARS, min(limit - 1, limit * max(tokens, 0) // cost))