Hermes Tool Result Compaction

Opt-in string-tool-result compaction with disk-backed raw storage, quota cleanup, documentation, benchmark/replay scripts, and 51 tests passing.

What this PR does

When tool_result_compaction.enabled: true is set in ~/.hermes/config.yaml, large string tool results above the configured threshold are:

1. Saved to disk at ~/.hermes/raw_results/<session_id>/<tool_call_id>_<tool_name>_<timestamp>.json
2. Replaced in message history with a compact JSON reference containing tool name, call id, original char/token count, first+last preview, raw result path, and a recovery note
3. Managed by disk quota — oldest raw result files are purged when default 500 MB quota is exceeded; the current file is protected from immediate cleanup

Disabled by default. No behavior change without explicit opt-in to config.yaml.

Design

• Opt-in: DEFAULT_ENABLED = False
• String-only: non-string / multimodal tool results are skipped by the existing isinstance(..., str) guard
• Fail-open: any config, filesystem, permission, or compaction error returns the original content unchanged (tested explicitly)
• LLM-free: deterministic first+last preview; no summarization model call
• Private storage: raw result directories use 0o700; raw JSON files use 0o600
• Existing pipeline compatible: runs after maybe_persist_tool_result() and _tool_result_content_for_active_model()
• Race-safe: symlinks excluded from iteration; stat failures in sort/cleanup fall back gracefully

Files

Config

tool_result_compaction:
  enabled: false
  threshold_tokens: 5000
  raw_result_dir: ""          # empty => ~/.hermes/raw_results
  max_disk_mb: 500
  preview_chars: 1000         # first 1000 + last 1000 chars

Benchmarks

Synthetic (10 results @ 50K chars each)

before_tokens_estimate: 125,000
after_tokens_estimate:    6,450
saved_percent_estimate:  94.84%

Replay (2 JSONL objects: 50K + small string)

saved_percent_estimate:   94.94%
compacted_count:          1

Both are LLM-free, using the same chars / 4 estimate as the compaction module.

Verification

py_compile: OK
pytest: 51 passed in 1.99s
ruff: All checks passed (11 files)
benchmark: 94.84% estimated savings

Commits (squashed to 4)

e2134a280 docs(tool-result-compaction): document configuration and tradeoffs
a60f96ef5 bench(tool-result-compaction): add synthetic and replay benchmarks
a5d301235 test(tool-result-compaction): cover compaction behavior and edge cases
74e14b732 feat(tool-result-compaction): add opt-in tool result compaction

Known tradeoffs

• raw_result_path is a local filesystem path embedded in the compacted JSON for model recovery. Works locally; remote/docker modes would need a reference-ID resolver. (Documented in Limitations.)
• Docs and benchmark scripts are in the same PR. Could be split into a follow-up if upstream prefers a minimal diff.

Status

Ready for review. 4 squashed commits, 51 tests passing, all checks green.