Add dummy toolUse message when its missing due to pagination in session management

[afarntrog]

Description

This pull request improves the robustness of session message history handling by ensuring that orphaned tool use and tool result messages are properly paired, preventing broken conversation states. It introduces a new helper for generating missing tool use content, updates the session manager to handle both types of orphaned messages, and adds comprehensive unit tests for these helpers.

Session message history fixes:

• Updated _fix_broken_tool_use in repository_session_manager.py to handle both orphaned toolUse messages (no toolResult) and orphaned toolResult messages (no toolUse), ensuring valid message history even after pagination or legacy bugs.
• Added use of the new generate_missing_tool_use_content helper to retroactively insert dummy toolUse messages when needed.

Tool helper enhancements:

• Added generate_missing_tool_use_content to _tool_helpers.py, which generates dummy toolUse content blocks for orphaned toolResult messages.

Testing improvements:

• Added test_tool_helpers.py with thorough tests for both generate_missing_tool_result_content and the new generate_missing_tool_use_content, covering single, multiple, empty, and realistic ID scenarios.

Related Issues

#1272

Documentation PR

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.

[codecov]

Codecov Report

❌ Patch coverage is 45.45455% with 6 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/strands/session/repository_session_manager.py	33.33%	5 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!