feat: add built-in repair_orphaned_tool_parts history processor

[anmolg1997]

Summary

• Adds pydantic_ai.history_processors.repair_orphaned_tool_parts, a ready-to-use history processor that removes structurally invalid tool call/return pairs from message history
• Prevents 400 errors from providers (especially Anthropic) that reject orphaned tool references after streaming timeouts, deferred tool drops, or history trimming
• Ships with 11 unit tests covering all edge cases

Problem

Multi-turn conversations with tools can accumulate broken message history: tool calls without matching results, or results referencing calls that don't exist. This is structurally invalid (a tool call without a result before the next turn doesn't make sense), and providers rightfully reject it. Anthropic is the strictest about enforcement (you get a 400), but even providers that silently tolerate it produce worse results from garbled history.

Common causes:

• Streaming response with ToolCallPart gets persisted, but agent times out before ToolReturnPart arrives
• Deferred tools get their results dropped or arrive with a different tool_call_id
• History processors (trimming, summarization) remove one side of a pair

Approach

Two-pass repair:

1. Orphaned returns/retries: ToolReturnPart or RetryPromptPart (with tool_name) whose tool_call_id has no matching ToolCallPart → removed
2. Orphaned calls: ToolCallPart whose tool_call_id has no matching ToolReturnPart or RetryPromptPart → removed

Output-validation RetryPromptParts (tool_name=None) are preserved since they're not tied to tool calls.

Empty messages (all parts removed) are dropped entirely.

Usage

from pydantic_ai import Agent
from pydantic_ai.history_processors import repair_orphaned_tool_parts

agent = Agent('openai:gpt-4o', history_processors=[repair_orphaned_tool_parts])

Changes

File	Change
pydantic_ai_slim/pydantic_ai/history_processors.py	New module with repair_orphaned_tool_parts function
tests/test_history_processors.py	11 tests covering matched pairs, orphaned calls, orphaned returns, mixed, empty history, text-only, output validation retries

Test plan

• 11/11 new tests passing
• No existing tests affected
• Handles edge cases: empty history, text-only conversations, output validation retries (tool_name=None), parallel tool calls, mixed orphans

Closes #4728

[devin-ai-integration]

Devin Review found 2 potential issues.

View 4 additional findings in Devin Review.

[adtyavrdhn]

Hey @anmolg1997

Thanks for this though with the changes in place we are aiming to introduce this as a capability in the harness: pydantic/pydantic-ai-harness#184

Feel free to discuss this with Douwe there :)

Closing this for now.

[anmolg1997]

Thanks @adtyavrdhn and @DouweM, makes sense to land this as a harness capability (ToolOrphanRepair) rather than in core. The harness is a better home for opt-in message sanitization.

For anyone finding this later: pydantic/pydantic-ai-harness#184 is the canonical impl. Same orphaning scenarios (orphaned calls -> synthetic returns, orphaned returns/retries -> strip), plus edge cases I hadn't covered (trailing responses, empty requests after repair, built-in tool parts).

Closing in favor of the harness PR. Happy to help review there if useful.