fix(provider): prompt-cache breakpoints — double rolling tail + tool-definition marker

[wqymi]

Summary

Fixes the low prompt-cache hit rate by correcting where message-level cache breakpoints land, and adds the missing tool-definition breakpoint. Cross-checked against cc-haha source, openclacky's apply_message_caching, upstream opencode PR #26786 (packages/llm/src/cache-policy.ts), and Anthropic's official prompt-caching docs.

Commits (cache breakpoint work):

1. pin prompt-cache breakpoints to rolling head — drop the drifting midpoint + before-last-user (by-index) markers that never tracked the request tail.
2. double-marker rolling tail + tool-definition cache breakpoint — replace the single tail marker with a double rolling tail, and add a tool-definition breakpoint.
3. skip assistant turns... then revert(provider): drop role-based skip — net no role filtering; the double-tail selects the last two messages by position.

Why the message-level change

Anthropic prompt caching is longest-common-prefix based with a backward lookback window (~20 blocks) from each breakpoint.

• A single tail marker only hits when a turn appends < 20 content blocks; agentic turns with many tool calls routinely exceed that → full-history miss.
• The decisive win is message removal: on a tool-call retry, Ctrl-C, or the user editing/deleting their latest message, a lone tail marker vanishes with that message — and how much surrounding prefix the provider then evicts depends on the upstream KV-cache implementation. A next-to-last marker is a still-present write the next lookback can land on, bounding the worst case to "recompute the removed message" instead of "recompute the whole history".
• Cost is ~equal to a single marker: the two adjacent breakpoints write roughly the same incremental bytes (split in two), and a cache hit never rewrites.

What changed

Message-level — applyCaching (transform.ts)

• Mark the last two non-system messages (rolling double buffer), by position. Mirrors openclacky's double-marker and cc's skipCacheWrite (which shifts the marker to the next-to-last message for the same reason).
• No role-based filtering: protocol gating already lives in supportsCacheMarkers (plain @ai-sdk/openai / @ai-sdk/openai-compatible never reach applyCaching, mirroring upstream's RESPECTS_INLINE_HINTS whitelist). The providers that do reach it (anthropic, bedrock, openrouter/copilot/alibaba on Claude) all honor message-level markers including on assistant turns.

Tools — new ProviderTransform.tools() (transform.ts + llm.ts)

• Cache hierarchy is tools → system → messages, so marking the last tool caches the whole tool-schema block as a stable prefix. Tools bypass message()'s providerID→SDK-key remap, so the marker is written under the SDK key directly (anthropic cacheControl / bedrock cachePoint) in llm.ts before streamText, after any _noop stub so it lands on the real last tool.

Notes on provider behavior (for reviewers)

• providerOptions is namespaced per provider; a provider reads only its own namespace. For protocols that don't consume cache_control (plain OpenAI), user and assistant markers are equally absent from the payload — there is no assistant-specific "silent drop". openai-compatible cache hits come from the server's implicit prefix caching, independent of our markers.

Verification

• bun test test/provider/transform.test.ts → 155 pass / 0 fail (multi-turn double-tail assertion, content-level provider marks last two by role-agnostic position, + 5 tools-breakpoint cases: anthropic/bedrock shapes, 1h TTL, unsupported providers, empty tools).
• bun typecheck → clean.

Doc

• internal/docs/cache-policy.md documents Fix C (double rolling tail, removal/KV-eviction rationale, protocol gating via supportsCacheMarkers) + Fix D (tools breakpoint). It's gitignored, so not in the diff.