Tool Result Offloading - #115
Conversation
…ime — lossless spill + paged read-back
Large tool results dominate agent context. New tool_result_offload module reduces a
result once, the moment it is produced — before it enters memory, the dump, or any
provider request — so history stays append-only (prompt-cache friendly) and the
reduction persists into traces.
- ToolResultLimit(threshold, action): Spill (default — persist payload, keep preview +
handle + JSON shape sketch inline) or Truncate (head/tail/head_tail clamp). Spill
degrades to a bounded truncation when no store is reachable.
- Configure globally via Agent(tool_result_limit=...) or per tool via
Tool(result_limit=...); int shorthand supported, None exempts. Pinned tools, error
results, and read_tool_result's own output are always exempt.
- LocalOffloadStore: relative-key handles, 0700 root, traversal/symlink-safe reads,
never-clobber writes, keep-forever with opt-in TTL pruning.
- read_tool_result asters when a store exists: line-numbered paging with hard
caps (500 lines / 50k chars) and literal-substring filtering.
summarize() hardening (the loudest compaction complaints across harnesses): user
messages carried verbatim across incremental passes (never paraphrased), canonical
record of every summarized region written to the store and readable back, conservative
continuation note instead of "continue without asking", grounding rules in the
summarizer prompts, and a rehydrate= hook re-run on every pass.
compact_tool_results() treats offloaded placeholders as already compacted (opt out with
keep_offloaded=False); replacement templates gain {handle}.
PR SummaryMedium Risk Overview Agents gain Memory compaction is aligned with offloading: Public exports, message deserialization for Reviewed by Cursor Bugbot for commit 8b02e15. Bugbot is set up for automated code reviews on this repo. Configure here. |
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit ae1feb0. Configure here.
…ctured field A compact_tool_results(replacement=...) rewrite can strip the read_tool_result pointer from a spilled result's placeholder prose while the structured offload_handle field survives. _format_message_for_transcript now emits the handle from the field, so the summary's canonical record always resolves back to the full payload regardless of placeholder mutations. Regression test pins the broken-chain scenario. Also fixes test_int_shorthand on Windows: Path.home() ignores $HOME there (USERPROFILE wins), so patch the method instead of the env var.
….md; polish test portability - CLAUDE.md: new section covering ToolResultLimit (Spill/Truncate, per-tool precedence, exemptions), the auto-registered read_tool_result tool, and the sectioned summarize() output (verbatim user messages, canonical record, rehydrate hook). - read_tool_result: add schema description for the handle param so the model knows where handles come from. - Symlink-escape test skips on platforms where symlink creation needs elevated privileges (unprivileged Windows) instead of erroring.
2 participants
No description provided.