fix: add fallback trim point for tool-heavy conversations in SlidingWindowConversationManager

[lufecadu]

Description

PR #2087 introduced user-first enforcement in reduce_context, which correctly prevents conversations from starting with an assistant message. However, in tool-heavy agent loops where every user message after the initial prompt contains toolResult, there are no valid plain user message trim points. This causes ContextWindowOverflowException on conversations that previously trimmed successfully.

This adds a fallback that trims to an assistant(toolUse) + user(toolResult) boundary when no plain user message exists within the trim range. This preserves valid message ordering for all providers while allowing tool-heavy conversations to be trimmed.

Related Issues

#2173

Type of Change

Bug fix

Testing

How have you tested the change? Verify that the changes do not break functionality or introduce warnings in consuming repositories: agents-docs, agents-tools, agents-cli

• I ran hatch run prepare

Checklist

• I have read the CONTRIBUTING document
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• My changes generate no new warnings
• Any dependent changes have been merged and published

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[afarntrog]

cc @JackYPCOnline

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[github-actions]

Assessment: Comment

Good bug fix that addresses a real regression in tool-heavy conversations. The fallback approach is sound and the core logic is correct.

Review Categories

• Testing: The preference test merges two unrelated test scenarios into one function (the new preference test + the old truncation test that was renamed over). These should be split. The fallback test assertions could be more precise about the expected trim outcome.
• Documentation: The fallback relaxes the user-first invariant from [BUG] force slidingWindowConversationManager to use user message. Currently, it could start with an assistant message. #2085/fix: enforce that the first message is a user message in the sliding window conversation manager #2087 — adding a brief comment explaining why assistant(toolUse) + user(toolResult) is an acceptable starting pattern for providers would help future maintainers.

The fix is well-scoped and the fallback logic handles the edge cases correctly.

[github-actions]

Assessment: Approve

All three items from the prior review have been addressed. The fix is correct, well-tested, and follows repository conventions.

Verification Details

• Prior feedback addressed: Tests properly split into separate functions, assertions specify exact trim point (count + toolUseId), and provider compatibility rationale documented in code comments.
• Algorithm correctness: Traced through the main scenario (8-message tool-heavy conversation) and edge cases (untrimmable history, last-message boundary, mismatched IDs). All paths behave correctly.
• Existing tests unaffected: The untrimmable_history test still raises ContextWindowOverflowException because the mismatched toolUseIds prevent fallback activation, and trim_index starts past the assistant message at index 0.