perf(ai): anthropic prompt cache + cache token accounting

[ABB65]

Summary

System prompt + tools were rebuilt and re-sent uncached on every request. Brain content index alone can grow past 10K tokens, so a typical 10-turn session was paying for the same prefix ten times. Anthropic's prompt cache cuts that prefix to ~10% of base input price when reused within 5 minutes; this PR wires the markers up.

Why this PR needed real surgery

The naive shape — wrap the existing buildSystemPrompt(...) string in a cached block — would have miscached because:

• buildSchemaSection embedded the active-model marker (### ▶ Posts vs ### Posts) keyed on uiContext.activeModelId.
• buildRulesSection injected the out_of_scope rule based on intent.

Cache markers placed over content that varies per request bust the prefix and pay the 1.25x creation penalty on every turn — net negative. So the prompt builder is actually split:

• buildStaticBody — role, architecture, config, schema (no active-model marker), relations, vocab, permissions, base rules, custom instructions
• buildDynamicBody — UI context (active-model annotation here), inferred intent, project state, intent-specific rules
• buildContentIndex — already separate (brain cache); its own cached block

buildSystemPromptBlocks(...) returns the three pieces; toSystemBlocks(...) materializes them as AISystemBlock[] with cache_control on the static body + content index (2 of 4 breakpoints). Last AITool gets cache_control too (3rd breakpoint, ~95% hit rate within a session).

Provider surface

// ai.ts
system: string | AISystemBlock[]         // string callers wrap to single uncached block
AISystemBlock.cacheControl?: { type: 'ephemeral' }
AITool.cacheControl?: { type: 'ephemeral' }
AIUsage: { inputTokens, outputTokens, cacheCreationInputTokens, cacheReadInputTokens }

Anthropic provider captures all three input buckets from message_start / message_delta and yields normalized message_end once. Engine accumulates across the tool loop and forwards on done.

Migration 008 — additive _v2 RPCs

Per review feedback, RPCs ship as _v2 rather than mutating signatures in place. Mid-deploy schema-and-app skew on Supabase is a real failure mode; _v1 stays registered, unused, and can be dropped in a future cleanup.

ALTER TABLE agent_usage / api_message_usage / messages
  ADD COLUMN cache_creation_input_tokens
  ADD COLUMN cache_read_input_tokens

CREATE FUNCTION increment_agent_usage_tokens_v2(... + 2 cache params)
CREATE FUNCTION increment_api_usage_tokens_v2(... + 2 cache params)

saveChatResult / saveApiChatResult switched to object-form args (positional list grew unwieldy).

Business semantic — UNCHANGED

Cache is a Contentrain-side cost win, not a customer-facing quota expansion:

• Plan quotas stay message-based (ai.messages_per_month, api.messages_per_month).
• cache_read_input_tokens do NOT earn extra messages.
• input_tokens semantic unchanged (= non-cached input only).
• Existing dashboard queries summing input_tokens stay correct.

Test plan

• pnpm typecheck clean
• pnpm lint — 0 errors
• pnpm test — 618 passed (608 + 10 new)
  • 3 new anthropic-ai: three-bucket stream capture, system-block + tools cache_control mapping
  • 6 new agent-system-prompt-cache: static body byte-identical across UI/intent/state changes (the actual cache-hit invariant), contentIndex separation, toSystemBlocks ≤ 2 cached blocks
  • 1 new db: cache tokens propagate through saveChatResult to agent_usage + messages row

Out of scope (separate PRs)

• Message-level cache breakpoint — history mutates per turn, needs prefix-stability analysis.
• 1-hour cache TTL beta — defer until we observe hit rates from this PR.
• Cache hit-rate dashboard UI — accounting columns ship here; UI is a separate concern.
• History budget increase — once we have observed hit rates, the conservative Sonnet/Opus values from PR refactor(chat): shared history builder with model/plan/source-aware budgets #52 can grow safely.

Sources

• Models overview
• Pricing
• Prompt caching