pi-cache-optimizer 2.5.5 → 2.5.7

package/README.md

@@ -101,6 +101,42 @@ 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 only advises; it does not edit `models.json`.
 
+### Channels without a `models.json` provider entry
+
+Some Pi channels may be available even when there is no provider block in `~/.pi/agent/models.json` yet. Keep existing authentication as-is and do not copy credentials, tokens, or API keys. Add only cache/routing compatibility overrides in `models.json`.
+
+Provider-level minimal override:
+
+```json
+{
+  "providers": {
+    "your-provider-id": {
+      "compat": {
+        "sendSessionAffinityHeaders": true
+      }
+    }
+  }
+}
+```
+
+If only one model should change, use `modelOverrides`:
+
+```json
+{
+  "providers": {
+    "your-provider-id": {
+      "modelOverrides": {
+        "gpt-5.5": {
+          "compat": {
+            "sendSessionAffinityHeaders": true
+          }
+        }
+      }
+    }
+  }
+}
+```
+
 ## Footer stats
 
 Stats are read-only local counters stored at `~/.pi/agent/pi-cache-optimizer-stats.json` and scoped by Pi session + provider/model. They contain only dates and numeric counters — no API keys, prompts, payloads, headers, responses, or model output.

package/README.zh-CN.md

@@ -101,6 +101,42 @@ LiteLLM / OneAPI / NewAPI / 类 OpenRouter 渠道等第三方 `openai-completion
 - 对 DeepSeek 模型，Pi Mono 指南期望在支持时同时设置 `compat.requiresReasoningContentOnAssistantMessages: true` 和 `compat.thinkingFormat: "deepseek"`，再配合缓存 / session-affinity 相关 compat。
 - 本扩展只给建议，不会修改 `models.json`。
 
+### 没有 `models.json` provider entry 的渠道
+
+有些 Pi 渠道可用时，`~/.pi/agent/models.json` 里可能还没有对应 provider block。保留现有认证方式，不要复制 credential、token 或 API key。只在 `models.json` 里添加缓存 / 路由兼容覆盖。
+
+Provider 级最小 override：
+
+```json
+{
+  "providers": {
+    "your-provider-id": {
+      "compat": {
+        "sendSessionAffinityHeaders": true
+      }
+    }
+  }
+}
+```
+
+如果只想影响单个模型，用 `modelOverrides`：
+
+```json
+{
+  "providers": {
+    "your-provider-id": {
+      "modelOverrides": {
+        "gpt-5.5": {
+          "compat": {
+            "sendSessionAffinityHeaders": true
+          }
+        }
+      }
+    }
+  }
+}
+```
+
 ## Footer 统计
 
 统计是只读本地计数，保存在 `~/.pi/agent/pi-cache-optimizer-stats.json`，按 Pi session + provider/model 隔离。文件只包含日期和数字计数，不包含 API key、prompt、payload、headers、响应或模型输出。

package/index.ts

@@ -775,6 +775,19 @@ function isOpenAICompatibleApi(api: unknown): boolean {
   return value === "openai-completions" || value === "openai-responses";
 }
 
+function isOpenAICompatibleProxyApi(api: unknown): boolean {
+  return lower(api) === "openai-completions";
+}
+
+function isResponsesPromptRewriteBypassApi(api: unknown): boolean {
+  const value = lower(api);
+  return value === "openai-codex-responses" || value === "openai-responses" || value === "azure-openai-responses";
+}
+
+function isMistralConversationsApi(api: unknown): boolean {
+  return lower(api) === "mistral-conversations";
+}
+
 function isOpenAIFamilyToken(token: string): boolean {
   return token.includes("gpt-") || token.includes("chatgpt") || OPENAI_REASONING_MODEL_PATTERN.test(token);
 }
@@ -1476,7 +1489,9 @@ function isNonEmptyString(value: unknown): boolean {
 
 function isOfficialOpenAIBaseUrl(model: PiModel): boolean {
   const value = lower(model.baseUrl).trim();
-  if (!value) return false;
+  if (!value) {
+    return lower(model.provider) === "openai";
+  }
 
   try {
     return new URL(value).hostname === "api.openai.com";
@@ -1490,7 +1505,7 @@ function describeMissingOpenAIFamilyProxyCompat(model: PiModel): string[] {
   const missing: string[] = [];
 
   if (!isOpenAIFamilyModel(model)) return missing;
-  if (lower(model.api) !== "openai-completions") return missing;
+  if (!isOpenAICompatibleProxyApi(model.api)) return missing;
   if (isOfficialOpenAIBaseUrl(model)) return missing;
 
   if (compat.supportsLongCacheRetention !== true) {
@@ -1513,7 +1528,7 @@ function describeMissingOpenAICompatibleProxyCompat(model: PiModel): string[] {
   const compat = getCompat(model);
   const missing: string[] = [];
 
-  if (lower(model.api) !== "openai-completions") return missing;
+  if (!isOpenAICompatibleProxyApi(model.api)) return missing;
   if (isOfficialOpenAIBaseUrl(model)) return missing;
 
   if (compat.supportsLongCacheRetention !== true) {
@@ -1538,7 +1553,76 @@ function getPromptCacheRetentionUnsupportedHint(): string {
   return "If this channel returns `400 Unsupported parameter: prompt_cache_retention`, remove/avoid `supportsLongCacheRetention`; this extension does not write that field directly, but Pi may send it when long retention is requested and compat says the proxy supports it.";
 }
 
-function appendOpenAIProxyCompatAdviceLines(lines: string[], missing: string[], options: { includeJsonIntro?: boolean } = {}): void {
+function hasPromptCacheRetentionUnsupportedSignal(headers: Record<string, string> | undefined): boolean {
+  if (!headers) return false;
+
+  const normalized = Object.entries(headers)
+    .map(([key, value]) => `${lower(key)}: ${lower(value)}`)
+    .join("\n");
+  if (!normalized.includes("prompt_cache_retention")) return false;
+
+  return [
+    "unsupported parameter",
+    "unsupported_parameter",
+    "unknown parameter",
+    "not supported",
+    "unsupported field",
+  ].some((needle) => normalized.includes(needle));
+}
+
+type CompatAdvicePlacement = {
+  providerLabel?: string;
+  modelId?: string;
+};
+
+function buildProviderCompatOverride(providerLabel: string, compat: Record<string, unknown>): Record<string, unknown> {
+  return {
+    providers: {
+      [providerLabel]: {
+        compat,
+      },
+    },
+  };
+}
+
+function buildModelCompatOverride(providerLabel: string, modelId: string, compat: Record<string, unknown>): Record<string, unknown> {
+  return {
+    providers: {
+      [providerLabel]: {
+        modelOverrides: {
+          [modelId]: {
+            compat,
+          },
+        },
+      },
+    },
+  };
+}
+
+function appendCredentialSafeProviderGuidance(lines: string[], placement: CompatAdvicePlacement, compatSuggestion: Record<string, unknown>): void {
+  const providerLabel = placement.providerLabel;
+  if (!providerLabel) return;
+
+  lines.push("");
+  lines.push("If this channel has no models.json provider entry yet:");
+  lines.push("- Keep existing authentication as-is; do not copy credentials, tokens, or API keys.");
+  lines.push(`- Add only cache/routing compat overrides in ${getModelsJsonDisplayPath()}.`);
+
+  if (Object.keys(compatSuggestion).length === 0) {
+    lines.push("- No safe copyable override is available for the missing flags shown above.");
+    return;
+  }
+
+  lines.push("Provider-level minimal override:");
+  lines.push(JSON.stringify(buildProviderCompatOverride(providerLabel, compatSuggestion), null, 2));
+
+  if (placement.modelId) {
+    lines.push("Single-model override (use this if only this model should change):");
+    lines.push(JSON.stringify(buildModelCompatOverride(providerLabel, placement.modelId, compatSuggestion), null, 2));
+  }
+}
+
+function appendOpenAIProxyCompatAdviceLines(lines: string[], missing: string[], options: { includeJsonIntro?: boolean } & CompatAdvicePlacement = {}): void {
   const suggestion = buildSafeOpenAIProxyCompatSuggestion(missing);
   const hasSafeSuggestion = Object.keys(suggestion).length > 0;
 
@@ -1558,6 +1642,8 @@ function appendOpenAIProxyCompatAdviceLines(lines: string[], missing: string[],
     lines.push("- supportsLongCacheRetention: optional. Enable only after your endpoint/proxy explicitly supports OpenAI long prompt cache retention.");
     lines.push(`- ${getPromptCacheRetentionUnsupportedHint()}`);
   }
+
+  appendCredentialSafeProviderGuidance(lines, options, suggestion);
 }
 
 /**
@@ -1577,6 +1663,7 @@ function buildOpenAIProxyCompatWarningText(key: string, missing: string[]): stri
   // If no slash is found, fall back to the key itself.
   const slashIdx = key.indexOf("/");
   const providerLabel = slashIdx > 0 ? key.slice(0, slashIdx) : key;
+  const modelId = slashIdx > 0 ? key.slice(slashIdx + 1) : undefined;
 
   const modelsJsonPath = getModelsJsonDisplayPath();
   const lines: string[] = [
@@ -1585,7 +1672,7 @@ function buildOpenAIProxyCompatWarningText(key: string, missing: string[]): stri
     ``,
   ];
 
-  appendOpenAIProxyCompatAdviceLines(lines, missing);
+  appendOpenAIProxyCompatAdviceLines(lines, missing, { providerLabel, modelId });
 
   return lines.join("\n");
 }
@@ -1647,7 +1734,7 @@ function buildDeepSeekCompatSuggestion(missing: string[]): Record<string, unknow
   return suggestion;
 }
 
-function appendDeepSeekCompatAdviceLines(lines: string[], missing: string[]): void {
+function appendDeepSeekCompatAdviceLines(lines: string[], missing: string[], placement: CompatAdvicePlacement = {}): void {
   const suggestion = buildDeepSeekCompatSuggestion(missing);
   if (Object.keys(suggestion).length > 0) {
     lines.push("Recommended DeepSeek compat snippet:");
@@ -1669,11 +1756,14 @@ function appendDeepSeekCompatAdviceLines(lines: string[], missing: string[]): vo
   if (missing.includes("supportsLongCacheRetention")) {
     lines.push("- supportsLongCacheRetention: enable for DeepSeek-compatible endpoints that support long cache retention.");
   }
+
+  appendCredentialSafeProviderGuidance(lines, placement, suggestion);
 }
 
 function buildDeepSeekCompatWarningText(key: string, missing: string[]): string {
   const slashIdx = key.indexOf("/");
   const providerLabel = slashIdx > 0 ? key.slice(0, slashIdx) : key;
+  const modelId = slashIdx > 0 ? key.slice(slashIdx + 1) : undefined;
   const modelsJsonPath = getModelsJsonDisplayPath();
   const lines: string[] = [
     `💡 pi-cache-optimizer: ${key} is DeepSeek-like but merged compat lacks ${missing.join(" and ")}.`,
@@ -1681,7 +1771,7 @@ function buildDeepSeekCompatWarningText(key: string, missing: string[]): string
     "",
   ];
 
-  appendDeepSeekCompatAdviceLines(lines, missing);
+  appendDeepSeekCompatAdviceLines(lines, missing, { providerLabel, modelId });
 
   return lines.join("\n");
 }
@@ -3001,6 +3091,29 @@ async function readPersistedCacheStats(): Promise<CacheStatsState | undefined> {
   return undefined;
 }
 
+function filterRestorableStatsForSession(
+  persisted: CacheStatsState | undefined,
+  currentSessionHash?: string,
+): Record<string, CacheStats> {
+  if (!persisted || !currentSessionHash) return {};
+
+  const prefix = `${currentSessionHash}:`;
+  const filteredModelStats: Record<string, CacheStats> = {};
+  for (const [fullKey, stats] of Object.entries(persisted.statsByModel)) {
+    if (fullKey.startsWith(prefix)) {
+      filteredModelStats[fullKey] = stats;
+    } else if (!fullKey.includes(":")) {
+      // Legacy v3-style key without session hash — migrate to current session.
+      filteredModelStats[`${currentSessionHash}:${fullKey}`] = stats;
+    } else if (fullKey.startsWith("_nosession:")) {
+      // Transitional _nosession bucket — migrate to current session.
+      filteredModelStats[`${currentSessionHash}:${fullKey.slice("_nosession:".length)}`] = stats;
+    }
+  }
+
+  return filteredModelStats;
+}
+
 /**
  * The closure-internal writer. Since the closure has access to currentSessionHash,
  * it passes the hash and statsByModel here. This function wraps them in the v4
@@ -3128,7 +3241,7 @@ async function writePersistedCacheStats(state: CacheStatsState, currentSessionHa
 
 
 function isCompatCheckApplicable(model: PiModel): boolean {
-  return lower(model.api) === "openai-completions" && !isOfficialOpenAIBaseUrl(model);
+  return isOpenAICompatibleProxyApi(model.api) && !isOfficialOpenAIBaseUrl(model);
 }
 
 function isPromptCacheRetention400Applicable(model: PiModel): boolean {
@@ -3163,10 +3276,10 @@ function describeRouterChannelDiagnostics(model: PiModel): string[] {
   const baseUrl = lower(model.baseUrl || "");
   const provider = lower(model.provider);
 
-  // Only OpenAI-compatible APIs are applicable for router/channel diagnostics.
-  // Custom transports like kiro-api, anthropic-messages, bedrock-converse-stream
-  // or non-OpenAI APIs are excluded.
-  if (api !== "openai-completions" && api !== "openai-responses") {
+  // Router/channel diagnostics only apply to OpenAI-compatible proxy APIs.
+  // Native APIs like mistral-conversations, azure-openai-responses,
+  // anthropic-messages, or bedrock-converse-stream are intentionally excluded.
+  if (api === "azure-openai-responses" || isMistralConversationsApi(api) || !isOpenAICompatibleApi(api)) {
     return notes;
   }
 
@@ -3305,6 +3418,33 @@ function describeRouterChannelDiagnostics(model: PiModel): string[] {
   return notes;
 }
 
+function getCompatCheckNotApplicableLines(model: PiModel): string[] {
+  const api = lower(model.api);
+
+  if (isMistralConversationsApi(api)) {
+    return [
+      "ℹ️ Compat check not applicable for this model.",
+      "   Native Mistral `mistral-conversations` uses provider-native transport; OpenAI-compatible proxy compat flags do not apply.",
+    ];
+  }
+
+  if (api === "azure-openai-responses") {
+    return [
+      "ℹ️ Compat check not applicable for this model.",
+      "   Native Azure OpenAI Responses uses the Responses transport; OpenAI-compatible proxy compat flags do not apply.",
+    ];
+  }
+
+  if (api === "openai-codex-responses" || (api === "openai-responses" && isOfficialOpenAIBaseUrl(model))) {
+    return [
+      "ℹ️ Compat check not applicable for this model.",
+      "   Native Responses transports already use Pi core request handling; OpenAI-compatible proxy compat flags do not apply.",
+    ];
+  }
+
+  return ["ℹ️ Compat check not applicable for this model."];
+}
+
 function buildDoctorDiagnosis(model: PiModel, options: { promptCacheRetention400?: boolean } = {}): string {
   const lines: string[] = [];
   lines.push(`Provider: ${model.provider}`);
@@ -3326,14 +3466,14 @@ function buildDoctorDiagnosis(model: PiModel, options: { promptCacheRetention400
     const modelsJsonPath = getModelsJsonDisplayPath();
     lines.push(`Edit ${modelsJsonPath} -> providers["${providerLabel}"] -> compat (same level as baseUrl/api/apiKey/models).`);
     if (deepSeekCompatApplicable) {
-      appendDeepSeekCompatAdviceLines(lines, missing);
+      appendDeepSeekCompatAdviceLines(lines, missing, { providerLabel, modelId: model.id });
     } else {
-      appendOpenAIProxyCompatAdviceLines(lines, missing);
+      appendOpenAIProxyCompatAdviceLines(lines, missing, { providerLabel, modelId: model.id });
     }
   } else if (deepSeekCompatApplicable || isCompatCheckApplicable(model)) {
     lines.push("✅ Compat fully configured.");
   } else {
-    lines.push("ℹ️ Compat check not applicable for this model.");
+    lines.push(...getCompatCheckNotApplicableLines(model));
   }
 
   if (isPromptCacheRetention400Applicable(model)) {
@@ -3507,9 +3647,9 @@ function buildCompatDiagnosis(model: PiModel): string | undefined {
     lines.push(`Edit ${modelsJsonPath} -> providers["${providerLabel}"] -> compat`);
     lines.push(`(at the same level as baseUrl/api/apiKey/models).`);
     if (deepSeekCompatApplicable) {
-      appendDeepSeekCompatAdviceLines(lines, missing);
+      appendDeepSeekCompatAdviceLines(lines, missing, { providerLabel, modelId: model.id });
     } else {
-      appendOpenAIProxyCompatAdviceLines(lines, missing);
+      appendOpenAIProxyCompatAdviceLines(lines, missing, { providerLabel, modelId: model.id });
     }
   }
 
@@ -3521,7 +3661,7 @@ function buildCompatDiagnosis(model: PiModel): string | undefined {
         lines.push(getPromptCacheRetentionUnsupportedHint());
       }
     } else {
-      lines.push("ℹ️ Compat check not applicable for this model.");
+      lines.push(...getCompatCheckNotApplicableLines(model));
     }
     lines.push("");
   }
@@ -3558,6 +3698,9 @@ export const __internals_for_tests = {
   isNonEmptyString,
   shouldInjectOpenAIPromptCacheKey,
   isOpenAICompatibleApi,
+  isOpenAICompatibleProxyApi,
+  isResponsesPromptRewriteBypassApi,
+  isMistralConversationsApi,
   isOpenAIFamilyModel,
   isOpenAIFamilyAssistantMessage,
   isOpenAIFamilyToken,
@@ -3573,6 +3716,7 @@ export const __internals_for_tests = {
   isOfficialOpenAIBaseUrl,
   isCompatCheckApplicable,
   isPromptCacheRetention400Applicable,
+  hasPromptCacheRetentionUnsupportedSignal,
   // Non-GPT OpenAI-compatible model detection
   isKimiLikeModel,
   isKimiLikeAssistantMessage,
@@ -3689,8 +3833,10 @@ export const __internals_for_tests = {
   getAssistantMessageModelTokenValues,
   getCompat,
   modelKey,
-  // Platform-friendly path helper
+  // Platform-friendly path helpers
   getModelsJsonDisplayPath,
+  buildProviderCompatOverride,
+  buildModelCompatOverride,
   captureCacheRetentionEnv,
   requestLongCacheRetention,
   restoreCacheRetentionEnv,
@@ -3727,6 +3873,7 @@ export const __internals_for_tests = {
   hashSessionId,
   makeSessionModelKey,
   modelKeyFromSessionKey,
+  filterRestorableStatsForSession,
   // Persistence helpers (for reload/reset tests)
   mergeCacheSessions,
   writePersistedCacheStats,
@@ -3753,6 +3900,15 @@ export default function (pi: ExtensionAPI) {
   /** In-memory recent usage samples per model key (not persisted, cleared on reload). */
   const recentSamplesByModelKey = new Map<string, CacheUsageSample[]>();
 
+  function syncSessionHash(ctx: Pick<ExtensionContext, "sessionManager">): void {
+    const sid = ctx.sessionManager.getSessionId();
+    if (sid && (sid !== currentSessionId || !currentSessionHashSet)) {
+      currentSessionId = sid;
+      currentSessionHash = hashSessionId(sid);
+      currentSessionHashSet = true;
+    }
+  }
+
   /**
    * Build a session-scoped stats key from the current session hash + model key.
    * Returns `${sessionHash}:${provider}/${id}`.
@@ -3909,13 +4065,7 @@ export default function (pi: ExtensionAPI) {
   }
 
   async function restoreCacheStats(reason: string, ctx: ExtensionContext): Promise<void> {
-    // Set session id on first load and on reload (same session).
-    const sid = ctx.sessionManager.getSessionId();
-    if (sid && (sid !== currentSessionId || !currentSessionHashSet)) {
-      currentSessionId = sid;
-      currentSessionHash = hashSessionId(sid);
-      currentSessionHashSet = true;
-    }
+    syncSessionHash(ctx);
 
     if (reason === "reload") {
       // /reload: preserve session-scoped stats (same session hash).
@@ -3927,73 +4077,31 @@ export default function (pi: ExtensionAPI) {
       clearRecentSamples();
 
       const persisted = await readPersistedCacheStats();
-      if (persisted && currentSessionHash) {
-        const prefix = `${currentSessionHash}:`;
-        const filteredModelStats: Record<string, CacheStats> = {};
-        for (const [fullKey, stats] of Object.entries(persisted.statsByModel)) {
-          if (fullKey.startsWith(prefix)) {
-            // Current session's data
-            filteredModelStats[fullKey] = stats;
-          } else if (!fullKey.includes(":")) {
-            // Legacy v3-style key without session hash — migrate to current session
-            filteredModelStats[`${currentSessionHash}:${fullKey}`] = stats;
-          } else if (fullKey.startsWith("_nosession:")) {
-            // _nosession migration remnant from old-path v4 write — migrate to current session
-            filteredModelStats[`${currentSessionHash}:${fullKey.slice("_nosession:".length)}`] = stats;
-          }
-        }
-        cacheStatsByModel = filteredModelStats;
-        cacheStatsLegacyFamily = persisted.legacyFamily;
-      } else if (persisted) {
-        cacheStatsByModel = persisted.statsByModel;
-        cacheStatsLegacyFamily = persisted.legacyFamily;
-      } else {
-        cacheStatsByModel = {};
-        cacheStatsLegacyFamily = emptyAllCacheStats();
-      }
+      cacheStatsByModel = filterRestorableStatsForSession(
+        persisted,
+        currentSessionHashSet ? currentSessionHash : undefined,
+      );
+      cacheStatsLegacyFamily = persisted?.legacyFamily ?? emptyAllCacheStats();
 
       await rollOverStatsIfNeeded(ctx);
       return;
     }
 
     // First load / process start: read persisted stats and filter for
-    // this session's entries. If the session has no persisted data yet,
-    // start fresh.
+    // this session's entries. If the session hash is unavailable, start
+    // fresh instead of loading all persisted session buckets.
     const persisted = await readPersistedCacheStats();
-    if (persisted && currentSessionHash) {
-      const prefix = `${currentSessionHash}:`;
-      const filteredModelStats: Record<string, CacheStats> = {};
-      for (const [fullKey, stats] of Object.entries(persisted.statsByModel)) {
-        if (fullKey.startsWith(prefix)) {
-          // Current session's data — load it.
-          filteredModelStats[fullKey] = stats;
-        } else if (!fullKey.includes(":")) {
-          // Legacy v3-style key without session hash (e.g. "otokapi/gpt-5.5").
-          // Migrate to current session by prefixing with the session hash.
-          filteredModelStats[`${currentSessionHash}:${fullKey}`] = stats;
-        } else if (fullKey.startsWith("_nosession:")) {
-          // _nosession migration remnant from old-path v4 write — migrate to current session
-          filteredModelStats[`${currentSessionHash}:${fullKey.slice("_nosession:".length)}`] = stats;
-        }
-        // Other sessions' entries are preserved in the file but not loaded
-        // into memory; they'll be rewritten on next persist.
-      }
-      cacheStatsByModel = filteredModelStats;
-      cacheStatsLegacyFamily = persisted.legacyFamily;
-    } else if (persisted) {
-      // Persisted data exists but no session hash set yet.
-      // This shouldn't normally happen — use the data as-is.
-      cacheStatsByModel = persisted.statsByModel;
-      cacheStatsLegacyFamily = persisted.legacyFamily;
-    } else {
-      cacheStatsByModel = {};
-      cacheStatsLegacyFamily = emptyAllCacheStats();
-    }
+    cacheStatsByModel = filterRestorableStatsForSession(
+      persisted,
+      currentSessionHashSet ? currentSessionHash : undefined,
+    );
+    cacheStatsLegacyFamily = persisted?.legacyFamily ?? emptyAllCacheStats();
     lastStatusText = undefined;
     await rollOverStatsIfNeeded(ctx);
   }
 
   async function publishStatus(ctx: ExtensionContext, model: PiModel | undefined = ctx.model): Promise<void> {
+    syncSessionHash(ctx);
     await rollOverStatsIfNeeded(ctx);
 
     const adapter = selectAdapterForModel(model);
@@ -4065,7 +4173,7 @@ export default function (pi: ExtensionAPI) {
 
   pi.on("before_agent_start", async (event, _ctx) => {
     // ────────────────────────────────────────────────────────────────
-    // OpenAI Responses API bypass (codex-responses + responses)
+    // OpenAI Responses-family bypass (codex-responses + responses + azure responses)
     //
     // OpenAI's Responses API endpoints — both the Codex backend
     // (openai-codex-responses, chatgpt.com) and the public
@@ -4091,11 +4199,8 @@ export default function (pi: ExtensionAPI) {
     // that use openai-completions are unaffected.
     // ────────────────────────────────────────────────────────────────
     const model = _ctx.model;
-    if (model) {
-      const api = lower(model.api);
-      if (api === "openai-codex-responses" || api === "openai-responses") {
-        return {};
-      }
+    if (model && isResponsesPromptRewriteBypassApi(model.api)) {
+      return {};
     }
 
     if (!runtimeOptimizerEnabled) return {};
@@ -4161,6 +4266,7 @@ export default function (pi: ExtensionAPI) {
     if (!runtimeOptimizerEnabled || !model) return;
     if (event.status !== 400) return;
     if (!isPromptCacheRetention400Applicable(model)) return;
+    if (!hasPromptCacheRetentionUnsupportedSignal(event.headers)) return;
 
     const key = modelKey(model);
     promptCacheRetention400Models.add(key);
@@ -4175,6 +4281,7 @@ export default function (pi: ExtensionAPI) {
   });
 
   pi.on("message_end", async (event, ctx) => {
+    syncSessionHash(ctx);
     const adapter = selectAdapterForAssistantMessage(event.message, ctx.model);
     if (!adapter) return;
 
@@ -4221,6 +4328,7 @@ export default function (pi: ExtensionAPI) {
   pi.registerCommand("cache-optimizer", {
     description: "Diagnose Pi cache configuration",
     handler: async (args: string, cmdCtx) => {
+      syncSessionHash(cmdCtx);
       const model = cmdCtx.model;
       const subcommand = args.trim().toLowerCase().split(/\s+/)[0] || "help";
 
@@ -4274,7 +4382,7 @@ export default function (pi: ExtensionAPI) {
           cmdCtx.ui.notify(
             isDeepSeekCompatCheckApplicable(model) || isCompatCheckApplicable(model)
               ? "✅ Compat fully configured."
-              : "ℹ️ Compat check not applicable for this model.",
+              : getCompatCheckNotApplicableLines(model).join("\n"),
             "info",
           );
         }
@@ -4372,7 +4480,7 @@ export default function (pi: ExtensionAPI) {
                 cmdCtx.ui.notify(
                   isDeepSeekCompatCheckApplicable(model) || isCompatCheckApplicable(model)
                     ? "✅ Compat fully configured."
-                    : "ℹ️ Compat check not applicable for this model.",
+                    : getCompatCheckNotApplicableLines(model).join("\n"),
                   "info",
                 );
               }
@@ -4425,6 +4533,8 @@ export default function (pi: ExtensionAPI) {
             diagnosis.push(`✅ Active model "${displayKey}": compat fully configured.`);
           } else {
             diagnosis.push(`ℹ️ Active model "${displayKey}": compat check not applicable.`);
+            const detailLines = getCompatCheckNotApplicableLines(model).slice(1);
+            for (const line of detailLines) diagnosis.push(line);
           }
         } else {
           diagnosis.push("No active model selected.");

package/package.json

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