Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

Studio: prompt caching for OpenRouter (#12264)

Long Yixing5913ef1b392b
diff --git a/studio/backend/core/inference/external_provider.py b/studio/backend/core/inference/external_provider.py
index f34cc5c5283..717049e0ff1 100644
--- a/studio/backend/core/inference/external_provider.py
+++ b/studio/backend/core/inference/external_provider.py
@@ -138,6 +138,18 @@ def _append_provider_path(base_url: str, endpoint: str) -> str:
return urlunsplit((parts.scheme, parts.netloc, path, parts.query, parts.fragment))
+def caches_at_the_last_block(
+ provider_type: Optional[str], model: Optional[str], enable_prompt_caching: Optional[bool]
+) -> bool:
+ if enable_prompt_caching is False:
+ return False
+ if provider_type == "anthropic":
+ return True
+ return provider_type == "openrouter" and (model or "").strip().lower().lstrip("~").startswith(
+ "anthropic/"
+ )
+
+
def _is_azure_openai_host(host: str) -> bool:
return host.endswith((".openai.azure.com", ".services.ai.azure.com"))
@@ -1469,6 +1481,7 @@ class ExternalProviderClient:
response_format: Optional[dict[str, Any]] = None,
stream: bool = True,
preserve_thinking: Optional[bool] = None,
+ thread_id: Optional[str] = None,
) -> AsyncGenerator[str, None]:
"""Yield OpenAI-format SSE lines from the external provider. OpenAI-compatible providers
forward lines verbatim; for Anthropic the native Messages API SSE is translated.
@@ -1694,6 +1707,17 @@ class ExternalProviderClient:
elif enable_thinking is True:
body["reasoning"] = {"enabled": True}
+ # Claude caches only behind cache_control; the top-level form advances the breakpoint every turn. Other
+ # families cache automatically and the field is documented for Claude's providers only.
+ if caches_at_the_last_block("openrouter", model, enable_prompt_caching):
+ cache_control = {"type": "ephemeral"}
+ if prompt_cache_ttl == "1h":
+ cache_control["ttl"] = "1h"
+ body["cache_control"] = cache_control
+ # Sticky routing keeps a conversation on the provider that holds its cache.
+ if thread_id:
+ body["session_id"] = str(thread_id)[:256]
+
# OpenRouter web plugin works on every model id including meta-routers (unlike `:online`). Forced-function
# tool_choice suppresses it, matching Gemini/Anthropic.
_or_tool_choice_forced_function = (
diff --git a/studio/backend/models/inference.py b/studio/backend/models/inference.py
index d25c1e15a77..b3ad0ed963f 100644
--- a/studio/backend/models/inference.py
+++ b/studio/backend/models/inference.py
@@ -2649,8 +2649,9 @@ class ChatCompletionRequest(BaseModel):
"informational. On Gemini, pass a string cache resource name such "
"as `cachedContents/abc123` to attach `cachedContent` on the native "
"request (boolean true is a no-op on Gemini because creating the "
- "cache requires a separate POST /cachedContents call). Ignored for "
- "every other provider. Treated as enabled when omitted."
+ "cache requires a separate POST /cachedContents call). On OpenRouter, "
+ "boolean true adds a top-level cache_control for anthropic/ models. "
+ "Ignored for every other provider. Treated as enabled when omitted."
),
)
@@ -2673,14 +2674,15 @@ class ChatCompletionRequest(BaseModel):
prompt_cache_ttl: Optional[str] = Field(
None,
description = (
- "[x-unsloth] Anthropic cache_control TTL. Defaults to the 5-minute "
+ "[x-unsloth] Anthropic cache_control TTL, also used for Claude on "
+ "OpenRouter. Defaults to the 5-minute "
"ephemeral pool when omitted. Pass `1h` to write into the 1-hour "
"pool instead -- 1h writes are billed at 2x base input vs 1.25x "
"for 5m, but reads stay at 0.1x for both, so 1h pays off the "
"moment a single extra read lands more than 5 minutes after the "
"write. Only `5m` and `1h` are forwarded; any other value is "
"silently ignored downstream so a stale frontend can't make the "
- "API 422 on the request. No-op on every non-Anthropic provider."
+ "API 422 on the request. No-op on every other provider."
),
)
compaction_threshold: Optional[int] = Field(
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index dc01bf014bf..d22631c2570 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -3886,7 +3886,11 @@ from core.inference.providers import (
provider_runs_local_tools,
validate_provider_base_url,
)
-from core.inference.external_provider import ExternalProviderClient, _is_openai_family_cloud
+from core.inference.external_provider import (
+ ExternalProviderClient,
+ _is_openai_family_cloud,
+ caches_at_the_last_block,
+)
from core.inference.external_tool_transport import OAICompatTransport
from core.inference.sse_control_frames import (
is_ui_control_sse_line,
@@ -25259,7 +25263,10 @@ async def _proxy_to_external_provider(
request,
include_api_key = run_studio_tool_loop,
provider_type = None if _external_nudge else provider_type,
- thread_id = getattr(payload, "thread_id", None),
+ # a thread's date note would sit on the cache breakpoint and move off it next turn.
+ thread_id = None
+ if caches_at_the_last_block(provider_type, model, payload.enable_prompt_caching)
+ else getattr(payload, "thread_id", None),
)
if _external_nudge:
chat_messages = _append_to_system_message(chat_messages, _external_nudge)
@@ -25304,6 +25311,7 @@ async def _proxy_to_external_provider(
compaction_threshold = payload.compaction_threshold,
fast_mode = payload.fast_mode,
response_format = _extract_response_format(payload),
+ thread_id = payload.thread_id,
)
# A managed runtime that drops a reply still closes with [DONE]; it is cut short, not done.
managed_finish = _TurnFinish()
diff --git a/studio/backend/tests/test_anthropic_cache_ttl.py b/studio/backend/tests/test_anthropic_cache_ttl.py
index d39d0e93842..d2f3806442d 100644
--- a/studio/backend/tests/test_anthropic_cache_ttl.py
+++ b/studio/backend/tests/test_anthropic_cache_ttl.py
@@ -1,12 +1,13 @@
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
-"""Unit tests for prompt_cache_ttl threading on the Anthropic path.
+"""Unit tests for prompt-cache request shaping on the Anthropic and OpenRouter paths.
Anthropic's ``cache_control`` marker takes an optional ``ttl``: default 5m
pool, ``ttl:"1h"`` the 1h pool. These tests pin the outbound body shape:
"1h" puts ``ttl:"1h"`` on both markers; default omits the field; garbage
-values are silently dropped.
+values are silently dropped. OpenRouter carries one top-level marker for
+Claude models and a ``session_id`` that keeps a thread on its cached provider.
"""
import asyncio
@@ -188,3 +189,85 @@ def test_opt_out_skips_cache_control(monkeypatch):
_drive(run())
assert _cache_controls(captured["body"]) == []
+
+
+# ── OpenRouter: top-level cache_control on Claude, sticky session per thread ──
+
+
+def _oai_compat_body(
+ monkeypatch,
+ model,
+ provider_type = "openrouter",
+ **kwargs,
+) -> dict:
+ captured: dict = {}
+
+ def handler(request: httpx.Request) -> httpx.Response:
+ captured["body"] = json.loads(request.content.decode("utf-8"))
+ return httpx.Response(
+ 200,
+ content = b"data: [DONE]\n\n",
+ headers = {"content-type": "text/event-stream"},
+ )
+
+ monkeypatch.setattr(
+ ep_mod,
+ "_http_client",
+ httpx.AsyncClient(transport = httpx.MockTransport(handler)),
+ )
+
+ async def run():
+ client = ExternalProviderClient(
+ provider_type = provider_type,
+ base_url = "https://example.test/v1",
+ api_key = "sk-test",
+ )
+ async for _ in client.stream_chat_completion(
+ messages = [{"role": "user", "content": "hi"}], model = model, **kwargs
+ ):
+ pass
+ await client.close()
+
+ _drive(run())
+ return captured["body"]
+
+
+ "kwargs,expected",
+ [
+ ({}, {"type": "ephemeral"}),
+ (
+ {"enable_prompt_caching": True, "prompt_cache_ttl": "1h"},
+ {"type": "ephemeral", "ttl": "1h"},
+ ),
+ ({"prompt_cache_ttl": "6m"}, {"type": "ephemeral"}),
+ ],
+)
[email protected]("model", ["anthropic/claude-sonnet-4.6", "~anthropic/claude-opus-latest"])
+def test_openrouter_claude_gets_top_level_cache_control(monkeypatch, model, kwargs, expected):
+ assert _oai_compat_body(monkeypatch, model, **kwargs)["cache_control"] == expected
+
+
+ "model,kwargs",
+ [
+ ("anthropic/claude-sonnet-4.6", {"enable_prompt_caching": False, "prompt_cache_ttl": "1h"}),
+ ("deepseek/deepseek-v3.2", {"enable_prompt_caching": True}),
+ ("openrouter/auto", {}),
+ ],
+)
+def test_openrouter_cache_control_skipped_off_claude_or_when_disabled(monkeypatch, model, kwargs):
+ assert "cache_control" not in _oai_compat_body(monkeypatch, model, **kwargs)
+
+
[email protected]("caching", [True, False])
+def test_openrouter_session_id_follows_the_thread(monkeypatch, caching):
+ body = _oai_compat_body(
+ monkeypatch, "deepseek/deepseek-v3.2", thread_id = "t" * 300, enable_prompt_caching = caching
+ )
+ assert body["session_id"] == "t" * 256
+ assert "session_id" not in _oai_compat_body(monkeypatch, "deepseek/deepseek-v3.2")
+ # Strict OpenAI-compatible endpoints 400 on unknown body fields.
+ assert "session_id" not in _oai_compat_body(
+ monkeypatch, "deepseek-chat", "deepseek", thread_id = "t"
+ )
diff --git a/studio/backend/tests/test_external_hosted_tool_passthrough.py b/studio/backend/tests/test_external_hosted_tool_passthrough.py
index 3a105a096d0..8ee0b70dee9 100644
--- a/studio/backend/tests/test_external_hosted_tool_passthrough.py
+++ b/studio/backend/tests/test_external_hosted_tool_passthrough.py
@@ -733,3 +733,59 @@ def test_a_request_without_tools_never_scans_the_skill_roots(monkeypatch):
chunks = _run(inf, _payload(enable_tools = False))
assert FakeExternalClient.last["passthrough"] is not None
assert any("hi" in chunk for chunk in chunks)
+
+
+def test_the_conversation_id_reaches_the_provider_client(monkeypatch):
+ inf = _install(monkeypatch, "openrouter")
+ _run(inf, _payload(enable_tools = False, thread_id = "thread-7"))
+ assert FakeExternalClient.last["passthrough"]["thread_id"] == "thread-7"
+
+ def _loop_raiser(transport, **_):
+ raise LoopEntered(transport._request_kwargs)
+
+ monkeypatch.setattr(inf, "stream_with_studio_tools", _loop_raiser)
+ with pytest.raises(LoopEntered) as excinfo:
+ _run(inf, _payload(enable_tools = True, enabled_tools = ["python"], thread_id = "thread-7"))
+ assert excinfo.value.args[0]["thread_id"] == "thread-7"
+
+
+ "provider_type, model, caching, noted",
+ [
+ ("anthropic", "claude-sonnet-4-6", None, False),
+ ("openrouter", "anthropic/claude-sonnet-4.6", None, False),
+ ("openrouter", "~anthropic/claude-opus-latest", True, False),
+ ("anthropic", "claude-sonnet-4-6", False, True),
+ ("openrouter", "anthropic/claude-sonnet-4.6", False, True),
+ ("openrouter", "deepseek/deepseek-v3.2", None, True),
+ ],
+)
+def test_a_thread_from_yesterday_keeps_the_claude_cache_breakpoint_stable(
+ monkeypatch, provider_type, model, caching, noted
+):
+ from datetime import date
+
+ inf = _install(monkeypatch, provider_type)
+ monkeypatch.setattr(
+ inf, "current_date_prompt_line", lambda **_k: "The current date is 2026-08-16."
+ )
+ monkeypatch.setattr(inf, "conversation_start_date", lambda *_a, **_k: date(2026, 8, 15))
+ monkeypatch.setattr(inf, "_request_has_api_key", lambda _request: False)
+ history = [
+ {"role": "user", "content": "first"},
+ {"role": "assistant", "content": "ok"},
+ {"role": "user", "content": "second"},
+ ]
+ _run(
+ inf,
+ _payload(
+ messages = history,
+ external_model = model,
+ enable_tools = False,
+ thread_id = "thread-7",
+ enable_prompt_caching = caching,
+ ),
+ )
+ sent = FakeExternalClient.last["passthrough"]
+ assert sent["thread_id"] == "thread-7"
+ assert sent["messages"][-1]["content"].startswith("[Current date: ") is noted
diff --git a/studio/frontend/src/components/assistant-ui/message-timing.tsx b/studio/frontend/src/components/assistant-ui/message-timing.tsx
index 9d8b1438c17..307a4d93d81 100644
--- a/studio/frontend/src/components/assistant-ui/message-timing.tsx
+++ b/studio/frontend/src/components/assistant-ui/message-timing.tsx
@@ -55,7 +55,6 @@ export const MessageTiming: FC<{
// contextUsage.cachedTokens from a prior turn.
const cacheHits =
st?.cache_n ?? custom?.contextUsage?.cachedTokens ?? 0;
- // Anthropic-only cache-write count.
const cacheWrites = custom?.contextUsage?.cacheWriteTokens ?? 0;
// DiffusionGemma reports separately-labelled throughput (no prefill, so no "prompt
// speed"), matching the CLI: in-step parallel, effective (canvas*blocks/wall), and
diff --git a/studio/frontend/src/features/chat/api/chat-adapter.ts b/studio/frontend/src/features/chat/api/chat-adapter.ts
index abd3dfa9873..d4b43dea47e 100644
--- a/studio/frontend/src/features/chat/api/chat-adapter.ts
+++ b/studio/frontend/src/features/chat/api/chat-adapter.ts
@@ -320,6 +320,7 @@ import {
generationIsSettled,
releaseLiveGenerationRun,
requestParsesThinkTags,
+ usageCacheWriteTokens,
} from "../utils/chat-generation-recovery";
import {
generateAudio,
@@ -421,9 +422,10 @@ interface ServerUsage {
prompt_tokens: number;
completion_tokens: number;
total_tokens: number;
- // External prompt-cache fields (external_provider.py); cache_creation is Anthropic-only.
+ // cache_creation is Anthropic's cache-write count, cache_write_tokens OpenRouter's.
prompt_tokens_details?: {
cached_tokens?: number;
+ cache_write_tokens?: number;
};
cache_creation_input_tokens?: number;
cache_read_input_tokens?: number;
@@ -6302,9 +6304,6 @@ export function createOpenAIStreamAdapter(
),
),
- ...(externalUsesStudioTools && resolvedThreadId
- ? { thread_id: resolvedThreadId }
- : {}),
...(externalCapabilities?.topK ? { top_k: params.topK } : {}),
...(externalCapabilities?.minP
? minPSamplingPayload(externalProvider?.providerType, params)
@@ -6373,9 +6372,6 @@ export function createOpenAIStreamAdapter(
...(sandboxAttachments.length > 0
? { sandbox_attachments: sandboxAttachments }
: {}),
- ...(resolvedThreadId
- ? { thread_id: resolvedThreadId }
- : {}),
...(ragEnabled || projectRagEnabled
? {
rag_scope: {
@@ -6440,6 +6436,8 @@ export function createOpenAIStreamAdapter(
},
{ forceRefreshPublicKey },
)),
+ // On every external request: OpenRouter's cache routing, and the prompt date unless Claude caches.
+ ...(resolvedThreadId ? { thread_id: resolvedThreadId } : {}),
...(openaiCodeExecContainerId
? {
openai_code_exec_container_id: openaiCodeExecContainerId,
@@ -8020,8 +8018,7 @@ export function createOpenAIStreamAdapter(
meta?.usage?.prompt_tokens_details?.cached_tokens ??
meta?.usage?.cache_read_input_tokens ??
0;
- // Anthropic-only (billed at the write premium).
- const cacheWriteTokens = meta?.usage?.cache_creation_input_tokens ?? 0;
+ const cacheWriteTokens = usageCacheWriteTokens(meta?.usage);
// Gate on the captured checkpoint and thread so a late completion from provider A cannot
// repaint the bar after a switch to B. A first turn is adopted onto an id mid-run, so read
diff --git a/studio/frontend/src/features/chat/chat-settings-sheet.tsx b/studio/frontend/src/features/chat/chat-settings-sheet.tsx
index f4ec3296392..156558ce6db 100644
--- a/studio/frontend/src/features/chat/chat-settings-sheet.tsx
+++ b/studio/frontend/src/features/chat/chat-settings-sheet.tsx
@@ -83,8 +83,8 @@ import {
type ExternalProviderConfig,
getExternalProviderApiKey,
parseExternalModelId,
- supportsProviderPromptCacheTtl,
- supportsProviderPromptCaching,
+ promptCacheTtlAppliesToModel,
+ promptCachingAppliesToModel,
} from "./external-providers";
import {
BUILTIN_PRESETS,
@@ -816,18 +816,24 @@ export function ChatSettingsPanel({
const systemPromptEditorDirty =
systemPromptDraft !== currentSystemPrompt ||
systemVariablesDraft !== currentSystemVariables;
+ const externalSelection = currentCheckpoint
+ ? parseExternalModelId(currentCheckpoint)
+ : null;
const showPromptCacheTtlControl = Boolean(
activeExternalProvider &&
- supportsProviderPromptCacheTtl(activeExternalProvider.providerType),
+ promptCacheTtlAppliesToModel(
+ activeExternalProvider.providerType,
+ externalSelection?.modelId,
+ ),
);
const showPromptCachingControl =
activeExternalProvider != null &&
- supportsProviderPromptCaching(activeExternalProvider.providerType);
+ promptCachingAppliesToModel(
+ activeExternalProvider.providerType,
+ externalSelection?.modelId,
+ );
const promptCachingEnabled =
activeExternalProvider?.enablePromptCaching !== false;
- const externalSelection = currentCheckpoint
- ? parseExternalModelId(currentCheckpoint)
- : null;
// The OpenRouter cap comes from the live catalog, which can land after this panel renders.
useSyncExternalStore(subscribeModelCatalog, modelCatalogVersion);
const maxTokensMax = isExternalModel
diff --git a/studio/frontend/src/features/chat/external-providers.ts b/studio/frontend/src/features/chat/external-providers.ts
index 13deb4df595..b557003adfc 100644
--- a/studio/frontend/src/features/chat/external-providers.ts
+++ b/studio/frontend/src/features/chat/external-providers.ts
@@ -51,12 +51,13 @@ export interface ExternalProviderConfig {
updatedAt: number;
}
-// Gemini supports prompt caching, but the wire flow needs a separate POST to
+// Providers whose caching setting is kept and sent; `promptCachingAppliesToModel` decides where
+// the switch shows. Gemini supports prompt caching, but the wire flow needs a separate POST to
// /v1beta/cachedContents before generateContent can reference the cache. Until that two-step
-// flow ships, keep the picker off so the toggle does not silently no-op for Gemini. See
+// flow ships, keep it out so the toggle does not silently no-op for Gemini. See
// https://ai.google.dev/gemini-api/docs/caching.
// The enable_prompt_caching boolean alone is not enough.
-const PROMPT_CACHING_PROVIDER_TYPES = new Set(["openai", "anthropic"]);
+const PROMPT_CACHING_PROVIDER_TYPES = new Set(["openai", "anthropic", "openrouter"]);
export function supportsProviderPromptCaching(
providerType: string | null | undefined,
@@ -65,9 +66,9 @@ export function supportsProviderPromptCaching(
}
/** Whether the provider lets the user choose between a short and long prompt-cache pool.
- * Anthropic exposes 5m and 1h ephemeral pools via `cache_control.ttl`; OpenAI's automatic
- * cache has no equivalent knob. */
-const PROMPT_CACHE_TTL_PROVIDER_TYPES = new Set(["anthropic"]);
+ * Anthropic exposes 5m and 1h ephemeral pools via `cache_control.ttl` (OpenRouter forwards it
+ * for Claude models); OpenAI's automatic cache has no equivalent knob. */
+const PROMPT_CACHE_TTL_PROVIDER_TYPES = new Set(["anthropic", "openrouter"]);
export function supportsProviderPromptCacheTtl(
providerType: string | null | undefined,
@@ -77,6 +78,34 @@ export function supportsProviderPromptCacheTtl(
);
}
+// OpenRouter acts on the cache settings only for Claude; its other models cache automatically.
+function cacheSettingsApplyToModel(
+ providerType: string | null | undefined,
+ modelId: string | null | undefined,
+): boolean {
+ return providerType !== "openrouter" || /^~?anthropic\//i.test(modelId ?? "");
+}
+
+export function promptCachingAppliesToModel(
+ providerType: string | null | undefined,
+ modelId: string | null | undefined,
+): boolean {
+ return (
+ supportsProviderPromptCaching(providerType) &&
+ cacheSettingsApplyToModel(providerType, modelId)
+ );
+}
+
+export function promptCacheTtlAppliesToModel(
+ providerType: string | null | undefined,
+ modelId: string | null | undefined,
+): boolean {
+ return (
+ supportsProviderPromptCacheTtl(providerType) &&
+ cacheSettingsApplyToModel(providerType, modelId)
+ );
+}
+
const PROMPT_CACHE_TTL_VALUES = new Set<"5m" | "1h">(["5m", "1h"]);
export function isPromptCacheTtl(value: unknown): value is "5m" | "1h" {
diff --git a/studio/frontend/src/features/chat/utils/chat-generation-recovery.ts b/studio/frontend/src/features/chat/utils/chat-generation-recovery.ts
index 0c00f4f8f23..71dffc6a40a 100644
--- a/studio/frontend/src/features/chat/utils/chat-generation-recovery.ts
+++ b/studio/frontend/src/features/chat/utils/chat-generation-recovery.ts
@@ -121,11 +121,20 @@ type RecoveryUsage = {
prompt_tokens?: unknown;
completion_tokens?: unknown;
total_tokens?: unknown;
- prompt_tokens_details?: { cached_tokens?: unknown };
+ prompt_tokens_details?: { cached_tokens?: unknown; cache_write_tokens?: unknown };
cache_creation_input_tokens?: unknown;
cache_read_input_tokens?: unknown;
};
+/** Tokens billed at the cache-write premium: Anthropic reports them top-level, OpenRouter in the details. */
+export function usageCacheWriteTokens(usage: RecoveryUsage | undefined): number {
+ if (typeof usage?.cache_creation_input_tokens === "number") {
+ return usage.cache_creation_input_tokens;
+ }
+ const details = usage?.prompt_tokens_details?.cache_write_tokens;
+ return typeof details === "number" ? details : 0;
+}
+
type RecoveryTimings = {
cache_n?: unknown;
predicted_per_second?: unknown;
@@ -187,10 +196,7 @@ export function recoveredGenerationFinalMetadata(options: {
(typeof usage.cache_read_input_tokens === "number"
? usage.cache_read_input_tokens
: 0),
- cacheWriteTokens:
- typeof usage.cache_creation_input_tokens === "number"
- ? usage.cache_creation_input_tokens
- : 0,
+ cacheWriteTokens: usageCacheWriteTokens(usage),
modelId,
};
}
diff --git a/studio/frontend/tests/chat-runtime-reload-status.test.ts b/studio/frontend/tests/chat-runtime-reload-status.test.ts
index 0888fada3a9..0e66cfb467e 100644
--- a/studio/frontend/tests/chat-runtime-reload-status.test.ts
+++ b/studio/frontend/tests/chat-runtime-reload-status.test.ts
@@ -145,6 +145,29 @@ test("active runs are read before messages so a concurrent create is visible", a
);
});
+test("terminal recovery reads cache writes from either provider's usage shape", () => {
+ const writesFor = (usage: Record<string, unknown>) =>
+ (
+ recoveredGenerationFinalMetadata({
+ current: {},
+ run: {
+ id: "run-1",
+ requestPayload: { model: "m" },
+ createdAt: 100,
+ startedAt: 120,
+ completedAt: 1120,
+ },
+ usage: { prompt_tokens: 8, completion_tokens: 2, total_tokens: 10, ...usage },
+ totalChunks: 1,
+ }).contextUsage as { cacheWriteTokens: number }
+ ).cacheWriteTokens;
+ assert.equal(writesFor({ prompt_tokens_details: { cache_write_tokens: 5 } }), 5);
+ assert.equal(
+ writesFor({ cache_creation_input_tokens: 7, prompt_tokens_details: { cache_write_tokens: 5 } }),
+ 7,
+ );
+});
+
test("terminal recovery restores final local usage and timing metadata", () => {
const metadata = recoveredGenerationFinalMetadata({
current: { generationSettled: true },
diff --git a/studio/frontend/tests/external-sampling-payload.test.ts b/studio/frontend/tests/external-sampling-payload.test.ts
index 47f55187f7e..61015049669 100644
--- a/studio/frontend/tests/external-sampling-payload.test.ts
+++ b/studio/frontend/tests/external-sampling-payload.test.ts
@@ -219,3 +219,74 @@ test("the external body opts into the stream usage chunk", () => {
include_usage: true,
});
});
+
+const {
+ isPromptCacheTtl,
+ promptCacheTtlAppliesToModel,
+ promptCachingAppliesToModel,
+ supportsProviderPromptCacheTtl,
+ supportsProviderPromptCaching,
+} = await import("../src/features/chat/external-providers.ts");
+
+// Evaluated from the top-level literal so a thread_id reachable only through the tool loop fails.
+const buildCacheFields = new Function(
+ "externalProvider",
+ "resolvedThreadId",
+ "supportsProviderPromptCaching",
+ "supportsProviderPromptCacheTtl",
+ "isPromptCacheTtl",
+ `return Object.assign({}, ${externalBodyLiteral()
+ .properties.filter(ts.isSpreadAssignment)
+ .map((property) => property.expression.getText())
+ .filter((text) => /PromptCach|^\(resolvedThreadId/.test(text))
+ .join(", ")});`,
+);
+
+function cacheFieldsFor(provider: Record<string, unknown>, threadId?: string) {
+ return buildCacheFields(
+ provider,
+ threadId,
+ supportsProviderPromptCaching,
+ supportsProviderPromptCacheTtl,
+ isPromptCacheTtl,
+ ) as Record<string, unknown>;
+}
+
+test("OpenRouter sends the caching toggle, its TTL and the thread on every external request", () => {
+ assert.deepEqual(cacheFieldsFor({ providerType: "openrouter" }, "thread-1"), {
+ enable_prompt_caching: true,
+ thread_id: "thread-1",
+ });
+ assert.deepEqual(
+ cacheFieldsFor({ providerType: "openrouter", promptCacheTtl: "1h" }),
+ { enable_prompt_caching: true, prompt_cache_ttl: "1h" },
+ );
+ assert.deepEqual(
+ cacheFieldsFor({ providerType: "openrouter", enablePromptCaching: false, promptCacheTtl: "1h" }),
+ { enable_prompt_caching: false },
+ );
+});
+
+test("the cache controls show for OpenRouter only on Claude models", () => {
+ for (const applies of [promptCachingAppliesToModel, promptCacheTtlAppliesToModel]) {
+ assert.equal(applies("anthropic", "claude-opus-5"), true);
+ assert.equal(applies("openrouter", "anthropic/claude-sonnet-4.6"), true);
+ assert.equal(applies("openrouter", "~anthropic/claude-opus-latest"), true);
+ assert.equal(applies("openrouter", "deepseek/deepseek-v3.2"), false);
+ assert.equal(applies("openrouter", undefined), false);
+ assert.equal(applies("gemini", "gemini-3-pro"), false);
+ }
+ assert.equal(promptCachingAppliesToModel("openai", "gpt-5.5"), true);
+ assert.equal(promptCacheTtlAppliesToModel("openai", "gpt-5.5"), false);
+ const sheet = readSrc("features/chat/chat-settings-sheet.tsx");
+ for (const name of ["promptCachingAppliesToModel", "promptCacheTtlAppliesToModel"]) {
+ assert.match(
+ sheet,
+ new RegExp(`${name}\\(\\s*activeExternalProvider\\.providerType,\\s*externalSelection\\?\\.modelId,?\\s*\\)`),
+ );
+ }
+});
+
+test("the live stream reads cache writes through the shared usage rule", () => {
+ assert.match(source, /const cacheWriteTokens = usageCacheWriteTokens\(meta\?\.usage\);/);
+});