Runtime: add WP_Agent_Tool_Pair_Validator

[lezama]

Summary

Adds WP_Agent_Tool_Pair_Validator — a small runtime utility that detects and prunes orphan tool_call / tool_result envelopes in a message list.

Why

Every tool-aware provider request shape (Anthropic-style tool_use/tool_result blocks, OpenAI-style tool_calls + tool messages) requires each call to be paired with its result. An unpaired transcript is a provider 400 waiting to happen, and there are several ways one can show up even on a substrate that "does the right thing" by default:

• Overflow archiving of a mid-cycle slice (the deterministic archive in WP_Agent_Conversation_Compaction keeps the boundary safe, but a re-archive of older content can split pairs the first pass didn't).
• Manual transcript edits — message deletes, re-ordering, merging two sessions.
• Partial transcript restore from an external store that doesn't preserve pair ordering guarantees.
• Failed tool execution that emits a call but never persisted its matching result (crash / timeout / process kill between persist points).

Pair-aware boundary picking already lives in WP_Agent_Conversation_Compaction::move_boundary_to_safe_index(), but it only protects the cutoff. This class complements it by validating arbitrary message lists, which is the case boundary-picking can't cover.

API

WP_Agent_Tool_Pair_Validator::validate( array \$messages ): array
WP_Agent_Tool_Pair_Validator::is_paired( array \$messages ): bool
WP_Agent_Tool_Pair_Validator::prune( array \$messages ): array
//  -> { messages, removed, events }

• Pairing is FIFO by payload.tool_name, mirroring how providers resolve tool-use IDs positionally when several pending calls share a name.
• prune() emits a tool_pair_validated (clean) or tool_pair_pruned lifecycle event in the same { type, metadata } shape used by the compaction lifecycle, so consumers can forward both through a single event sink.
• No mutations to existing classes. Pure-additive: opt-in helper that consumers can run before dispatch.

Composition

Where	Today	With this PR
Compaction boundary	Safe — preserve_tool_boundaries=true keeps the cutoff between pairs	Unchanged
Mid-region orphans after overflow archive	Possible	prune() recovers a sendable transcript
Imported / restored transcripts	Trust the source	is_paired() gates dispatch; prune() repairs
Tool-execution crash between call persist and result persist	Caller writes a stub result manually	prune() removes the dangling call

Test plan

• php tests/tool-pair-validator-smoke.php — new smoke covering empty, plain, paired, orphan-call, orphan-result, FIFO matching by name, crossed names, prune output + lifecycle events, clean-prune no-op. (33 assertions)
• composer test — full suite green; no regressions in existing compaction / loop / channels smokes.
• Reviewer: confirm the FIFO-by-name matching matches expectations (alternative would be strict positional matching ignoring name — see PR comment if you'd prefer that).

🤖 Generated with Claude Code