pi-cache-optimizer 2.6.21 → 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

@@ -14,6 +14,12 @@ type CacheRetentionEnvSnapshot = {
 
 const PI_CACHE_RETENTION_ENV = "PI_CACHE_RETENTION";
 const LONG_CACHE_RETENTION_VALUE = "long";
+const PI_CACHE_RETENTION_BASELINE_SYMBOL = Symbol.for("pi.cache.optimizer.retention-baseline.v1");
+
+type CacheRetentionBaselineV1 = {
+  version: 1;
+  snapshot: CacheRetentionEnvSnapshot;
+};
 
 function captureCacheRetentionEnv(env: MutableEnv = process.env): CacheRetentionEnvSnapshot {
   return {
@@ -36,7 +42,28 @@ function restoreCacheRetentionEnv(snapshot: CacheRetentionEnvSnapshot, env: Muta
   }
 }
 
-const STARTUP_CACHE_RETENTION_ENV = captureCacheRetentionEnv();
+function isCacheRetentionBaselineV1(value: unknown): value is CacheRetentionBaselineV1 {
+  if (typeof value !== "object" || value === null) return false;
+  const record = value as { version?: unknown; snapshot?: unknown };
+  if (record.version !== 1 || typeof record.snapshot !== "object" || record.snapshot === null) return false;
+  const snapshot = record.snapshot as { wasSet?: unknown; value?: unknown };
+  return typeof snapshot.wasSet === "boolean" &&
+    (snapshot.value === undefined || typeof snapshot.value === "string");
+}
+
+function getOrCaptureCacheRetentionBaseline(
+  env: MutableEnv = process.env,
+  globals: Record<symbol, unknown> = globalThis as Record<symbol, unknown>,
+): CacheRetentionEnvSnapshot {
+  const existing = globals[PI_CACHE_RETENTION_BASELINE_SYMBOL];
+  if (isCacheRetentionBaselineV1(existing)) return { ...existing.snapshot };
+
+  const snapshot = captureCacheRetentionEnv(env);
+  globals[PI_CACHE_RETENTION_BASELINE_SYMBOL] = { version: 1, snapshot: { ...snapshot } };
+  return snapshot;
+}
+
+const STARTUP_CACHE_RETENTION_ENV = getOrCaptureCacheRetentionBaseline();
 
 /**
  * Pi Cache Optimizer (formerly pi-deepseek-cache-optimizer)
@@ -76,6 +103,7 @@ const NO_SKILL_COMPRESSION_ENV = "PI_CACHE_OPTIMIZER_NO_SKILL_COMPRESSION";
 const NO_PROMPT_REWRITE_ENV = "PI_CACHE_OPTIMIZER_NO_PROMPT_REWRITE";
 const PI_ROUTING_REGISTRY_SYMBOL = Symbol.for("pi.routing.registry.v1");
 const PI_CACHE_HINTS_SYMBOL = Symbol.for("pi.cache.hints.v1");
+const PI_CACHE_HINTS_OWNER_SYMBOL = Symbol.for("pi.cache.optimizer.hints-owner.v1");
 
 let runtimeOptimizerEnabled = true;
 
@@ -921,16 +949,29 @@ function getCacheHintsService(): PiCacheHintsV1 | undefined {
   return isCacheHintsServiceV1(candidate) ? candidate : undefined;
 }
 
-function installCacheHintsService(service: PiCacheHintsV1): () => void {
+function markOptimizerOwnedCacheHintsService(service: PiCacheHintsV1): PiCacheHintsV1 {
+  (service as PiCacheHintsV1 & Record<symbol, unknown>)[PI_CACHE_HINTS_OWNER_SYMBOL] = true;
+  return service;
+}
+
+function isOptimizerOwnedCacheHintsService(value: unknown): boolean {
+  return typeof value === "object" && value !== null &&
+    (value as Record<symbol, unknown>)[PI_CACHE_HINTS_OWNER_SYMBOL] === true;
+}
+
+function installCacheHintsService(
+  service: PiCacheHintsV1,
+  options: { discardPrevious?: (value: unknown) => boolean } = {},
+): () => void {
   const globals = getProtocolGlobal();
   const previous = globals[PI_CACHE_HINTS_SYMBOL];
   globals[PI_CACHE_HINTS_SYMBOL] = service;
   return () => {
     if (globals[PI_CACHE_HINTS_SYMBOL] !== service) return;
-    if (previous === undefined) {
-      delete globals[PI_CACHE_HINTS_SYMBOL];
-    } else {
+    if (previous !== undefined && !options.discardPrevious?.(previous)) {
       globals[PI_CACHE_HINTS_SYMBOL] = previous;
+    } else {
+      delete globals[PI_CACHE_HINTS_SYMBOL];
     }
   };
 }
@@ -1129,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";
 }
@@ -1155,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";
@@ -3919,6 +4020,15 @@ function mergeCacheSessions(
   return sessions;
 }
 
+function createSerializedAsyncRunner(): <T>(operation: () => Promise<T>) => Promise<T> {
+  let tail: Promise<unknown> = Promise.resolve();
+  return <T>(operation: () => Promise<T>): Promise<T> => {
+    const result = tail.then(operation);
+    tail = result.catch(() => undefined);
+    return result;
+  };
+}
+
 function mergeCacheTotals(
   existingTotalsByModel: Record<string, CacheStats>,
   stateTotalsByModel: Record<string, CacheStats>,
@@ -5826,7 +5936,10 @@ export const __internals_for_tests = {
   shouldInjectOpenAIPromptCacheKey,
   shouldInjectOpenAIPromptCacheKeyForModel,
   isOpenAICompatibleApi,
+  isAnthropicMessagesApi,
   isOpenAICompatibleProxyApi,
+  collectAnthropicCacheControlsInWireOrder,
+  normalizeAnthropicCacheControlTtlOrder,
   isPiBuiltInLlamaCppModel,
   isResponsesPromptRewriteBypassApi,
   isMistralConversationsApi,
@@ -6025,10 +6138,15 @@ export const __internals_for_tests = {
   isVirtualRoutingModel,
   installCacheHintsService,
   getCacheHintsService,
+  markOptimizerOwnedCacheHintsService,
+  isOptimizerOwnedCacheHintsService,
+  getOrCaptureCacheRetentionBaseline,
+  PI_CACHE_RETENTION_BASELINE_SYMBOL,
   // Persistence helpers (for reload/reset tests)
   mergeCacheSessions,
   mergeCacheTotals,
   mergeLastRoutedModels,
+  createSerializedAsyncRunner,
   writePersistedCacheStats,
   readPersistedCacheStats,
   STATE_FILE_PATH,
@@ -6078,7 +6196,9 @@ export default function (pi: ExtensionAPI) {
   let lastStatusText: string | undefined;
   let persistenceWarningShown = false;
   let persistTimer: ReturnType<typeof setTimeout> | null = null;
+  const enqueuePersist = createSerializedAsyncRunner();
   let replacePersistedTotalsOnNextWrite = false;
+  let forceReplaceTotalsAfterFailure = false;
   const pendingDeletedTotalModelKeys = new Set<string>();
   let integrityNotificationShown = false;
   let currentSessionId = "";
@@ -6100,7 +6220,7 @@ export default function (pi: ExtensionAPI) {
     }
   }
 
-  const uninstallCacheHintsService = installCacheHintsService({
+  const uninstallCacheHintsService = installCacheHintsService(markOptimizerOwnedCacheHintsService({
     version: 1,
     getHints(input: PiCacheHintsInput): PiCacheHintsOutput | undefined {
       if (!runtimeOptimizerEnabled || isEnabledEnv(process.env[NO_PROMPT_REWRITE_ENV])) return undefined;
@@ -6119,8 +6239,7 @@ export default function (pi: ExtensionAPI) {
         cacheRetention: hint.cacheRetention,
       };
     },
-  });
-  void uninstallCacheHintsService;
+  }), { discardPrevious: isOptimizerOwnedCacheHintsService });
 
   /**
    * Build a session-scoped stats key from the current session hash + model key.
@@ -6243,28 +6362,59 @@ export default function (pi: ExtensionAPI) {
     lastStatusText = undefined;
   }
 
-  async function persistCacheStats(ctx?: ExtensionContext): Promise<void> {
-    try {
-      await writePersistedCacheStats(
-        getCacheStatsState(),
-        currentSessionHashSet ? currentSessionHash : undefined,
-        {
-          deleteModelKeys: Array.from(pendingDeletedTotalModelKeys),
-          replaceTotals: replacePersistedTotalsOnNextWrite,
-        },
-      );
-      pendingDeletedTotalModelKeys.clear();
-      replacePersistedTotalsOnNextWrite = false;
-    } catch (error) {
-      console.warn(`${LOG_PREFIX}: failed to persist cache stats`, error);
-      if (!persistenceWarningShown) {
-        persistenceWarningShown = true;
-        ctx?.ui.notify(
-          `${LOG_PREFIX}: failed to persist footer stats; using in-memory stats for this process.`,
-          "warning",
-        );
-      }
+  function snapshotCacheStatsState(): CacheStatsState {
+    const state = getCacheStatsState();
+    const statsByModel = Object.fromEntries(
+      Object.entries(state.statsByModel).map(([key, stats]) => [key, { ...stats }]),
+    );
+    const totalsByModel = Object.fromEntries(
+      Object.entries(state.totalsByModel).map(([key, stats]) => [key, { ...stats }]),
+    );
+    const legacyFamily: Partial<Record<CacheProviderId, CacheStats>> = {};
+    for (const id of CACHE_PROVIDER_IDS) {
+      const stats = state.legacyFamily[id];
+      if (stats) legacyFamily[id] = { ...stats };
     }
+    const lastRoutedModelBySession = state.lastRoutedModelBySession
+      ? Object.fromEntries(
+        Object.entries(state.lastRoutedModelBySession).map(([key, model]) => [key, { ...model }]),
+      )
+      : undefined;
+    return { statsByModel, totalsByModel, legacyFamily, lastRoutedModelBySession };
+  }
+
+  function persistCacheStats(ctx?: ExtensionContext): Promise<void> {
+    const state = snapshotCacheStatsState();
+    const sessionHash = currentSessionHashSet ? currentSessionHash : undefined;
+    const deleteModelKeys = Array.from(pendingDeletedTotalModelKeys);
+    const replaceTotals = replacePersistedTotalsOnNextWrite;
+    // This queued write owns the current intents. Later mutations can enqueue
+    // independent intents without an earlier completion clearing them.
+    pendingDeletedTotalModelKeys.clear();
+    replacePersistedTotalsOnNextWrite = false;
+
+    return enqueuePersist(async () => {
+      const recoverFromEarlierFailure = forceReplaceTotalsAfterFailure;
+      try {
+        await writePersistedCacheStats(state, sessionHash, {
+          deleteModelKeys,
+          replaceTotals: replaceTotals || recoverFromEarlierFailure,
+        });
+        if (recoverFromEarlierFailure) forceReplaceTotalsAfterFailure = false;
+      } catch (error) {
+        // The next queued write must replace totals authoritatively so a failed
+        // reset/delete cannot merge stale persisted counters back into state.
+        forceReplaceTotalsAfterFailure = true;
+        console.warn(`${LOG_PREFIX}: failed to persist cache stats`, error);
+        if (!persistenceWarningShown) {
+          persistenceWarningShown = true;
+          ctx?.ui.notify(
+            `${LOG_PREFIX}: failed to persist footer stats; using in-memory stats for this process.`,
+            "warning",
+          );
+        }
+      }
+    });
   }
 
   /** Schedule a debounced persist. Coalesces rapid message_end writes
@@ -6554,10 +6704,22 @@ export default function (pi: ExtensionAPI) {
   }
 
   pi.on("session_start", async (event, ctx) => {
+    if (runtimeOptimizerEnabled) requestLongCacheRetention();
     await restoreCacheStats(event.reason, ctx);
     await publishStatus(ctx);
   });
 
+  pi.on("session_shutdown", async (_event, ctx) => {
+    try {
+      await flushPersistCacheStats(ctx);
+    } finally {
+      latestCacheHint = undefined;
+      delete getProtocolGlobal().__piCacheOptimizerCacheKey__;
+      uninstallCacheHintsService();
+      restoreCacheRetentionEnv(STARTUP_CACHE_RETENTION_ENV);
+    }
+  });
+
   pi.on("model_select", async (event, ctx) => {
     if (runtimeOptimizerEnabled) notifyCacheCompatIfNeeded(resolveRouteModel(event.model, ctx) ?? event.model, ctx, warnedModels);
     await publishStatus(ctx, event.model);
@@ -6684,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
@@ -6700,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
@@ -6718,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.21",
+  "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",