pi-cache-optimizer 2.6.18 → 2.6.21

package/README.md

@@ -8,7 +8,7 @@
 
 Pi extension for improving provider-side KV / prompt cache hit rates. It keeps stable prompt content near the front, adds a conservative OpenAI-compatible `prompt_cache_key` fallback, warns about common proxy cache-routing gaps, and shows read-only footer cache stats.
 
-> Renamed from `pi-deepseek-cache-optimizer`. Existing footer counters migrate automatically. The extension does **not** touch `~/.pi/agent/models.json` during normal operation; only `/cache-optimizer fix` can edit it, and only after an explicit interactive preview + confirmation with an automatic timestamped backup.
+> Renamed from `pi-deepseek-cache-optimizer`. Existing footer counters migrate automatically. The extension does **not** touch Pi's `models.json` during normal operation (default: `~/.pi/agent/models.json`; custom agent dirs use `PI_CODING_AGENT_DIR`); only `/cache-optimizer fix` can edit it, and only after an explicit interactive preview + confirmation with an automatic timestamped backup.
 
 ## Contents
 
@@ -30,7 +30,7 @@ Pi extension for improving provider-side KV / prompt cache hit rates. It keeps s
 - Reorders stable system-prompt content before dynamic context.
 - Compresses Pi skill listings and strips session-overview churn.
 - Requests long cache retention when Pi/provider compat supports it.
-- Adds a session-id `prompt_cache_key` fallback for `openai-completions` / `openai-responses` payloads when no effective key exists.
+- Adds a session-id `prompt_cache_key` fallback for `openai-completions` / `openai-responses` payloads when no effective key exists, including Pi's built-in `llama.cpp` provider as Pi 0.82 core does.
 - Warns once for third-party OpenAI-compatible proxies missing cache/session-affinity compat flags.
 - Detects adaptive-thinking compat for Claude (opus-4.6+, sonnet-4.6+ including Sonnet 5, fable-5+) and Kimi Coding K3 / `kimi-for-coding` custom channels.
 - Shows restart-persistent provider/model footer stats for supported model families.
@@ -80,7 +80,11 @@ On Pi 0.79.7 and newer, `pi update` updates Pi itself only. To update installed
 
 ## OpenAI-compatible proxy setup
 
-Third-party `openai-completions` proxies (LiteLLM / OneAPI / NewAPI / OpenRouter-like channels) often route one session across multiple upstream backends. That splits provider-side prompt caches. Start with session affinity:
+Third-party `openai-completions` proxies (LiteLLM / OneAPI / NewAPI / OpenRouter-like channels) often route one session across multiple upstream backends. That splits provider-side prompt caches.
+
+Pi 0.81+ also has a built-in `llama.cpp` provider using an OpenAI-shaped transport. Pi 0.82 core generates a session `prompt_cache_key` for it when cache retention is enabled, so this extension preserves that key and may add the same conservative fallback when missing. The built-in provider's explicit compat fingerprint is excluded from generic proxy routing/session-affinity advice, but a custom or overridden provider that merely reuses the id `llama.cpp` is treated like any other OpenAI-compatible channel. `prompt_cache_retention` remains subject to the normal safety rule: keep it only for official OpenAI or an explicit `supportsLongCacheRetention: true` opt-in in `models.json`; otherwise strip it before sending.
+
+For real proxies, start with session affinity:
 
 ```json
 {
@@ -199,7 +203,7 @@ Pi 0.80.9+ already includes Kimi K3 in built-in Kimi Coding, Moonshot AI / China
 
 ### 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`.
+Some Pi channels may be available even when there is no provider block in Pi's agent `models.json` yet (default: `~/.pi/agent/models.json`; with `PI_CODING_AGENT_DIR`, use `$PI_CODING_AGENT_DIR/models.json`). 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:
 
@@ -235,7 +239,7 @@ If only one model should change, use `modelOverrides`:
 
 ## Footer stats
 
-Stats are read-only local counters stored at `~/.pi/agent/pi-cache-optimizer-stats.json` and keyed by provider/model, so the same channel/model keeps today's footer counters after a Pi process or terminal restart. The file also keeps hashed session buckets for migration/reload bookkeeping. It contains only dates and numeric counters — no API keys, prompts, payloads, headers, responses, or model output.
+Stats are read-only local counters stored in Pi's agent directory (default: `~/.pi/agent/pi-cache-optimizer-stats.json`; custom agent dirs use `PI_CODING_AGENT_DIR`) and keyed by provider/model, so the same channel/model keeps today's footer counters after a Pi process or terminal restart. The file also keeps hashed session buckets for migration/reload bookkeeping. It contains only dates and numeric counters — no API keys, prompts, payloads, headers, responses, or model output.
 
 Pi 0.79+ also includes a built-in footer `CH` marker for the latest prompt cache hit rate. This extension complements that marker with persisted provider/model counters plus proxy compat diagnostics.
 
@@ -364,7 +368,7 @@ When the query matches the current session/route, `hints` may contain `systemPro
 pi remove npm:pi-cache-optimizer
 ```
 
-Then run `/reload` or restart Pi. Optional local stats cleanup:
+Then run `/reload` or restart Pi. Optional local stats cleanup (if you use `PI_CODING_AGENT_DIR`, delete the same files from that directory instead):
 
 | Platform | Delete local stats files |
 |---|---|

package/README.zh-CN.md

@@ -8,7 +8,7 @@
 
 用于提升 Pi 中 provider 侧 KV Cache / Prompt Cache 命中率的扩展：把稳定 prompt 内容前置，给 OpenAI-compatible 请求补保守的 `prompt_cache_key`，提示代理渠道常见缓存路由兼容问题，并在底部显示只读缓存统计。
 
-> 本包已从 `pi-deepseek-cache-optimizer` 改名。已有底部统计会自动迁移。正常运行时扩展不会触碰你的 `~/.pi/agent/models.json`；只有 `/cache-optimizer fix` 会在展示交互式预览、风险提示并得到明确确认后写入，且会先创建带时间戳的自动备份。
+> 本包已从 `pi-deepseek-cache-optimizer` 改名。已有底部统计会自动迁移。正常运行时扩展不会触碰 Pi 的 `models.json`（默认 `~/.pi/agent/models.json`；自定义 agent 目录使用 `PI_CODING_AGENT_DIR`）；只有 `/cache-optimizer fix` 会在展示交互式预览、风险提示并得到明确确认后写入，且会先创建带时间戳的自动备份。
 
 ## 目录
 
@@ -30,7 +30,7 @@
 - 将稳定的 system prompt 内容移动到动态上下文之前。
 - 压缩 Pi skill 列表，并移除 session-overview 中的易变字段。
 - 在 Pi / provider compat 支持时请求长缓存保留。
-- 对 `openai-completions` / `openai-responses` 请求，在没有有效 key 时使用 Pi session id 补 `prompt_cache_key`。
+- 对 `openai-completions` / `openai-responses` 请求，在没有有效 key 时使用 Pi session id 补 `prompt_cache_key`；Pi 0.82 core 对内置 `llama.cpp` 也使用这一语义。
 - 对缺少缓存 / session-affinity compat 的第三方 OpenAI-compatible 代理给出一次性提醒。
 - 检测 Claude（opus-4.6+、sonnet-4.6+ 含 Sonnet 5、fable-5+）以及 Kimi Coding K3 / `kimi-for-coding` 自定义渠道的 adaptive-thinking compat。
 - 为支持的模型家族显示可跨 Pi 进程 / 终端重启延续的 provider/model footer 缓存统计。
@@ -80,7 +80,11 @@ Pi 0.79.7 及之后，`pi update` 默认只更新 Pi 本体。若要更新已安
 
 ## OpenAI-compatible 代理配置
 
-LiteLLM / OneAPI / NewAPI / 类 OpenRouter 渠道等第三方 `openai-completions` 代理，常会把同一个 session 分散到多个上游后端，导致 provider 侧 prompt cache 被拆散。建议先启用 session affinity：
+LiteLLM / OneAPI / NewAPI / 类 OpenRouter 渠道等第三方 `openai-completions` 代理，常会把同一个 session 分散到多个上游后端，导致 provider 侧 prompt cache 被拆散。
+
+Pi 0.81+ 也内置了使用 OpenAI-shaped transport 的 `llama.cpp` provider。Pi 0.82 core 在启用 cache retention 时会为它生成 session `prompt_cache_key`，因此本扩展会保留该 key，并在缺失时使用同样的保守 fallback。只有符合 Pi 内置 provider 明确 compat 指纹的模型会跳过通用 proxy 路由 / session-affinity 建议；仅复用 `llama.cpp` id 的自定义或覆盖 provider 仍按普通 OpenAI-compatible 渠道处理。`prompt_cache_retention` 继续遵循统一安全规则：仅官方 OpenAI 或在 `models.json` 中显式设置 `supportsLongCacheRetention: true` 时保留，否则发送前移除。
+
+对真正的代理，建议先启用 session affinity：
 
 ```json
 {
@@ -199,7 +203,7 @@ Pi 0.80.9+ 已在内置 Kimi Coding、Moonshot AI / 中国区、OpenRouter 和 V
 
 ### 没有 `models.json` provider entry 的渠道
 
-有些 Pi 渠道可用时，`~/.pi/agent/models.json` 里可能还没有对应 provider block。保留现有认证方式，不要复制 credential、token 或 API key。只在 `models.json` 里添加缓存 / 路由兼容覆盖。
+有些 Pi 渠道可用时，Pi agent `models.json`（默认 `~/.pi/agent/models.json`；若设置了 `PI_CODING_AGENT_DIR`，则为 `$PI_CODING_AGENT_DIR/models.json`）里可能还没有对应 provider block。保留现有认证方式，不要复制 credential、token 或 API key。只在 `models.json` 里添加缓存 / 路由兼容覆盖。
 
 Provider 级最小 override：
 
@@ -235,7 +239,7 @@ Provider 级最小 override：
 
 ## Footer 统计
 
-统计是只读本地计数，保存在 `~/.pi/agent/pi-cache-optimizer-stats.json`，按 provider/model 作为 footer 展示维度，因此同一个渠道/模型在 Pi 进程或终端重启后会延续今天的统计。文件也保留 hashed session buckets，用于迁移和 reload 记录。文件只包含日期和数字计数，不包含 API key、prompt、payload、headers、响应或模型输出。
+统计是只读本地计数，保存在 Pi agent 目录（默认 `~/.pi/agent/pi-cache-optimizer-stats.json`；自定义 agent 目录使用 `PI_CODING_AGENT_DIR`），按 provider/model 作为 footer 展示维度，因此同一个渠道/模型在 Pi 进程或终端重启后会延续今天的统计。文件也保留 hashed session buckets，用于迁移和 reload 记录。文件只包含日期和数字计数，不包含 API key、prompt、payload、headers、响应或模型输出。
 
 Pi 0.79+ 已内置 footer `CH` 标记，用于显示最近一次 prompt cache hit rate。本扩展在此基础上补充持久化的 provider/model 计数，以及代理 compat 诊断。
 
@@ -364,7 +368,7 @@ const hints = (globalThis as Record<symbol, any>)[CACHE_HINTS]?.getHints?.({
 pi remove npm:pi-cache-optimizer
 ```
 
-然后运行 `/reload` 或重启 Pi。可选：删除本地统计文件：
+然后运行 `/reload` 或重启 Pi。可选：删除本地统计文件（如果使用 `PI_CODING_AGENT_DIR`，请删除该目录中的同名文件）：
 
 | 平台 | 删除本地统计文件 |
 |---|---|

package/index.ts

@@ -3,7 +3,7 @@ import { copyFile, mkdir, readFile, rename, unlink, writeFile } from "node:fs/pr
 import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
-import type { BuildSystemPromptOptions, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { getAgentDir, type BuildSystemPromptOptions, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 
 type MutableEnv = Record<string, string | undefined>;
 
@@ -63,7 +63,9 @@ type CacheProviderId = "deepseek" | "openai" | "claude" | "gemini";
 
 const LOG_PREFIX = "pi-cache-optimizer";
 const STATUS_KEY = "pi-cache-stats";
-const STATE_DIR = join(homedir(), ".pi", "agent");
+
+/** Use Pi core's resolver so rebranded config names and env semantics stay aligned. */
+const STATE_DIR = getAgentDir();
 const STATE_FILE_PATH = join(STATE_DIR, "pi-cache-optimizer-stats.json");
 const LEGACY_STATE_FILE_PATH = join(STATE_DIR, "deepseek-cache-optimizer-stats.json");
 const CACHE_PROVIDER_IDS: CacheProviderId[] = ["deepseek", "openai", "claude", "gemini"];
@@ -141,6 +143,12 @@ const AYA_MODEL_PATTERN = /(^|[\/\s:_-])aya($|[\-_.:\/\s])/i;
 const ORION_MODEL_PATTERN = /(^|[\/\s:_-])orion($|[\-_.:\/\s])/i;
 
 type CacheCompat = {
+  supportsStore?: boolean;
+  supportsDeveloperRole?: boolean;
+  supportsReasoningEffort?: boolean;
+  supportsUsageInStreaming?: boolean;
+  supportsStrictMode?: boolean;
+  maxTokensField?: "max_completion_tokens" | "max_tokens";
   sendSessionAffinityHeaders?: boolean;
   sessionAffinityFormat?: "openai" | "openai-nosession" | "openrouter";
   supportsLongCacheRetention?: boolean;
@@ -980,24 +988,50 @@ function getCompat(model: PiModel | undefined): CacheCompat {
   return modelCompat;
 }
 
+/** Join display-only path fragments without resolving them for I/O. */
+function joinDisplayPath(base: string, child: string, platform: string = process.platform): string {
+  const sep = platform.startsWith("win") ? "\\" : "/";
+  return `${base.replace(/[\\/]+$/, "")}${sep}${child}`;
+}
+
 /**
- * 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).
+ * Return a platform-friendly display path for Pi's agent directory.
  *
- * 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.
+ * Derives the display path from Pi core's `getAgentDir()` result. Home-relative
+ * paths use `%USERPROFILE%` on Windows and `~` on Unix-like systems; custom
+ * absolute or relative agent directories remain visible as configured.
  */
-function getModelsJsonDisplayPath(platform: string = process.platform): string {
-  if (platform.startsWith("win")) {
-    return `%USERPROFILE%\\.pi\\agent\\models.json`;
+function getAgentDirDisplayPath(
+  platform: string = process.platform,
+  agentDir: string = getAgentDir(),
+  homeDir: string = homedir(),
+): string {
+  const sep = platform.startsWith("win") ? "\\" : "/";
+  const normalizedAgentDir = agentDir.replace(/[\\/]+/g, sep);
+  const normalizedHomeDir = homeDir.replace(/[\\/]+/g, sep).replace(/[\\/]+$/, "");
+  const homePrefix = `${normalizedHomeDir}${sep}`;
+
+  if (normalizedAgentDir === normalizedHomeDir || normalizedAgentDir.startsWith(homePrefix)) {
+    const relative = normalizedAgentDir.slice(normalizedHomeDir.length).replace(/^[\\/]+/, "");
+    const homeLabel = platform.startsWith("win") ? "%USERPROFILE%" : "~";
+    return relative ? `${homeLabel}${sep}${relative}` : homeLabel;
   }
-  return "~/.pi/agent/models.json";
+
+  return normalizedAgentDir;
+}
+
+/**
+ * Return a platform-friendly display path for Pi's `models.json`.
+ *
+ * This is a DISPLAY helper only. Actual I/O uses `MODELS_JSON_PATH`, resolved
+ * from the same custom agent/config directory rules as `STATE_DIR`.
+ */
+function getModelsJsonDisplayPath(
+  platform: string = process.platform,
+  agentDir: string = getAgentDir(),
+  homeDir: string = homedir(),
+): string {
+  return joinDisplayPath(getAgentDirDisplayPath(platform, agentDir, homeDir), "models.json", platform);
 }
 
 function isEnabledEnv(value: string | undefined): boolean {
@@ -1099,6 +1133,28 @@ function isOpenAICompatibleProxyApi(api: unknown): boolean {
   return lower(api) === "openai-completions";
 }
 
+function isPiBuiltInLlamaCppModel(model: PiModel | undefined): boolean {
+  if (lower(model?.provider) !== "llama.cpp" || !isOpenAICompatibleProxyApi(model?.api)) return false;
+
+  // Pi's built-in llama.cpp provider supplies this exact explicit compat
+  // fingerprint. Provider ids are extension-overridable and models.json can add
+  // cache/routing overrides, so provider id alone must never imply exemption.
+  const compat = getCompat(model);
+  return compat.supportsStore === false
+    && compat.supportsDeveloperRole === false
+    && compat.supportsReasoningEffort === false
+    && compat.supportsUsageInStreaming === false
+    && compat.supportsStrictMode === false
+    && compat.maxTokensField === "max_tokens"
+    && compat.sendSessionAffinityHeaders === undefined
+    && compat.sessionAffinityFormat === undefined
+    && compat.supportsLongCacheRetention === undefined;
+}
+
+function shouldInjectOpenAIPromptCacheKeyForModel(model: PiModel | undefined): boolean {
+  return isOpenAICompatibleApi(model?.api);
+}
+
 function isResponsesPromptRewriteBypassApi(api: unknown): boolean {
   const value = lower(api);
   return value === "openai-codex-responses" || value === "openai-responses" || value === "azure-openai-responses";
@@ -1738,10 +1794,21 @@ function modelFromAssistantMessage(message: unknown, fallback: PiModel | undefin
   const api = firstNonEmptyString(record.api, fallback?.api) ?? "";
   if (!id || !provider) return fallback;
 
+  const fallbackName = isNonEmptyString(fallback?.name) ? fallback.name : undefined;
+  const preservesFallbackIdentity =
+    !isVirtualRoutingModel(fallback) &&
+    provider === fallback?.provider &&
+    id === fallback?.id &&
+    fallbackName !== undefined;
+
   return {
     ...(fallback ?? {}),
     id,
-    name: id,
+    // Direct providers such as kimi-coding may echo only a short model id
+    // (`k3`) while the active model name (`Kimi K3`) carries the adapter token.
+    // Preserve that display name only when response and fallback identities are
+    // exactly the same; routed/different identities keep message-local naming.
+    name: preservesFallbackIdentity ? fallbackName : id,
     provider,
     api,
     baseUrl: fallback?.baseUrl ?? "",
@@ -2031,6 +2098,7 @@ function describeMissingOpenAICompatibleProxyCompat(model: PiModel): string[] {
 
   if (!isOpenAICompatibleProxyApi(model.api)) return missing;
   if (isOfficialOpenAIBaseUrl(model)) return missing;
+  if (isPiBuiltInLlamaCppModel(model)) return missing;
 
   if (compat.sendSessionAffinityHeaders === undefined) {
     missing.push("sendSessionAffinityHeaders");
@@ -2058,6 +2126,7 @@ function describeOptionalOpenAICompatibleProxyCompat(model: PiModel): string[] {
 
   if (!isOpenAICompatibleProxyApi(model.api)) return optional;
   if (isOfficialOpenAIBaseUrl(model)) return optional;
+  if (isPiBuiltInLlamaCppModel(model)) return optional;
 
   if (compat.supportsLongCacheRetention !== true) {
     optional.push("supportsLongCacheRetention");
@@ -2231,7 +2300,7 @@ function describeMissingDeepSeekCompat(model: PiModel): string[] {
 }
 
 function isDeepSeekCompatCheckApplicable(model: PiModel): boolean {
-  return isDeepSeekLikeModel(model) && isOpenAICompatibleApi(model.api);
+  return isDeepSeekLikeModel(model) && isOpenAICompatibleApi(model.api) && !isPiBuiltInLlamaCppModel(model);
 }
 
 function describeMissingCacheCompatForModel(model: PiModel): string[] {
@@ -2315,7 +2384,7 @@ const CACHE_PROVIDER_ADAPTERS: CacheProviderAdapter[] = [
       return normalizeWithFallback(message, getDeepSeekRawUsage, { allowInputOnlyPiUsage: true });
     },
     warningText(model) {
-      if (!isDeepSeekLikeModel(model) || !isOpenAICompatibleApi(model.api)) return undefined;
+      if (!isDeepSeekCompatCheckApplicable(model)) return undefined;
 
       const missing = describeMissingDeepSeekCompat(model);
       if (missing.length === 0) return undefined;
@@ -2337,7 +2406,7 @@ const CACHE_PROVIDER_ADAPTERS: CacheProviderAdapter[] = [
       return normalizeWithFallback(message, getAnthropicRawUsage);
     },
     warningText(model) {
-      if (!isClaudeLikeModel(model) || !isOpenAICompatibleApi(model.api)) return undefined;
+      if (!isClaudeLikeModel(model) || !isOpenAICompatibleApi(model.api) || isPiBuiltInLlamaCppModel(model)) return undefined;
       if (getCompat(model).cacheControlFormat === "anthropic") return undefined;
 
       return (
@@ -3947,12 +4016,13 @@ async function writePersistedCacheStats(
 
 
 function isCompatCheckApplicable(model: PiModel): boolean {
-  return isOpenAICompatibleProxyApi(model.api) && !isOfficialOpenAIBaseUrl(model);
+  return isOpenAICompatibleProxyApi(model.api) && !isOfficialOpenAIBaseUrl(model) && !isPiBuiltInLlamaCppModel(model);
 }
 
 function isPromptCacheRetention400Applicable(model: PiModel): boolean {
   return isOpenAICompatibleApi(model.api) &&
     !isOfficialOpenAIBaseUrl(model) &&
+    !isPiBuiltInLlamaCppModel(model) &&
     getCompat(model).supportsLongCacheRetention === true;
 }
 
@@ -3969,6 +4039,7 @@ function isPromptCacheRetention400Applicable(model: PiModel): boolean {
  */
 function isSessionAffinity403Applicable(model: PiModel): boolean {
   if (!isOpenAICompatibleProxyApi(model.api)) return false;
+  if (isPiBuiltInLlamaCppModel(model)) return false;
   return getCompat(model).sendSessionAffinityHeaders === true;
 }
 
@@ -3985,6 +4056,7 @@ function isSessionAffinity403Applicable(model: PiModel): boolean {
 function isOpenAISdkHeader403Applicable(model: PiModel): boolean {
   if (!isOpenAICompatibleProxyApi(model.api)) return false;
   if (isOfficialOpenAIBaseUrl(model)) return false;
+  if (isPiBuiltInLlamaCppModel(model)) return false;
   return getCompat(model).sendSessionAffinityHeaders !== true;
 }
 
@@ -4026,6 +4098,13 @@ function describeRouterChannelDiagnostics(model: PiModel): string[] {
     return notes;
   }
 
+  // Pi 0.81+ built-in llama.cpp uses an OpenAI-shaped transport, but its
+  // untouched explicit compat fingerprint does not expose proxy-routing or
+  // session-affinity configuration. Same-id overrides are not exempt.
+  if (isPiBuiltInLlamaCppModel(model)) {
+    return notes;
+  }
+
   // ── 1. OpenRouter ────────────────────────────────────────────────
   if (
     baseUrl.includes("openrouter.ai") ||
@@ -5745,8 +5824,10 @@ export const __internals_for_tests = {
   hasEffectivePromptCacheKey,
   isNonEmptyString,
   shouldInjectOpenAIPromptCacheKey,
+  shouldInjectOpenAIPromptCacheKeyForModel,
   isOpenAICompatibleApi,
   isOpenAICompatibleProxyApi,
+  isPiBuiltInLlamaCppModel,
   isResponsesPromptRewriteBypassApi,
   isMistralConversationsApi,
   isOpenAIFamilyModel,
@@ -5884,8 +5965,10 @@ export const __internals_for_tests = {
   getAssistantMessageModelTokenValues,
   getCompat,
   modelKey,
+  modelFromAssistantMessage,
   consolidateDirectProviderStatsModel,
   // Platform-friendly path helpers
+  getAgentDirDisplayPath,
   getModelsJsonDisplayPath,
   buildProviderCompatOverride,
   buildModelCompatOverride,
@@ -6482,6 +6565,10 @@ export default function (pi: ExtensionAPI) {
 
   pi.on("before_agent_start", async (event, _ctx) => {
     latestCacheHint = undefined;
+    // Clear the legacy global before any bypass/disable early return. A valid
+    // rewrite path republishes the current session key below; otherwise callers
+    // must not observe a stale key from the previously selected model/route.
+    delete getProtocolGlobal().__piCacheOptimizerCacheKey__;
     const routeSnapshot = resolveActiveRouteSnapshot(_ctx.model, _ctx);
     const routedModel = routeSnapshot
       ? findModelInRegistry(_ctx.modelRegistry, routeSnapshot.provider, routeSnapshot.modelId) ?? routeSnapshotToPiModel(routeSnapshot, _ctx.model)
@@ -6567,7 +6654,11 @@ export default function (pi: ExtensionAPI) {
         timestamp: Date.now(),
       };
       const globals = getProtocolGlobal();
-      globals.__piCacheOptimizerCacheKey__ = promptCacheKey;
+      if (promptCacheKey) {
+        globals.__piCacheOptimizerCacheKey__ = promptCacheKey;
+      } else {
+        delete globals.__piCacheOptimizerCacheKey__;
+      }
     };
 
     if (optimized.changed && optimized.systemPrompt.trim().length > 0) {
@@ -6628,7 +6719,7 @@ export default function (pi: ExtensionAPI) {
 
     if (!shouldInjectOpenAIPromptCacheKey()) return undefined;
     const requestModel = resolveRouteModel(ctx.model, ctx) ?? ctx.model;
-    if (!isOpenAICompatibleApi(requestModel?.api)) return undefined;
+    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.18",
+  "version": "2.6.21",
   "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",