pi-cache-optimizer 2.4.4 → 2.4.5

package/README.md

@@ -62,7 +62,7 @@ This extension is pure Node.js — no shell exec, no native bindings, no platfor
 | Windows | Works through the bash shell Pi requires on Windows (Git Bash, Cygwin, MSYS2, or WSL). See Pi's [Windows setup](https://github.com/earendil-works/pi-coding-agent/blob/main/docs/windows.md). |
 | Termux / Android | Works inside Pi's Termux setup. |
 
-State files under `~/.pi/agent/` are resolved via Node's `os.homedir()`, so on Windows the path automatically expands to `C:\Users\<you>\.pi\agent\...`. All shell snippets in this README are bash, matching the shell Pi runs in on every supported platform; no PowerShell or `cmd.exe` translation is needed when commands are executed inside (or for) Pi.
+State files under `~/.pi/agent/` are resolved via Node's `os.homedir()`, so on Windows the path automatically expands to `C:\Users\<you>\.pi\agent\...`. The extension's compat warnings, `/cache-optimizer doctor`, and `/cache-optimizer compat` show the platform-appropriate path automatically (`~/.pi/agent/models.json` on Linux/macOS, `%USERPROFILE%\.pi\agent\models.json` on Windows). All shell snippets in this README are bash, matching the shell Pi runs in on every supported platform; no PowerShell or `cmd.exe` translation is needed when commands are executed inside (or for) Pi.
 
 ## Quickstart
 
@@ -126,6 +126,64 @@ rm -f ~/.pi/agent/deepseek-cache-optimizer-stats.json
 
 
 
+## Adding an OpenAI-compatible proxy channel
+
+When adding a third-party OpenAI-compatible proxy provider (e.g. `otokapi`, `cafecode`,
+OpenRouter, etc.) to `~/.pi/agent/models.json`, the `compat` flags for cache optimization
+are NOT required for the model to work — but they dramatically improve cache durability.
+
+### Minimal provider config template
+
+```jsonc
+{
+  "providers": {
+    "your-provider-id": {
+      "api": "openai-completions",  // or "openai-responses"
+      "baseUrl": "https://your-proxy.example.com/v1",
+      "apiKey": "your-api-key",
+      "models": {
+        "gpt-5.5": {
+          "id": "gpt-5.5",
+          "name": "GPT 5.5",
+          "contextWindowTokens": 128000,
+          "maxOutputTokens": 8192,
+          "thinking": {
+            // Use the thinking modes your proxy actually supports.
+            // Pi maps --thinking <level> to tokens via thinkingLevelMap.
+            // The template below keeps each level distinct — DO NOT
+            // map everything to "xhigh". Your proxy may not support
+            // all levels; remove unsupported ones or test each.
+            "thinkingLevelMap": {
+              "off": null,
+              "minimal": "minimal",
+              "low": "low",
+              "medium": "medium",
+              "high": "high",
+              "xhigh": "xhigh"
+            }
+          },
+          "compat": {
+            "supportsLongCacheRetention": true,
+            "sendSessionAffinityHeaders": true
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+Key points:
+
+- `thinkingLevelMap` keeps distinct levels. If your proxy does not support a particular
+  level (e.g. `minimal`), remove that entry or set to `null`. Do **not** collapse all
+  levels to `"xhigh"` — that defeats user control over reasoning effort.
+- `compat` flags help Pi request longer cache retention and send session-affinity
+  headers for proxy-side cache locality. Only enable them if your proxy supports them.
+- The extension detects model families by `id`/`name` strings, not by provider id,
+  base URL, or API type. Use recognizable model ids (e.g. `gpt-5.5`, `kimi-k2.5`) for
+  correct stats adapter selection.
+
 ## Footer cache stats
 
 The Pi footer displays stats for the **active model family** only, for example:
@@ -166,10 +224,18 @@ Reset behavior:
 
 For direct DeepSeek or DeepSeek-like OpenAI-compatible proxies, configure the provider or model `compat` like this:
 
-```json
+The `compat` block goes inside your provider object in `~/.pi/agent/models.json`, at
+the same level as `baseUrl`, `api`, `apiKey`, and `models`:
+
+```jsonc
 {
   "providers": {
     "deepseek": {
+      "api": "openai-completions",
+      "baseUrl": "https://api.deepseek.com/v1",
+      "apiKey": "sk-...",
+      "models": { /* ... */ },
+      // 👇 compat goes here, NOT inside models
       "compat": {
         "thinkingFormat": "deepseek",
         "supportsLongCacheRetention": true,
@@ -191,6 +257,63 @@ For Claude/Anthropic models behind an OpenAI-compatible endpoint, the extension
 
 > Reminder: only enable session-affinity headers or cache-control compat when your endpoint or proxy supports them.
 
+## Diagnostic command
+
+The extension registers a Pi command `/cache-optimizer` for interactive diagnosis.
+
+```
+/cache-optimizer              — interactive menu (or text help when no UI)
+/cache-optimizer doctor        — show provider, model, API, base URL, compat status
+/cache-optimizer compat        — show compat suggestion with edit instructions
+```
+
+When run without arguments, `/cache-optimizer` shows an interactive selection menu
+(Doctor / Compat / Cancel) when the Pi UI supports it (`ctx.ui.select`). In
+non-interactive terminals, it falls back to text help with current model compat
+status.
+
+### `/cache-optimizer doctor`
+
+Displays the active model's provider, model id, name, API type, base URL, current
+`compat` flags, and any missing cache/session-affinity flags. If flags are missing,
+it also shows a copyable JSON snippet and the exact edit location.
+
+When all compat flags are present and applicable (third-party `openai-completions`
+proxy), the output shows `✅ Compat fully configured.` For models where the
+compat check does not apply (official OpenAI, non-`openai-completions` APIs,
+custom transports), it shows `ℹ️ Compat check not applicable for this model.`:
+
+```text
+Provider: otokapi
+Model:    gpt-5.5
+API:      openai-completions
+Base URL: https://otokapi.example.com/v1
+Compat:   {}
+⚠️  Missing compat flags: supportsLongCacheRetention, sendSessionAffinityHeaders
+Edit ~/.pi/agent/models.json -> providers["otokapi"] -> compat (same level as baseUrl/api/apiKey/models):
+{
+  "supportsLongCacheRetention": true,
+  "sendSessionAffinityHeaders": true
+}
+```
+
+### `/cache-optimizer compat`
+
+Shows only the compat suggestion for the active model, including file path,
+provider path, and copyable JSON snippet. When no flags are missing, it shows
+`✅ Compat fully configured.` if the model is an applicable third-party proxy,
+or `ℹ️ Compat check not applicable for this model.` otherwise.
+
+### Security
+
+The command reads only metadata exposed by Pi through `ctx.model`:
+provider, id, name, api, baseUrl, compat. It does NOT read or expose:
+- API keys or environment secrets
+- Request/response payloads
+- Prompts or model outputs
+- HTTP headers
+- Raw `~/.pi/agent/models.json` content
+
 ## How it works
 
 Provider caches are usually based on exact or near-exact prefix matching. Pi's system prompt contains stable content that is likely shared across sessions (tools, skills, guidelines) and dynamic content that changes frequently (git status, task context).

package/README.zh-CN.md

@@ -65,7 +65,7 @@ Generic OpenAI-compatible 代理**不会**仅因为使用 OpenAI 形状 API 或
 | Windows | 通过 Pi 在 Windows 下要求的 bash shell 运行（Git Bash、Cygwin、MSYS2 或 WSL）。详见 Pi 的 [Windows setup](https://github.com/earendil-works/pi-coding-agent/blob/main/docs/windows.md)。 |
 | Termux / Android | 在 Pi 的 Termux 环境中可用。 |
 
-状态文件 `~/.pi/agent/` 通过 Node 的 `os.homedir()` 解析，所以在 Windows 上会自动展开为 `C:\Users\<你>\.pi\agent\...`。本文档中所有 shell 命令均使用 bash 语法，与 Pi 在每个受支持平台下运行的 shell 一致；只要在 Pi 内（或为 Pi 而执行）运行，就**不需要**改写为 PowerShell 或 `cmd.exe` 形式。
+状态文件 `~/.pi/agent/` 通过 Node 的 `os.homedir()` 解析，所以在 Windows 上会自动展开为 `C:\Users\<你>\.pi\agent\...`。扩展的 compat 提醒、`/cache-optimizer doctor` 和 `/cache-optimizer compat` 会自动显示适合当前平台的路径（Linux/macOS 上显示 `~/.pi/agent/models.json`，Windows 上显示 `%USERPROFILE%\.pi\agent\models.json`）。本文档中所有 shell 命令均使用 bash 语法，与 Pi 在每个受支持平台下运行的 shell 一致；只要在 Pi 内（或为 Pi 而执行）运行，就**不需要**改写为 PowerShell 或 `cmd.exe` 形式。
 
 ## 快速开始
 
@@ -129,6 +129,56 @@ rm -f ~/.pi/agent/deepseek-cache-optimizer-stats.json
 
 
 
+## 添加 OpenAI-compatible 代理渠道
+
+当在 `~/.pi/agent/models.json` 中添加第三方 OpenAI-compatible 代理 provider（例如 `otokapi`、`cafecode`、OpenRouter 等）时，缓存优化的 `compat` 标志对模型正常使用不是必需的，但它们能显著提高缓存持久性。
+
+### 最小 provider 配置模板
+
+```jsonc
+{
+  "providers": {
+    "your-provider-id": {
+      "api": "openai-completions",  // 或 "openai-responses"
+      "baseUrl": "https://your-proxy.example.com/v1",
+      "apiKey": "your-api-key",
+      "models": {
+        "gpt-5.5": {
+          "id": "gpt-5.5",
+          "name": "GPT 5.5",
+          "contextWindowTokens": 128000,
+          "maxOutputTokens": 8192,
+          "thinking": {
+            // 使用你的代理实际支持的 thinking 级别。
+            // Pi 通过 thinkingLevelMap 将 --thinking <level> 映射为 token。
+            // 下面模板保持各级别独立 —— 不要全部映射为 "xhigh"。
+            // 你的代理可能不支持所有级别；移除不支持的或逐个测试。
+            "thinkingLevelMap": {
+              "off": null,
+              "minimal": "minimal",
+              "low": "low",
+              "medium": "medium",
+              "high": "high",
+              "xhigh": "xhigh"
+            }
+          },
+          "compat": {
+            "supportsLongCacheRetention": true,
+            "sendSessionAffinityHeaders": true
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+关键点：
+
+- `thinkingLevelMap` 保持不同的 level 独立。如果你的代理不支持某个级别（例如 `minimal`），请移除该条目或设为 `null`。**不要**将所有级别都映射为 `"xhigh"` —— 那会破坏用户对推理努力度的控制。
+- `compat` 标志帮助 Pi 请求更长的缓存保留时间，并通过发送 session-affinity headers 实现代理侧缓存本地性。仅在代理支持时才启用。
+- 扩展通过模型 `id`/`name` 字符串来检测模型家族，而不是通过 provider id、base URL 或 API 类型。请使用易识别的模型 id（例如 `gpt-5.5`、`kimi-k2.5`），以便正确匹配统计 adapter。
+
 ## 底部缓存统计
 
 Pi footer 只显示**当前活跃模型 family** 的统计，例如：
@@ -167,12 +217,19 @@ Gemini cache 1/2 · 0.18M/0.50M tok (36%)
 
 ## 建议的 compat 配置
 
-对直连 DeepSeek 或 DeepSeek-like OpenAI-compatible 代理，建议在对应 provider 或 model 的 `compat` 中配置：
+对直连 DeepSeek 或 DeepSeek-like OpenAI-compatible 代理，建议在对应 provider 或 model 的 `compat` 中配置。
+
+`compat` 块应该放在 `~/.pi/agent/models.json` 中 provider 对象内部，与 `baseUrl`、`api`、`apiKey`、`models` 同级：
 
-```json
+```jsonc
 {
   "providers": {
     "deepseek": {
+      "api": "openai-completions",
+      "baseUrl": "https://api.deepseek.com/v1",
+      "apiKey": "sk-...",
+      "models": { /* ... */ },
+      // 👇 compat 在此位置，而不是在 models 内部
       "compat": {
         "thinkingFormat": "deepseek",
         "supportsLongCacheRetention": true,
@@ -194,6 +251,51 @@ Gemini cache 1/2 · 0.18M/0.50M tok (36%)
 
 > 提醒：只有在 endpoint 或代理明确支持时，才建议启用 session-affinity headers 或 cache-control compat。
 
+## 诊断命令
+
+扩展注册了 Pi 命令 `/cache-optimizer` 用于交互式诊断。
+
+```
+/cache-optimizer              — 交互菜单（无 UI 时显示文字帮助）
+/cache-optimizer doctor        — 显示 provider、model、API、base URL、compat 状态
+/cache-optimizer compat        — 显示 compat 建议和编辑说明
+```
+
+不带参数时，当 Pi UI 支持时（`ctx.ui.select` 可用），`/cache-optimizer` 会显示交互选择菜单（Doctor / Compat / Cancel）。在非交互终端中，会回退到文字帮助和当前模型 compat 状态。
+
+### `/cache-optimizer doctor`
+
+显示当前模型的 provider、model id、名称、API 类型、base URL、当前 `compat` 标志以及缺少的缓存/session-affinity 标志。如果缺少标志，还会显示可复制的 JSON 片段和精确编辑位置。
+
+如果所有 compat 标志都已配置且适用（第三方 `openai-completions` 代理），输出显示 `✅ Compat fully configured.`。对于不适用 compat 检查的模型（官方 OpenAI、非 `openai-completions` API、custom transport），显示 `ℹ️ Compat check not applicable for this model.`：
+
+```text
+Provider: otokapi
+Model:    gpt-5.5
+API:      openai-completions
+Base URL: https://otokapi.example.com/v1
+Compat:   {}
+⚠️  Missing compat flags: supportsLongCacheRetention, sendSessionAffinityHeaders
+Edit ~/.pi/agent/models.json -> providers["otokapi"] -> compat (same level as baseUrl/api/apiKey/models):
+{
+  "supportsLongCacheRetention": true,
+  "sendSessionAffinityHeaders": true
+}
+```
+
+### `/cache-optimizer compat`
+
+仅显示当前模型的 compat 建议，包括文件路径、provider 路径和可复制 JSON 片段。当没有缺失标志时，如果模型是适用的第三方代理则显示 `✅ Compat fully configured.`，否则显示 `ℹ️ Compat check not applicable for this model.`。
+
+### 安全说明
+
+命令只读取 Pi 通过 `ctx.model` 暴露的元数据：provider、id、name、api、baseUrl、compat。它**不会**读取或暴露：
+- API key 或环境密钥
+- 请求/响应 payload
+- Prompt 或模型输出
+- HTTP headers
+- `~/.pi/agent/models.json` 的原始内容
+
 ## 原理
 
 Provider 缓存通常依赖精确或近似精确的前缀匹配。Pi 的 system prompt 包含跨会话稳定的内容（工具定义、技能、规范），也包含每次变化的动态内容（git status、当前任务）。

package/index.ts

@@ -48,6 +48,16 @@ const NO_PROMPT_REWRITE_ENV = "PI_CACHE_OPTIMIZER_NO_PROMPT_REWRITE";
 // persisted metrics.
 let promptTruncationDetected = false;
 
+// Timestamp (ms) of the most recent integrity truncation event.
+// Used by /cache-optimizer doctor to surface recovery guidance.
+// Reset to 0 on reload.
+let lastPromptIntegrityWarningAt = 0;
+
+/** Getter for lastPromptIntegrityWarningAt (exported for tests via __internals_for_tests). */
+function getLastPromptIntegrityWarningAt(): number {
+  return lastPromptIntegrityWarningAt;
+}
+
 // Minimum count of skills before compression is worth applying.
 // Below this, pi's verbose XML block is small enough that the overhead of
 // an additional one-line index isn't worth the loss of per-skill
@@ -548,6 +558,26 @@ function getCompat(model: PiModel | undefined): CacheCompat {
   return (model?.compat ?? {}) as CacheCompat;
 }
 
+/**
+ * Return a platform-friendly display path for `~/.pi/agent/models.json`.
+ *
+ * On Windows (platform starts with "win") the path is shown as
+ * `%USERPROFILE%\.pi\agent\models.json` to match Windows conventions.
+ * On all other platforms (Linux, macOS, etc.) it is shown as
+ * `~/.pi/agent/models.json` (the Unix-style tilde shorthand).
+ *
+ * This is a DISPLAY helper only. Actual path resolution is done by Pi
+ * (via Node `os.homedir()` + path.join), and this string is never used
+ * for I/O — only for warning/doctor/README text so that users on any
+ * platform see a copyable path they recognize.
+ */
+function getModelsJsonDisplayPath(platform: string = process.platform): string {
+  if (platform.startsWith("win")) {
+    return `%USERPROFILE%\\.pi\\agent\\models.json`;
+  }
+  return "~/.pi/agent/models.json";
+}
+
 function isEnabledEnv(value: string | undefined): boolean {
   if (!value) return false;
   const normalized = value.trim().toLowerCase();
@@ -994,9 +1024,15 @@ function buildOpenAIProxyCompatWarningText(key: string, missing: string[]): stri
     suggestion[flag] = true;
   }
 
+  // Extract provider id from the model key (e.g. "otokapi/gpt-5.5" -> "otokapi").
+  // 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 modelsJsonPath = getModelsJsonDisplayPath();
   const lines: string[] = [
     `💡 pi-cache-optimizer: ${key} is a third-party GPT/OpenAI-compatible proxy but merged compat lacks ${missing.join(" and ")}.`,
-    `Add under the model's compat in ~/.pi/agent/models.json (only if the endpoint supports them):`,
+    `Edit ${modelsJsonPath} -> providers["${providerLabel}"] -> compat (at the same level as baseUrl/api/apiKey/models):`,
     ``,
     JSON.stringify(suggestion, null, 2),
     ``,
@@ -1050,9 +1086,12 @@ const CACHE_PROVIDER_ADAPTERS: CacheProviderAdapter[] = [
       if (missing.length === 0) return undefined;
 
       const key = modelKey(model);
+      const slashIdx = key.indexOf("/");
+      const providerLabel = slashIdx > 0 ? key.slice(0, slashIdx) : key;
+      const modelsJsonPath = getModelsJsonDisplayPath();
       return (
         `💡 pi-cache-optimizer: ${key} is DeepSeek-like but merged compat lacks ${missing.join(" and ")}. ` +
-        "Proxies may reduce or hide cache hits; add these compat flags in ~/.pi/agent/models.json when the endpoint supports them."
+        `Proxies may reduce or hide cache hits. Edit ${modelsJsonPath} -> providers["${providerLabel}"] -> compat (at the same level as baseUrl/api/apiKey/models).`
       );
     },
   },
@@ -1519,6 +1558,76 @@ async function writePersistedCacheStats(state: CacheStatsState): Promise<void> {
 
 
 
+function isCompatCheckApplicable(model: PiModel): boolean {
+  return lower(model.api) === "openai-completions" && !isOfficialOpenAIBaseUrl(model);
+}
+
+function buildDoctorDiagnosis(model: PiModel): string {
+  const lines: string[] = [];
+  lines.push(`Provider: ${model.provider}`);
+  lines.push(`Model:    ${model.id}`);
+  if (model.name && model.name !== model.id) lines.push(`Name:     ${model.name}`);
+  lines.push(`API:      ${model.api}`);
+  lines.push(`Base URL: ${model.baseUrl || "(default)"}`);
+
+  const compat = getCompat(model);
+  lines.push(`Compat:   ${JSON.stringify(compat)}`);
+
+  const missing = describeMissingOpenAICompatibleProxyCompat(model);
+  if (missing.length > 0) {
+    lines.push(`⚠️  Missing compat flags: ${missing.join(", ")}`);
+    const key = modelKey(model);
+    const slashIdx = key.indexOf("/");
+    const providerLabel = slashIdx > 0 ? key.slice(0, slashIdx) : key;
+    const suggestion = Object.fromEntries(missing.map((f) => [f, true]));
+    const modelsJsonPath = getModelsJsonDisplayPath();
+    lines.push(`Edit ${modelsJsonPath} -> providers["${providerLabel}"] -> compat (same level as baseUrl/api/apiKey/models):`);
+    lines.push(JSON.stringify(suggestion, null, 2));
+  } else if (isCompatCheckApplicable(model)) {
+    lines.push("✅ Compat fully configured.");
+  } else {
+    lines.push("ℹ️ Compat check not applicable for this model.");
+  }
+
+  // ── Integrity diagnostics ──
+  if (lastPromptIntegrityWarningAt > 0) {
+    const ago = Date.now() - lastPromptIntegrityWarningAt;
+    const mins = Math.floor(ago / 60000);
+    if (mins < 5) {
+      lines.push("");
+      lines.push("⚠️  Recent prompt integrity issue detected:");
+      lines.push(`   Last detected ${mins > 0 ? `${mins} min` : `${Math.floor(ago / 1000)}s`} ago. The prompt reorder was`);
+      lines.push(`   skipped on that turn to preserve structural markers.`);
+      lines.push(`   Common causes: extension system prompt format change, substring collision.`);
+      lines.push(`   Steps:`);
+      lines.push(`     1. Run /reload to reset (may clear transient issues).`);
+      lines.push(`     2. Set PI_CACHE_OPTIMIZER_NO_PROMPT_REWRITE=1 & /reload to disable reorder.`);
+      lines.push(`     3. If persistent, file an issue with this doctor output.`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+function buildCompatDiagnosis(model: PiModel): string | undefined {
+  const missing = describeMissingOpenAICompatibleProxyCompat(model);
+  if (missing.length === 0) return undefined;
+
+  const key = modelKey(model);
+  const slashIdx = key.indexOf("/");
+  const providerLabel = slashIdx > 0 ? key.slice(0, slashIdx) : key;
+  const suggestion = Object.fromEntries(missing.map((f) => [f, true]));
+  const modelsJsonPath = getModelsJsonDisplayPath();
+  return (
+    `Active model: ${key}\n` +
+    `Missing: ${missing.join(", ")}\n\n` +
+    `Edit ${modelsJsonPath} -> providers["${providerLabel}"] -> compat` +
+    ` (at the same level as baseUrl/api/apiKey/models) and add:\n` +
+    `${JSON.stringify(suggestion, null, 2)}\n\n` +
+    `Only enable if your endpoint supports them.`
+  );
+}
+
 // Internal helpers exported only so the task verification script
 // (.trellis/tasks/.../verify.ts) can exercise them. They are not part of the
 // extension's public API; pi only invokes the default export below.
@@ -1576,6 +1685,14 @@ export const __internals_for_tests = {
   getAssistantMessageModelTokenValues,
   getCompat,
   modelKey,
+  // Platform-friendly path helper
+  getModelsJsonDisplayPath,
+  // Integrity diagnostics
+  getLastPromptIntegrityWarningAt,
+  // Diagnostic command helpers
+  isCompatCheckApplicable,
+  buildDoctorDiagnosis,
+  buildCompatDiagnosis,
   // Cache stats helpers (module-level, usable from verify script)
   addUsageToCacheStats,
   formatCacheStats,
@@ -1592,8 +1709,10 @@ export default function (pi: ExtensionAPI) {
   let lastStatusText: string | undefined;
   let persistenceWarningShown = false;
   let persistTimer: ReturnType<typeof setTimeout> | null = null;
+  let integrityNotificationShown = false;
   const PERSIST_DEBOUNCE_MS = 2000;
 
+
   function getCacheStatsState(): CacheStatsState {
     return { statsByModel: cacheStatsByModel, legacyFamily: cacheStatsLegacyFamily };
   }
@@ -1698,6 +1817,9 @@ export default function (pi: ExtensionAPI) {
       cacheStatsByModel = {};
       cacheStatsLegacyFamily = emptyAllCacheStats();
       lastStatusText = undefined;
+      // Reset integrity diagnostics on reload
+      lastPromptIntegrityWarningAt = 0;
+      integrityNotificationShown = false;
       await flushPersistCacheStats(ctx);
       return;
     }
@@ -1737,6 +1859,35 @@ export default function (pi: ExtensionAPI) {
     if (promptTruncationDetected && statusText !== undefined) {
       statusText = statusText + " ⚠️ integrity";
       promptTruncationDetected = false;
+      lastPromptIntegrityWarningAt = Date.now();
+
+      // One-time notification with recovery steps (per session).
+      if (!integrityNotificationShown) {
+        integrityNotificationShown = true;
+        ctx.ui.notify(
+          `⚠️ ${LOG_PREFIX}: A prompt structural marker was lost during reorder on this turn. ` +
+          `The original prompt was used instead to preserve integrity.\n\n` +
+          `Recovery steps:\n` +
+          `1. Run /reload to reset (may clear transient issues).\n` +
+          `2. Set PI_CACHE_OPTIMIZER_NO_PROMPT_REWRITE=1 and /reload to disable reorder.\n` +
+          `3. If persistent, run /cache-optimizer doctor and file an issue (no API keys/prompts).`,
+          "warning",
+        );
+      }
+    }
+
+    // ⚠️ compat footer marker: if the active model is a non-official
+    // openai-completions model with missing supportsLongCacheRetention
+    // or sendSessionAffinityHeaders, append the marker to indicate that
+    // compat configuration is incomplete. Re-evaluated on every status
+    // update so the marker persists through stats changes and day
+    // rollovers. Redundant setStatus calls are blocked by the
+    // `lastStatusText` early return above.
+    if (statusText !== undefined && model) {
+      const compatMissing = describeMissingOpenAICompatibleProxyCompat(model);
+      if (compatMissing.length > 0) {
+        statusText = statusText + " ⚠️ compat";
+      }
     }
 
     if (statusText === lastStatusText) return;
@@ -1868,4 +2019,99 @@ export default function (pi: ExtensionAPI) {
     schedulePersistCacheStats(ctx);
     await publishStatus(ctx);
   });
+
+  // ────────────────────────────────────────────────────────────────
+  // Register /cache-optimizer command
+  // Subcommands:
+  //   doctor  — show current model/provider/api/baseUrl/compat status
+  //   compat  — show compat suggestion with file path
+  //   (no args) — show help summary + current diagnosis
+  // ────────────────────────────────────────────────────────────────
+  pi.registerCommand("cache-optimizer", {
+    description: "Diagnose Pi cache configuration",
+    handler: async (args: string, cmdCtx) => {
+      const model = cmdCtx.model;
+      const subcommand = args.trim().toLowerCase().split(/\s+/)[0] || "help";
+
+      if (subcommand === "doctor") {
+        if (!model) {
+          cmdCtx.ui.notify("No active model selected. Select a model first with /model or pi --model.", "warning");
+          return;
+        }
+        cmdCtx.ui.notify(buildDoctorDiagnosis(model), "info");
+      } else if (subcommand === "compat") {
+        if (!model) {
+          cmdCtx.ui.notify("No active model selected. Select a model first with /model or pi --model.", "warning");
+          return;
+        }
+        const compatResult = buildCompatDiagnosis(model);
+        if (compatResult) {
+          cmdCtx.ui.notify(compatResult, "warning");
+        } else {
+          cmdCtx.ui.notify(
+            isCompatCheckApplicable(model)
+              ? "✅ Compat fully configured."
+              : "ℹ️ Compat check not applicable for this model.",
+            "info",
+          );
+        }
+      } else {
+        // Try interactive selection menu when UI supports it
+        if (cmdCtx.hasUI) {
+          const menuOptions = [
+            "🩺 Doctor — Show current model cache configuration",
+            "⚙️  Compat — Show compat suggestion with edit instructions",
+            "❌ Cancel",
+          ];
+          const choice = await cmdCtx.ui.select("Cache Optimizer", menuOptions);
+          if (choice === menuOptions[0]) {
+            if (!model) {
+              cmdCtx.ui.notify("No active model selected. Select a model first with /model or pi --model.", "warning");
+            } else {
+              cmdCtx.ui.notify(buildDoctorDiagnosis(model), "info");
+            }
+          } else if (choice === menuOptions[1]) {
+            if (!model) {
+              cmdCtx.ui.notify("No active model selected. Select a model first with /model or pi --model.", "warning");
+            } else {
+              const compatResult = buildCompatDiagnosis(model);
+              if (compatResult) {
+                cmdCtx.ui.notify(compatResult, "warning");
+              } else {
+                cmdCtx.ui.notify(
+                  isCompatCheckApplicable(model)
+                    ? "✅ Compat fully configured."
+                    : "ℹ️ Compat check not applicable for this model.",
+                  "info",
+                );
+              }
+            }
+          }
+          // choice === "cancel" or undefined → no action
+          return;
+        }
+
+        // Fallback: text help when no interactive UI
+        const diagnosis: string[] = [];
+        diagnosis.push("📋 /cache-optimizer commands:");
+        diagnosis.push("  doctor  — Show current model/provider/api/baseUrl/compat status");
+        diagnosis.push("  compat  — Show compat suggestion with edit location");
+        diagnosis.push("");
+        if (model) {
+          const missing = describeMissingOpenAICompatibleProxyCompat(model);
+          if (missing.length > 0) {
+            diagnosis.push(`⚠️  Active model "${modelKey(model)}" missing compat: ${missing.join(", ")}`);
+            diagnosis.push('Run "/cache-optimizer compat" for edit instructions.');
+          } else if (isCompatCheckApplicable(model)) {
+            diagnosis.push(`✅ Active model "${modelKey(model)}": compat fully configured.`);
+          } else {
+            diagnosis.push(`ℹ️ Active model "${modelKey(model)}": compat check not applicable.`);
+          }
+        } else {
+          diagnosis.push("No active model selected.");
+        }
+        cmdCtx.ui.notify(diagnosis.join("\n"), "info");
+      }
+    },
+  });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-cache-optimizer",
-  "version": "2.4.4",
+  "version": "2.4.5",
   "description": "Pi extension that improves provider-side KV/prompt cache hit rates (DeepSeek, OpenAI, Claude, Gemini) by reordering the system prompt, requesting long retention, and showing footer cache stats. Renamed from pi-deepseek-cache-optimizer.",
   "keywords": [
     "pi-package",