Skip to content

The agent that grows with you

fix(agent): persist the turn budget's spill stubs onto the flushed tool rows

Teknium614fddb694bb
diff --git a/agent/session_persistence.py b/agent/session_persistence.py
index 9fc8a0207c3..6cdb926b954 100644
--- a/agent/session_persistence.py
+++ b/agent/session_persistence.py
@@ -254,6 +254,44 @@ def _db_flush_row(agent, msg: dict, is_current_turn_user: bool) -> dict[str, Any
return row
+def sync_rewritten_tool_rows(agent, batch: list[dict], contents_before: list[Any]) -> int:
+ """Carry an end-of-batch rewrite of already-flushed tool results (the turn budget's spill
+ stubs) onto their durable rows; returns the rows rewritten.
+
+ Each result was flushed as it landed, so its row holds the full body. Replay reads the
+ store, so a row left stale reloads the spilled bytes next turn: the request grows by
+ everything the budget removed and its cached prefix diverges at the first spilled row.
+ The full body survives as the archived twin ``rewrite_pruned_rows`` keeps, beside the
+ spill file. A store without the in-place writer, or a row another writer moved, keeps
+ today's row.
+ """
+ session_db, session_id = getattr(agent, "_session_db", None), getattr(agent, "session_id", None)
+ rewrite = getattr(session_db, "rewrite_pruned_rows", None)
+ if getattr(agent, "_persist_disabled", False) or not session_id or not callable(rewrite):
+ return 0
+ changed = [
+ (msg, before) for msg, before in zip(batch, contents_before)
+ if msg.get(_DB_PERSISTED_MARKER) and msg.get("role") == "tool" and msg.get("content") != before]
+ if not changed:
+ return 0
+ rows = [(_db_flush_row(agent, {**msg, "content": before}, False), _db_flush_row(agent, msg, False))
+ for msg, before in changed]
+ from hermes_state_errors import PruneRowUnresolvedError
+ try:
+ with _persist_lock(agent):
+ written = rewrite(session_id, rows)
+ except PruneRowUnresolvedError as exc: # PruneRowStaleError included: another writer owns the row now
+ logger.info("Tool-result rewrite not persisted; the stored row keeps the full body: %s", exc)
+ return 0
+ except Exception as exc: # health: allow BLE001 -- a store failure must not fail the turn; the row keeps its body
+ logger.warning("Tool-result rewrite not persisted: %s", exc)
+ return 0
+ for (msg, _before), (_original, replacement) in zip(changed, rows):
+ if isinstance(replacement.get(DB_ROW_SNAPSHOT), str):
+ msg[DB_ROW_SNAPSHOT] = replacement[DB_ROW_SNAPSHOT]
+ return int(written)
+
+
def _db_flush_collect(agent, messages: list[dict], conversation_history: Optional[list[dict]],
replay_history: bool = False):
"""Scan for un-flushed messages; returns ``(rows, msgs)`` to write in one transaction. ``replay_history``
diff --git a/agent/tool_executor.py b/agent/tool_executor.py
index cb58137a2ac..9cf7a8f4796 100644
--- a/agent/tool_executor.py
+++ b/agent/tool_executor.py
@@ -44,6 +44,7 @@ from agent.inline_tool_executors import (
tool_hook_ids,
)
from agent.message_metadata import stamp_data_use
+from agent.session_persistence import sync_rewritten_tool_rows
from agent.tool_dispatch_helpers import (
_NEVER_PARALLEL_TOOLS,
_is_destructive_command,
@@ -1225,6 +1226,7 @@ def _finalize_tool_batch(agent, messages: list, effective_task_id: str, num_tool
contents_before = [message.get("content") for message in batch]
enforce_turn_budget(batch, env=get_active_env(effective_task_id), config=budget)
plugin_live_notes.keep_after_turn_budget(agent, batch)
+ sync_rewritten_tool_rows(agent, batch, contents_before)
record_tool_batch(agent, batch, contents_before)
agent._apply_pending_steer_to_tool_results(messages, num_tools)
diff --git a/tests/agent/test_turn_budget_durable_rows.py b/tests/agent/test_turn_budget_durable_rows.py
new file mode 100644
index 00000000000..2ccd457a06d
--- /dev/null
+++ b/tests/agent/test_turn_budget_durable_rows.py
@@ -0,0 +1,117 @@
+"""A tool result the per-turn budget spills must replay as the stub it was sent as.
+
+Each tool result is flushed to the session store as it lands; the turn budget then swaps the
+largest ones for ``<persisted-output>`` previews in memory. The gateway, the TUI resume path and
+``--resume`` rebuild history from the store, so a row left holding the full body comes back on the
+next turn: the request grows by everything the budget removed (past ``context_length`` in the live
+repro) and its cached prefix diverges at the first spilled row.
+"""
+
+import contextlib
+import os
+import sqlite3
+import uuid
+from types import SimpleNamespace
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from tools.budget_config import BudgetConfig
+from tools.tool_result_storage import PERSISTED_OUTPUT_TAG
+
+_LARGE = "L" * 4_000
+
+
+def _tc(name, arguments, call_id):
+ return SimpleNamespace(id=call_id, type="function", function=SimpleNamespace(name=name, arguments=arguments))
+
+
+def _tool_defs(*names):
+ return [{"type": "function", "function": {"name": n, "description": n,
+ "parameters": {"type": "object", "properties": {}}}}
+ for n in names]
+
+
+def agent_and_db(tmp_path):
+ from hermes_state import SessionDB
+
+ db = SessionDB(db_path=tmp_path / "state.db")
+ with (
+ patch("model_tools.get_tool_definitions", return_value=_tool_defs("web_search", "terminal")),
+ patch("model_tools.check_toolset_requirements", return_value={}),
+ patch("agent.process_bootstrap.OpenAI"),
+ patch.dict(os.environ, {"OPENROUTER_API_KEY": "test-key"}),
+ ):
+ from run_agent import AIAgent
+
+ agent = AIAgent(
+ api_key="test-key-1234567890", base_url="https://openrouter.ai/api/v1", model="test/model",
+ quiet_mode=True, skip_context_files=True, skip_memory=True,
+ session_db=db, session_id=f"sess-{uuid.uuid4().hex[:8]}",
+ )
+ agent.client = MagicMock()
+ yield agent, db
+ db.close()
+
+
+def _run_batch(agent, calls):
+ messages = [{"role": "user", "content": "read them"},
+ {"role": "assistant", "content": "", "tool_calls": [
+ {"id": c.id, "type": "function",
+ "function": {"name": c.function.name, "arguments": c.function.arguments}} for c in calls]}]
+ budget = BudgetConfig(default_result_size=100_000, turn_budget=6_000, preview_size=64)
+
+ def fake_handle(name, args, task_id, **kwargs):
+ return _LARGE if "large" in kwargs["tool_call_id"] else "small"
+
+ with (
+ patch("model_tools.handle_function_call", side_effect=fake_handle),
+ patch("agent.tool_executor._budget_for_agent", return_value=budget),
+ ):
+ agent._execute_tool_calls(SimpleNamespace(content="", tool_calls=calls), messages, "task-1")
+ return messages
+
+
+ "calls",
+ [
+ [_tc("web_search", '{"query":"a"}', "p-large-1"), _tc("web_search", '{"query":"b"}', "p-large-2"),
+ _tc("web_search", '{"query":"c"}', "p-small")],
+ [_tc("terminal", '{"command":"a"}', "s-large-1"), _tc("terminal", '{"command":"b"}', "s-large-2"),
+ _tc("terminal", '{"command":"c"}', "s-small")],
+ [_tc("web_search", '{"query":"a"}', "m-large-1"), _tc("terminal", '{"command":"b"}', "m-large-2"),
+ _tc("terminal", '{"command":"c"}', "m-small")],
+ ],
+ ids=["parallel", "sequential", "mixed"],
+)
+def test_replayed_history_carries_the_budget_stub_that_was_sent(agent_and_db, calls):
+ agent, db = agent_and_db
+ messages = _run_batch(agent, calls)
+
+ live = {m["tool_call_id"]: m["content"] for m in messages if m.get("role") == "tool"}
+ spilled = [cid for cid, content in live.items() if PERSISTED_OUTPUT_TAG in content]
+ assert spilled, "the fixture must make the turn budget spill at least one result"
+
+ # The gateway's live-replay read (gateway/session_transcript.load_transcript).
+ replay = db.get_messages_as_conversation(agent.session_id, repair_alternation=True)
+ replayed = {m["tool_call_id"]: m["content"] for m in replay if m.get("role") == "tool"}
+ assert replayed == live
+
+
+def test_spilled_full_body_stays_searchable_and_next_flush_appends_once(agent_and_db):
+ agent, db = agent_and_db
+ calls = [_tc("web_search", '{"query":"a"}', "q-large-1"), _tc("web_search", '{"query":"b"}', "q-large-2")]
+ messages = _run_batch(agent, calls)
+
+ with contextlib.closing(sqlite3.connect(db.db_path)) as conn:
+ full_bodies = conn.execute(
+ "SELECT active FROM messages WHERE session_id = ? AND role = 'tool' AND instr(content, ?) > 0 "
+ "ORDER BY id", (agent.session_id, _LARGE)).fetchall()
+ # The result the budget kept inline, plus the archived twin of the one it spilled.
+ assert full_bodies == [(1,), (0,)]
+
+ messages.append({"role": "assistant", "content": "done"})
+ assert agent._flush_messages_to_session_db(messages) is True
+ replay = db.get_messages_as_conversation(agent.session_id, repair_alternation=True)
+ assert [m["role"] for m in replay] == ["user", "assistant", "tool", "tool", "assistant"]