pi-cache-optimizer 2.6.22 → 2.6.23

package/README.md

@@ -113,6 +113,14 @@ Notes:
 - For DeepSeek models, the Pi Mono guidance expects `compat.requiresReasoningContentOnAssistantMessages: true` and `compat.thinkingFormat: "deepseek"` alongside cache/session-affinity flags when the endpoint supports them.
 - This extension's `doctor` and `compat` commands only advise; they do not modify `models.json`.
 
+## Anthropic cache TTL compatibility
+
+Anthropic processes cache breakpoints in `tools → system → messages` order and rejects a `ttl: "1h"` breakpoint that appears after a 5-minute breakpoint. An ephemeral `cache_control` without `ttl` uses the default 5-minute retention.
+
+For `anthropic-messages` channels, the extension checks the final serialized payload before sending. If it detects an invalid short-to-long transition, it conservatively downgrades that request's `1h` breakpoints to the default 5-minute TTL. Legal long-only and `1h → 5m` payloads are left unchanged. This is based on payload structure, not provider names such as `pipi-cc`.
+
+If a proxy adds its own conflicting cache controls after Pi's request hook, set `compat.supportsLongCacheRetention: false` for that provider/model so Pi does not emit `ttl: "1h"`.
+
 ## Adaptive thinking models
 
 Claude models from opus-4.6 / sonnet-4.6 (including Sonnet 5) / fable-5 onwards require `forceAdaptiveThinking: true` in compat. Kimi Coding K3 (`k3`) and `kimi-for-coding` also use adaptive thinking and need `allowEmptySignature: true` so replayed empty-signature thinking blocks remain valid. Without the required compat, Pi may send a legacy thinking payload or replay thinking incorrectly.

package/README.zh-CN.md

@@ -113,6 +113,14 @@ Pi 0.81+ 也内置了使用 OpenAI-shaped transport 的 `llama.cpp` provider。P
 - 对 DeepSeek 模型，Pi Mono 指南期望在支持时同时设置 `compat.requiresReasoningContentOnAssistantMessages: true` 和 `compat.thinkingFormat: "deepseek"`，再配合缓存 / session-affinity 相关 compat。
 - 本扩展的 `doctor` 和 `compat` 命令只给建议，不会修改 `models.json`。
 
+## Anthropic 缓存 TTL 兼容
+
+Anthropic 按 `tools → system → messages` 顺序处理 cache breakpoint，并拒绝位于 5 分钟 breakpoint 之后的 `ttl: "1h"` breakpoint。省略 `ttl` 的 ephemeral `cache_control` 使用默认 5 分钟保留时间。
+
+对于 `anthropic-messages` 渠道，本扩展会在发送前检查最终序列化 payload。如果检测到非法的短 TTL → 长 TTL 顺序，会保守地把该请求中的 `1h` breakpoint 降级为默认 5 分钟 TTL。合法的纯 `1h` 和 `1h → 5m` payload 保持不变。判断依据是 payload 结构，而不是 `pipi-cc` 等 provider 名称。
+
+如果代理在 Pi request hook 之后自行添加冲突的 cache control，可为该 provider/model 设置 `compat.supportsLongCacheRetention: false`，使 Pi 不再发送 `ttl: "1h"`。
+
 ## Adaptive thinking 模型
 
 Claude 从 opus-4.6 / sonnet-4.6（含 Sonnet 5）/ fable-5 开始需要在 compat 中设置 `forceAdaptiveThinking: true`。Kimi Coding K3（`k3`）和 `kimi-for-coding` 也使用 adaptive thinking，并需要 `allowEmptySignature: true`，以正确重放空 signature 的 thinking block。缺少这些 compat 时，Pi 可能发送旧版 thinking payload 或错误重放 thinking。

package/index.ts

@@ -1170,6 +1170,10 @@ function isOpenAICompatibleApi(api: unknown): boolean {
   return value === "openai-completions" || value === "openai-responses";
 }
 
+function isAnthropicMessagesApi(api: unknown): boolean {
+  return lower(api) === "anthropic-messages";
+}
+
 function isOpenAICompatibleProxyApi(api: unknown): boolean {
   return lower(api) === "openai-completions";
 }
@@ -1196,6 +1200,62 @@ function shouldInjectOpenAIPromptCacheKeyForModel(model: PiModel | undefined): b
   return isOpenAICompatibleApi(model?.api);
 }
 
+function collectAnthropicCacheControlsInWireOrder(payload: unknown): UnknownRecord[] {
+  const record = asRecord(payload);
+  if (!record) return [];
+
+  const controls: UnknownRecord[] = [];
+  const collectFromBlock = (value: unknown): void => {
+    const cacheControl = asRecord(asRecord(value)?.cache_control);
+    if (cacheControl?.type === "ephemeral") controls.push(cacheControl);
+  };
+
+  // Anthropic processes cache breakpoints in tools → system → messages order.
+  if (Array.isArray(record.tools)) {
+    for (const tool of record.tools) collectFromBlock(tool);
+  }
+  if (Array.isArray(record.system)) {
+    for (const block of record.system) collectFromBlock(block);
+  }
+  if (Array.isArray(record.messages)) {
+    for (const message of record.messages) {
+      const content = asRecord(message)?.content;
+      if (!Array.isArray(content)) continue;
+      for (const block of content) collectFromBlock(block);
+    }
+  }
+
+  return controls;
+}
+
+/**
+ * Anthropic requires every 1h cache breakpoint to precede every 5m breakpoint.
+ * An ephemeral cache_control without ttl uses Anthropic's default 5m retention.
+ * If the final serialized payload contains a short → long transition, downgrade
+ * all 1h breakpoints to the default 5m so the request remains valid.
+ */
+function normalizeAnthropicCacheControlTtlOrder(payload: unknown): boolean {
+  const controls = collectAnthropicCacheControlsInWireOrder(payload);
+  let seenShort = false;
+  let hasInvalidLongAfterShort = false;
+
+  for (const control of controls) {
+    const ttl = control.ttl;
+    if (ttl === undefined || ttl === "5m") {
+      seenShort = true;
+    } else if (ttl === "1h" && seenShort) {
+      hasInvalidLongAfterShort = true;
+      break;
+    }
+  }
+  if (!hasInvalidLongAfterShort) return false;
+
+  for (const control of controls) {
+    if (control.ttl === "1h") delete control.ttl;
+  }
+  return true;
+}
+
 function isResponsesPromptRewriteBypassApi(api: unknown): boolean {
   const value = lower(api);
   return value === "openai-codex-responses" || value === "openai-responses" || value === "azure-openai-responses";
@@ -5876,7 +5936,10 @@ export const __internals_for_tests = {
   shouldInjectOpenAIPromptCacheKey,
   shouldInjectOpenAIPromptCacheKeyForModel,
   isOpenAICompatibleApi,
+  isAnthropicMessagesApi,
   isOpenAICompatibleProxyApi,
+  collectAnthropicCacheControlsInWireOrder,
+  normalizeAnthropicCacheControlTtlOrder,
   isPiBuiltInLlamaCppModel,
   isResponsesPromptRewriteBypassApi,
   isMistralConversationsApi,
@@ -6783,6 +6846,16 @@ export default function (pi: ExtensionAPI) {
   });
 
   pi.on("before_provider_request", (event, ctx) => {
+    const requestModel = resolveRouteModel(ctx.model, ctx) ?? ctx.model;
+
+    // Anthropic rejects mixed cache breakpoints when a 1h block appears after
+    // a 5m/default block in wire order (tools → system → messages). Normalize
+    // only provably-invalid final payloads; legal long-only and long→short
+    // payloads keep their original retention.
+    if (isAnthropicMessagesApi(requestModel?.api)) {
+      normalizeAnthropicCacheControlTtlOrder(event.payload);
+    }
+
     // ── Safety: strip prompt_cache_retention from payload for models that
     // are not authorised to send it. Pi defaults supportsLongCacheRetention
     // to true for all openai-completions models, but most third-party APIs
@@ -6799,14 +6872,13 @@ export default function (pi: ExtensionAPI) {
     if (runtimeOptimizerEnabled) {
       const payload = event.payload as UnknownRecord;
       if (payload && typeof payload.prompt_cache_retention === 'string') {
-        const rModel = resolveRouteModel(ctx.model, ctx) ?? ctx.model;
-        if (rModel) {
-          if (isOfficialOpenAIBaseUrl(rModel)) {
+        if (requestModel) {
+          if (isOfficialOpenAIBaseUrl(requestModel)) {
             // Gate 1: Official OpenAI → keep
-          } else if (promptCacheRetention400Models.has(modelKey(rModel))) {
+          } else if (promptCacheRetention400Models.has(modelKey(requestModel))) {
             // Gate 2: 400 history → strip (overrides user opt-in)
             delete payload.prompt_cache_retention;
-          } else if (hasExplicitLongRetentionOptIn(rModel)) {
+          } else if (hasExplicitLongRetentionOptIn(requestModel)) {
             // Gate 3: Explicit user opt-in → keep
           } else {
             // Gate 4: Safe default → strip
@@ -6817,7 +6889,6 @@ export default function (pi: ExtensionAPI) {
     }
 
     if (!shouldInjectOpenAIPromptCacheKey()) return undefined;
-    const requestModel = resolveRouteModel(ctx.model, ctx) ?? ctx.model;
     if (!shouldInjectOpenAIPromptCacheKeyForModel(requestModel)) return undefined;
 
     return addOpenAIPromptCacheKey(event.payload, getSessionPromptCacheKey(ctx));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-cache-optimizer",
-  "version": "2.6.22",
+  "version": "2.6.23",
   "description": "Improve Pi prompt/KV cache hit rates with stable prompts, OpenAI-compatible cache keys, proxy compat warnings, and footer cache stats.",
   "keywords": [
     "pi-package",