fix(ai): layer prompt cache breakpoints - #38725

What

Use Anthropic and Bedrock's four cache breakpoints as layered reusable prefixes:

1. last tool definition
2. first system block
3. last system block, when distinct
4. rolling final conversation message

This preserves tool-prefix reuse, base-agent reuse across matching sessions, full-system reuse within a project, and rolling reuse through long tool loops.

Before / After

Before

cache: "auto" marked the last tool, only the last system block, and the latest user message. The missing first-system boundary prevented reuse of the stable base agent independently from project instructions. During long tool loops, the fixed user-message marker eventually fell beyond Anthropic and Bedrock's 20-block lookback, forcing the large prefix to be rewritten.

After

The first and distinct last system blocks expose both stable system layers. The conversation marker advances to the final message on every request, keeping the previous marker near the tail as tool results accumulate. A single system block is marked once, and existing manual hints count against the shared four-marker budget before automatic placement.

The recorded 11-call regression reads 12,288 cached tokens on the appended request and writes only 19 new tokens.

How

• packages/ai/src/cache-policy.ts adds first/last system placement, preserves the rolling one-message tail, and budgets automatic markers after counting manual hints.
• packages/ai/src/schema/options.ts and packages/ai/README.md document the four reusable prefix layers and deterministic tool-order requirement.
• packages/ai/test/cache-policy.test.ts verifies Anthropic and Bedrock wire placement, one-system deduplication, direct policy-level budgeting, manual-hint preservation, and idempotent reapplication.
• packages/ai/test/provider/anthropic-messages-cache.recorded.test.ts accepts either a cold cache write or a warm cache read on the first request while requiring the appended request to reuse the established prefix.
• packages/ai/test/provider/bedrock-converse.test.ts opts an unrelated media-lowering assertion out of default cache placement.

Scope

This PR changes only the Anthropic/Bedrock automatic cache-breakpoint policy. Tool definitions are already deterministically sorted by Core's tool registry; this PR does not change tool registration or ordering. It deliberately excludes GPT-Sol control coverage, request-prefix diagnostics, and TUI cache-reuse reporting.

Testing

• bun run test in packages/ai: 446 passed, 28 skipped, 0 failed
• focused cache policy and recorded replay: 16 passed, 0 failed
• bun typecheck in packages/ai: passed
• pre-push bun turbo typecheck --concurrency=3: 33 tasks passed
• git diff --check: passed
• live Anthropic recording: first request wrote 12,288 cache tokens; appended request read 12,288 and wrote 19

No cassette re-recording was needed: the recorded long-tool request has one system block, so first/last system deduplication leaves its wire body unchanged.

Flow

flowchart LR
  T[Stable ordered tools] -->|breakpoint 1| A[Base agent system]
  A -->|breakpoint 2| P[Project system context]
  P -->|breakpoint 3| C[Conversation]
  C -->|rolling breakpoint 4| N[Next tool-loop request]