fix(providers): drop leading non-user turns before provider call

[dmnkhorvath]

Summary

Closes #6302.

ZeroClaw constructed conversation histories that strict providers (Google Gemini) reject with HTTP 400 (Please ensure that function call turn comes immediately after a user turn or after a function response turn.). Permissive providers (Anthropic, GLM) silently tolerated the malformed shape. PR #960 had patched this for the Telegram channel runtime path; CLI / gateway / agent-loop paths were untouched.

This PR is two layered fixes, both required because investigation revealed the bug had two distinct causes:

1. zeroclaw-providers/src/history_sanitizer.rs — provider-edge cleanup

A new provider-agnostic enforce_leading_user_turn pass, called from multimodal::prepare_messages_for_provider. Drops the contiguous sequence of leading non-user, non-system messages immediately before the LLM call. Conservative: if no user turn exists anywhere, leaves messages alone so the upstream provider error surfaces. Emits a tracing::warn! when it acts so the symptom is observable.

2. zeroclaw-runtime/src/agent/history_pruner.rs — root-cause prevention

After commit 1 was deployed, captured Gemini requests showed the bug had a deeper layer: on later iterations of the agent loop, the messages list contained no user turn at all — only assistant.tool_calls and tool responses. Sanitizing that to drop everything would just produce an empty-contents error.

Root cause: protected_indices() only protected system messages and the last keep_recent items. When a multi-round tool-using conversation grew past max_tokens, phase-2 budget enforcement happily dropped the original user message because it had fallen outside the keep_recent window. remove_orphaned_tool_messages then cleaned dangling tool rows but left the assistant.tool_calls row in place (its only requirement was a preceding assistant, not a preceding user). The result was a history beginning with assistant.tool_calls — universally invalid for Gemini.

Two changes:

• Prevention — protected_indices now also protects the first user turn after the leading system block, so pruning can never strip the canonical conversation prefix.
• Defense in depth — remove_orphaned_tool_messages gains a third pass that drops a leading assistant/tool block lacking a preceding user. Existing persisted sessions that already contain the malformed shape get auto-healed on next load. Conservative when no user turn exists.

Five existing pruner tests codified the previous (Gemini-invalid) shape of remove_orphaned_tool_messages keeping leading orphan assistants. They were updated to inject a leading user message — preserves their original orphan-removal intent without depending on the now-fixed broken shape.

Out of scope

Tool-call ↔ tool-response pairing (orphan tool messages without preceding assistant.tool_calls, empty tool_calls: [] arrays) — tracked in #6298.

Risk

Medium. Touches the hot path of every LLM call but behavior is strictly subtractive — only drops messages that would otherwise produce a 400 on Gemini and are uninterpretable on every other provider. No new config flags. No system messages affected.

Validation

Static:

• 12 new unit tests across both crates (8 in history_sanitizer, 4 in history_pruner).
• All 1611 zeroclaw-runtime lib tests pass.
• All 791 zeroclaw-providers lib tests pass.
• cargo fmt --all -- --check clean.
• cargo clippy -p zeroclaw-runtime -p zeroclaw-providers --all-targets -- -D warnings clean.

End-to-end (LiteLLM-routed Gemini, on actual broken-history session that previously 400'd):

$ zeroclaw agent -m "respond with the literal text OK"
... Preemptive context trim: estimated tokens exceed budget estimated=96492 budget=32000 iteration=1
... WARN history_pruner: Removed 5 leading non-user turn(s) from history (#6302) count=5
OK   ← previously: Error: All providers/models failed. ... GeminiException BadRequestError 400

$ zeroclaw agent -m "be creative and do something based on the toolset you have, ask for permission when needed, go!"
I tried to build a custom terminal UI and write a fractal generator to the workspace, but it looks like those actions were blocked.
I've got a whole arsenal here: I can fetch the weather in Svalbard, aggregate the latest world news, check crypto balances, scrape web pages, or generate a custom PDF report.
What kind of trouble should we get into today?

Both prompts succeed; auto-heal warnings fire on the first iteration and the agent loop completes normally afterward.

Test plan

• CI green
• Manual: zeroclaw agent -m "..." against LiteLLM-routed Gemini with poisoned session history — 400 cleared, sanitizer + pruner warnings observable in logs.

🤖 Generated with Claude Code