feat(compress): N-user tail guarantee via compression.min_tail_user_messages (salvage of #22566)

[teknium1]

Salvage of PR #22566 — compression.min_tail_user_messages (N-user tail guarantee)

Salvages @zhangyang-crazy-one's #22566: a config-driven guarantee that the last N real user messages survive in the uncompressed tail during context compression. Contributor commit cherry-picked with authorship preserved (Jerry <jerry@hermes.local>, mapped to @zhangyang-crazy-one via contributors/emails/).

The gap on main

Main has a single last-user tail anchor (_ensure_last_user_message_in_tail, #10896/#22523) plus the actionable-turn filters from #69291 — but nothing guarantees more than one real user turn survives. When bulky tool outputs fill tail_token_budget, users 2..N roll into the summary. Verified live on main:

N=1 (main behavior): cut=4 → tail users: ['real 2', 'real 1']   ← 'real 3' summarized away
N=3 (this PR):       cut=2 → tail users: ['real 3', 'real 2', 'real 1']

(3 user turns each followed by a 6 000-char tool-heavy assistant reply, tail budget 150 tokens.)

What was salvaged from the contributor (cherry-picked)

• _ensure_last_n_user_messages_in_tail() — generalizes the single anchor to N; N<=1 delegates directly to _ensure_last_user_message_in_tail for byte-identical regression safety.
• min_tail_user_messages ContextCompressor param + agent_init.py parse + cli.py embedded default + gateway cache-busting key ("compression", "min_tail_user_messages").
• 7 tests in TestMinTailUserMessages (N=3, N=5, tool-group integrity, fewer-than-N, already-in-tail no-op, no-users-beyond-head, N=1 parity).
• The contributor's head already fixed 2 of 3 sweeper-review concerns: the N-helper doesn't call _align_boundary_backward (a user message is a clean boundary — calling it can pull the cut into the preceding tool group and split it), and summary handoffs are filtered out of the collection walk. Credit where due.

Dropped from the branch (out of scope): unrelated DeepSeek/Weixin/run_agent hunks — only the compressor mechanism + config wiring is ported.

Follow-up fixes on top (maintainer commit)

1. N-collector now counts only REAL actionable turns. The contributor's collector used bare role == "user" + _is_context_summary_content — blank platform echoes and synthetic continuation/todo rows would consume N slots, silently degrading the guarantee to N−1 (or worse) real turns and re-importing the fix(compression): anchor compaction on the latest actionable user turn #69291 bug class. The collector now uses the exact filter pair _find_last_user_message_idx uses post-fix(compression): anchor compaction on the latest actionable user turn #69291: _is_actionable_user_turn(msg) and not _is_synthetic_compression_user_turn(msg).
2. Default flipped 3 → 1 (behavior-preserving). Verified empirically: a default of 3 CHANGES the tail cut on current main for transcripts whose budget covers only the last turn (cut N=1: 5 vs cut N=3: 4 on a 12-message probe). Since the salvage bar is "existing behavior unchanged unless configured", the default ships as 1 — exactly the existing single-user anchor — and N>1 is opt-in. The _find_tail_cut_by_tokens call site is additionally gated on min_tail_user_messages > 1, so the default path is byte-identical to main (and the single anchor's fix(compressor): prevent orphan user turn after compaction (turn-pair preservation) #22523 causal-coupling forward-push logic is never re-run after the assistant anchor).
3. Hardened config parse in agent_init.py matching the max_attempts parser shape: booleans rejected (bool subclasses int), fractional floats rejected, floor 1.
4. Closed the recurring external-PR config gap: the original PR only wired cli.py. Added hermes_cli/config.py DEFAULT_CONFIG + cli-config.yaml.example + docs table row (website/docs/developer-guide/context-compression-and-caching.md).

Precedence semantics (documented contract)

The N-guarantee wins over tail_token_budget, and _MAX_TAIL_MESSAGE_FLOOR stays a minimum, not a cap. The budget walk (bounded by the 8-message floor and the 1.5× soft ceiling) computes the initial cut; the N-anchor then only ever pulls the cut backward — the same monotonic "tail can only grow" contract as the existing user/assistant anchors, applied after them and before the final forward tool-group re-alignment. Rationale: the anchors exist precisely for the case where the budget makes the wrong call (bulky tool outputs), so budget-wins would make the knob a no-op in the one scenario it targets. A user message is a clean boundary, so the anchored index can never split a tool_call/result pair; the pinned test asserts no-orphan in both directions.

Regression tests added

Test	Pins
test_blank_echo_does_not_count_toward_n	Blank/whitespace platform echoes don't consume N slots (#69291 class)
test_synthetic_compression_rows_do_not_count_toward_n	Compaction handoffs + continuation markers don't count toward N
test_n_boundary_never_orphans_tool_results	Full pipeline: tool call/result ids in the tail match exactly (no split in either direction)
test_n_guarantee_wins_over_tail_token_budget_and_floor	N-anchor beats a tiny budget; anchored tail legitimately exceeds it
test_default_is_behavior_preserving	Default cut byte-identical to explicit min_tail_user_messages=1
test_default_config_ships_behavior_preserving_value	DEFAULT_CONFIG["compression"]["min_tail_user_messages"] == 1

Validation

Check	Result
tests/agent/test_context_compressor.py (incl. 13 TestMinTailUserMessages tests)	✅ 208 passed
Sibling anchor/provenance/rotation suites (test_compression_rotation_state, test_compressor_actionable_tail_anchor, test_compressor_assistant_tail_anchor, test_context_compressor_temporal_anchoring, test_context_compressor_zero_user_provenance)	✅ 79 passed
tests/agent/test_compression_max_attempts_config.py (adjacent parser seam)	✅ 9 passed
Combined re-run post-rebase	✅ 296 passed, 0 failed
ruff check on all touched files	✅ clean
Live probe: N=1 vs N=3 cut on tool-heavy transcript	✅ gap reproduced, fix verified (numbers above)
Default-3 behavior change probe	✅ confirmed change → default gated to 1

Credit: @zhangyang-crazy-one for the mechanism, the clean-boundary insight (no _align_boundary_backward in the N-helper), and the handoff filtering — both post-review fixes were already on their head.

Infographic

[github-actions]

૮ >ﻌ< ა ci review

_{ran on 5de9338}

all good!