feat(compression): add configurable warn_after_compressions threshold (#53876)

[IsshikiSenn]

Make the repeated-compression warning threshold configurable via compression.warn_after_compressions (default 2, 0 disables). Long-running sessions can raise the threshold without patching source.

Closes #53876

What does this PR do?

The repeated-compression warning ("Session compressed N times — accuracy may degrade. Consider /new to start fresh.") was hardcoded to fire when compression_count >= 2. That is too aggressive for long-running sessions (multi-agent orchestration, research tasks) where multiple compactions are normal, and there was no way to tune or disable the warning without editing source.

This PR adds compression.warn_after_compressions under the existing compression: config section. Default 2 preserves current behavior; set to 0 to disable the warning entirely, or raise it (e.g. 5) for sessions that expect many compactions. The value is read at agent construction time in agent_init.py and consumed in compress_context() — same pattern as other agent-level compression settings like compression_in_place.

Related Issue

Fixes #53876

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 🔒 Security fix
• 📝 Documentation update
• ✅ Tests (adding or improving test coverage)
• ♻️ Refactor (no behavior change)
• 🎯 New skill (bundled or hub)

Changes Made

• hermes_cli/config.py — add compression.warn_after_compressions: 2 to DEFAULT_CONFIG
• agent/agent_init.py — read config and set agent.compression_warn_after_compressions (max(0, int(...)))
• agent/conversation_compression.py — replace hardcoded >= 2 with configurable threshold check
• cli-config.yaml.example — document the new key
• website/docs/user-guide/configuration.md — add to Context Compression reference
• tests/agent/test_compression_count_warning_36908.py — extend coverage for custom threshold, boundary, and 0 = disabled

Intentionally out of scope: gateway cache-busting (change takes effect on next agent construction / new session), Desktop curated settings allowlist, warning deduplication, CLI status-bar compression styling.

How to Test

1. Run unit tests:

   scripts/run_tests.sh tests/agent/test_compression_count_warning_36908.py

2. Default behavior (unchanged): leave warn_after_compressions unset or at 2; after the 2nd compaction, the warning should appear via _emit_status / gateway status callback.
3. Custom threshold: set compression.warn_after_compressions: 5 in ~/.hermes/config.yaml, start a new session (or restart gateway), compress 4 times — no warning; on the 5th compaction — warning fires.
4. Disable: set compression.warn_after_compressions: 0; no repeated-compression warning regardless of count.

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (fix(scope):, feat(scope):, etc.)
• I searched for existing PRs to make sure this isn't a duplicate
• My PR contains only changes related to this fix/feature (no unrelated commits)
• I've run pytest tests/ -q and all tests pass — run scripts/run_tests.sh tests/agent/test_compression_count_warning_36908.py locally before merge
• I've added tests for my changes (required for bug fixes, strongly encouraged for features)
• I've tested on my platform: macOS 26.5.1 (25F80)

Documentation & Housekeeping

• I've updated relevant documentation (README, docs/, docstrings) — or N/A
• I've updated cli-config.yaml.example if I added/changed config keys — or N/A
• I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows — or N/A
• I've considered cross-platform impact (Windows, macOS) per the compatibility guide — or N/A
• I've updated tool descriptions/schemas if I changed tool behavior — or N/A

Screenshots / Logs

N/A — config-only change; behavior verified via unit tests.

[Copilot]

Pull request overview

Adds a new compression.warn_after_compressions configuration knob to control (or disable) the “Session compressed N times…” repeated-compression warning, making long-running sessions less noisy without requiring source edits.

Changes:

• Introduces compression.warn_after_compressions (default 2, 0 disables) in the default config and user-facing config examples/docs.
• Threads the config value into agent initialization (agent.compression_warn_after_compressions) and uses it in conversation_compression.py instead of the hardcoded >= 2.
• Extends the existing regression test to cover custom thresholds and the disabled (0) case.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
agent/agent_init.py	Reads compression.warn_after_compressions from config and stores it on the agent.
agent/conversation_compression.py	Uses the agent-configured threshold to decide when to emit the repeated-compression warning.
hermes_cli/config.py	Adds the new key to DEFAULT_CONFIG (preserving existing default behavior).
cli-config.yaml.example	Documents the new config key and its intended behavior.
website/docs/user-guide/configuration.md	Adds the new key to the compression reference and describes its behavior.
tests/agent/test_compression_count_warning_36908.py	Adds coverage for custom thresholds and 0 = disabled.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[tonydwb]

Code Review Summary

Verdict: Approved

Clean feature: adds a configurable warn_after_compressions threshold (default 2, 0 to disable). The config plumbing is correct through agent_init.py -> agent.compression_warn_after_compressions -> conversation_compression.py. Test coverage is thorough with the _build_agent_with_db helper updated to accept the new parameter. The CLI config example is well-documented.

---

Reviewed by Hermes Agent

[tonydwb]

Code Review Summary

Verdict: Comment — Clean configuration enhancement

Adds a configurable compression.warn_after_compressions threshold to control when the repeated-compression warning fires. Default 2 (existing behavior), 0 disables entirely.

Changes:

• agent/agent_init.py: Reads config value and stores on agent
• agent/conversation_compression.py: Uses configured threshold instead of hardcoded >= 2
• hermes_cli/config.py: Adds default to DEFAULT_CONFIG
• cli-config.yaml.example: Documents new key
• website/docs/user-guide/configuration.md: User-facing docs
• tests/agent/test_compression_count_warning_36908.py: 3 new tests for custom threshold, fire-at-threshold, and disabled cases

Assessment:

• Well-scoped: 6 files, 80 additions
• Backward-compatible (default matches existing behavior)
• Test coverage for all edge cases
• Docs and config examples updated
• No security concerns

---

Reviewed by Hermes Agent

[teknium1]

Thanks for the focused configuration addition. The underlying request remains valid on current main: agent/conversation_compression.py:935-942 still warns at a hardcoded count of two.

Problems

• agent/agent_init.py reads this value only during construction, but gateway/run.py:15743-15754 omits compression.warn_after_compressions from cached-agent invalidation. A running gateway therefore retains the old setting, while website/docs/user-guide/configuration.md:762-764 promises hot reload for compression.*.
• The added int(...) coercion can raise on null or non-numeric YAML and prevent agent construction. The PR tests bypass this path by assigning the agent attribute directly.

Suggested changes

• Add the new key to _CACHE_BUSTING_CONFIG_KEYS and cover a changed gateway signature in tests/gateway/test_agent_cache.py.
• Fall back to 2 for invalid values and add a config-to-agent construction regression covering custom, disabled, and invalid input.

This is an automated hermes-sweeper review.

[IsshikiSenn]

Thanks for the review — addressed both points on the latest commit:

1. Gateway hot-reload — added ("compression", "warn_after_compressions") to _CACHE_BUSTING_CONFIG_KEYS in gateway/run.py, with coverage in tests/gateway/test_agent_cache.py (extract + signature change).
2. Config coercion — wrapped the int(...) parse in agent/agent_init.py with except (TypeError, ValueError) and a silent fallback to 2. Added a config→attribute regression covering custom (5), disabled (0), null, and non-numeric ("abc") inputs.

Left protect_first_n / the docs tip alone to keep this PR scoped to the review items. Happy to follow up separately if you want those tightened too.