Add keep_last_n_items filter to handoff_filters module

[Rehan-Ul-Haq]

Description

This PR adds a new filter function keep_last_n_items to the handoff_filters module. This function allows users to keep only the most recent n items in the input history of a HandoffInputData object, with an option to remove tool messages before truncating.

Functionality

• Keeps the last n items from the input history
• Option to first remove tool messages (function/tool calls) before truncating
• Maintains behavior consistent with existing filters
• Properly handles string history inputs
• Includes comprehensive error handling for invalid inputs

Changes Made

• Added keep_last_n_items function to src/agents/extensions/handoff_filters.py
• Added tests for the new function to tests/test_extension_filters.py

Use Cases

This filter is useful for:

• Limiting context size when sending data between agents
• Focusing on the most recent conversation history
• Reducing token usage by eliminating older messages
• Maintaining a sliding window of conversation context

Testing

All tests pass, including dedicated tests for:

• Basic functionality
• Handling tool messages
• Edge cases like empty histories and string-based histories
• Error handling for invalid inputs