The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
fix(compression): one-shot runs start no wasted pass; releasing an agent cancels its pass
Teknium77af0690a862
diff --git a/agent/prepared_compaction.py b/agent/prepared_compaction.pyindex 24e4b93926d..da6dc5344ec 100644--- a/agent/prepared_compaction.py+++ b/agent/prepared_compaction.py@@ -211,10 +211,15 @@ def _worker_copy(compressor: Any) -> Any:def _blocked_for_platform(agent: Any, origin: str) -> bool:- """A turn-end pass in a session that ends with its turn (a cron run, a delegated child) is never used."""+ """A turn-end pass in a session that ends with its turn (a cron run, a delegated child, a one-shot) is never+ used."""if origin != "turn-end":return False- return getattr(agent, "platform", None) in ("cron", "subagent") or getattr(agent, "_delegate_depth", 0) > 0+ if getattr(agent, "platform", None) in ("cron", "subagent") or getattr(agent, "_delegate_depth", 0) > 0:+ return True+ from agent.oneshot_footprint import agent_is_oneshot++ return agent_is_oneshot(agent) # ``chat -q``: the agent is released right after the replyclass PreparedCompaction:@@ -228,17 +233,20 @@ class PreparedCompaction:# Set by the first compaction that needed memory-provider context; such compactions summarise fresh.self._needs_provider_context = False- def discard(self, reason: str) -> None:- """Drop the candidate and cancel a running pass (it can no longer publish)."""+ def discard(self, reason: str, code: str = "session_boundary") -> None:+ """Drop the candidate and cancel a running pass (it can no longer publish); ``code`` is the closed+ reason opt-in shared metrics count."""with self._lock:entry, pending, self._entry, self._pending = self._entry, self._pending, None, Noneif pending is not None:- pending.cancel("session_boundary")+ pending.cancel(code)if entry is not None or pending is not None:- _record("discarded", reason="session_boundary")- if entry is not None:+ _record("discarded", reason=code)+ dropped = entry or (pending.window if pending is not None else None)+ if dropped is not None:logger.info(- "prepared compaction: dropped window=%d-%d reason=%s", entry.compress_start, entry.compress_end, reason,+ "prepared compaction: dropped session=%s window=%d-%d reason=%s%s", dropped.session_id,+ dropped.compress_start, dropped.compress_end, reason, "" if entry is not None else " (pass running)",)def stop_for_provider_context(self) -> None:@@ -285,11 +293,12 @@ class PreparedCompaction:pending.cancel(code if code in _WAIT_CANCEL_REASONS else "superseded")if reason is not None or entry is None:if entry is not None or pending is not None:- logger.info("prepared compaction: splice miss reason=%s", reason)+ logger.info("prepared compaction: splice miss session=%s reason=%s", session_id, reason)_record("discarded", reason=reason.code, wait_seconds=waited)return Nonelogger.info(- "prepared compaction: splice hit window=%d-%d (fresh cut %d)", entry.compress_start, entry.compress_end, end,+ "prepared compaction: splice hit session=%s window=%d-%d (fresh cut %d)", session_id, entry.compress_start,+ entry.compress_end, end,)_record("used", reason="aux_fallback_main" if entry.telemetry.get("fallback_used") else None, wait_seconds=waited)return entry@@ -312,8 +321,8 @@ class PreparedCompaction:cancel_check = _capture_aux_cancel_check()fallback = time.monotonic() + float(_effective_aux_timeout("compression", None))logger.info(- "prepared compaction: waiting for the running pass window=%d-%d",- pending.window.compress_start, pending.window.compress_end,+ "prepared compaction: waiting for the running pass session=%s window=%d-%d",+ pending.window.session_id, pending.window.compress_start, pending.window.compress_end,)try:while not pending.done.wait(@@ -422,8 +431,8 @@ class PreparedCompaction:started = time.monotonic()try:logger.info(- "prepared compaction: pass started origin=%s window=%d-%d turns=%d",- origin, window.compress_start, window.compress_end, len(turns),+ "prepared compaction: pass started session=%s origin=%s window=%d-%d turns=%d",+ window.session_id, origin, window.compress_start, window.compress_end, len(turns),)with (thread_scoped_silence(), aux_interrupt_protection(cancel_event=token.cancelled),@@ -431,7 +440,8 @@ class PreparedCompaction:):summary = worker._generate_summary(turns, focus_topic=focus)if token.cancelled.is_set():- logger.info("prepared compaction: pass cancelled after %.1fs (superseded)", time.monotonic() - started)+ logger.info("prepared compaction: pass cancelled session=%s after %.1fs (%s)", window.session_id,+ time.monotonic() - started, token.cancel_reason)elif summary:telemetry = worker._active_compression_telemetry or {}entry = PreparedSummary(@@ -440,17 +450,19 @@ class PreparedCompaction:call_state={name: getattr(worker, name, None) for name in _SUMMARY_CALL_STATE},telemetry={key: telemetry.get(key) for key in _SUMMARY_CALL_TELEMETRY},)- logger.info("prepared compaction: pass completed window=%d-%d in %.1fs",- window.compress_start, window.compress_end, time.monotonic() - started)+ logger.info("prepared compaction: pass completed session=%s window=%d-%d in %.1fs",+ window.session_id, window.compress_start, window.compress_end, time.monotonic() - started)else:- logger.warning("prepared compaction: pass failed after %.1fs: %s", time.monotonic() - started,+ logger.warning("prepared compaction: pass failed session=%s after %.1fs: %s", window.session_id,+ time.monotonic() - started,worker._last_summary_error or "summariser returned nothing")event, failure_class = "pass_failed", _pass_failure_class(worker)except AuxiliaryExplicitCancellation:# The closed stream raises a BaseException; it must not reach the thread's excepthook (stderr).- logger.info("prepared compaction: pass cancelled after %.1fs (superseded)", time.monotonic() - started)+ logger.info("prepared compaction: pass cancelled session=%s after %.1fs (%s)", window.session_id,+ time.monotonic() - started, token.cancel_reason)except Exception:- logger.warning("prepared compaction: pass crashed", exc_info=True)+ logger.warning("prepared compaction: pass crashed session=%s", window.session_id, exc_info=True)event, failure_class = "internal_error", "exception"finally:with self._lock:@@ -480,6 +492,14 @@ def _pass_failure_class(worker: Any) -> str:return terminal or (worker._active_compression_telemetry or {}).get("failure_class") or "summary_generation_failed"+def release_for_agent(agent: Any) -> None:+ """The agent is being released (cache eviction, rewind, close): no compaction of it can splice the summary,+ so stop paying for a running pass."""+ prepared = getattr(getattr(agent, "context_compressor", None), "prepared_compaction", None)+ if prepared is not None:+ prepared.discard("agent released", "agent_released")++def adopt(compressor: Any, prepared: PreparedSummary) -> None:"""Leave the live compressor as the inline summary call would have: the summary is the iterative base,failure state cleared, the pass's main-model fallback (if any) carried over, its call in the telemetry."""diff --git a/hermes_cli/observability/schemas/hermes.shared_metrics.v4.schema.json b/hermes_cli/observability/schemas/hermes.shared_metrics.v4.schema.jsonindex efe623be862..63a8a34a077 100644--- a/hermes_cli/observability/schemas/hermes.shared_metrics.v4.schema.json+++ b/hermes_cli/observability/schemas/hermes.shared_metrics.v4.schema.json@@ -5351,6 +5351,7 @@},"reason": {"enum": [+ "agent_released","aux_fallback_main","discarded_while_waiting","fresh_required",diff --git a/hermes_cli/observability/shared_metrics_prepared_compaction.py b/hermes_cli/observability/shared_metrics_prepared_compaction.pyindex ce02cecc397..bd563590d08 100644--- a/hermes_cli/observability/shared_metrics_prepared_compaction.py+++ b/hermes_cli/observability/shared_metrics_prepared_compaction.py@@ -21,7 +21,7 @@ PREPARED_COMPACTION_EVENTS = frozenset({})PREPARED_COMPACTION_ORIGINS = frozenset({"none", "tool_batch", "turn_end"})PREPARED_COMPACTION_REASONS = frozenset({- "aux_fallback_main", "discarded_while_waiting", "fresh_required", "head_moved", "host_cancelled",+ "agent_released", "aux_fallback_main", "discarded_while_waiting", "fresh_required", "head_moved", "host_cancelled","inside_tail", "none", "other_session", "pass_failed_while_waiting", "provider_context", "rewound","running_not_fit", "session_boundary", "shape_changed", "superseded", "text_changed","transcript_shorter", "wait_timeout",diff --git a/run_agent.py b/run_agent.pyindex b060e185e2d..698d937eaca 100644--- a/run_agent.py+++ b/run_agent.py@@ -937,6 +937,8 @@ class AIAgent(_quietly(self._close_codex_session)if getattr(self, "_memory_manager", None) is not None:_quietly(self._memory_manager.release_soft)+ from agent.prepared_compaction import release_for_agent+ _quietly(release_for_agent, self)def close(self) -> None:"""Release every resource this agent holds (idempotent); each phase is guarded so one failure never@@ -945,6 +947,8 @@ class AIAgent(_quietly(self.shutdown_memory_provider, session_messages if isinstance(session_messages, list) else None)self._close_task_resources(getattr(self, "session_id", None) or "")self._close_active_children(soft=False)+ from agent.prepared_compaction import release_for_agent+ _quietly(release_for_agent, self)_quietly(self._drop_shared_client, lambda c: self._close_openai_client(c, reason="agent_close", shared=True))self._close_request_clients("agent_close")_quietly(self._close_codex_session)diff --git a/tests/agent/test_prepared_compaction.py b/tests/agent/test_prepared_compaction.pyindex 7ae54069454..074fce17740 100644--- a/tests/agent/test_prepared_compaction.py+++ b/tests/agent/test_prepared_compaction.py@@ -181,8 +181,9 @@ def test_gates_start_no_pass(setup):assert cc.calls == [][email protected]("agent_attrs", [{"platform": "cron"}, {"platform": "subagent"}, {"_delegate_depth": 1}],- ids=["cron", "subagent-platform", "delegated-child"])[email protected]("agent_attrs", [+ {"platform": "cron"}, {"platform": "subagent"}, {"_delegate_depth": 1}, {"_oneshot_session": True},+], ids=["cron", "subagent-platform", "delegated-child", "one-shot"])def test_turn_end_pass_skipped_where_the_session_ends_with_the_turn(agent_attrs):cc = _compressor()agent = _agent(cc)@@ -483,15 +484,17 @@ def test_session_reset_during_the_wait_wakes_it_without_waiting_for_the_pass():assert cc.prepared_compaction._entry is None[email protected]("boundary", ["reset", "end", "rebind"])[email protected]("boundary", ["reset", "end", "rebind", "agent-released"])def test_session_boundary_discards_candidate_and_running_pass(boundary):def cross(cc, msgs):if boundary == "reset":cc.on_session_reset()elif boundary == "end":cc.on_session_end("S1", msgs)- else: # /resume or /branch onto another session+ elif boundary == "rebind": # /resume or /branch onto another sessioncc.bind_session_state(None, "S2")+ else: # gateway cache eviction / rewind / close release the agent without a session boundary+ pc.release_for_agent(_agent(cc))msgs = _messages(30)completed = _compressor()diff --git a/website/docs/developer-guide/context-compression-and-caching.md b/website/docs/developer-guide/context-compression-and-caching.mdindex ffd1820ef2b..1f144b377cd 100644--- a/website/docs/developer-guide/context-compression-and-caching.md+++ b/website/docs/developer-guide/context-compression-and-caching.md@@ -677,8 +677,8 @@ With `compression.prepare_ahead: true` (read at agent construction, so it takessession or gateway agent rebuild), `agent/prepared_compaction.py` writes the next summary beforethe trigger fires. When the last provider-reported prompt count is within 12% of the trigger(`threshold_tokens`) below it, the turn loop starts one background pass, before a tool batch runs or-at turn end. Turn-end passes are skipped for cron runs and delegated children, whose sessions end-with the turn. The pass plans the same window `compress()` plans (`_plan_compaction_window`) and calls+at turn end. Turn-end passes are skipped for cron runs, delegated children and one-shot sessions+(`hermes chat -q`, `-z`), whose agents end with the turn. The pass plans the same window `compress()` plans (`_plan_compaction_window`) and callsthe same `_generate_summary` on a copy of the compressor and of the window's messages, so the livetranscript, the system prompt and the prompt cache are untouched until compaction. There is one passper compaction: while a summary is held, no further pass starts, however much the prompt grows.@@ -712,7 +712,12 @@ compactions where a memory provider contributes summary context (the first suchfurther passes for that agent, since each would be thrown away). A running pass overtaken by compaction or a sessionboundary (including a rebind to another session id on `/resume` or `/branch`) is cancelled: itcannot publish, and its summary stream is closed rather than billed to completion. A failed pass pauses further passes but never arms the live compressor's failure cooldown. State is per compressor and in memory only, so a gateway agent-eviction or process restart simply means the next compaction runs inline. Plugin context engines,+eviction or process restart simply means the next compaction runs inline; releasing the agent (cache+eviction, a rewind, `close()`) also cancels a running pass. A held summary therefore helps only an+agent that lives across turns (interactive CLI, TUI/Desktop and messaging sessions); a `-q --resume`+chain builds a new agent per run and gets no head start. Pass log lines carry `session=<id>`, and+opt-in shared metrics count adoption and every pass and splice outcome+(`hermes.prepared_compaction.count`, see the shared-metrics guide). Plugin context engines,Codex app-server sessions, native Responses compaction and micro-compaction are not prepared.diff --git a/website/docs/developer-guide/relay-shared-metrics.md b/website/docs/developer-guide/relay-shared-metrics.mdindex db83ed9cae8..2129e088555 100644--- a/website/docs/developer-guide/relay-shared-metrics.md+++ b/website/docs/developer-guide/relay-shared-metrics.md@@ -569,7 +569,7 @@ appears in any dimension: the free-text splice-miss reason is reduced to a close| Metric | Dimensions | Question it answers ||---|---|---|-| `hermes.prepared_compaction.count` | event (`pass_started`, `pass_completed`, `pass_failed`, `pass_cancelled`, `used`, `discarded`, `compaction_failed`, `auto_disabled`, `skipped_busy`, `internal_error`), origin (`tool_batch`, `turn_end`: the hook that started the pass; `none` on compaction-side events), reason (`none`, `fresh_required`, `provider_context`, `other_session`, `head_moved`, `inside_tail`, `transcript_shorter`, `shape_changed`, `rewound`, `text_changed`, `running_not_fit`, `wait_timeout`, `host_cancelled`, `discarded_while_waiting`, `pass_failed_while_waiting`, `superseded`, `session_boundary`, `aux_fallback_main`), failure class (the `hermes.compression.count` vocabulary; `none` unless the event is a failure), wait bucket (`none`, `lt_1s`, `1s_to_5s`, `5s_to_30s`, `30s_to_120s`, `gte_120s`: how long a compaction waited on a running pass) | Do prepared passes pay off, and if not, why. Pass side (from the background thread): `pass_started`, `pass_completed` (summary published), `pass_failed` (the summariser returned nothing; its class is the one an inline attempt would log, a terminal summary failure first), `pass_cancelled` (the pass saw its cancel event; reason `superseded`, `session_boundary`, `wait_timeout` or `host_cancelled`, set by whoever cancelled it), `skipped_busy` (the process-wide cap of two concurrent passes refused one) and `internal_error` (failure class `exception`). Compaction side: `used` (the summary was spliced; reason `aux_fallback_main` when the pass fell back from the summary model to the main model), `discarded` (a completed or running summary the compaction did not use, with the splice-miss code and any wait; a session boundary dropping one reads `session_boundary`), `compaction_failed` (a compaction that spliced a prepared summary but did not commit, with its attempt class) and `auto_disabled` (the first compaction needing memory-provider context turned passes off for the agent). One pass can count on both sides, e.g. `discarded` + `pass_cancelled` for a running pass that did not fit. |+| `hermes.prepared_compaction.count` | event (`pass_started`, `pass_completed`, `pass_failed`, `pass_cancelled`, `used`, `discarded`, `compaction_failed`, `auto_disabled`, `skipped_busy`, `internal_error`), origin (`tool_batch`, `turn_end`: the hook that started the pass; `none` on compaction-side events), reason (`none`, `fresh_required`, `provider_context`, `other_session`, `head_moved`, `inside_tail`, `transcript_shorter`, `shape_changed`, `rewound`, `text_changed`, `running_not_fit`, `wait_timeout`, `host_cancelled`, `discarded_while_waiting`, `pass_failed_while_waiting`, `superseded`, `session_boundary`, `agent_released`, `aux_fallback_main`), failure class (the `hermes.compression.count` vocabulary; `none` unless the event is a failure), wait bucket (`none`, `lt_1s`, `1s_to_5s`, `5s_to_30s`, `30s_to_120s`, `gte_120s`: how long a compaction waited on a running pass) | Do prepared passes pay off, and if not, why. Pass side (from the background thread): `pass_started`, `pass_completed` (summary published), `pass_failed` (the summariser returned nothing; its class is the one an inline attempt would log, a terminal summary failure first), `pass_cancelled` (the pass saw its cancel event; reason `superseded`, `session_boundary`, `agent_released`, `wait_timeout` or `host_cancelled`, set by whoever cancelled it), `skipped_busy` (the process-wide cap of two concurrent passes refused one) and `internal_error` (failure class `exception`). Compaction side: `used` (the summary was spliced; reason `aux_fallback_main` when the pass fell back from the summary model to the main model), `discarded` (a completed or running summary the compaction did not use, with the splice-miss code and any wait; a session boundary dropping one reads `session_boundary`, releasing the agent (cache eviction, rewind, close, a one-shot or managed-worker turn ending) reads `agent_released`), `compaction_failed` (a compaction that spliced a prepared summary but did not commit, with its attempt class) and `auto_disabled` (the first compaction needing memory-provider context turned passes off for the agent). One pass can count on both sides, e.g. `discarded` + `pass_cancelled` for a running pass that did not fit. |<!-- ---- v5 harness ---- -->#### Agent-harness accuracy