feat(manage_messages): add conversation history management tool

[cagataycali]

Summary

Add manage_messages tool for direct manipulation of agent.messages with turn-aware operations.

Features

• list: View conversation by turns or filtered by role
• list_tools: View all tool calls with IDs for granular management
• stats: Get conversation statistics
• export/import: Persist and restore conversations
• drop: Remove complete turns safely
• drop_tools: Remove specific tool calls by ID or name
• compact: Strip toolUse/toolResult from turns (keep text content)
• clear: Reset conversation history

Key Highlights

• Turn-aware operations that maintain message integrity
• Preserves active turn during all operations (no orphaned toolUse/toolResult)
• Preserves thinking/redacted_thinking blocks (Bedrock requirement)
• Fixes incomplete tool cycles on import with synthetic results
• Configurable summary length via STRANDS_MESSAGE_SUMMARY_LEN env var
• 99% test coverage

Usage Examples

from strands import Agent
from strands_tools import manage_messages

agent = Agent(tools=[manage_messages])

# View conversation
agent.tool.manage_messages(action="list")
agent.tool.manage_messages(action="list", role="user")

# View tool calls
agent.tool.manage_messages(action="list_tools")

# Get statistics
agent.tool.manage_messages(action="stats")

# Export/import for persistence
agent.tool.manage_messages(action="export", path="/tmp/conversation.json")
agent.tool.manage_messages(action="import", path="/tmp/conversation.json")

# Drop turns to manage context window
agent.tool.manage_messages(action="drop", turns="0,2,5")
agent.tool.manage_messages(action="drop", start=0, end=5)

# Drop specific tool calls
agent.tool.manage_messages(action="drop_tools", tool_ids="tooluse_abc123")
agent.tool.manage_messages(action="drop_tools", tool_name="shell")

# Compact turns (strip tool blocks, keep text)
agent.tool.manage_messages(action="compact")

# Clear all messages
agent.tool.manage_messages(action="clear")

Testing

• Added comprehensive test suite with 99% coverage
• Tests cover all actions, edge cases, and error handling
• Tests for thinking block preservation (Bedrock compatibility)

Checklist

• Code follows project style guidelines
• Tests pass locally
• Documentation included in docstrings
• No breaking changes