Skip to content

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

Match and digest api_content, drop stop, keep ends of long text, and recheck capacity

Elevatormusic582c5aff266a
diff --git a/evidence/plugin-integration.json b/evidence/plugin-integration.json
index 0eedba0..fb894d5 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-06T08:32:14Z",
+ "started_utc": "2026-10-06T08:45:08Z",
"hermes": {
"commit": "45871e100feceb89769536c88e5e6e265226a409",
"clean": true
@@ -10,13 +10,13 @@
"plugin_files_sha256": {
"warm_compaction/__init__.py": "11e038f05813627b2d1d8b82b3b775ecfe41015746c8e90ed6d452cfdaec65a6",
"warm_compaction/capture.py": "3ee60f35ae4e8fc0376ab6634c721ae1ca429593d10730f19addc3be545fe682",
- "warm_compaction/engine.py": "95ae73286225c664512f567584e99ce07ff409a9071789ddc2a1d29eb24ec2a3",
- "warm_compaction/fallback.py": "f2551f0cf957b07fa6ba79dd92c8c5e211d70810d675e492ca509063b92de5a1",
+ "warm_compaction/engine.py": "83e2434a172a540e7e21053fd8da6d7204bc8eacadab1809213095821b362b96",
+ "warm_compaction/fallback.py": "5997b3c96ad7bbdaa4f505ffb470aa850c7c7afd33630f02823b3fdda6c46339",
"warm_compaction/handoff.py": "2fcdc2af2eba2d36eaabfef912ce0dd6d64bccc7849849e6411869a0025a06c2",
"warm_compaction/layout.py": "fd4d260380ce2cc44aa846758762a05bb4737c10677bceec0b17fd3c59c943f5",
"warm_compaction/plugin.yaml": "d67560fd4625ec80d9e26f3e6d712763e77474f68d469c7e48f09fd3506ccc71",
- "warm_compaction/rows.py": "a8943216049ef95742466c5628108154e239b96672726c732c508e30c95ac914",
- "warm_compaction/warm.py": "7e1df5fb42e962567baf0644943ab260680af42273a65e017d8cddaa0c978d40"
+ "warm_compaction/rows.py": "c0c0b7cfc5bebfa9caa58e9621ff3eda0db108c7976ca769da159be13574874b",
+ "warm_compaction/warm.py": "d5b619314975fad925137fd6b2b730634c4b264ee6a5fd402969810364a26775"
},
"privacy": "metadata only: names, counts, codes, booleans, and times; no message text",
"scenarios": [
@@ -75,11 +75,11 @@
"threshold_tokens": 100000,
"context_length": 200000
},
- "compress_seconds": 0.13,
+ "compress_seconds": 0.109,
"warm_last": {
"path": "warm",
"reason": "accepted",
- "elapsed_s": 0.032,
+ "elapsed_s": 0.021,
"prompt_tokens": 33883,
"cached_tokens": 16941
},
@@ -188,7 +188,7 @@
"install",
"run"
],
- "process_seconds": 59.565
+ "process_seconds": 56.444
},
{
"scenario": "manual_fallback",
@@ -247,11 +247,11 @@
"threshold_tokens": 100000,
"context_length": 200000
},
- "compress_seconds": 0.259,
+ "compress_seconds": 0.224,
"warm_last": {
"path": "fallback",
"reason": "provider_error",
- "elapsed_s": 0.125,
+ "elapsed_s": 0.094,
"prompt_tokens": null,
"cached_tokens": null
},
@@ -259,7 +259,7 @@
"final_session_id": "wc-manual_fallback",
"continuation_keeps_custom_system_text": false,
"fence_denied": {
- "child_process_blocked": 4,
+ "child_process_blocked": 5,
"network_host_blocked": 1
},
"fence_blocked_programs": [
@@ -360,7 +360,7 @@
"install",
"run"
],
- "process_seconds": 35.611
+ "process_seconds": 33.685
},
{
"scenario": "manual_fixed",
@@ -418,11 +418,11 @@
"threshold_tokens": 100000,
"context_length": 200000
},
- "compress_seconds": 0.271,
+ "compress_seconds": 0.249,
"warm_last": {
"path": "fixed",
"reason": "provider_error",
- "elapsed_s": 0.125,
+ "elapsed_s": 0.109,
"prompt_tokens": null,
"cached_tokens": null
},
@@ -531,7 +531,7 @@
"install",
"run"
],
- "process_seconds": 32.453
+ "process_seconds": 31.663
},
{
"scenario": "auto_tool_loop",
@@ -617,7 +617,7 @@
"warm_last_1": {
"path": "warm",
"reason": "accepted",
- "elapsed_s": 0.0,
+ "elapsed_s": 0.016,
"prompt_tokens": 35205,
"cached_tokens": 17602
},
@@ -630,8 +630,8 @@
},
"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",
@@ -645,6 +645,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"
@@ -733,7 +734,7 @@
"install",
"run"
],
- "process_seconds": 34.825
+ "process_seconds": 35.646
},
{
"scenario": "rollback",
@@ -783,11 +784,11 @@
"threshold_tokens": 100000,
"context_length": 200000
},
- "compress_seconds": 0.142,
+ "compress_seconds": 0.143,
"warm_last": {
"path": "warm",
"reason": "accepted",
- "elapsed_s": 0.0,
+ "elapsed_s": 0.015,
"prompt_tokens": 33873,
"cached_tokens": 16936
},
@@ -969,10 +970,10 @@
"run",
"rollback"
],
- "process_seconds": 41.308
+ "process_seconds": 42.283
}
],
- "finished_utc": "2026-10-06T08:35:38Z",
+ "finished_utc": "2026-10-06T08:48:28Z",
"passed": true,
"run_folder": "outside repository"
}
diff --git a/tests/test_wc_engine.py b/tests/test_wc_engine.py
index 13dcd36..af6b7d9 100644
--- a/tests/test_wc_engine.py
+++ b/tests/test_wc_engine.py
@@ -223,6 +223,18 @@ class EngineTest(unittest.TestCase):
self.assertEqual((self.engine.warm_last["path"], self.engine.warm_last["reason"]),
("fallback", "middleware_repeated"))
+ def test_capacity_is_checked_again_after_the_request_middleware(self):
+ def expand(request=None, **context):
+ request["messages"][-2]["content"] += " " + "context " * 200_000
+ return {"request": request}
+ wc_hermes_stub.REQUEST_MIDDLEWARE.append(expand)
+ rows = old_turns()
+ reply = assistant("final")
+ self.seed(rows, reply)
+ self.engine.compress([*rows, reply])
+ self.assertEqual((self.engine.warm_last["path"], self.engine.warm_last["reason"]), ("fallback", "capacity"))
+ self.assertEqual(self.post.calls, [])
+
def test_a_request_middleware_that_changes_the_captured_part_stops_the_warm_request(self):
# The captured body already went through the request middleware. A second pass would apply it twice.
def prepend(request=None, **context):
diff --git a/tests/test_wc_fallback.py b/tests/test_wc_fallback.py
index 35f86ec..e08bdde 100644
--- a/tests/test_wc_fallback.py
+++ b/tests/test_wc_fallback.py
@@ -74,6 +74,20 @@ class TranscriptTest(unittest.TestCase):
self.assertIn("## Goal", text)
self.assertIn("## Next step\nthe final step", text)
+ def test_the_first_user_slot_keeps_the_end(self):
+ first = "start " + "x" * 6_000 + " the real question"
+ rows = [user(first), *[assistant("z" * 3_900) for _ in range(12)]]
+ text = transcript(rows, PREFIXES)
+ slot = text.split("[first user message]\n", 1)[1].split("\n\n", 1)[0]
+ self.assertTrue(slot.startswith("start "))
+ self.assertTrue(slot.endswith(" the real question"))
+
+ def test_long_tool_call_arguments_keep_the_end(self):
+ arguments = '{"patch": "' + "y" * 1_000 + '", "path": "src/final.py"}'
+ text = render_row(assistant("", [("c1", "write", arguments)]))
+ self.assertIn('"path": "src/final.py"})', text)
+ self.assertIn('(tool call c1 write: {"patch": "', text)
+
def test_names_are_in_the_transcript_labels(self):
text = transcript([user("ship it", name="alice"), user("wait", name="bob"), assistant("ok", name="lead")],
PREFIXES)
diff --git a/tests/test_wc_warm.py b/tests/test_wc_warm.py
index fbcb2d2..4bca7f0 100644
--- a/tests/test_wc_warm.py
+++ b/tests/test_wc_warm.py
@@ -53,6 +53,20 @@ class SplitHistoryTest(unittest.TestCase):
self.assertEqual(caught.exception.code, "history_changed")
+class ApiContentHistoryTest(unittest.TestCase):
+ def test_the_reply_matches_by_its_api_content(self):
+ rows = history()
+ capture = capture_for(rows, assistant("The answer is 4."))
+ new_rows, _trailing = split_history(capture, [*rows, assistant("", api_content="The answer is 4.")])
+ self.assertEqual(len(new_rows), 1)
+
+ def test_the_digest_covers_the_api_content(self):
+ from warm_compaction.rows import row_digest
+ self.assertNotEqual(row_digest(user("hi", api_content="[a]\n\nhi")), row_digest(user("hi", api_content="[b]\n\nhi")))
+ self.assertNotEqual(row_digest(user("hi", api_content="[a]\n\nhi")), row_digest(user("hi")))
+ self.assertEqual(row_digest(dict(tool("c1", "r"), api_content="x")), row_digest(tool("c1", "r")))
+
+
class WireRowTest(unittest.TestCase):
def test_keeps_api_fields_only(self):
row = assistant(None, [("c1", "read", {"path": "a b"})], reasoning="r", _db_persisted=True)
@@ -152,6 +166,12 @@ class BuildRequestTest(unittest.TestCase):
INSTRUCTION)["messages"][-3]
self.assertNotIn("extra_content", sent["tool_calls"][0])
+ def test_the_stop_setting_is_not_sent(self):
+ # A stop sequence of the main request could cut the handoff after the five headings.
+ body = self.build(capture_for(self.rows, self.reply, body_extra={"stop": ["\n## Next"], "temperature": 0.2}))
+ self.assertNotIn("stop", body)
+ self.assertEqual(body["temperature"], 0.2)
+
def test_sends_every_trailing_user_row(self):
# The tail can keep only the newest of several user rows. The handoff must see the older ones too.
self.messages = [*self.messages, user("u4 " + "x" * 5_000)]
diff --git a/warm_compaction/engine.py b/warm_compaction/engine.py
index 9f85770..b190c21 100644
--- a/warm_compaction/engine.py
+++ b/warm_compaction/engine.py
@@ -213,7 +213,7 @@ class WarmCompactionEngine(ContextEngine):
handoff.build_instruction(focus_topic, memory))
if self._cancelled():
raise warm.WarmRefusal("cancelled")
- reply = self._execute(body, len(capture["body"]["messages"]))
+ reply = self._execute(body, len(capture["body"]["messages"]), capture.get("prompt_tokens"))
record.update(prompt_tokens=reply["prompt_tokens"], cached_tokens=reply["cached_tokens"])
text, reason = handoff.gate(reply, prefixes)
if text is None:
@@ -227,7 +227,7 @@ class WarmCompactionEngine(ContextEngine):
record.update(path="warm", reason="accepted")
return text
- def _execute(self, body: dict[str, Any], captured: int) -> dict[str, Any]:
+ def _execute(self, body: dict[str, Any], captured: int, measured: int | None = None) -> dict[str, Any]:
"""Send the warm request through the Hermes llm_request and llm_execution middleware, as Hermes sends a
main request. A request middleware can change the request, for example to redact the new rows. An
execution middleware can audit, block, or replace the request. A block, a rewrite, or a replaced reply
@@ -251,6 +251,9 @@ class WarmCompactionEngine(ContextEngine):
or changed["messages"][:captured] != body["messages"][:captured]):
raise warm.WarmRefusal("middleware_rewrite")
body = changed
+ # A request middleware can add text to the new rows. Check the size again before the request is sent.
+ if not warm.fits(body, int(self.context_length or 0), measured, captured):
+ raise warm.WarmRefusal("capacity")
# A copy that no middleware can change in place.
base = copy.deepcopy(body)
sent: list[tuple[dict[str, Any], dict[str, Any]]] = []
diff --git a/warm_compaction/fallback.py b/warm_compaction/fallback.py
index dad3d63..583333d 100644
--- a/warm_compaction/fallback.py
+++ b/warm_compaction/fallback.py
@@ -121,7 +121,8 @@ def render_row(row: Any, call_names: dict[str, str] | None = None) -> str:
lines.append(text)
for call_id, name, arguments in tool_calls_of(row):
shown = arguments if isinstance(arguments, str) else compact_json(arguments)
- lines.append(f"(tool call {' '.join(part for part in (call_id, name) if part)}: {_cut(shown, ARGUMENT_CHARS)})")
+ label = " ".join(part for part in (call_id, name) if part)
+ lines.append(f"(tool call {label}: {_cut_middle(shown, ARGUMENT_CHARS)})")
return "\n".join(lines)
@@ -140,8 +141,9 @@ def transcript(messages: list, prefixes: Iterable[str]) -> str:
EARLIER_SUMMARY_TOKENS, middle=True))
first = next((row for row in messages if is_real_user(row, prefixes)), None)
if first is not None:
+ # The start and the end: a long request often has the question or the output rules at the end.
head.append("[first user message]\n" + _bound(visible_text(api_content(first)).strip(), FIRST_USER_CHARS,
- FIRST_USER_TOKENS))
+ FIRST_USER_TOKENS, middle=True))
budget = TRANSCRIPT_CHARS - sum(len(part) + 2 for part in head)
tokens = TRANSCRIPT_TOKENS - sum(estimate_tokens(part) + 1 for part in head)
# A tool row takes the names of the nearest earlier tool calls. Providers can use the same call id again
diff --git a/warm_compaction/rows.py b/warm_compaction/rows.py
index 00c210d..9c498fc 100644
--- a/warm_compaction/rows.py
+++ b/warm_compaction/rows.py
@@ -120,13 +120,16 @@ def estimate_tokens(value: Any) -> int:
def row_digest(row: Any) -> str:
- """Return the SHA-256 of the canonical JSON of the row fields that the model sees."""
+ """Return the SHA-256 of the canonical JSON of the row fields that the model sees, with the api_content
+ sidecar of a user or assistant row."""
canonical = {
"role": attr(row, "role"),
"content": attr(row, "content"),
"tool_call_id": attr(row, "tool_call_id"),
"name": attr(row, "name"),
"tool_calls": [list(call) for call in tool_calls_of(row)],
+ # The text that the provider saw, when Hermes keeps it in the api_content sidecar.
+ "api_content": api_content(row) if api_content(row) is not attr(row, "content") else None,
}
text = json.dumps(canonical, sort_keys=True, separators=(",", ":"), default=str)
return hashlib.sha256(text.encode("ascii")).hexdigest()
diff --git a/warm_compaction/warm.py b/warm_compaction/warm.py
index 929db15..05fa83e 100644
--- a/warm_compaction/warm.py
+++ b/warm_compaction/warm.py
@@ -35,7 +35,9 @@ def _matches_reply(row: Any, reply: dict[str, Any]) -> bool:
if attr(row, "role") != "assistant":
return False
calls = [[call_id, name] for call_id, name, _arguments in tool_calls_of(row)]
- return calls == reply["tool_calls"] and reply_text(attr(row, "content")) == reply_text(reply["content"])
+ # Hermes can keep the sent reply text in api_content and leave content empty or normalized.
+ text = reply_text(reply["content"])
+ return calls == reply["tool_calls"] and text in (reply_text(attr(row, "content")), reply_text(api_content(row)))
def split_history(capture: dict[str, Any], messages: list) -> tuple[list, list]:
@@ -258,6 +260,8 @@ def build_request(capture: dict[str, Any], messages: list, route: tuple, context
request["messages"] = [*body["messages"], *added, {"role": "user", "content": instruction}]
request["stream"] = False
request.pop("stream_options", None)
+ # A stop sequence of the main request could cut the handoff after the five headings.
+ request.pop("stop", None)
if not fits(request, context_length, capture.get("prompt_tokens"), len(body["messages"])):
raise WarmRefusal("capacity")
return request