Hermes Agent context engine: the main model writes the compaction handoff on its cached prompt prefix
Stop other gate failures after one retry
pablerasdcdb3a282b08
diff --git a/README.md b/README.mdindex ccf177d..294f1f2 100644--- a/README.md+++ b/README.md@@ -206,7 +206,7 @@ The complete body still has at most 2,048 estimated tokens. The original reply mEach request gets a fresh random end marker, in the form `[END OF SUMMARY <nonce>]`. The reply must contain that exact marker once, as its final visible line. The plugin removes the marker before it stores the summary. A fixed marker, an old marker, text after the marker, or a missing marker fails the check. This checks the reply format. It does not prove that every fact is correct or tell the plugin why the server stopped; the public auxiliary API does not report a finish reason.-If a reply fails the checks, the plugin can retry twice. Each retry uses the same original transcript, a fresh marker, and a shorter summary instruction of at most 300 words. When the failure is a missing or duplicated end marker, the retry repeats the marker requirement explicitly. It does not try to complete a partial reply. All calls share a 120-second deadline. The plugin checks cancellation and route changes before each call and after each reply. It does not retry a request error. If no reply passes, it preserves the input history.+If a reply fails the checks, the plugin retries once; a missing or duplicated end marker earns one more retry. Each retry uses the same original transcript, a fresh marker, and a shorter summary instruction of at most 300 words. When the failure is a missing or duplicated end marker, the retry repeats the marker requirement explicitly. It does not try to complete a partial reply. All calls share a 120-second deadline. The plugin checks cancellation and route changes before each call and after each reply. It does not retry a request error. If no reply passes, it preserves the input history.When the server applies the requested generation limit, the request is about 18,000 tokens or less: about 8,000 transcript tokens, the instruction, and up to 8,192 generated tokens. The focus topic and memory context take their space from the transcript budget. Use a fallback model with at least a 24,000-token context window. The deadline can prevent a retry or reject a late reply, but the public API cannot stop an in-flight call. Hermes controls its own retries, so two plugin calls can cause more than two server requests.@@ -339,7 +339,7 @@ The plugin was faster than both other engines in 10 of 10 cases. hermes-lcm and- Responses and Anthropic Messages use their own source checks. Native signed and encrypted replay records stay whole and count in tail estimates. A record that leaves no room for a valid new history fails with `path=aborted` and a safe capacity code, without replacing the input history. See [Provider support](docs/provider-support.md).- 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`, and in the free room after the system rows and tool schemas of a usable capture, the reply reserve, and a summary: a large system prompt can make a short history compact. 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 its attachment mark: a web URL or a file name stays (at most 200 characters), a data URL does not. 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. The fallback body is limited to 2,048 estimated tokens, including dense CJK text. The existing 4,096-token reserve also leaves room for bounded quotes. If the summary and quotes cannot fit safely, the current compaction pass stops and preserves its input history. The sizes come from the fields that Hermes sends: row metadata does not count; reasoning counts only on a route that needs it back (DeepSeek, Kimi, MiMo thinking; a capture of the route shows it, else a stored row with `reasoning_content`); `reasoning_details` counts only on a route that replays it, without the private native-assistant entries; the native-assistant entry type that the provider profile declares (`native_reasoning_details_type`) counts on every route of the provider, as Hermes replays it; a tool call counts only its id, type, name, and arguments, and a usable thought signature counts only for a Gemini or Gemma model. When the fallback summary is used and the latest user request in front of the tail must be cut, the cut middle goes after the summary as a bounded quote, in what the summary budget has left: the fallback transcript had only the start and end of a long row. When no quote fits there, the current compaction pass stops and preserves its input history. A fallback summary that does not fit in the free room also stops the current compaction pass. A model, session, window, or threshold change at any time during the compaction discards its result (reason `route_changed`). On a Gemini or Gemma route, a tool call with a thought signature stays whole: Gemini needs it back as it was. A change of the provider or the key forgets the capture, also from an empty provider and key. A warm summary that does not fit in the free room (a dense reply under a low threshold, for example) is not used: the fallback summary runs (reason `summary_too_large`). A retry middleware cannot send the warm request a second time, also after a failed send. A warm reply body above 1 MiB is not read (reason `response_too_large`). The fallback request does not start after a model, provider, or session switch. The plugin API has no request on a fixed route (an override needs a trust setting), so a switch in the short time after that check, before the host resolves the auxiliary route, can still send the transcript to the new route. Reasoning is cut only when a usable capture of the route shows that the route sends it: other reasoning (of an earlier route after a model switch, for example) does not go to the fallback model. The latest user request in front of the tail gets the room that stays after the tail is cut. Hermes notifications, task lists, and recovery nudges are not user requests only when the whole text matches the Hermes template. The copied user messages get the room that stays after the tail is cut. 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 summary, the prepended row, and the tail take 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 same reserve applies when the captured request had no positive `max_tokens` or `max_completion_tokens`: the provider default is not known. The host token count is not used for the overhead: it does not use the plugin tokenizer.-- Responses warm requests are streamed; Chat Completions and Messages warm requests are not streamed. No warm request is retried. Its time limit is 120 seconds. The fallback has one shared 120-second deadline for at most two plugin calls; the host can keep an in-flight call running beyond that deadline. Native formats have additional limits in [Provider support](docs/provider-support.md).+- Responses warm requests are streamed; Chat Completions and Messages warm requests are not streamed. No warm request is retried. Its time limit is 120 seconds. The fallback has one shared 120-second deadline for at most two plugin calls (three when the failure is a missing or duplicated end marker); the host can keep an in-flight call running beyond that deadline. Native formats have additional limits in [Provider support](docs/provider-support.md).- On Chat Completions routes, per-request `extra_headers` supports only one `x-opencode-session` header, with a non-empty plain ASCII string value, no control characters, and no leading or trailing space. Other headers, duplicate names with different case, non-empty `extra_query`, or an invalid `extra_body` use the fallback (`request_options_unsupported`). A JSON `extra_body.extra_headers` field cannot be combined with the session header. A request with `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.- Each new agent writes this Hermes warning to the log: `Context engine 'warm_compaction' loaded but no engine instance found`. Hermes first tries its context engine loader, which cannot make this engine. Then Hermes uses the engine of the enabled plugin. The warning has no effect.diff --git a/tests/test_wc_engine.py b/tests/test_wc_engine.pyindex 2b8fa79..afadab0 100644--- a/tests/test_wc_engine.py+++ b/tests/test_wc_engine.py@@ -1780,13 +1780,13 @@ class EngineTest(unittest.TestCase):self.assertEqual(status["fallback_output_tokens"], expected_output)self.assertEqual(status["fallback_requested_max_tokens"], 8192)self.assertEqual(status["fallback_end_marker"], marker)- self.assertEqual(status["fallback_attempts"], 3)+ self.assertEqual(status["fallback_attempts"], 3 if reason == "missing_end_marker" else 2)self.assertEqual(status["fallback_body_tokens"], estimate_tokens(text.removesuffix("\n" + END_LINE)))logged = "\n".join(logs.output)self.assertIn(f"fallback_output_tokens={expected_output}", logged)self.assertIn("fallback_requested_max_tokens=8192", logged)self.assertIn(f"fallback_end_marker={marker}", logged)- self.assertIn("fallback_attempts=3", logged)+ self.assertIn(f"fallback_attempts={3 if reason == 'missing_end_marker' else 2}", logged)self.assertNotIn(HEADINGS_TEXT, logged + json.dumps(status))def test_late_backup_errors_after_cancel_or_route_switch_keep_history(self):@@ -2196,12 +2196,12 @@ class EngineTest(unittest.TestCase):provider="custom", api_mode=ROUTE[2])self.assert_aborted(engine, rows, "error:RuntimeError")- def test_three_all_unknown_replies_preserve_history(self):+ def test_all_unknown_replies_preserve_history(self):self.llm = FakeLlm(FALLBACK_TEXT + "\n" + END_LINE)engine = self.engine = self.make(warm=False, tail_tokens=10)rows = [*old_turns(4), user("Check JOB-X3."), assistant("done")]self.assert_aborted(engine, rows, "gate:no_useful_evidence")- self.assertEqual(len(self.llm.calls), 3)+ self.assertEqual(len(self.llm.calls), 2)def test_failed_summary_keeps_the_middles_that_the_tail_would_cut(self):self.llm.error = RuntimeError("synthetic failure")diff --git a/tests/test_wc_fallback.py b/tests/test_wc_fallback.pyindex 1263b3f..d385b4f 100644--- a/tests/test_wc_fallback.py+++ b/tests/test_wc_fallback.py@@ -269,7 +269,7 @@ class LlmSummaryTest(unittest.TestCase):self.assertEqual(llm_summary(llm, [user("hi")], PREFIXES, failure=failure), (None, None))self.assertEqual(failure["reason"], "gate:body_token_limit")self.assertGreater(failure["body_tokens"], MAX_TOKENS)- self.assertEqual(len(llm.calls), 3)+ self.assertEqual(len(llm.calls), 2)def test_content_checks_stay_in_force(self):for text, reason in (("answer", "heading_missing"), (SUMMARY + "\n[CONTEXT SUMMARY]: x", "carrier_marker"),@@ -457,7 +457,7 @@ class CurrentStateSourceTest(unittest.TestCase):if expected == "- progress unknown":self.assertEqual(result, (None, None))self.assertEqual(failure["reason"], "gate:no_useful_evidence")- self.assertEqual(len(llm.calls), 3)+ self.assertEqual(len(llm.calls), 2)else:self.assertEqual(result, (body, 321))self.assertEqual(failure, {})@@ -619,7 +619,7 @@ class CurrentStateSourceTest(unittest.TestCase):llm, failure = FakeLlm(text=body + "\n" + END_LINE), {}self.assertEqual(llm_summary(llm, [user("Check progress.")], PREFIXES, failure=failure), (None, None))self.assertEqual(failure["reason"], "gate:body_token_limit")- self.assertEqual(len(llm.calls), 3)+ self.assertEqual(len(llm.calls), 2)def test_an_actual_protocol_failure_retries_with_the_same_source(self):reported = "not complete"@@ -714,7 +714,7 @@ class AllFieldsSourceTest(unittest.TestCase):raw = field_summary("## Next step", '- "Review JOB-X3 after approval."\nDo not perform it yet.')llm = FakeLlm(raw + "\n" + END_LINE)self.assertEqual(llm_summary(llm, [user("Review JOB-X3.")], PREFIXES), (None, None))- self.assertEqual(len(llm.calls), 3)+ self.assertEqual(len(llm.calls), 2)def test_next_step_keeps_supported_action_and_records_lost_tail_condition(self):raw = field_summary("## Next step", '- "Review JOB-X3."\nDo not perform it yet.')@@ -839,7 +839,7 @@ class SourceContextTest(unittest.TestCase):llm = FakeLlm(raw + "\n" + END_LINE)self.assertEqual(llm_summary(llm, [assistant(prior, _compressed_summary=True), row], PREFIXES),(None, None))- self.assertEqual(len(llm.calls), 3)+ self.assertEqual(len(llm.calls), 2)def test_bounded_context_keeps_tail_fact_but_drops_missing_middle(self):from warm_compaction.fallback import EXTRAS_CHARS, EXTRAS_TOKENS, _bound@@ -865,7 +865,7 @@ class SourceContextTest(unittest.TestCase):llm = FakeLlm(raw + "\n" + END_LINE)self.assertEqual(llm_summary(llm, [user("Check memory.")], PREFIXES, memory_context=memory), (None, None))self.assertIn("[cut]", llm.calls[0][0][0]["content"])- self.assertEqual(len(llm.calls), 3)+ self.assertEqual(len(llm.calls), 2)def test_context_and_transcript_do_not_make_new_source_adjacency(self):quoted = "Transcript report.\nMemory report."@@ -913,10 +913,10 @@ class UsefulEvidenceTest(unittest.TestCase):def test_all_unknown_retries_then_refuses_without_provider_text(self):llm, failure = FakeLlm(SUMMARY + "\n" + END_LINE), {}self.assertEqual(llm_summary(llm, [user("Check JOB-X3.")], PREFIXES, failure=failure), (None, None))- self.assertEqual(len(llm.calls), 3)+ self.assertEqual(len(llm.calls), 2)self.assertEqual(failure["reason"], "gate:no_useful_evidence")- self.assertEqual(failure["attempts"], 3)- self.assertIn("failed a summary check", llm.calls[2][0][0]["content"])+ self.assertEqual(failure["attempts"], 2)+ self.assertIn("failed a summary check", llm.calls[1][0][0]["content"])self.assertNotIn("Check JOB-X3.", str(failure))def test_generated_labels_alone_do_not_count_as_useful_evidence(self):@@ -927,7 +927,7 @@ class UsefulEvidenceTest(unittest.TestCase):llm, failure = FakeLlm(body + "\n" + END_LINE), {}self.assertEqual(llm_summary(llm, rows, PREFIXES, failure=failure), (None, None))self.assertEqual(failure["reason"], "gate:no_useful_evidence")- self.assertEqual(len(llm.calls), 3)+ self.assertEqual(len(llm.calls), 2)def test_copied_appendix_cannot_cut_a_core_fact_that_fits_the_existing_share(self):fact = "JOB-X3 output is 28 V."@@ -960,7 +960,7 @@ class UsefulEvidenceTest(unittest.TestCase):self.assertEqual(llm_summary(llm, [assistant("", [("c1", "read", "")])], PREFIXES, failure=failure),(None, None))self.assertEqual(failure["reason"], "gate:no_useful_evidence")- self.assertEqual(len(llm.calls), 3)+ self.assertEqual(len(llm.calls), 2)self.assertEqual(llm_summary(FakeLlm(body + "\n" + END_LINE), [user(label)], PREFIXES), (body, 321))def test_nonempty_supplied_tool_argument_can_supply_evidence(self):@@ -1139,7 +1139,7 @@ class PriorStateTest(unittest.TestCase):llm = FakeLlm(raw + "\n" + END_LINE)self.assertEqual(llm_summary(llm, [assistant(prior, _compressed_summary=True), user(wrapper)], PREFIXES),(None, None))- self.assertEqual(len(llm.calls), 3)+ self.assertEqual(len(llm.calls), 2)def test_no_one_layer_decode_from_arbitrary_user_or_tool_rows(self):prior = state_summary('- "Task not complete."')@@ -1193,7 +1193,7 @@ class PriorStateTest(unittest.TestCase):llm, failure = FakeLlm(raw + "\n" + END_LINE), {}self.assertEqual(llm_summary(llm, [assistant(reported)], PREFIXES, failure=failure), (None, None))self.assertEqual(failure["reason"], "gate:" + reason)- self.assertEqual(len(llm.calls), 3)+ self.assertEqual(len(llm.calls), 2)def test_lone_surrogate_in_expanded_source_is_stored_as_json_escape(self):reported = "Task not complete \ud800."diff --git a/warm_compaction/fallback.py b/warm_compaction/fallback.pyindex 5654e99..f0c2d13 100644--- a/warm_compaction/fallback.py+++ b/warm_compaction/fallback.py@@ -27,8 +27,11 @@ PURPOSE = "warm_compaction_fallback"MAX_TOKENS = 2048MAX_STATE_TOKENS = 512REQUEST_MAX_TOKENS = 8192-# The attempts of one fallback summary: the first reply plus up to two retries of an invalid reply.+# The attempts of one fallback summary. A missing or duplicated end marker gets the first reply plus up to+# two retries (three attempts); every other gate failure stops after the first reply plus one retry (two), so+# a hopeless content failure does not burn a third summary call.MAX_ATTEMPTS = 3+MAX_ATTEMPTS_OTHER = 2TIMEOUT_S = 120.0TRANSCRIPT_CHARS = 32_000EARLIER_SUMMARY_CHARS = 8_000@@ -570,7 +573,7 @@ def llm_summary(llm: Any, messages: list, prefixes: Iterable[str], *, focus_topifailure: dict[str, Any] | None = None) -> tuple[str | None, int | None]:"""Return (summary text, prompt tokens) from ctx.llm, or (None, None) when the request or the reply fails.ready checks the route and cancellation before each call and after each reply.- An invalid reply gets up to two retries. All calls share one time limit.+ An invalid reply gets one retry; a missing or duplicated end marker gets two. All calls share one time limit.failure gets safe codes and bounded reply metadata only. It never gets provider text."""if failure is not None:failure.clear()@@ -660,7 +663,8 @@ def llm_summary(llm: Any, messages: list, prefixes: Iterable[str], *, focus_topiif text is not None:tokens = getattr(getattr(result, "usage", None), "input_tokens", None)return text, tokens if isinstance(tokens, int) and not isinstance(tokens, bool) and tokens > 0 else None- if attempt == MAX_ATTEMPTS:+ if attempt >= (MAX_ATTEMPTS if reason in ("missing_end_marker", "duplicate_end_marker")+ else MAX_ATTEMPTS_OTHER):metadata = _reply_metadata(result, raw, end_line, body, attempt)if failure is not None:failure["reason"] = f"gate:{reason}"@@ -669,6 +673,7 @@ def llm_summary(llm: Any, messages: list, prefixes: Iterable[str], *, focus_topi"end_marker=%s attempts=%s body_tokens=%s", reason, metadata["output_tokens"],metadata["requested_max_tokens"], metadata["end_marker"], metadata["attempts"],metadata["body_tokens"])+ return None, Nonereturn None, None