Skip to content

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

Merge current main and finish provider exclusion checks

Elevatormusic35c4e3e13bf5
diff --cc README.md
index 712d641,725d951..d1c1d22
--- a/README.md
+++ b/README.md
@@@ -167,7 -167,7 +167,8 @@@ The settings are in `plugins.entries.wa
| `tail_tokens` | int, 0 or more | 0: 2.5% of the context window, from 10,000 to 25,000 | Size of the verbatim tail, at most half of the compaction threshold |
| `user_copy_chars` | int, 0 or more | 24,000 | Total characters of user messages that the summary copies |
| `warm` | bool | true | Set false to use only the fallback summary, for comparison runs |
+ | `summary_words` | int, 1 or more | 600 | Word count the handoff instruction asks for. It applies to the warm request and the fallback summary. A larger value records more of a long session. The task, not this value, controls the final reply size |
+| `warm_providers` | text | empty: every provider | Comma-separated provider names that may use the warm path. A provider outside the list sends no warm request, so a route that can miss its prefix cache does not pay for the whole prompt. Names are matched without case. An empty value keeps every provider |
```yaml
plugins:
diff --cc evidence/codex-provider-exclusion-final-review-20261009.json
index 0000000,0000000..8744f0e
new file mode 100644
--- /dev/null
+++ b/evidence/codex-provider-exclusion-final-review-20261009.json
@@@ -1,0 -1,0 +1,153 @@@
++{
++ "ai_agents": [
++ {
++ "harness": "Codex collaboration subagent",
++ "model": "gpt-6.1-sol",
++ "work": "Prepare conflict resolution, final regression, runner, and integration controller."
++ },
++ {
++ "harness": "Codex Desktop primary agent",
++ "model": "Exact identifier unavailable in this session.",
++ "work": "Review changes, execute Docker checks, inspect evidence, and publish."
++ }
++ ],
++ "checks": [
++ {
++ "container_removed": true,
++ "elapsed_seconds": 2.618,
++ "exit_code": 1,
++ "expected_test_count": 2,
++ "log_sha256": "4f4cca3cdefd102d69daa50d0232d2fc68a19f22db41a2fa06815cea6fb0ccfa",
++ "matched_expected_result": true,
++ "runner_python_implementation": "cpython",
++ "runner_python_version": "3.12.13 (main, Jun 16 2026, 00:21:10) [GCC 15.2.0]",
++ "runner_python_version_info": [
++ 3,
++ 12,
++ 13,
++ "final",
++ 0
++ ],
++ "source_and_runner_bytes_unchanged": true,
++ "stage": "red",
++ "timed_out": false
++ },
++ {
++ "container_removed": true,
++ "elapsed_seconds": 2.754,
++ "exit_code": 0,
++ "expected_test_count": 2,
++ "log_sha256": "fd5ebb87e8addfdd7d0cada2a435b0c8fc18a90090149370a42c05310ad1be13",
++ "matched_expected_result": true,
++ "runner_python_implementation": "cpython",
++ "runner_python_version": "3.12.13 (main, Jun 16 2026, 00:21:10) [GCC 15.2.0]",
++ "runner_python_version_info": [
++ 3,
++ 12,
++ 13,
++ "final",
++ 0
++ ],
++ "source_and_runner_bytes_unchanged": true,
++ "stage": "green",
++ "timed_out": false
++ },
++ {
++ "container_removed": true,
++ "elapsed_seconds": 8.927,
++ "exit_code": 1,
++ "expected_test_count": 127,
++ "log_sha256": "f17a283e6b913bf25e5430af2cfb9613a7338532eec894cdb429d7d17265eccd",
++ "matched_expected_result": true,
++ "outcome": "unavailable",
++ "passed_tests": 126,
++ "runner_python_implementation": "cpython",
++ "runner_python_version": "3.12.13 (main, Jun 16 2026, 00:21:10) [GCC 15.2.0]",
++ "runner_python_version_info": [
++ 3,
++ 12,
++ 13,
++ "final",
++ 0
++ ],
++ "source_and_runner_bytes_unchanged": true,
++ "stage": "engine",
++ "timed_out": false,
++ "unavailable_reason": "Loopback socket denied by executor policy; full current-head CI remains required",
++ "unavailable_tests": 1
++ }
++ ],
++ "commands": [
++ "python -B -m unittest discover -s tests -p test_wc_engine.py -k without_capture -v",
++ "python -B -m unittest discover -s tests -p test_wc_engine.py"
++ ],
++ "docker_image": "python@sha256:aa679aa4eed6eb56c1dc6ad3f1b98b7d2d788fd961596779d188fdedad97fb38",
++ "docker_result_sha256": "5e61ef61acab0b612168a391c533881c1bf8b6c85fb2197075489c835fdd4527",
++ "integration_main": "d719ec400bfa7cc9e2a56cc6d3c7b3be850dcc89",
++ "isolation": {
++ "containers_removed": true,
++ "credentials": "none",
++ "network": "none",
++ "non_root_uid": 65534,
++ "runner_read_only": true,
++ "source_read_only": true
++ },
++ "limits": [
++ "Full current-head CI and real Hermes loopback checks remain required.",
++ "The new commit preserves later policy bytes that these engine checks did not execute.",
++ "These checks do not prove deployed compatibility, cache reuse, or a performance gain."
++ ],
++ "prior_pr23_head": "e83dcdfb71a683f84daa89d4824a4bc6aa821a1c",
++ "result_summary": {
++ "after_fix": "2 tests passed",
++ "before_fix": "2 tests, 1 expected failure",
++ "engine": "127 tests: 126 passed, 1 unavailable under denied loopback sockets"
++ },
++ "runner_sha256": {
++ "pr23-final-container-runner.py": "8d091c8fb2313fb22167ba23cf0a049b4f491922510d9d68852645565e868a25",
++ "pr23-final-seccomp.json": "d602e7b6cc3b88932ea37a753f6bb0d77928f7a9ea1dccbcb0cd8f633589db7c"
++ },
++ "scope": "Synthetic provider-exclusion regression and integrated engine unit checks",
++ "source_archives": {
++ "final-tree.tar": {
++ "bytes": 1433600,
++ "sha256": "21d1d16c3dbeaed6403d9d557cd799e546df8631e4b5f09057a805081e6c920e",
++ "tree": "ae9083ea40e87dd2a82611356c158afe19581342"
++ },
++ "red-tree.tar": {
++ "bytes": 1433600,
++ "sha256": "b5e9a11834971e8cd5fc03044311548aa0d695050088278aeac3cdb83596a1f3",
++ "tree": "ecdad5bcc738606374b3959c5a103a9048e1d16d"
++ }
++ },
++ "source_files": {
++ "README.md": {
++ "bytes": 35245,
++ "git_blob": "d1c1d2267b4a04b97deed4ea4ce184749abfb3ad",
++ "sha256": "bf291222be56c7adae31640aa373127c626fe7f4998b0cd61dc699042dd891aa"
++ },
++ "tests/test_wc_engine.py": {
++ "bytes": 118459,
++ "git_blob": "35cea25993a7c4a694fa3f6943e15b1dd91b4163",
++ "sha256": "b518e3eb515e892cca6a996659d4bde815b20cb7bffd7ee16fd91f6b723580f2"
++ },
++ "warm_compaction/engine.py": {
++ "bytes": 51383,
++ "git_blob": "cfaf4b51456b188c1eb508bd3b54739d1e1f2c70",
++ "sha256": "ca54152b497b1d9cb2ad184b9c3da70f5aa54640de7cd9457787de42eb3e42be"
++ },
++ "warm_compaction/plugin.yaml": {
++ "bytes": 1312,
++ "git_blob": "f2002f6e4dc8eb40b2e0774fb76c771a014d538d",
++ "sha256": "2315d2ff3f0ce7c2e45998d07ee087c2911f202922851a44783b949314c04a8c"
++ }
++ },
++ "source_manifest_sha256": {
++ "final": "bdad0e6acee61d6b02aa742f91218565728a5bd7c0f1bf5fa6b3ecb93fa0a4ed",
++ "red": "661ed785f5ff754ca31be9de78fb0000ad3c45cfafcea822c9dd53202d284e82"
++ },
++ "tested_source_trees": {
++ "after_fix": "ae9083ea40e87dd2a82611356c158afe19581342",
++ "before_fix": "ecdad5bcc738606374b3959c5a103a9048e1d16d"
++ }
++}
diff --cc tests/test_wc_engine.py
index 8f87e91,35ca8f1..35cea25
--- a/tests/test_wc_engine.py
+++ b/tests/test_wc_engine.py
@@@ -1553,110 -1578,17 +1578,159 @@@ class EngineTest(unittest.TestCase)
self.assertEqual((engine.warm_last["path"], engine.warm_last["reason"]), ("fallback", "disabled"))
self.assertEqual(self.post.calls, [])
+ def test_the_word_count_setting_reaches_the_warm_request(self):
+ engine = self.make(summary_words=1200)
+ rows = old_turns()
+ reply = assistant("final")
+ self.seed(rows, reply)
+ engine.compress([*rows, reply])
+ self.assertEqual(engine.warm_last["path"], "warm")
+ sent = " ".join(str(row.get("content")) for row in self.post.calls[0]["body"]["messages"])
+ self.assertIn("Use at most 1200 words.", sent)
+ self.assertNotIn("600 words", sent)
+
+ def test_a_provider_outside_the_list_skips_the_warm_request(self):
+ # The route is kept out of the warm path: no warm request is sent, and the fallback summary runs.
+ engine = self.make(warm_providers="opencode-go,commandcode")
+ rows = old_turns()
+ reply = assistant("final")
+ self.seed(rows, reply)
+ engine.compress([*rows, reply])
+ self.assertEqual((engine.warm_last["path"], engine.warm_last["reason"]),
+ ("fallback", "provider_not_allowed"))
+ self.assertEqual(self.post.calls, [])
+
++ def test_three_provider_exclusions_without_capture_do_not_report_a_warm_failure(self):
++ engine = self.make(warm_providers="opencode-go,commandcode", summary_words=777)
++ history = [*old_turns(), assistant("final")]
++ with self.assertNoLogs("warm_compaction.engine", level="WARNING"):
++ for _ in range(3):
++ self.compress_committed(engine, history)
++ self.assertEqual((engine.warm_last["path"], engine.warm_last["reason"]),
++ ("fallback", "provider_not_allowed"))
++ self.assertEqual((engine._warm_failures, engine._warm_fixed, engine._warm_failure_reasons),
++ (0, 0, []))
++ self.assertEqual(engine.get_automatic_compaction_status_message(
++ phase="compress", default_message="Compacting"), "Compacting")
++ self.assertEqual(self.post.calls, [])
++ self.assertEqual((len(self.llm.calls), engine.compression_count), (3, 3))
++ for messages, _kwargs in self.llm.calls:
++ self.assertIn("Use at most 777 words.", str(messages))
++
++ def test_an_allowed_provider_without_capture_still_reports_the_failure_streak(self):
++ engine = self.make(warm_providers="custom")
++ history = [*old_turns(), assistant("final")]
++ with self.assertLogs("warm_compaction.engine", level="WARNING") as logs:
++ for _ in range(3):
++ self.compress_committed(engine, history)
++ self.assertEqual((engine.warm_last["path"], engine.warm_last["reason"]),
++ ("fallback", "no_capture"))
++ self.assertEqual((engine._warm_failures, engine._warm_fixed), (3, 0))
++ self.assertEqual(engine._warm_failure_reasons, ["no_capture"] * 3)
++ self.assertEqual(self.post.calls, [])
++ self.assertEqual(len(self.llm.calls), 3)
++ self.assertEqual(sum("Warm compaction skipped (no_capture); used the fallback summary" in line
++ for line in logs.output), 3)
++ self.assertEqual(sum("Warm compaction failed 3 times in a row (no_capture)" in line
++ for line in logs.output), 1)
++ notice = engine.get_automatic_compaction_status_message(phase="compress", default_message="Compacting")
++ self.assertIn("the last 3 compactions", notice)
++ self.assertIn("no_capture", notice)
++
+ def test_three_provider_exclusions_do_not_report_a_warm_failure(self):
+ engine = self.make(warm_providers="opencode-go,commandcode")
+ rows, reply = old_turns(), assistant("final")
+ with self.assertNoLogs("warm_compaction.engine", level="WARNING"):
+ for _ in range(3):
+ self.seed(rows, reply)
+ self.compress_committed(engine, [*rows, reply])
+ self.assertEqual((engine.warm_last["path"], engine.warm_last["reason"]),
+ ("fallback", "provider_not_allowed"))
+ self.assertEqual((engine._warm_failures, engine._warm_fixed, engine._warm_failure_reasons),
+ (0, 0, []))
+ self.assertEqual(engine.get_automatic_compaction_status_message(
+ phase="compress", default_message="Compacting"), "Compacting")
+ self.assertEqual(self.post.calls, [])
+ self.assertEqual((len(self.llm.calls), engine.compression_count), (3, 3))
+ self.assertIsNone(engine._warm_notice)
+ self.assertFalse(engine._warm_notice_issued)
+
+ def test_an_allowed_provider_error_still_reports_the_failure_streak(self):
+ engine = self.make(warm_providers="custom")
+ rows, reply = old_turns(), assistant("final")
+ requests = []
+
+ def refused(*args, **kwargs):
+ requests.append(True)
+ return 500, b"{}"
+
+ engine._post = refused
+ with self.assertLogs("warm_compaction.engine", level="WARNING") as logs:
+ for _ in range(3):
+ self.seed(rows, reply)
+ self.compress_committed(engine, [*rows, reply])
+ self.assertEqual((engine.warm_last["path"], engine.warm_last["reason"]),
+ ("fallback", "provider_error"))
+ self.assertEqual((engine._warm_failures, engine._warm_fixed), (3, 0))
+ self.assertEqual(engine._warm_failure_reasons, ["provider_error"] * 3)
+ self.assertEqual((len(requests), len(self.llm.calls)), (3, 3))
+ self.assertEqual(sum("Warm compaction skipped (provider_error); used the fallback summary" in line
+ for line in logs.output), 3)
+ self.assertEqual(sum("Warm compaction failed 3 times in a row (provider_error)" in line
+ for line in logs.output), 1)
+ notice = engine.get_automatic_compaction_status_message(phase="compress", default_message="Compacting")
+ self.assertIn("the last 3 compactions", notice)
+ self.assertIn("provider_error", notice)
+
+ def test_an_excluded_provider_with_a_failed_fallback_still_reports_the_failure_streak(self):
+ engine = self.make(warm_providers="opencode-go,commandcode")
+ rows, reply = old_turns(), assistant("final")
+ self.llm.error = RuntimeError("synthetic fallback failure")
+ with self.assertLogs("warm_compaction.engine", level="WARNING") as logs:
+ for _ in range(3):
+ self.seed(rows, reply)
+ self.compress_committed(engine, [*rows, reply])
+ self.assertEqual((engine.warm_last["path"], engine.warm_last["reason"]),
+ ("fixed", "provider_not_allowed"))
+ self.assertEqual((engine._warm_failures, engine._warm_fixed), (3, 3))
+ self.assertEqual(engine._warm_failure_reasons, ["provider_not_allowed"] * 3)
+ self.assertEqual(self.post.calls, [])
+ self.assertEqual(len(self.llm.calls), 3)
+ self.assertEqual(sum("Warm compaction skipped (provider_not_allowed); used the fixed summary" in line
+ for line in logs.output), 3)
+ self.assertEqual(sum("Warm compaction failed 3 times in a row (provider_not_allowed)" in line
+ for line in logs.output), 1)
+ notice = engine.get_automatic_compaction_status_message(phase="compress", default_message="Compacting")
+ self.assertIn("the last 3 compactions", notice)
+ self.assertIn("the fallback summary could not be used 3 of 3 times", notice)
+
+ def test_a_provider_inside_the_list_uses_the_warm_request(self):
+ engine = self.make(warm_providers="opencode-go, custom ")
+ rows = old_turns()
+ reply = assistant("final")
+ self.seed(rows, reply)
+ engine.compress([*rows, reply])
+ self.assertEqual(engine.warm_last["path"], "warm")
+ self.assertNotEqual(self.post.calls, [])
+
+ def test_an_empty_provider_list_allows_every_provider(self):
+ engine = self.make(warm_providers="")
+ rows = old_turns()
+ reply = assistant("final")
+ self.seed(rows, reply)
+ engine.compress([*rows, reply])
+ self.assertEqual(engine.warm_last["path"], "warm")
+
+ def test_the_provider_names_match_without_case_or_spaces(self):
+ from warm_compaction.engine import provider_allowed
+ self.assertTrue(provider_allowed("", "nous"))
+ self.assertTrue(provider_allowed(None, "nous"))
+ self.assertTrue(provider_allowed(" Opencode-Go , commandcode ", "opencode-go"))
+ self.assertTrue(provider_allowed("opencode-go,commandcode", "COMMANDCODE"))
+ self.assertFalse(provider_allowed("opencode-go,commandcode", "nous"))
+ self.assertFalse(provider_allowed("opencode-go", ""))
+
++
def test_cancelled_attempt_keeps_the_history(self):
rows = old_turns()
reply = assistant("final")
@@@ -1939,16 -1871,27 +2013,27 @@@ class SettingsTest(unittest.TestCase)
def test_valid_values(self):
values = {"threshold": 0.6, "tail_tokens": 12_000, "user_copy_chars": 0, "warm": False,
- "warm_providers": "opencode-go,commandcode"}
- "summary_words": 1200}
++ "summary_words": 1200, "warm_providers": "opencode-go,commandcode"}
self.assertEqual(self.module.read_settings(lambda key, default: values.get(key, default)), values)
def test_invalid_values_use_the_defaults_with_a_warning(self):
values = {"threshold": 2.0, "tail_tokens": -1, "user_copy_chars": "big", "warm": "no",
- "warm_providers": 7}
- "summary_words": 0}
++ "summary_words": 0, "warm_providers": 7}
with self.assertLogs("warm_compaction.engine", level="WARNING") as logs:
settings = self.module.read_settings(lambda key, default: values.get(key, default))
self.assertEqual(settings, self.module.DEFAULTS)
-- self.assertEqual(len(logs.output), 5)
++ self.assertEqual(len(logs.output), 6)
+
+ def test_a_word_count_below_one_uses_the_default(self):
+ def reader(values):
+ return lambda key, default: values.get(key, default)
+
+ for bad in (0, -5, "big", True):
+ with self.subTest(bad=bad):
+ with self.assertLogs("warm_compaction.engine", level="WARNING"):
+ settings = self.module.read_settings(reader({"summary_words": bad}))
+ self.assertEqual(settings["summary_words"], self.module.DEFAULTS["summary_words"])
+ self.assertEqual(self.module.DEFAULTS["summary_words"], 600)
def test_tail_budget(self):
self.assertEqual(self.module.tail_budget(0, 200_000), 10_000)
diff --cc warm_compaction/engine.py
index dd753c4,9f9e871..cfaf4b5
--- a/warm_compaction/engine.py
+++ b/warm_compaction/engine.py
@@@ -19,7 -19,7 +19,8 @@@ logger = logging.getLogger(__name__
NAME = "warm_compaction"
DEFAULTS: dict[str, Any] = {"threshold": 0.50, "tail_tokens": 0, "user_copy_chars": 24_000, "warm": True,
- "summary_words": handoff.DEFAULT_SUMMARY_WORDS}
++ "summary_words": handoff.DEFAULT_SUMMARY_WORDS,
+ "warm_providers": ""}
THRESHOLD_RANGE = (0.10, 0.95)
TAIL_SHARE = 0.025
TAIL_MIN = 10_000
@@@ -68,10 -67,10 +69,12 @@@ HERMES_DB_MARKER = "_db_persisted
def _valid(key: str, value: Any) -> bool:
if key == "warm":
return isinstance(value, bool)
+ if key == "warm_providers":
+ return isinstance(value, str)
if isinstance(value, bool):
return False
+ if key == "summary_words":
+ return isinstance(value, int) and value >= 1
if key == "threshold":
return isinstance(value, (int, float)) and THRESHOLD_RANGE[0] <= float(value) <= THRESHOLD_RANGE[1]
return isinstance(value, int) and value >= 0
@@@ -526,13 -517,8 +530,13 @@@ class WarmCompactionEngine(ContextEngin
try:
if not self._settings["warm"]:
raise warm.WarmRefusal("disabled")
- if capture is None:
- raise warm.WarmRefusal("no_capture")
+ # A provider that is not in the list never sends a warm request. A route that rotates its upstream
+ # can miss the prefix cache, and the warm request would then pay for the whole prompt. The
+ # fallback summary, which sends a small transcript, runs in its place.
+ if not provider_allowed(self._settings.get("warm_providers"), attempt[2]):
+ raise warm.WarmRefusal("provider_not_allowed")
+ if capture is None:
+ raise warm.WarmRefusal("no_capture")
# The capture belongs to the key that sent it. Hermes can give the key as a function whose value
# changes (a token that refreshes or rotates): resolve it one time, for this check and the request.
key = warm.api_key_text(attempt[1])
diff --cc warm_compaction/plugin.yaml
index 821ddbc,56c2222..f2002f6
--- a/warm_compaction/plugin.yaml
+++ b/warm_compaction/plugin.yaml
@@@ -28,7 -28,7 +28,11 @@@ config_schema
type: bool
default: true
description: Use the warm request. Set false for comparison runs.
+ summary_words:
+ type: int
+ default: 600
+ description: Word count the handoff instruction asks for, for the warm request and the fallback summary.
+ warm_providers:
+ type: str
+ default: ""
+ description: Comma-separated provider names that may use the warm path. Empty means every provider.