Hermes Agent context engine: the main model writes the compaction handoff on its cached prompt prefix
Refuse extra sent fields, keep clone thresholds, check the attempt after the send, and estimate sent content
Elevatormusicdabf48cdddbd
diff --git a/README.md b/README.mdindex d7df897..14f78fe 100644--- a/README.md+++ b/README.md@@ -197,7 +197,8 @@ 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 the warm request before it is sent (`route_changed` or `cancelled`).+- 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 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 warm request is not streamed and not retried. Its time limit is 120 seconds. The fallback request also has a 120-second limit.diff --git a/evidence/plugin-integration.json b/evidence/plugin-integration.jsonindex 3737e9f..10f81ac 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:08:25Z",+ "started_utc": "2026-10-06T14:23:16Z","hermes": {"commit": "45871e100feceb89769536c88e5e6e265226a409","clean": true@@ -10,13 +10,13 @@"plugin_files_sha256": {"warm_compaction/__init__.py": "11e038f05813627b2d1d8b82b3b775ecfe41015746c8e90ed6d452cfdaec65a6","warm_compaction/capture.py": "387a5bda2c97530c6e9114e810ac062199e3731c12a582d75598d2bdb95e8c57",- "warm_compaction/engine.py": "44a21ca2c779d0e404dc70feaf57fcaa28d36ff5b741cfe5094f056f9704e961",+ "warm_compaction/engine.py": "9723eb19203be4df6341197b9a6d5b622f99e2844063cd9f345100de4d9b3bb6","warm_compaction/fallback.py": "f4cf08186f38fc9a46f47af2bedf22584b6ede4f11de1c3abd0fd598aec2f8a4","warm_compaction/handoff.py": "9afea62ec2f8ef46cbeefd70b1071bb6c7111fa6fd1cd073e1fb2c7eae30f3c2","warm_compaction/layout.py": "2ade107c1b6fc4f4d1bc35e0118c17184d8fe241484aad4b36d03800acb965c7","warm_compaction/plugin.yaml": "d67560fd4625ec80d9e26f3e6d712763e77474f68d469c7e48f09fd3506ccc71",- "warm_compaction/rows.py": "689c0619df6a7f8b89ef05ae87ec81b62c812ce34f81bfe557eb653158effac4",- "warm_compaction/warm.py": "6ef65b128412838f70bd8d66f6fe98db87c48aacd81e21df8b7d48f8e411353a"+ "warm_compaction/rows.py": "d2ca064205e4d2c021240efcf64bb85c70e144c424dabafdbae085a0855f0836",+ "warm_compaction/warm.py": "f76aa64c739f8db7e228c25f9f3ee0c7d890c48eea8215f75577a2d6e5f4736b"},"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.108,+ "compress_seconds": 0.106,"warm_last": {"path": "warm","reason": "accepted",- "elapsed_s": 0.03,+ "elapsed_s": 0.025,"prompt_tokens": 33892,"cached_tokens": 16946},@@ -189,7 +189,7 @@"install","run"],- "process_seconds": 53.422+ "process_seconds": 53.734},{"scenario": "manual_fallback",@@ -248,11 +248,11 @@"threshold_tokens": 100000,"context_length": 200000},- "compress_seconds": 0.231,+ "compress_seconds": 0.244,"warm_last": {"path": "fallback","reason": "provider_error",- "elapsed_s": 0.094,+ "elapsed_s": 0.125,"prompt_tokens": null,"cached_tokens": null},@@ -361,7 +361,7 @@"install","run"],- "process_seconds": 40.886+ "process_seconds": 33.806},{"scenario": "manual_fixed",@@ -419,11 +419,11 @@"threshold_tokens": 100000,"context_length": 200000},- "compress_seconds": 0.221,+ "compress_seconds": 0.259,"warm_last": {"path": "fixed","reason": "provider_error",- "elapsed_s": 0.11,+ "elapsed_s": 0.125,"prompt_tokens": null,"cached_tokens": null},@@ -532,7 +532,7 @@"install","run"],- "process_seconds": 29.409+ "process_seconds": 30.941},{"scenario": "auto_tool_loop",@@ -620,7 +620,7 @@"warm_last_1": {"path": "warm","reason": "accepted",- "elapsed_s": 0.015,+ "elapsed_s": 0.031,"prompt_tokens": 35209,"cached_tokens": 17604},@@ -633,8 +633,8 @@},"compression_count": 2,"fence_denied": {- "child_process_blocked": 8,- "network_host_blocked": 1+ "network_host_blocked": 1,+ "child_process_blocked": 7},"fence_blocked_programs": ["git",@@ -648,7 +648,6 @@"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"@@ -737,7 +736,7 @@"install","run"],- "process_seconds": 34.311+ "process_seconds": 35.27},{"scenario": "rollback",@@ -787,7 +786,7 @@"threshold_tokens": 100000,"context_length": 200000},- "compress_seconds": 0.142,+ "compress_seconds": 0.156,"warm_last": {"path": "warm","reason": "accepted",@@ -950,8 +949,7 @@"stored": 30},"fence_denied": {- "child_process_blocked": 5,- "network_host_blocked": 1+ "child_process_blocked": 4},"fence_blocked_programs": ["git",@@ -959,9 +957,7 @@"python","python3"],- "fence_blocked_hosts": [- "hermes-assets.nousresearch.com"- ]+ "fence_blocked_hosts": []},"exit": [0,@@ -973,10 +969,10 @@"run","rollback"],- "process_seconds": 37.639+ "process_seconds": 39.944}],- "finished_utc": "2026-10-06T14:11:40Z",+ "finished_utc": "2026-10-06T14:26:30Z","passed": true,"run_folder": "outside repository"}diff --git a/tests/test_wc_engine.py b/tests/test_wc_engine.pyindex 8006848..e711af9 100644--- a/tests/test_wc_engine.py+++ b/tests/test_wc_engine.py@@ -231,10 +231,13 @@ class EngineTest(unittest.TestCase):rows = old_turns()reply = assistant("final")self.seed(rows, reply)- self.engine.compress([*rows, reply])+ history = [*rows, reply]+ self.assertIs(self.engine.compress(history), history)self.assertEqual(self.post.calls, [])+ # The summary would be of the old route: the attempt is discarded, and no fallback runs.self.assertEqual((self.engine.warm_last["path"], self.engine.warm_last["reason"]),- ("fallback", "route_changed"))+ ("cancelled", "route_changed"))+ self.assertEqual(self.llm.calls, [])def test_preflight_counts_the_captured_overhead_and_reply_reserve(self):# A large system prompt and tool schemas take space that the history estimate does not show.@@ -273,6 +276,32 @@ class EngineTest(unittest.TestCase):self.seed(rows[:-1], rows[-1])self.assertFalse(engine.should_compress_preflight([*rows, user("next")]))+ def test_a_switch_during_the_send_discards_the_result(self):+ # The send blocks on the network; a model or session switch can occur before it returns.+ sent = fake_post()++ def post(url, data, headers, timeout_s):+ engine.update_model(model="other-model", context_length=200_000, base_url="https://other/v1",+ api_key="other-key", provider="custom", api_mode=ROUTE[2])+ return sent(url, data, headers, timeout_s)+ self.post = post+ engine = self.make()+ rows = old_turns()+ reply = assistant("final")+ self.seed(rows, reply)+ history = [*rows, reply]+ self.assertIs(engine.compress(history), history)+ self.assertEqual((engine.warm_last["path"], engine.warm_last["reason"]), ("cancelled", "route_changed"))+ self.assertEqual(self.llm.calls, [])++ def test_preflight_estimates_only_the_sent_content(self):+ # Hermes sends api_content in place of content: the stored display text is not in the request.+ rows = []+ for index in range(30):+ text = f"ask {index} " + "x" * 8_000+ rows += [user(text, api_content=text + "\n\n[ctx]"), assistant(f"answer {index}")]+ self.assertFalse(self.engine.should_compress_preflight(rows))+def test_a_second_send_is_refused_before_it_sends(self):def twice(request=None, next_call=None, **context):first = next_call()@@ -610,6 +639,13 @@ class EngineTest(unittest.TestCase):self.assertIs(self.engine.compress(messages), messages)self.assertIsNone(self.engine.warm_last)+ def test_clone_keeps_the_model_thresholds(self):+ self.engine.model_thresholds = {"fake": 0.25}+ clone = self.engine.clone_for_agent()+ self.engine.model_thresholds["fake"] = 0.9+ clone.update_model(model=ROUTE[0], context_length=200_000, base_url=ROUTE[1], api_mode=ROUTE[2])+ self.assertEqual(clone.threshold_tokens, 50_000)+def test_clone_shares_the_store_and_not_the_session(self):clone = self.engine.clone_for_agent()self.assertIsNot(clone, self.engine)diff --git a/tests/test_wc_warm.py b/tests/test_wc_warm.pyindex 07e8e8d..2546347 100644--- a/tests/test_wc_warm.py+++ b/tests/test_wc_warm.py@@ -284,6 +284,19 @@ class BuildRequestTest(unittest.TestCase):self.build(capture)self.assertEqual(caught.exception.code, "source_transform_unsupported")+ def test_refuses_a_sent_row_with_an_extra_field(self):+ # A field that the stored row does not give (a provider control, for example) changes what the model reads.+ for index, field in ((1, {"recipient": "x"}), (-1, {"prefix": True})):+ capture = capture_for(self.rows, self.reply)+ capture["body"]["messages"][index].update(field)+ with self.subTest(field=field), self.assertRaises(WarmRefusal) as caught:+ self.build(capture)+ self.assertEqual(caught.exception.code, "source_transform_unsupported")+ # Hermes prompt caching marks rows with cache_control on some routes.+ capture = capture_for(self.rows, self.reply)+ capture["body"]["messages"][1]["cache_control"] = {"type": "ephemeral"}+ self.build(capture)+def test_refuses_a_renamed_or_unnamed_user_row_and_accepts_an_unnamed_tool_row(self):self.rows = [user("u1", name="alice"), assistant("", [("c0", "read", "{}")]), tool("c0", "r0", name="read"),user("u2")]diff --git a/warm_compaction/engine.py b/warm_compaction/engine.pyindex 0aec91e..44a0e75 100644--- a/warm_compaction/engine.py+++ b/warm_compaction/engine.py@@ -11,7 +11,7 @@ from agent.context_engine import ContextEnginefrom . import fallback, handoff, layout, warmfrom .capture import CaptureStore-from .rows import api_content, attr, estimate_tokens, hermes_value+from .rows import api_content, attr, estimate_tokens, hermes_value, sent_rowslogger = logging.getLogger(__name__)@@ -144,8 +144,12 @@ class WarmCompactionEngine(ContextEngine):def clone_for_agent(self) -> "WarmCompactionEngine":"""Return a new engine for one agent. The clone shares the capture store and the model access."""- return WarmCompactionEngine(store=self._store, llm=self._llm, settings=self._settings, task=self._task,- post=self._post, clock=self._clock)+ clone = WarmCompactionEngine(store=self._store, llm=self._llm, settings=self._settings, task=self._task,+ post=self._post, clock=self._clock)+ # The per-model thresholds that update_model resolves (a copy: the clone must not change with this engine).+ if getattr(self, "model_thresholds", None):+ clone.model_thresholds = copy.deepcopy(self.model_thresholds)+ return clonedef on_session_start(self, session_id: str, **kwargs: Any) -> None:if kwargs.get("boundary_reason") == "compression" and kwargs.get("old_session_id"):@@ -182,7 +186,8 @@ class WarmCompactionEngine(ContextEngine):for the system rows and the tool schemas."""if self.threshold_tokens <= 0:return False- tokens = estimate_tokens(messages)+ # As Hermes sends the rows: the stored display text of a row with api_content is not in the request.+ tokens = estimate_tokens(sent_rows(messages))window = int(self.context_length or 0)budget = self._budget_capture(self._store.latest(self._wc_session_id), messages)if budget is not None:@@ -229,7 +234,7 @@ class WarmCompactionEngine(ContextEngine):summary = self._warm_summary(messages, capture, focus_topic, memory, prefixes, record, attempt)# The middles that the tail cuts (see layout.bound_tail): the rows before the tail do not have them.removed: list = []- if summary is None and not self._cancelled():+ if summary is None and not self._cancelled() and self._attempt() == attempt:layout.bound_tail(messages[start:], self._tail_cap(SUMMARY_RESERVE, overhead, reserve), removed)# Only the rows before the tail: the tail stays as it is, and a transcript of the whole history# can spend its budget on the tail.@@ -241,6 +246,12 @@ class WarmCompactionEngine(ContextEngine):record.update(path="cancelled", reason=record["reason"] or "cancelled")self._finish(record, started)return messages+ if self._attempt() != attempt:+ # A model or session switch during the attempt (while a request was on the network, for example): the+ # summary is of the old route or session. Hermes keeps the history.+ record.update(path="cancelled", reason="route_changed")+ self._finish(record, started)+ return messagesif summary is None:summary = fallback.fixed_summary([*messages[:start], *removed], prefixes)record["path"] = "fixed"@@ -354,6 +365,9 @@ class WarmCompactionEngine(ContextEngine):if self._attempt() != attempt:raise warm.WarmRefusal("route_changed")result = warm.send(base, route[1], api_key, post=self._post, extra_headers=headers, ssl_context=tls)+ # The send blocks on the network: a switch can occur before it returns.+ if self._attempt() != attempt:+ raise warm.WarmRefusal("route_changed")sent.append((result, dict(result)))return resulttry:diff --git a/warm_compaction/rows.py b/warm_compaction/rows.pyindex d5b8fb8..93f8a33 100644--- a/warm_compaction/rows.py+++ b/warm_compaction/rows.py@@ -99,6 +99,20 @@ def visible_text(content: Any) -> str:MIDDLE_MARK = " [cut] "+def sent_rows(messages: list) -> list:+ """Return the rows as Hermes sends them, for an estimate: the api_content sidecar in place of the content, and+ no private (underscore) fields."""+ out = []+ for row in messages:+ if isinstance(row, dict):+ sent = {key: value for key, value in row.items() if key != "api_content" and not key.startswith("_")}+ sent["content"] = api_content(row)+ out.append(sent)+ else:+ out.append(row)+ return out++def cut_bounds(text: str, limit: int) -> tuple[int, int]:"""Return (end of the kept start, start of the kept end) of cut_middle: text[first:second] is the removedpart."""diff --git a/warm_compaction/warm.py b/warm_compaction/warm.pyindex f04073d..eab588c 100644--- a/warm_compaction/warm.py+++ b/warm_compaction/warm.py@@ -147,6 +147,24 @@ def _same_row(wire: Any, row: Any) -> bool:_arguments(arguments) for _id, _name, arguments in tool_calls_of(row)]+# Fields that Hermes adds to a sent row on some routes, apart from wire_row: the prompt caching marker.+TRANSPORT_FIELDS = frozenset({"cache_control"})+++def _no_extra_fields(wire: Any, expected: dict[str, Any]) -> bool:+ """True when the sent row and its tool calls have no field that Hermes does not send for the stored row (a+ provider control that a middleware added, for example): the model reads it."""+ if not isinstance(wire, dict):+ return True+ if set(wire) - set(expected) - TRANSPORT_FIELDS:+ return False+ for call, want in zip(wire.get("tool_calls") or [], expected.get("tool_calls") or []):+ if isinstance(call, dict) and (set(call) - set(want) or (+ isinstance(call.get("function"), dict) and set(call["function"]) - set(want.get("function") or {}))):+ return False+ return True++def _same_replay_fields(wire: Any, expected: dict[str, Any]) -> bool:"""True when the sent row has the reasoning fields and thought signatures that Hermes replays for the storedrow on this route. The provider reads them, so a change makes a prefix that the history does not have."""@@ -167,8 +185,9 @@ def check_source(body: dict[str, Any], history_rows: list, base_url: Any = None)raise WarmRefusal("source_transform_unsupported")# The replayed fields follow the captured request only: the new rows do not change what Hermes sent.echo = needs_reasoning_echo(body, [])- if not all(_same_replay_fields(wire, wire_row(row, echo, body.get("model"), base_url))- for wire, row in zip(sent[offset:], history_rows)):+ expected = [wire_row(row, echo, body.get("model"), base_url) for row in history_rows]+ if not all(_same_replay_fields(wire, want) and _no_extra_fields(wire, want)+ for wire, want in zip(sent[offset:], expected)):raise WarmRefusal("source_transform_unsupported")