pi-cache-optimizer 2.6.23 → 2.6.24

package/README.md

@@ -117,9 +117,9 @@ Notes:
 
 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`.
+For every `anthropic-messages` channel, the extension checks the final serialized payload and immediately downgrades a visibly invalid short-to-long transition. Legal long-only and `1h → 5m` payloads remain unchanged, including third-party endpoints that genuinely support 1-hour retention.
 
-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"`.
+Some proxies rewrite or insert hidden 5-minute breakpoints after Pi's request hook. If a provider returns Anthropic's explicit TTL-ordering error, the extension records a process-local provider/model fallback so the next subsequent request uses the default 5-minute TTL. This error is a non-retryable HTTP 400 in Pi 0.82.1, so the extension does not claim that Pi's automatic retry will rerun the failed turn; if another layer retries it, that retry also uses the fallback. `/cache-optimizer doctor` reports the fallback and `/cache-optimizer fix` can persist a model-scoped `supportsLongCacheRetention: false` with the normal confirmation/backup flow. Other 400 errors and prompt-too-long failures do not activate this fallback. The runtime observation lasts until the current process exits and survives extension reloads within that process.
 
 ## Adaptive thinking models
 

package/README.zh-CN.md

@@ -117,9 +117,9 @@ Pi 0.81+ 也内置了使用 OpenAI-shaped transport 的 `llama.cpp` provider。P
 
 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 名称。
+对于所有 `anthropic-messages` 渠道，本扩展都会检查最终序列化 payload，并立即降级可见的非法短 TTL → 长 TTL 顺序。合法的纯 `1h` 和 `1h → 5m` payload 保持不变，包括真正支持 1 小时保留的第三方 endpoint。
 
-如果代理在 Pi request hook 之后自行添加冲突的 cache control，可为该 provider/model 设置 `compat.supportsLongCacheRetention: false`，使 Pi 不再发送 `ttl: "1h"`。
+部分代理会在 Pi request hook 之后重写或插入隐藏的 5 分钟 breakpoint。如果 provider 返回 Anthropic 明确的 TTL 顺序错误，本扩展会记录当前进程内的 provider/model fallback，使下一次后续请求使用默认 5 分钟 TTL。Pi 0.82.1 将此错误视为不可自动重试的 HTTP 400，因此扩展不会声称 Pi 会自动重跑失败 turn；如果其它层发起重试，该重试也会使用 fallback。`/cache-optimizer doctor` 会显示该 fallback，`/cache-optimizer fix` 可通过现有确认/备份流程，以 model level 持久写入 `supportsLongCacheRetention: false`。其它 400 和 prompt-too-long 错误不会触发该 fallback。运行时观测会持续到当前进程退出，并会在同一进程内的扩展 reload 后保留。
 
 ## Adaptive thinking 模型
 

package/index.ts

@@ -104,6 +104,32 @@ 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");
+const ANTHROPIC_TTL_FALLBACK_SYMBOL = Symbol.for("pi.cache.optimizer.anthropic-ttl-fallback.v1");
+
+type AnthropicTtlFallbackStateV1 = {
+  version: 1;
+  modelKeys: Set<string>;
+  warnedModelKeys: Set<string>;
+};
+
+function getAnthropicTtlFallbackState(): AnthropicTtlFallbackStateV1 {
+  const globals = globalThis as Record<symbol, unknown>;
+  const existing = globals[ANTHROPIC_TTL_FALLBACK_SYMBOL] as Partial<AnthropicTtlFallbackStateV1> | undefined;
+  if (
+    existing?.version === 1 &&
+    existing.modelKeys instanceof Set &&
+    existing.warnedModelKeys instanceof Set
+  ) {
+    return existing as AnthropicTtlFallbackStateV1;
+  }
+  const state: AnthropicTtlFallbackStateV1 = {
+    version: 1,
+    modelKeys: new Set<string>(),
+    warnedModelKeys: new Set<string>(),
+  };
+  globals[ANTHROPIC_TTL_FALLBACK_SYMBOL] = state;
+  return state;
+}
 
 let runtimeOptimizerEnabled = true;
 
@@ -1234,6 +1260,28 @@ function collectAnthropicCacheControlsInWireOrder(payload: unknown): UnknownReco
  * If the final serialized payload contains a short → long transition, downgrade
  * all 1h breakpoints to the default 5m so the request remains valid.
  */
+function downgradeAnthropicLongCacheControls(payload: unknown): boolean {
+  let changed = false;
+  for (const control of collectAnthropicCacheControlsInWireOrder(payload)) {
+    if (control.ttl === "1h") {
+      delete control.ttl;
+      changed = true;
+    }
+  }
+  return changed;
+}
+
+function hasAnthropicCacheTtlOrderError(message: unknown): boolean {
+  const record = getAssistantRecord(message);
+  if (record?.stopReason !== "error" || typeof record.errorMessage !== "string") return false;
+
+  const error = lower(record.errorMessage);
+  return error.includes("cache_control") &&
+    error.includes("ttl='1h'") &&
+    error.includes("ttl='5m'") &&
+    error.includes("must not come after");
+}
+
 function normalizeAnthropicCacheControlTtlOrder(payload: unknown): boolean {
   const controls = collectAnthropicCacheControlsInWireOrder(payload);
   let seenShort = false;
@@ -1250,10 +1298,7 @@ function normalizeAnthropicCacheControlTtlOrder(payload: unknown): boolean {
   }
   if (!hasInvalidLongAfterShort) return false;
 
-  for (const control of controls) {
-    if (control.ttl === "1h") delete control.ttl;
-  }
-  return true;
+  return downgradeAnthropicLongCacheControls(payload);
 }
 
 function isResponsesPromptRewriteBypassApi(api: unknown): boolean {
@@ -4374,7 +4419,7 @@ function getCompatCheckNotApplicableLines(model: PiModel): string[] {
   return ["ℹ️ Compat check not applicable for this model."];
 }
 
-function buildDoctorDiagnosis(model: PiModel, options: { promptCacheRetention400?: boolean; sessionAffinity403?: boolean; openAISdkHeader403?: boolean } = {}): string {
+function buildDoctorDiagnosis(model: PiModel, options: { promptCacheRetention400?: boolean; anthropicTtlOrderError?: boolean; sessionAffinity403?: boolean; openAISdkHeader403?: boolean } = {}): string {
   const lines: string[] = [];
   lines.push(`Provider: ${model.provider}`);
   lines.push(`Model:    ${model.id}`);
@@ -4433,6 +4478,13 @@ function buildDoctorDiagnosis(model: PiModel, options: { promptCacheRetention400
     }
   }
 
+  if (options.anthropicTtlOrderError) {
+    lines.push("");
+    lines.push("⚠️  An Anthropic cache-control TTL ordering error was observed for this model.");
+    lines.push("   Runtime requests now fall back from 1h to the default 5-minute cache TTL.");
+    lines.push(`   Run /cache-optimizer fix to set model-level supportsLongCacheRetention: false in ${getModelsJsonDisplayPath()}.`);
+  }
+
   // ── Session affinity 403 diagnostics ──
   // Advises the user when sendSessionAffinityHeaders is enabled, since some
   // third-party proxies / CDNs / WAFs block Pi's custom session-affinity HTTP
@@ -4858,6 +4910,8 @@ interface FixSuggestion {
   providerLabel: string;
   modelId: string;
   compatKeys: Record<string, unknown>;
+  /** Runtime-observed failures must never broaden a model-specific fix. */
+  forceModelLevel?: boolean;
 }
 
 /**
@@ -5519,8 +5573,9 @@ function syntheticModelForId(providerLabel: string, id: string): PiModel {
  * Decide whether the fix should write provider-level or model-level compat.
  *
  * Strategy (auto-detect, prefer provider level when safe):
- * - Channel-capability keys (session affinity / long retention) are always
- *   provider-safe.
+ * - Channel-capability keys (session affinity / long retention) are normally
+ *   provider-safe; runtime-observed model failures explicitly override this
+ *   default through chooseFixPlacement(..., forceModelLevel=true).
  * - Model-behavior keys (forceAdaptiveThinking, allowEmptySignature,
  *   thinkingFormat, ...) are provider-safe ONLY when every sibling model in
  *   the provider also matches the same detection (all adaptive-generation /
@@ -5599,7 +5654,15 @@ function chooseFixPlacement(
   location: ModelNodeLocation,
   compatKeys: Record<string, unknown>,
   providerLabel: string,
+  forceModelLevel = false,
 ): { placement: "provider" | "model"; reason: string } {
+  if (forceModelLevel) {
+    return {
+      placement: "model",
+      reason: "runtime-observed provider/model failure — scoping the repair to the affected model",
+    };
+  }
+
   const decision = decideFixPlacement(compatKeys, providerLabel, location.allModelIds);
   const existingModelKeys = findExistingCompatKeysInJsonc(
     original,
@@ -5939,6 +6002,8 @@ export const __internals_for_tests = {
   isAnthropicMessagesApi,
   isOpenAICompatibleProxyApi,
   collectAnthropicCacheControlsInWireOrder,
+  downgradeAnthropicLongCacheControls,
+  hasAnthropicCacheTtlOrderError,
   normalizeAnthropicCacheControlTtlOrder,
   isPiBuiltInLlamaCppModel,
   isResponsesPromptRewriteBypassApi,
@@ -6186,6 +6251,9 @@ export default function (pi: ExtensionAPI) {
   const warnedModels = new Set<string>();
   const promptCacheRetention400Models = new Set<string>();
   const warnedPromptCacheRetention400Models = new Set<string>();
+  const anthropicTtlFallbackState = getAnthropicTtlFallbackState();
+  const anthropicTtlOrderErrorModels = anthropicTtlFallbackState.modelKeys;
+  const warnedAnthropicTtlOrderErrorModels = anthropicTtlFallbackState.warnedModelKeys;
   const sendSessionAffinityHeaders403Models = new Set<string>();
   const warnedSendSessionAffinityHeaders403Models = new Set<string>();
   const openAISdkHeader403Models = new Set<string>();
@@ -6207,6 +6275,41 @@ export default function (pi: ExtensionAPI) {
   let lastActualRoutedModel: PersistedRoutedModelRef | undefined;
   let latestCacheHint: PiCacheHintSnapshot | undefined;
   const PERSIST_DEBOUNCE_MS = 2000;
+
+  function buildObservedRuntimeFixSuggestion(model: PiModel): FixSuggestion | undefined {
+    const key = modelKey(model);
+    const slashIdx = key.indexOf("/");
+    const providerLabel = slashIdx > 0 ? key.slice(0, slashIdx) : key;
+
+    if (
+      anthropicTtlOrderErrorModels.has(key) ||
+      (isPromptCacheRetention400Applicable(model) && promptCacheRetention400Models.has(key))
+    ) {
+      return {
+        providerLabel,
+        modelId: model.id,
+        compatKeys: { supportsLongCacheRetention: false },
+        forceModelLevel: true,
+      };
+    }
+    if (isSessionAffinity403Applicable(model) && sendSessionAffinityHeaders403Models.has(key)) {
+      return { providerLabel, modelId: model.id, compatKeys: { sendSessionAffinityHeaders: false } };
+    }
+    return undefined;
+  }
+
+  function buildCommandFixSuggestion(model: PiModel): FixSuggestion | undefined {
+    const regular = buildFixSuggestion(model);
+    const observed = buildObservedRuntimeFixSuggestion(model);
+    if (!regular) return observed;
+    if (!observed) return regular;
+    return {
+      providerLabel: regular.providerLabel,
+      modelId: regular.modelId,
+      compatKeys: { ...regular.compatKeys, ...observed.compatKeys },
+      forceModelLevel: regular.forceModelLevel || observed.forceModelLevel,
+    };
+  }
   /** In-memory recent usage samples per model key (not persisted, cleared on reload). */
   const recentSamplesByModelKey = new Map<string, CacheUsageSample[]>();
 
@@ -6849,11 +6952,15 @@ export default function (pi: ExtensionAPI) {
     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);
+    // a 5m/default block in wire order (tools → system → messages). Repair any
+    // conflict visible in Pi's final payload immediately. Some proxies inject
+    // hidden short breakpoints after this hook; only models that have actually
+    // returned the explicit TTL-order error receive the process-local 5m fallback.
+    if (requestModel && isAnthropicMessagesApi(requestModel.api)) {
+      const visibleConflictFixed = normalizeAnthropicCacheControlTtlOrder(event.payload);
+      if (!visibleConflictFixed && anthropicTtlOrderErrorModels.has(modelKey(requestModel))) {
+        downgradeAnthropicLongCacheControls(event.payload);
+      }
     }
 
     // ── Safety: strip prompt_cache_retention from payload for models that
@@ -6957,6 +7064,29 @@ export default function (pi: ExtensionAPI) {
 
   pi.on("message_end", async (event, ctx) => {
     syncSessionHash(ctx);
+    const msgRecord = asRecord(event.message);
+
+    // Record only Anthropic's explicit mixed-TTL ordering error. This is a
+    // non-retryable 400 in Pi 0.82.1, so the fallback applies to the next
+    // subsequent request (and to a retry only if another layer initiates one).
+    if (hasAnthropicCacheTtlOrderError(event.message)) {
+      const fallbackModel = resolveRouteModel(ctx.model, ctx) ?? ctx.model;
+      const errorModel = modelFromAssistantMessage(event.message, fallbackModel) ?? fallbackModel;
+      if (errorModel && isAnthropicMessagesApi(errorModel.api)) {
+        const key = modelKey(errorModel);
+        anthropicTtlOrderErrorModels.add(key);
+        if (!warnedAnthropicTtlOrderErrorModels.has(key)) {
+          warnedAnthropicTtlOrderErrorModels.add(key);
+          ctx.ui.notify(
+            `⚠️ ${LOG_PREFIX}: ${key} returned an Anthropic cache-control TTL ordering error. ` +
+            `The next request will fall back to the default 5-minute cache TTL. ` +
+            `Run /cache-optimizer fix to set model-level supportsLongCacheRetention: false persistently.`,
+            "warning",
+          );
+        }
+      }
+    }
+
     const adapter = selectAdapterForAssistantMessage(event.message, ctx.model);
     if (!adapter) return;
 
@@ -6967,7 +7097,6 @@ export default function (pi: ExtensionAPI) {
     // returns as a valid (non-undefined) snapshot, which would inflate
     // totalRequests and skew cache hit-rate accuracy. The final successful
     // response is emitted as a separate message_end with real usage data.
-    const msgRecord = asRecord(event.message);
     if (msgRecord?.stopReason === "error" || msgRecord?.stopReason === "aborted") {
       return;
     }
@@ -7074,7 +7203,7 @@ export default function (pi: ExtensionAPI) {
           cmdCtx.ui.notify("No active model selected. Select a model first with /model or pi --model.", "warning");
           return;
         }
-        const diagnosis = buildDoctorDiagnosis(model, { promptCacheRetention400: promptCacheRetention400Models.has(modelKey(model)), sessionAffinity403: sendSessionAffinityHeaders403Models.has(modelKey(model)), openAISdkHeader403: openAISdkHeader403Models.has(modelKey(model)) });
+        const diagnosis = buildDoctorDiagnosis(model, { promptCacheRetention400: promptCacheRetention400Models.has(modelKey(model)), anthropicTtlOrderError: anthropicTtlOrderErrorModels.has(modelKey(model)), sessionAffinity403: sendSessionAffinityHeaders403Models.has(modelKey(model)), openAISdkHeader403: openAISdkHeader403Models.has(modelKey(model)) });
         const adapter = selectAdapterForModel(model);
         const sk = model ? sessionModelKey(model) : undefined;
         const statsState = model ? cacheStatsTotalsByModel[modelKey(model)] : undefined;
@@ -7147,37 +7276,7 @@ export default function (pi: ExtensionAPI) {
           return;
         }
 
-        let suggestion = buildFixSuggestion(model);
-
-        // If no regular missing compat flags but the model has a recorded
-        // prompt_cache_retention 400 (Pi sent `prompt_cache_retention` and
-        // the provider rejected it), offer to override
-        // `supportsLongCacheRetention` to false in models.json.
-        if (!suggestion && isPromptCacheRetention400Applicable(model) && promptCacheRetention400Models.has(modelKey(model))) {
-          const key = modelKey(model);
-          const slashIdx = key.indexOf("/");
-          const providerLabel = slashIdx > 0 ? key.slice(0, slashIdx) : key;
-          suggestion = {
-            providerLabel,
-            modelId: model.id,
-            compatKeys: { supportsLongCacheRetention: false },
-          };
-        }
-
-        // If no regular missing compat flags but the model has a recorded
-        // 403 while sendSessionAffinityHeaders was enabled (Pi sent custom
-        // session-affinity HTTP headers and the proxy/CDN blocked them), offer
-        // to override `sendSessionAffinityHeaders` to false in models.json.
-        if (!suggestion && isSessionAffinity403Applicable(model) && sendSessionAffinityHeaders403Models.has(modelKey(model))) {
-          const key = modelKey(model);
-          const slashIdx = key.indexOf("/");
-          const providerLabel = slashIdx > 0 ? key.slice(0, slashIdx) : key;
-          suggestion = {
-            providerLabel,
-            modelId: model.id,
-            compatKeys: { sendSessionAffinityHeaders: false },
-          };
-        }
+        const suggestion = buildCommandFixSuggestion(model);
 
         if (!suggestion) {
           const key = modelKey(model);
@@ -7203,6 +7302,13 @@ export default function (pi: ExtensionAPI) {
               "Create or edit the entry below to override supportsLongCacheRetention to false.",
             );
           }
+          if (anthropicTtlOrderErrorModels.has(modelKey(model))) {
+            manualLines.push(
+              "",
+              "💡 This model returned an Anthropic cache-control TTL ordering error.",
+              "Create or edit the entry below to override supportsLongCacheRetention to false.",
+            );
+          }
           if (sendSessionAffinityHeaders403Models.has(modelKey(model))) {
             manualLines.push(
               "",
@@ -7365,9 +7471,15 @@ export default function (pi: ExtensionAPI) {
           return;
         }
 
-        // Compose the modified text — auto-detect the best placement level:
-        // provider level (channel-wide) when safe for all sibling models, else model level.
-        const decision = chooseFixPlacement(originalText, location, suggestion.compatKeys, suggestion.providerLabel);
+        // Compose the modified text — observed runtime failures are always
+        // model-scoped; ordinary compat fixes use the safety-based placement.
+        const decision = chooseFixPlacement(
+          originalText,
+          location,
+          suggestion.compatKeys,
+          suggestion.providerLabel,
+          suggestion.forceModelLevel,
+        );
         const modifiedText = composeFixInsertion(originalText, location, suggestion.compatKeys, decision.placement);
 
         // Self-check
@@ -7495,7 +7607,7 @@ export default function (pi: ExtensionAPI) {
             if (!model) {
               cmdCtx.ui.notify("No active model selected. Select a model first with /model or pi --model.", "warning");
             } else {
-              const diagnosis = buildDoctorDiagnosis(model, { promptCacheRetention400: promptCacheRetention400Models.has(modelKey(model)), sessionAffinity403: sendSessionAffinityHeaders403Models.has(modelKey(model)), openAISdkHeader403: openAISdkHeader403Models.has(modelKey(model)) });
+              const diagnosis = buildDoctorDiagnosis(model, { promptCacheRetention400: promptCacheRetention400Models.has(modelKey(model)), anthropicTtlOrderError: anthropicTtlOrderErrorModels.has(modelKey(model)), sessionAffinity403: sendSessionAffinityHeaders403Models.has(modelKey(model)), openAISdkHeader403: openAISdkHeader403Models.has(modelKey(model)) });
               const adapter = selectAdapterForModel(model);
               const sk = model ? sessionModelKey(model) : undefined;
               const statsState = model ? cacheStatsTotalsByModel[modelKey(model)] : undefined;
@@ -7539,7 +7651,7 @@ export default function (pi: ExtensionAPI) {
               cmdCtx.ui.notify("No active model selected. Select a model first with /model or pi --model.", "warning");
               return;
             }
-            const suggestion = buildFixSuggestion(model);
+            const suggestion = buildCommandFixSuggestion(model);
             if (!suggestion) {
               const key = modelKey(model);
               cmdCtx.ui.notify(`✅ Nothing to fix for "${key}". Compat already configured.`, "info");
@@ -7567,7 +7679,13 @@ export default function (pi: ExtensionAPI) {
               return;
             }
 
-            const menuDecision = chooseFixPlacement(originalText, location, suggestion.compatKeys, suggestion.providerLabel);
+            const menuDecision = chooseFixPlacement(
+              originalText,
+              location,
+              suggestion.compatKeys,
+              suggestion.providerLabel,
+              suggestion.forceModelLevel,
+            );
             const modifiedText = composeFixInsertion(originalText, location, suggestion.compatKeys, menuDecision.placement);
             const checkError = selfCheckFix(originalText, modifiedText, suggestion.providerLabel, suggestion.modelId, suggestion.compatKeys, menuDecision.placement);
             if (checkError !== null) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-cache-optimizer",
-  "version": "2.6.23",
+  "version": "2.6.24",
   "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",