[provider-anthropic] Support 1h prompt-cache TTL — verified working against the live API, no beta header required

[Joi]

Summary

provider-anthropic hardcodes cache_control: {"type": "ephemeral"} (5-minute TTL) at all three breakpoint sites (__init__.py:2136, :3719, :3745, verified on main 2026-07-20). There is no config to request the 1-hour TTL.

For human-paced interactive sessions, any gap >5 minutes between turns expires the cache and the next call re-writes the FULL context at cache-write rates. Observed: a single 282k-token cache-write event after one thinking pause (session data in the companion loop-streaming issue). With large system prompts (bundles + MCP tool schemas commonly reach 130k+ tokens base), these expiry re-writes dominate cost.

Verified against the live API (2026-07-20)

ttl: "1h" is accepted today with no beta header:

• cache_control: {type: ephemeral, ttl: "1h"} -> HTTP 200
• usage returns a per-TTL breakdown: cache_creation: {ephemeral_5m_input_tokens: 0, ephemeral_1h_input_tokens: 4419}

This also means the comment in _cost.py:131 ("Anthropic's usage object returns a single cache_creation_input_tokens count") is stale — the API now distinguishes tiers, so 1h writes (2x base input) can be cost-tracked correctly.

Suggested change

1. New provider config key cache_ttl: "5m" | "1h" (default "5m", preserving current behavior), applied at all three breakpoint sites.
2. _cost.py: read the cache_creation per-TTL breakdown and price 1h writes at 2x base input.

Economics: 1h writes cost 2x vs 1.25x, but for sessions with several >5min gaps per hour, converting full-context re-writes (1.25x each) into cache reads (0.1x) is a large net win.

Happy to submit the PR — small, config-gated, default-off.

Related

• Companion issue: [loop-streaming] Ephemeral hook injections break prompt-cache prefix continuity — conversation history is re-written (1.25x) on every provider call #336
• Existing PRs fix: resolve extraction data disconnect with dual-write architecture #58 / feat: add tips synthesizer tool and real-world usage guide from learnings #65 on amplifier-module-provider-anthropic cover missing Fable rates in _RATES; the per-TTL cost handling here composes with those.

[Joi]

Branch for this is up, split out from my #336 work so the two can be reviewed independently:

feat/prompt-cache-1h-ttl — branched off current main (99b3df31), 1 commit ahead, 0 behind, no conflicts.

amplifier_module_provider_anthropic/__init__.py |  43 +/-
amplifier_module_provider_anthropic/_cost.py    |  21 +/-
tests/test_prompt_cache_ttl.py                  | 148 +
3 files changed, +206/-6

Contents:

• cache_ttl config key accepting "5m" (default, current behavior) or "1h", with invalid values warned and coerced to "5m"
• a _cache_control() builder that emits bare {"type": "ephemeral"} for the 5-minute tier and adds {"ttl": "1h"} only when opted in — so the default path is byte-identical to today
• _cost.py: prices the 1-hour tier at 2x base input, split from the per-TTL breakdown Anthropic's usage object now returns (cache_creation.ephemeral_5m_input_tokens / ephemeral_1h_input_tokens). Callers that don't pass the split keep the prior all-5-minute pricing, so this is backwards compatible.

18 new tests, all passing. Note there are 3 pre-existing failures in tests/test_tool_repair.py::test_streaming_* on unmodified main (mock incompatible with the pinned anthropic==0.96.0) — unrelated to this branch; details in #336.

This branch deliberately does not touch _apply_message_cache_control — the last-two-message breakpoint change is scoped to #336's branch, so you can take either of these without the other.

No PR opened; happy to file one if useful.

[Joi]

Correction — do not merge this branch. The TTL never reaches the message breakpoint.

I posted feat/prompt-cache-1h-ttl earlier today with "18 new tests, all passing." The tests pass and the feature does not work on the main caching path. Retracting.

_cache_control() is consulted in exactly two places on that branch:

:2177  _format_system_with_cache   -> block["cache_control"] = self._cache_control()
:3780  _apply_tool_cache_control   -> tools[-1]["cache_control"] = self._cache_control()
:3783  _apply_message_cache_control -> still hardcodes bare {"type": "ephemeral"}

So cache_ttl: "1h" applies to the system block and the tool list, and never to conversation history. Anthropic requires ttl inside each individual cache_control definition, so a request whose caching is carried by message history — the common case — silently stays on the 5-minute tier. Worse for the mixed case: system and tools get an hour while the conversation tail expires in five minutes, which is close to the opposite of the intent.

The test names show exactly how this got through:

test_ttl_applied_at_tool_breakpoint
test_ttl_applied_at_system_breakpoint

There is no message-breakpoint test. The suite covers both places the feature works and neither place it doesn't, so "18 passing" was evidence of nothing on this axis. That is my error, not a subtle one.

Two smaller things in the same branch, for whoever picks it up:

• _cost.py:141 still carries the comment "Anthropic's usage object returns a single cache_creation_input_tokens count and does not distinguish TTLs" — directly contradicted by the same branch's own code, which reads cache_creation.ephemeral_5m_input_tokens / ephemeral_1h_input_tokens. Stale comment left in place while the premise it states was being removed.
• The new cache_ttl config key is not documented in the README config section and is not surfaced through get_info() alongside enable_prompt_caching, so it is undiscoverable through the normal configuration surfaces.

The 1-hour TTL itself is real and worth having — the cost-splitting logic in _cost.py looks correct to me. The wiring is incomplete. A fixed version needs _apply_message_cache_control to route through _cache_control() and a test asserting ttl on the message breakpoint specifically.

Related retraction on the #336 branches: #336.