Skip to content

The agent that grows with you

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.py
index 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 reply
class 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, None
if 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 None
logger.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.json
index 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.py
index 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.py
index 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.py
index 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 session
cc.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.md
index 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 takes
session or gateway agent rebuild), `agent/prepared_compaction.py` writes the next summary before
the 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 calls
the same `_generate_summary` on a copy of the compressor and of the window's messages, so the live
transcript, the system prompt and the prompt cache are untouched until compaction. There is one pass
per 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 such
further passes for that agent, since each would be thrown away). A running pass overtaken by compaction or a session
boundary (including a rebind to another session id on `/resume` or `/branch`) is cancelled: it
cannot 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.md
index 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