Skip to content

Latest commit

 

History

History
96 lines (67 loc) · 18.6 KB

SUPPORTED_PROVIDERS.md

File metadata and controls

96 lines (67 loc) · 18.6 KB

Supported providers and endpoints

Endpoints

The plugin handles three wire formats: the Anthropic Messages API (POST …/messages), OpenAI Chat Completions (POST …/chat/completions) and the OpenAI Responses API (POST …/responses, used by OpenCode's native openai provider). On every wire it needs to know which cache profile a model belongs to, except for the two Anthropic provider IDs (anthropic, omniroute-anthropic), which are always Claude:

Claude (anthropic) GPT-5.6+ (openai) Everything else (implicit)
Cache control it rewrites cache_control breakpoints prompt_cache_breakpoint on text parts none
TTL by mode 5m / 1h / hybrid 30m (automatic) / 12h / 12h breakpoint on the prefix with the automatic 30m tail none
Breakpoint injection when OpenCode sent none yes (your prompts and compaction, not pings or titles) only the 12h breakpoint for 1h / hybrid no
One-off calls (titles and other one-off generate calls) unchanged sent with prompt_cache_options: { mode: "explicit" } and no breakpoints, so they write nothing to the cache unchanged
x-cache-ttl sentinel header stripped yes yes yes
Cache usage observed (sidebar cached row) yes yes yes
Keepalive pings yes (5m, 1h; hybrid follows its 5m tail) yes (30m, 12h; hybrid follows its 30m tail) never

The Claude column applies on the Anthropic Messages and Chat Completions wires, for any provider ID once the model is classified as Claude; a Claude model on the Responses API is only observed, like an implicit one. Claude models cache only where a request marks a breakpoint. OpenCode's openrouter provider marks them for anthropic/* models, but its openai-compatible provider marks none, so the plugin adds the same three (the last tool, the system prompt, the last message) when the request has no cache_control at all. Other models, such as DeepSeek's, cache on the provider's side with no breakpoints to rewrite. The plugin only reads the usage in their responses.

What the plugin sends to GPT-5.6+

Mode Chat Completions Responses
5m nothing (automatic 30m cache) nothing (automatic 30m cache)
1h prompt_cache_breakpoint: { mode: "explicit", ttl: "12h" } on the last text part of the last user, system, developer or tool message the same breakpoint on the last input_text part of a user or system message, or of a trailing tool output (function_call_output, whose string output is turned into an input_text part first), walking back past tool calls and assistant output
hybrid the 12h breakpoint on the last text part of the leading system messages; the tail keeps the automatic 30m cache the same breakpoint on the first input item, whatever its role: instructions is a plain string that can't carry one, and the prefix up to that item (instructions, tools, the first message) is the same every turn
titles and other one-off generate calls prompt_cache_options: { mode: "explicit" }, no breakpoints the same

The plugin never sends a request-level prompt_cache_options.ttl. It is ignored on Chat Completions and OpenRouter rejects it with a 400 on Responses unless mode is "explicit", and explicit mode on a normal turn would disable the automatic cache for the message tail. The 12h lifetime is always a ttl on the breakpoint itself. Pings are never changed beyond aligning their messages with the session's last request.

OpenAI's usage reports how many tokens were read and written but not the lifetime, so the sidebar shows ttl 30m (requested) or ttl 12h (requested).

Older models such as gpt-5 answer 400 to prompt_cache_options and prompt_cache_breakpoint, so the plugin never sends them. A model counts as GPT-5.6+ only when its name matches (gpt-5.6 and up, gpt-6 and up) or when you map it yourself with "openai" in cacheProfiles.

On the Messages wire, requests to the anthropic and omniroute-anthropic providers are always Claude and skip the list below. Any other provider ID on any wire goes through it. Examples of Anthropic-compatible endpoints under another provider ID:

Endpoint, model Profile Result
Claude model on a proxy's /messages (name contains claude, or starts with anthropic/) anthropic The session's TTL mode and the beta header are applied, and keepalive pings
DeepSeek, Kimi, MiniMax or GLM on their /messages endpoint, or OpenRouter /api/v1/messages with a non-Claude model implicit Observed only: nothing is rewritten and no pings are sent
A Claude alias without "claude" in its name (auto/fast) implicit until a response or a cacheProfiles entry says otherwise Learned from the model the latest response reported

A model counts as Claude or GPT-5.6+, in this order:

  1. Your cacheProfiles patterns (see Settings): "anthropic", "openai" or "implicit". On the Messages wire (/messages) an "openai" entry has no effect: the OpenAI profile doesn't apply to that wire, so the model falls back to implicit (observed only).
  2. Its name: the OpenCode model ID or the model in the request body contains claude, or has an anthropic/ prefix (as in openrouter/anthropic/…) for Claude; matches the GPT-5.6+ pattern above for OpenAI.
  3. What the latest response said it ran on, for Claude only: the response's model or provider field names Anthropic or Claude (on the Messages wire, the model the response reports). This is how an alias such as auto/opus-5 gets picked up. The result applies from the next request and is remembered across restarts, so a Claude alias is unmanaged for its first turn only. A router alias that switches models runs one turn behind, and on the Messages wire a request it rejects (status 400 or 422) drops the learned entry; rate-limit and server errors keep it. A response naming a GPT-5.6+ model never makes an alias openai: a router alias can send its next turn to an older model, which answers the OpenAI cache fields with a 400. Map an alias that always lands on GPT-5.6+ yourself with "openai" in cacheProfiles, for example "auto/coding": "openai".

Anything else is treated as implicit. A -1h variant on an implicit model has its x-cache-ttl header stripped and nothing else changed.

On Chat Completions, Claude requests in 1h and hybrid carry the same anthropic-beta: extended-cache-ttl-2025-04-11 header as on the Anthropic wire. OpenRouter adds it itself, but some proxies need it before they honour the 1h TTL. GPT requests never get that header. The OpenAI usage format doesn't say which TTL the provider granted, so the sidebar shows ttl 1h (requested) for Claude there, and 30m or 12h for GPT.

OmniRoute and other proxies

OmniRoute forwards prompt_cache_options but currently drops prompt_cache_breakpoint. Through it, caching turned off on one-off calls works, while the 12h lifetime (1h and hybrid modes) does not reach OpenAI yet: the request is expected to be billed as the automatic 30m cache (observed in the probe, not measured for every route). This is fixed upstream in OmniRoute PR #18255 (issue #18254, merged 2026-10-27) but not yet in a release (the latest is v3.8.52); until a release includes it, reach GPT-5.6+ through OpenRouter or OpenAI directly if you want 12h. In 1h keepalive still pings on the 12h schedule, so on OmniRoute those pings are expected to arrive after the 30m cache is gone and miss (expected, not measured). Use 5m for GPT sessions on such a proxy until a release includes the fix.

Example provider configs with -1h variants:

Claude Agent

The claude-agent provider runs the claude CLI as a subprocess, so its requests skip OpenCode's HTTP layer and the plugin's hooks never fire. The plugin can't rewrite these requests, change their TTL or ping them, and /cache-manager has no effect on them.

The sidebar reads the session's model and token counts from OpenCode instead. Those counts have no TTL split, so the ttl row is a fixed 1h (detected): it comes from the CLI's own usage, which reported only 1h cache writes when this was checked, and isn't read per session. If the CLI changes its TTL, the row won't follow.

How each provider caches

Providers change their caching often. This table reflects their documentation as of October 2026; check the sources below for the current rules.

Provider How it caches Cache lifetime Cache writes cost This plugin
Anthropic (Claude) Explicit cache_control breakpoints (up to 4), or one top-level cache_control 5m or 1h, chosen per breakpoint 1.25x input (5m), 2x input (1h) Managed: TTL, breakpoints, keepalive
OpenAI, GPT-5.6 and later Automatic by default. Optional explicit prompt_cache_breakpoint on text blocks (with its own ttl), and prompt_cache_options: { mode } on the request At least 30m (default) or 12h 1.25x input (30m), 2.5x input (12h), also when caching is automatic Managed: 12h breakpoints, caching off for one-off calls, keepalive
OpenAI, before GPT-5.6 Automatic. prompt_cache_key helps route related requests to the same cache prompt_cache_retention: in_memory (about 5 to 10 minutes idle, up to 1 hour) or 24h Free Observed only
Alibaba (Qwen, and some DeepSeek models on OpenRouter) Explicit cache_control breakpoints, same syntax as Anthropic 5m 1.25x input Observed only. Can be opted in with cacheProfiles ("anthropic"), but the plugin then also applies Claude's TTL handling
Google Gemini 2.5 and later Automatic. On OpenRouter, a cache_control breakpoint also works, and only the last one is used Automatic: 3 to 5 minutes on average. Breakpoint: 5m, not extended by reads Free (automatic). Input price plus 5 minutes of storage (breakpoint) Observed only
DeepSeek Automatic, on disk Cleared when unused, usually within a few hours to a few days Same as input Observed only
Grok, Moonshot, Groq, Z.AI Automatic Not documented Free Observed only

A few details that matter for long agent sessions:

  • OpenAI GPT-5.6 and later bill every cache write, even with automatic caching. A one-off prompt of 1,024 tokens or more therefore costs more with caching on. Setting prompt_cache_options.mode to "explicit" with no breakpoints turns caching off for that request. A request-level prompt_cache_options.ttl is ignored on Chat Completions and rejected on Responses through OpenRouter (it requires mode: "explicit", which turns off the automatic cache for the tail); the 12h lifetime works through a ttl on prompt_cache_breakpoint, which is what the plugin sends. Older models such as gpt-5 answer 400.
  • OpenRouter keeps a session on the same provider (sticky routing) while caching pays off, for up to 10 idle minutes. It uses the session_id body field or x-session-id header as the key when present, which OpenCode sends.

Sources