feat(run_agent): opt-in prune of historical reasoning_content beyond N turns

[Julientalbot]

⚠️ Draft for design review. This PR ships a working, tested implementation but I'd like upstream feedback on (a) the config key naming, (b) the blocklist scope, and (c) whether the prune should happen on the per-call copy (current implementation) or on the stored session. See the "Open questions" section below.

Problem

Long agent sessions (Telegram bots, long CLI/headless runs) accumulate reasoning_content / reasoning / reasoning_details on every assistant turn. PRs #15250 (DeepSeek) and #17400 (Kimi) made these fields sticky in the message store because those models require their own reasoning to be replayed for correctness.

The downside on other agentic stacks (grok-4.x, OpenAI o1/o4 via Responses, etc.): replaying every historical reasoning block can amount to several MB of cached tokens per turn, biasing the model toward narrative continuation rather than fresh tool execution.

This is empirically observable on a real-world Alfred Telegram session shipped with this branch's repro corpus: the pivot into IWE (Intention Without Execution — model says "I'll check the directory" and emits no tool_call) happens around turn #12, immediately after the assistant history accumulates dense reasoning content from earlier productive turns. The reasoning replay biases the model toward "reasoning about the next reasoning" rather than acting.

Fix (opt-in, off by default)

A new config key on the agent section, off by default — no behavioural drift for current users:

agent:
  max_reasoning_history_turns: 5   # int or null/missing

When unset (default None), behaviour is unchanged — full history replays.
When set to N (positive int), only the last N assistant turns retain their reasoning_content / reasoning / reasoning_details keys; older assistant turns have these keys removed from the per-call copy. The stored session messages are never mutated — session continuity, replays, and the session JSON on disk all remain untouched.

Models matching the new class attribute _REASONING_HISTORY_REQUIRED_MODELS = ("deepseek", "kimi", "moonshot") short-circuit the prune with a one-time warning, since pruning would break tool-call accuracy on these models (per #15250 / #17400).

The new method _prune_reasoning_history is called right after _sanitize_api_messages at both call sites (the main loop and _handle_max_iterations), keeping the flow consistent.

Tests

9 new cases in TestPruneReasoningHistory:

• test_default_no_op — no config = no behavioural change
• test_prune_keeps_last_n_on_grok — N=2 on grok-4.3 strips reasoning from older assistant turns, keeps last 2
• test_blocklist_deepseek_no_op_with_warning — blocklist short-circuits + warning
• test_blocklist_kimi_no_op — same for kimi
• test_blocklist_warning_is_idempotent — warning fires only once per agent instance
• test_negative_n_is_no_op — -1 is normalised to None at init
• test_assistant_count_below_n_no_op — fewer assistant turns than N: nothing to prune
• test_non_assistant_messages_untouched — user/tool messages never modified
• test_does_not_mutate_input — caller's message list is never mutated

pytest tests/run_agent/test_run_agent.py -v -k PruneReasoningHistory → 9 passed.

Open questions for design review

1. Naming. max_reasoning_history_turns is descriptive but verbose. Alternatives: keep_recent_reasoning_turns, reasoning_history_window, prune_old_reasoning. Preference?

2. Blocklist scope. Current list is ("deepseek", "kimi", "moonshot"). Should we add others (e.g. Qwen-3 / GLM that also use reasoning_content channels)? Should the blocklist be config-overridable, or kept hardcoded as a safety rail?

3. Per-call vs stored. Current implementation prunes only the per-call copy (the conservative choice — preserves session JSON). Alternative: prune self._session_messages in place, freeing memory and shrinking the on-disk session file. Comments?

4. Default policy. Should there be a sensible default for non-blocklisted models when the config is missing? (My current answer: no — opt-in only, no surprises.)

5. Interaction with compression. Should the prune respect compression.protect_last_n (don't strip reasoning from the protected window) or stay simple (independent N)? Current implementation: independent N.

Pairing

Last in a small series of PRs improving IWE detection on grok-4.x and adjacent agentic stacks:

• feat(transports/codex): pass reasoning.effort to xAI Responses API #22055 — pass reasoning.effort to xAI Responses (otherwise silently dropped on the xAI direct path)
• feat(run_agent): extend codex intermediate-ack detection to French + relax prior-tool bail #22059 — extend _looks_like_codex_intermediate_ack to French + relax the global bail-on-prior-tool
• feat(run_agent): runtime intermediate-ack nudge when tool_use_enforcement=required #22061 — runtime nudge when tool_use_enforcement: required (extends the existing detector to non-codex_responses paths)
• this PR — opt-in reasoning history prune (Draft for design discussion)

The four are independent and can land in any order.

[teknium1]

Thanks for the focused, opt-in proposal. Current main has moved the affected request-building paths, and this needs design rework before it can be safely salvaged.

Problems

• The moving N-turn cutoff changes historical API messages after they have already been sent. That conflicts with the prompt-caching invariant in AGENTS.md:1132-1137; current request assembly also normalizes payloads for stable prefixes in agent/conversation_loop.py:915+.
• The proposed field list does not cover the stated xAI/OpenAI Responses case. Current xAI Responses tests require replaying encrypted reasoning in tests/run_agent/test_codex_xai_oauth_recovery.py:399-476.
• The model-substring blocklist conflicts with current endpoint-based Kimi/Moonshot detection in run_agent.py:5486-5504, and omits the existing MiMo replay requirement.
• The PR does not add the required DEFAULT_CONFIG entry (AGENTS.md:584-590).

Suggested changes

• Settle the cache-safe replay design first, then implement it at the current request builders: agent/conversation_loop.py and agent/chat_completion_helpers.py.
• Use the existing provider/transport capability predicates and add transport-level replay tests.

Automated hermes-sweeper review.

[teknium1]

This model-substring blocklist does not match the current provider contract: run_agent.py:5486-5504 deliberately detects Kimi/Moonshot from the active provider/endpoint because OpenRouter-style re-exports can use the same model name but reject their native reasoning replay protocol. It also omits the current MiMo requirement.

[teknium1]

A turn that was previously sent with reasoning changes once it ages beyond N, invalidating the historical request prefix. AGENTS.md:1132-1137 explicitly forbids altering past context mid-conversation to preserve prompt caching; this needs a cache-safe design rather than a per-call moving cutoff.