tool_result_storage.py 24 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493
  1. """Tool result persistence -- preserves large outputs instead of truncating. Layers against
  2. context overflow: (1) per-tool caps inside each tool; (2) ``maybe_persist_tool_result`` —
  3. output over the tool's threshold is persisted and replaced by a preview + path; canonical home
  4. is ALWAYS host-side ``$HERMES_HOME/cache/spillover/{id}.txt`` (works for sessions that never
  5. ran a terminal), remote backends get the translated in-sandbox path (probed for readability)
  6. else a copy in the sandbox temp dir; (3) ``enforce_turn_budget``."""
  7. import hashlib
  8. import json
  9. import logging
  10. import math
  11. import os
  12. import re
  13. import shlex
  14. import sqlite3
  15. import tempfile
  16. import threading
  17. import time
  18. from tools.budget_config import DEFAULT_PREVIEW_SIZE_CHARS, BudgetConfig, DEFAULT_BUDGET
  19. logger = logging.getLogger(__name__)
  20. PERSISTED_OUTPUT_TAG = "<persisted-output>"
  21. PERSISTED_OUTPUT_CLOSING_TAG = "</persisted-output>"
  22. STORAGE_DIR = os.path.join(tempfile.gettempdir(), "hermes-results")
  23. SPILLOVER_SUBDIR = "cache/spillover"
  24. # Fallback spillover age only (unreadable config); the real default is the session
  25. # retention window — see _spillover_retention_hours().
  26. SPILLOVER_MAX_AGE_HOURS = 24
  27. _BUDGET_TOOL_NAME = "__budget_enforcement__"
  28. # The exact key set tools/mcp_tool_handlers.py::_render_call_tool_result emits. A JSON object whose
  29. # keys stay inside this set is that handler's own envelope, never an arbitrary tool's JSON payload.
  30. _MCP_ENVELOPE_KEYS = frozenset({"result", "structuredContent", "_meta"})
  31. _ENVELOPE_METADATA_TAG = "<mcp-result-metadata>"
  32. _ENVELOPE_METADATA_CLOSING_TAG = "</mcp-result-metadata>"
  33. _UNSAFE_RESULT_FILENAME_CHARS = re.compile(r"[^A-Za-z0-9_.-]+")
  34. _MAX_RESULT_FILENAME_STEM = 120
  35. _spillover_prune_lock = threading.Lock()
  36. _spillover_pruned_homes: set = set() # profile home keys already swept this process
  37. def get_spillover_dir():
  38. """Return $HERMES_HOME/cache/spillover as a Path (not created)."""
  39. from hermes_constants import get_hermes_home
  40. return get_hermes_home() / SPILLOVER_SUBDIR
  41. def _spillover_retention_hours() -> int:
  42. """Default spillover age = the session retention window (``sessions.retention_days``).
  43. Spill files are archives the durable transcript points at, not a cache: a session resumed
  44. days later must still find what the ``<persisted-output>`` pointer promises (#126351).
  45. Falls back to the legacy 24h cache age when the config is unreadable."""
  46. try:
  47. from hermes_cli.config import load_config_readonly
  48. days = float((load_config_readonly().get("sessions") or {}).get("retention_days", 90))
  49. if not math.isfinite(days): # YAML ``.inf`` / ``.nan`` parse as floats; int() would raise
  50. return SPILLOVER_MAX_AGE_HOURS
  51. except Exception: # health: allow BLE001 -- any config read/parse failure means the legacy floor
  52. return SPILLOVER_MAX_AGE_HOURS
  53. # ``retention_days: 0`` is legal (ended sessions pruned at once) but session prune never
  54. # touches OPEN sessions, while a zero-hour spill cutoff deletes the file the first spill
  55. # just wrote (the pointer then names a missing path). Floor at the legacy cache age.
  56. return max(SPILLOVER_MAX_AGE_HOURS, int(days * 24))
  57. # How a spill archive is named inside transcript text: every pointer form — the host path,
  58. # the ``~``-relative translation, the in-container mounted path — carries the ``spillover/<name>``
  59. # segment. Sandbox-fallback pointers (``…/hermes-results/<name>``) do not, so their host-side
  60. # original stays unreferenced and is reclaimed by the orphan sweep, never by ownership.
  61. # Either separator: Windows host paths are backslashed (JSON-escaped as ``\\`` inside structured content).
  62. _SPILLOVER_NAME_RE = re.compile(r"spillover(?:/|\\+)([A-Za-z0-9_.-]+)")
  63. # instr(), not LIKE: structured content is stored behind a NUL sentinel and LIKE stops at NUL.
  64. SPILLOVER_SQL_FILTER = "(instr(content, 'spillover') > 0 OR instr(api_content, 'spillover') > 0)"
  65. _ARCHIVE_PATH_RE = re.compile(r"(?:^|[/\\])(?:spillover|hermes-results)[/\\][^/\\]+$")
  66. def expired_archive_fields(path: str) -> dict:
  67. """Extra read_file not-found fields for a persisted-tool-result path: the archive was pruned,
  68. so the model gets "expired" instead of a generic miss it might take for a typo (#126351)."""
  69. if not isinstance(path, str) or not _ARCHIVE_PATH_RE.search(path):
  70. return {}
  71. return {"expired": True, "hint": (
  72. "This was a persisted tool result archive and it has expired (pruned with its "
  73. "session or by the cache sweep); the full output is no longer recoverable. Inspect "
  74. "the current state before re-running the original tool — the call that produced it "
  75. "may already have taken effect.")}
  76. def spillover_names_in_text(*texts) -> set:
  77. """Spillover archive basenames referenced by transcript message text (empty set on none)."""
  78. names: set = set()
  79. for text in texts:
  80. if isinstance(text, str) and "spillover" in text:
  81. names.update(_SPILLOVER_NAME_RE.findall(text))
  82. return names
  83. def referenced_spillover_names(spill_dir) -> set | None:
  84. """Basenames under *spill_dir* still referenced by any message in the home's ``state.db``.
  85. ``set()`` when no database exists (no sessions → nothing references anything), ``None``
  86. when the reference set is UNKNOWN (unreadable / truncated query) so callers fail closed
  87. and keep the files; a plain read-only connection is enough, the write path owns the locks."""
  88. db_path = spill_dir.parent.parent / "state.db"
  89. if not db_path.exists():
  90. return set()
  91. try:
  92. # as_uri(): a plain f"file:{path}" breaks on Windows drive letters
  93. conn = sqlite3.connect(f"{db_path.as_uri()}?mode=ro", uri=True, timeout=5.0)
  94. try:
  95. rows = conn.execute(
  96. f"SELECT content, api_content FROM messages WHERE {SPILLOVER_SQL_FILTER} LIMIT 20001"
  97. ).fetchall()
  98. finally:
  99. conn.close()
  100. except (sqlite3.Error, OSError):
  101. return None
  102. if len(rows) > 20000: # truncated reference set: treat as unknown, never guess
  103. return None
  104. names: set = set()
  105. for content, api_content in rows:
  106. names |= spillover_names_in_text(content, api_content)
  107. return names
  108. def cleanup_spillover_cache(max_age_hours: int | None = None) -> int:
  109. """Delete spillover files older than *max_age_hours*; returns count removed (same
  110. contract as the ``cleanup_*_cache`` helpers the gateway housekeeping loop runs hourly).
  111. A ``None`` age means the session retention window, not a cache TTL — an explicit
  112. ``max_age_hours`` (tests, legacy callers) still wins. An expired file is deleted only
  113. when no message in the home's state.db references it: the transcript's
  114. ``<persisted-output>`` promise outlives the archive's mtime exactly as long as the
  115. owning session does (#126351) — referenced archives leave with their session, via the
  116. unlink SessionDB delete/prune performs, not with the age sweep."""
  117. age_hours = _spillover_retention_hours() if max_age_hours is None else max_age_hours
  118. cutoff = time.time() - (age_hours * 3600)
  119. expired = []
  120. try:
  121. entries = list(get_spillover_dir().iterdir())
  122. except OSError:
  123. return 0
  124. for f in entries:
  125. try:
  126. if f.is_file() and f.stat().st_mtime < cutoff:
  127. expired.append(f)
  128. except OSError:
  129. pass
  130. if not expired:
  131. return 0
  132. referenced = referenced_spillover_names(get_spillover_dir())
  133. removed = 0
  134. for f in expired:
  135. if referenced is None or f.name in referenced: # unknown set: fail closed, keep
  136. continue
  137. try:
  138. f.unlink()
  139. removed += 1
  140. except OSError:
  141. pass
  142. return removed
  143. def _prune_spillover_once() -> None:
  144. """Best-effort prune, at most once per process PER PROFILE HOME (CLI-only installs never run
  145. housekeeping; a multiplexed gateway must sweep every profile's ``cache/spillover``, not just the
  146. first one that spilled)."""
  147. from hermes_constants import hermes_home_key
  148. home_key = hermes_home_key()
  149. with _spillover_prune_lock:
  150. if home_key in _spillover_pruned_homes:
  151. return
  152. _spillover_pruned_homes.add(home_key)
  153. try:
  154. if removed := cleanup_spillover_cache():
  155. logger.debug("Pruned %d expired spillover file(s)", removed)
  156. except Exception as exc:
  157. logger.debug("Spillover prune failed: %s", exc)
  158. def _is_host_side_env(env) -> bool:
  159. """True when this process should write the spill file directly: ``env=None`` (no sandbox
  160. yet) or a backend whose files are the host's. Others resolve ``read_file`` inside the sandbox."""
  161. if env is None:
  162. return True
  163. from tools.environments.base import env_uses_host_filesystem
  164. return env_uses_host_filesystem(env)
  165. def _write_to_spillover(content: str, filename: str):
  166. """Write host-side to $HERMES_HOME/cache/spillover; returns path str or None.
  167. The write is size-verified before the caller tells the model "Full output saved":
  168. a partially-flushed file (quota, ENOSPC race) fails closed to the bounded inline
  169. truncation instead of referencing an archive that silently lost bytes.
  170. """
  171. data = content.encode("utf-8", errors="replace")
  172. try:
  173. spill_dir = get_spillover_dir()
  174. spill_dir.mkdir(parents=True, exist_ok=True)
  175. path = spill_dir / filename
  176. path.write_bytes(data)
  177. persisted_size = os.stat(path).st_size
  178. except OSError as exc:
  179. logger.warning("Spillover write failed for %s: %s", filename, exc)
  180. return None
  181. if persisted_size != len(data):
  182. logger.warning(
  183. "Spillover write for %s is not lossless (%d bytes on disk, "
  184. "expected %d) — discarding archive",
  185. filename, persisted_size, len(data),
  186. )
  187. try:
  188. path.unlink()
  189. except OSError:
  190. pass
  191. return None
  192. _prune_spillover_once()
  193. return str(path)
  194. def _sandbox_visible_spillover_path(host_path: str, env) -> str | None:
  195. """Path where a remote backend can read *host_path*, or None. Translates via the image
  196. tools' helper, forces a sync for synced backends, then PROBES readability — a persistent
  197. container created before spillover joined the mount list lacks the bind mount and must
  198. fall back to the in-sandbox write."""
  199. try:
  200. from tools.credential_files import to_agent_visible_cache_path
  201. visible = to_agent_visible_cache_path(host_path)
  202. except Exception as exc:
  203. logger.debug("Spillover path translation failed: %s", exc)
  204. return None
  205. try:
  206. if (sync_manager := getattr(env, "_sync_manager", None)) is not None:
  207. sync_manager.sync(force=True)
  208. except Exception as exc:
  209. logger.debug("Spillover sync failed: %s", exc)
  210. try:
  211. if env.execute(f"test -r {shlex.quote(visible)}", timeout=15).get("returncode", 1) == 0:
  212. return visible
  213. except Exception as exc:
  214. logger.debug("Spillover readability probe failed: %s", exc)
  215. return None
  216. def _resolve_storage_dir(env) -> str:
  217. """Return the best temp-backed storage dir for this environment."""
  218. get_temp_dir = getattr(env, "get_temp_dir", None)
  219. temp_dir = None
  220. if callable(get_temp_dir):
  221. try:
  222. temp_dir = get_temp_dir()
  223. except Exception as exc:
  224. logger.debug("Could not resolve env temp dir: %s", exc)
  225. return f"{temp_dir.rstrip('/') or '/'}/hermes-results" if temp_dir else STORAGE_DIR
  226. def _safe_result_filename(tool_use_id: str) -> str:
  227. """Return a single safe filename for a tool result id."""
  228. raw_id = str(tool_use_id or "tool_result")
  229. safe_stem = _UNSAFE_RESULT_FILENAME_CHARS.sub("_", raw_id).strip("._-")
  230. changed = safe_stem != raw_id
  231. safe_stem = safe_stem or "tool_result"
  232. if changed or len(safe_stem) > _MAX_RESULT_FILENAME_STEM:
  233. digest = hashlib.sha256(raw_id.encode("utf-8")).hexdigest()[:12]
  234. safe_stem = safe_stem[:_MAX_RESULT_FILENAME_STEM].rstrip("._-") or "tool_result"
  235. safe_stem = f"{safe_stem}_{digest}"
  236. return f"{safe_stem}.txt"
  237. def generate_preview(content: str, max_chars: int = DEFAULT_PREVIEW_SIZE_CHARS) -> tuple[str, bool]:
  238. """Truncate at last newline within max_chars. Returns (preview, has_more)."""
  239. if len(content) <= max_chars:
  240. return content, False
  241. last_nl = content.rfind("\n", 0, max_chars)
  242. return content[:last_nl + 1 if last_nl > max_chars // 2 else max_chars], True
  243. def _pageable_text(content: str) -> str:
  244. """Rewrite an MCP handler result envelope into the text it wraps, else return *content*.
  245. ``tools/mcp_tool_handlers.py::_render_call_tool_result`` hands the model a JSON string
  246. (``{"result": <text>, ...}``) so structured metadata survives inline delivery. Persisting
  247. that string verbatim put a multi-hundred-KB document on ONE line with escaped newlines, so
  248. the ``read_file`` offset/limit pagination the ``<persisted-output>`` block recommends could
  249. not be used at all (#90426).
  250. Recognized by SHAPE, not by tool name: the envelope is the only JSON object in the codebase
  251. whose keys are a subset of ``{"result", "structuredContent", "_meta"}`` with a non-empty
  252. string ``result``. That keeps opaque JSON from any other tool verbatim, and it also covers
  253. the aggregate path (``enforce_turn_budget`` persists under ``_BUDGET_TOOL_NAME``, so a
  254. ``mcp__``-prefix test would miss exactly the results it has to fix).
  255. Sibling members are appended after the text in a delimited metadata block instead of being
  256. dropped: they are the structured payloads ``_render_call_tool_result`` deliberately keeps
  257. for the model (#115430), and the spill file is the only copy left once the envelope is
  258. replaced by the preview. Anything unrecognized — unparseable JSON, a non-object, an unknown
  259. key, a missing/empty/non-string ``result`` (e.g. a structuredContent-only result, which has
  260. no pageable text) — is persisted verbatim, exactly as before.
  261. """
  262. try:
  263. payload = json.loads(content)
  264. except (TypeError, ValueError):
  265. return content
  266. if not isinstance(payload, dict) or not payload or not set(payload) <= _MCP_ENVELOPE_KEYS:
  267. return content
  268. text = payload.get("result")
  269. if not isinstance(text, str) or not text:
  270. return content
  271. extras = {key: value for key, value in payload.items() if key != "result"}
  272. if not extras:
  273. return text
  274. try:
  275. metadata = json.dumps(extras, ensure_ascii=False, indent=1, sort_keys=True, default=str)
  276. except (TypeError, ValueError):
  277. return text
  278. return f"{text}\n\n{_ENVELOPE_METADATA_TAG}\n{metadata}\n{_ENVELOPE_METADATA_CLOSING_TAG}\n"
  279. def _write_to_sandbox(content: str, remote_path: str, env) -> bool:
  280. """Write content into the sandbox via env.execute(); True on success. Content goes through
  281. stdin, not the command string: Linux ``MAX_ARG_STRLEN`` caps one argv element at 128 KB,
  282. so a heredoc-in-command silently failed for exactly the oversized results this handles.
  283. The write is round-trip verified with ``wc -c`` (one extra exec RTT per oversized result):
  284. a zero exit from ``cat`` does not prove the bytes landed (quota/ENOSPC races, API-body
  285. truncation on payload backends). A measured mismatch removes the archive and fails closed;
  286. an unprobeable backend (no ``wc``, exec error, unparseable output) stays best-effort success."""
  287. storage_dir = os.path.dirname(remote_path)
  288. # Private dir: archived results carry tool output (can hold secrets) under a
  289. # shared temp root on remote backends. The umask also covers the cat redirect.
  290. from tools.code_execution_rpc import _private_dirs_cmd
  291. cmd = (f"{_private_dirs_cmd(storage_dir)} "
  292. f"&& cat > {shlex.quote(remote_path)}")
  293. if env.execute(cmd, timeout=30, stdin_data=content).get("returncode", 1) != 0:
  294. return False
  295. expected = len(content.encode("utf-8", errors="replace"))
  296. try:
  297. probe = env.execute(f"wc -c < {shlex.quote(remote_path)}", timeout=15)
  298. except Exception as exc:
  299. logger.debug("Sandbox size probe failed for %s: %s", remote_path, exc)
  300. return True
  301. if probe.get("returncode", 1) != 0:
  302. return True
  303. raw = str(probe.get("output", "") or "").strip().split()
  304. if not raw or not raw[-1].isdigit():
  305. return True
  306. persisted_size = int(raw[-1])
  307. if persisted_size == expected:
  308. return True
  309. logger.warning("Sandbox spill for %s is not lossless (%d bytes in sandbox, expected %d) — discarding archive",
  310. remote_path, persisted_size, expected)
  311. try:
  312. env.execute(f"rm -f {shlex.quote(remote_path)}", timeout=15)
  313. except Exception:
  314. pass
  315. return False
  316. def _build_persisted_message(preview: str, has_more: bool, original_size: int,
  317. file_path: str) -> str:
  318. """Build the <persisted-output> replacement block."""
  319. size_kb = original_size / 1024
  320. size_str = f"{size_kb / 1024:.1f} MB" if size_kb >= 1024 else f"{size_kb:.1f} KB"
  321. return (
  322. f"{PERSISTED_OUTPUT_TAG}\n"
  323. f"This tool result was too large ({original_size:,} characters, {size_str}).\n"
  324. f"Full output saved to: {file_path}\n"
  325. "Use the read_file tool with offset and limit to access specific sections of this output.\n"
  326. "Recovery: page through the saved file with read_file (offset/limit) or "
  327. "process it with execute_code — do NOT re-request the same data from the "
  328. "remote API; the archive is kept while this session's transcript references "
  329. "it. If it is missing, inspect the current state before retrying — the call "
  330. "that produced it may already have taken effect.\n\n"
  331. f"Preview (first {len(preview)} chars):\n"
  332. + preview + ("\n..." if has_more else "")
  333. + f"\n{PERSISTED_OUTPUT_CLOSING_TAG}")
  334. _PERSISTED_PATH_RE = re.compile(r"^Full output saved to: (.+)$", re.MULTILINE)
  335. def extract_persisted_path(content: str) -> str | None:
  336. """File path from a <persisted-output> block, or None (lets the result-reference stubbing
  337. guard in agent/tool_guardrails.py carry the spillover path instead of leaving it dangling)."""
  338. match = (_PERSISTED_PATH_RE.search(content)
  339. if isinstance(content, str) and PERSISTED_OUTPUT_TAG in content else None)
  340. return match.group(1).strip() if match else None
  341. def maybe_persist_tool_result(content: str, tool_name: str, tool_use_id: str, env=None,
  342. config: BudgetConfig = DEFAULT_BUDGET,
  343. threshold: float | None = None) -> str:
  344. """Layer 2: persist an oversized result, return preview + path. ``threshold`` overrides
  345. ``config.resolve_threshold(tool_name)``; falls back to inline truncation when no write
  346. location succeeds."""
  347. if threshold is None:
  348. threshold = config.resolve_threshold(tool_name)
  349. if threshold == float("inf") or len(content) <= threshold:
  350. return content
  351. # The size decision above stays on the raw inline result (that is what cost context); the file
  352. # and the preview carry the pageable text inside an MCP envelope (#90426).
  353. persisted_content = _pageable_text(content)
  354. filename = _safe_result_filename(tool_use_id)
  355. preview, has_more = generate_preview(persisted_content, max_chars=config.preview_size)
  356. def _persisted(path: str, host_suffix: str = "") -> str:
  357. logger.info("Persisted large tool result: %s (%s, %d chars -> %s%s)",
  358. tool_name, tool_use_id, len(persisted_content), path, host_suffix)
  359. return _build_persisted_message(preview, has_more, len(persisted_content), path)
  360. # Always persist host-side first: cache/spillover is the single canonical home.
  361. host_path = _write_to_spillover(persisted_content, filename)
  362. host_side = _is_host_side_env(env)
  363. if host_side and host_path is not None:
  364. return _persisted(host_path)
  365. if not host_side:
  366. # Remote backend: reference the mounted/synced path when the sandbox can actually read
  367. # it, else write into the sandbox temp dir (containers without the spillover mount).
  368. visible = _sandbox_visible_spillover_path(host_path, env) if host_path else None
  369. if visible is not None:
  370. return _persisted(visible, f" [host: {host_path}]")
  371. remote_path = f"{_resolve_storage_dir(env)}/{filename}"
  372. try:
  373. if _write_to_sandbox(persisted_content, remote_path, env):
  374. return _persisted(remote_path)
  375. except Exception as exc:
  376. logger.warning("Sandbox write failed for %s: %s", tool_use_id, exc)
  377. logger.info("Inline-truncating large tool result: %s (%d chars, no sandbox write)",
  378. tool_name, len(content))
  379. return (f"{preview}\n\n[Truncated: tool response was {len(content):,} chars. "
  380. "Full output could not be saved to sandbox.]")
  381. def _content_text_size(content) -> int:
  382. """Characters of TEXT a tool message carries: a string's length, or the summed text parts of a multimodal
  383. part list (image parts are governed by the vision embed budget, and a list's ``len`` counts parts)."""
  384. if isinstance(content, list):
  385. return sum(len(p.get("text") or "") for p in content if isinstance(p, dict) and p.get("type") == "text")
  386. return len(content or "")
  387. def _spill_largest_text_part(parts: list, tool_use_id: str, env, config: BudgetConfig) -> tuple[list, int]:
  388. """Persist the largest non-persisted text part of a multimodal list; ``(new parts, chars saved)``."""
  389. texts = [(i, p["text"]) for i, p in enumerate(parts) if isinstance(p, dict) and p.get("type") == "text"
  390. and isinstance(p.get("text"), str) and PERSISTED_OUTPUT_TAG not in p["text"]]
  391. if not texts:
  392. return parts, 0
  393. idx, text = max(texts, key=lambda t: len(t[1]))
  394. replacement = maybe_persist_tool_result(content=text, tool_name=_BUDGET_TOOL_NAME,
  395. tool_use_id=f"{tool_use_id}_part{idx}", env=env, config=config, threshold=0)
  396. if replacement == text:
  397. return parts, 0
  398. return [*parts[:idx], {**parts[idx], "text": replacement}, *parts[idx + 1:]], len(text) - len(replacement)
  399. def enforce_turn_budget(tool_messages: list[dict], env=None,
  400. config: BudgetConfig = DEFAULT_BUDGET) -> list[dict]:
  401. """Layer 3: persist the largest non-persisted results first until the turn's aggregate is
  402. under budget. Mutates the list in-place and returns it. A multimodal result (part list) counts its
  403. text characters and spills its largest text part; its images stay inline."""
  404. sizes = [_content_text_size(msg.get("content", "")) for msg in tool_messages]
  405. total_size = sum(sizes)
  406. candidates = [(i, size) for i, size in enumerate(sizes)
  407. if isinstance(tool_messages[i].get("content"), list)
  408. or PERSISTED_OUTPUT_TAG not in tool_messages[i].get("content", "")]
  409. if total_size <= config.turn_budget:
  410. return tool_messages
  411. for idx, size in sorted(candidates, key=lambda x: x[1], reverse=True):
  412. if total_size <= config.turn_budget:
  413. break
  414. content = tool_messages[idx]["content"]
  415. tool_use_id = tool_messages[idx].get("tool_call_id", f"budget_{idx}")
  416. if isinstance(content, list):
  417. parts, saved = _spill_largest_text_part(content, tool_use_id, env, config)
  418. if saved:
  419. total_size -= saved
  420. tool_messages[idx]["content"] = parts
  421. logger.info("Budget enforcement: persisted a text part of tool result %s (%d chars)", tool_use_id, saved)
  422. continue
  423. replacement = maybe_persist_tool_result(
  424. content=content, tool_name=_BUDGET_TOOL_NAME, tool_use_id=tool_use_id,
  425. env=env, config=config, threshold=0)
  426. if replacement != content:
  427. total_size += len(replacement) - size
  428. tool_messages[idx]["content"] = replacement
  429. logger.info("Budget enforcement: persisted tool result %s (%d chars)",
  430. tool_use_id, size)
  431. return tool_messages