Remove toolUse message when its missing due to pagination in session manager (strands-agents#1274)

* Remove toolUse message when its missing due to pagination in session manager

Author: afarntrog

src/strands/session/repository_session_manager.py

@@ -165,12 +165,35 @@ def initialize(self, agent: "Agent", **kwargs: Any) -> None:
             agent.messages = self._fix_broken_tool_use(agent.messages)
 
     def _fix_broken_tool_use(self, messages: list[Message]) -> list[Message]:
-        """Add tool_result after orphaned tool_use messages.
+        """Fix broken tool use/result pairs in message history.
 
-        Before 1.15.0, strands had a bug where they persisted sessions with a potentially broken messages array.
-        This method retroactively fixes that issue by adding a tool_result outside of session management. After 1.15.0,
-        this bug is no longer present.
+        This method handles two issues:
+        1. Orphaned toolUse messages without corresponding toolResult.
+           Before 1.15.0, strands had a bug where they persisted sessions with a potentially broken messages array.
+           This method retroactively fixes that issue by adding a tool_result outside of session management.
+           After 1.15.0, this bug is no longer present.
+        2. Orphaned toolResult messages without corresponding toolUse (e.g., when pagination truncates messages)
+
+        Args:
+            messages: The list of messages to fix
+            agent_id: The agent ID for fetching previous messages
+            removed_message_count: Number of messages removed by the conversation manager
+
+        Returns:
+            Fixed list of messages with proper tool use/result pairs
         """
+        # First, check if the oldest message has orphaned toolResult (no preceding toolUse) and remove it.
+        if messages:
+            first_message = messages[0]
+            if first_message["role"] == "user" and any("toolResult" in content for content in first_message["content"]):
+                logger.warning(
+                    "Session message history starts with orphaned toolResult with no preceding toolUse. "
+                    "This typically happens when messages are truncated due to pagination limits. "
+                    "Removing orphaned toolResult message to maintain valid conversation structure."
+                )
+                messages.pop(0)
+
+        # Then check for orphaned toolUse messages
         for index, message in enumerate(messages):
             # Check all but the latest message in the messages array
             # The latest message being orphaned is handled in the agent class
@@ -188,7 +211,7 @@ def _fix_broken_tool_use(self, messages: list[Message]) -> list[Message]:
                     ]
 
                     missing_tool_use_ids = list(set(tool_use_ids) - set(tool_result_ids))
-                    # If there area missing tool use ids, that means the messages history is broken
+                    # If there are missing tool use ids, that means the messages history is broken
                     if missing_tool_use_ids:
                         logger.warning(
                             "Session message history has an orphaned toolUse with no toolResult. "

tests/strands/session/test_repository_session_manager.py

@@ -552,3 +552,46 @@ def test_bidi_agent_messages_with_offset_zero(session_manager, mock_bidi_agent):
 
     # Verify all messages restored (offset=0, no removed_message_count)
     assert len(mock_bidi_agent.messages) == 5
+
+
+def test_fix_broken_tool_use_removes_orphaned_tool_result_at_start(session_manager):
+    """Test that orphaned toolResult at the start of conversation is removed."""
+    messages = [
+        {
+            "role": "user",
+            "content": [
+                {
+                    "toolResult": {
+                        "toolUseId": "orphaned-result-123",
+                        "status": "success",
+                        "content": [{"text": "Seattle, USA"}],
+                    }
+                }
+            ],
+        },
+        {"role": "assistant", "content": [{"text": "You live in Seattle, USA."}]},
+        {"role": "user", "content": [{"text": "I like pizza"}]},
+    ]
+
+    fixed_messages = session_manager._fix_broken_tool_use(messages)
+
+    # Should remove the first message with orphaned toolResult
+    assert len(fixed_messages) == 2
+    assert fixed_messages[0]["role"] == "assistant"
+    assert fixed_messages[0]["content"][0]["text"] == "You live in Seattle, USA."
+    assert fixed_messages[1]["role"] == "user"
+    assert fixed_messages[1]["content"][0]["text"] == "I like pizza"
+
+
+def test_fix_broken_tool_use_does_not_affect_normal_conversations(session_manager):
+    """Test that normal conversations without orphaned toolResults are unaffected."""
+    messages = [
+        {"role": "user", "content": [{"text": "Hello"}]},
+        {"role": "assistant", "content": [{"text": "Hi there!"}]},
+        {"role": "user", "content": [{"text": "How are you?"}]},
+    ]
+
+    fixed_messages = session_manager._fix_broken_tool_use(messages)
+
+    # Should remain unchanged
+    assert fixed_messages == messages

tests/strands/tools/test_tool_helpers.py

@@ -0,0 +1,34 @@
+"""Tests for tool helper functions."""
+
+from strands.tools._tool_helpers import generate_missing_tool_result_content
+
+
+class TestGenerateMissingToolResultContent:
+    """Tests for generate_missing_tool_result_content function."""
+
+    def test_single_tool_use_id(self):
+        """Test generating content for a single tool use ID."""
+        tool_use_ids = ["tool_123"]
+        result = generate_missing_tool_result_content(tool_use_ids)
+
+        assert len(result) == 1
+        assert "toolResult" in result[0]
+        assert result[0]["toolResult"]["toolUseId"] == "tool_123"
+        assert result[0]["toolResult"]["status"] == "error"
+        assert result[0]["toolResult"]["content"] == [{"text": "Tool was interrupted."}]
+
+    def test_multiple_tool_use_ids(self):
+        """Test generating content for multiple tool use IDs."""
+        tool_use_ids = ["tool_123", "tool_456", "tool_789"]
+        result = generate_missing_tool_result_content(tool_use_ids)
+
+        assert len(result) == 3
+        for i, tool_id in enumerate(tool_use_ids):
+            assert "toolResult" in result[i]
+            assert result[i]["toolResult"]["toolUseId"] == tool_id
+            assert result[i]["toolResult"]["status"] == "error"
+
+    def test_empty_list(self):
+        """Test generating content for empty list."""
+        result = generate_missing_tool_result_content([])
+        assert result == []