pi-cache-optimizer 2.4.1 → 2.4.2

package/README.md

@@ -82,6 +82,7 @@ After installation, `PI_CACHE_RETENTION=long` is applied automatically, the syst
 
 | Env var | Effect |
 |---------|--------|
+| `PI_CACHE_OPTIMIZER_NO_PROMPT_REWRITE=1` | Skip all `before_agent_start` prompt mutations (churn strip, skill compression, stable-prefix reorder); footer stats and `prompt_cache_key` fallback remain active |
 | `PI_CACHE_OPTIMIZER_NO_SKILL_COMPRESSION=1` | Keep pi's verbose `<available_skills>` XML (opt out of one-line index) |
 | `PI_CACHE_OPTIMIZER_OPENAI_CACHE_KEY=0` | Disable the OpenAI-family `prompt_cache_key` fallback (default is enabled) |
 | `PI_CACHE_OPTIMIZER_NO_OPENAI_CACHE_KEY=1` | Disable the OpenAI-family `prompt_cache_key` fallback |

package/README.zh-CN.md

@@ -85,6 +85,7 @@ pi install npm:pi-cache-optimizer
 
 | 环境变量 | 作用 |
 |---------|------|
+| `PI_CACHE_OPTIMIZER_NO_PROMPT_REWRITE=1` | 跳过所有 `before_agent_start` prompt 修改（session-overview 字段剥离、skills 压缩、稳定前缀重排）；底部统计和 `prompt_cache_key` 兜底仍然生效 |
 | `PI_CACHE_OPTIMIZER_NO_SKILL_COMPRESSION=1` | 保留 pi 的 verbose `<available_skills>` XML（退出一行索引模式） |
 | `PI_CACHE_OPTIMIZER_OPENAI_CACHE_KEY=0` | 禁用 OpenAI-family `prompt_cache_key` 兜底（默认启用） |
 | `PI_CACHE_OPTIMIZER_NO_OPENAI_CACHE_KEY=1` | 禁用 OpenAI-family `prompt_cache_key` 兜底 |

package/index.ts

@@ -37,6 +37,7 @@ const OPENAI_CACHE_KEY_ENV = "PI_CACHE_OPTIMIZER_OPENAI_CACHE_KEY";
 const NO_OPENAI_CACHE_KEY_ENV = "PI_CACHE_OPTIMIZER_NO_OPENAI_CACHE_KEY";
 const OPENAI_PROMPT_CACHE_KEY_MAX_LENGTH = 64;
 const NO_SKILL_COMPRESSION_ENV = "PI_CACHE_OPTIMIZER_NO_SKILL_COMPRESSION";
+const NO_PROMPT_REWRITE_ENV = "PI_CACHE_OPTIMIZER_NO_PROMPT_REWRITE";
 
 // WORM-flag: if optimizeSystemPrompt ever detects that its blind-replace
 // logic has accidentally truncated a structural marker (any XML tag or
@@ -856,6 +857,43 @@ function describeMissingOpenAIFamilyProxyCompat(model: PiModel): string[] {
   return missing;
 }
 
+/**
+ * Build the warning text displayed to users when an OpenAI-family third-party
+ * proxy is missing one or more cache/session-affinity compat flags.
+ *
+ * The returned string contains a parseable JSON object (via JSON.stringify)
+ * listing only the missing flags with recommended value `true`. Inline
+ * explanations for each flag follow the JSON snippet as separate prose lines,
+ * so the JSON remains valid and copyable.
+ *
+ * Expected use: the openai adapter's warningText calls this function; tests
+ * exercise it via __internals_for_tests.
+ */
+function buildOpenAIProxyCompatWarningText(key: string, missing: string[]): string {
+  const suggestion: Record<string, boolean> = {};
+  for (const flag of missing) {
+    suggestion[flag] = true;
+  }
+
+  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):`,
+    ``,
+    JSON.stringify(suggestion, null, 2),
+    ``,
+  ];
+
+  for (const flag of missing) {
+    if (flag === "supportsLongCacheRetention") {
+      lines.push("- supportsLongCacheRetention: confirm your endpoint or proxy supports long prompt cache retention.");
+    } else if (flag === "sendSessionAffinityHeaders") {
+      lines.push("- sendSessionAffinityHeaders: keeps requests on the same backend for proxy cache locality (session affinity).");
+    }
+  }
+
+  return lines.join("\n");
+}
+
 function describeMissingDeepSeekCompat(model: PiModel): string[] {
   const compat = getCompat(model);
   const missing: string[] = [];
@@ -935,11 +973,7 @@ const CACHE_PROVIDER_ADAPTERS: CacheProviderAdapter[] = [
     warningText(model) {
       const missing = describeMissingOpenAIFamilyProxyCompat(model);
       if (missing.length === 0) return undefined;
-
-      return (
-        `💡 pi-cache-optimizer: ${modelKey(model)} looks like a third-party GPT/OpenAI-compatible proxy but merged compat lacks ${missing.join(" and ")}. ` +
-        `For better cache locality, add compat: { "supportsLongCacheRetention": true, "sendSessionAffinityHeaders": true } in ~/.pi/agent/models.json when the endpoint supports these fields.`
-      );
+      return buildOpenAIProxyCompatWarningText(modelKey(model), missing);
     },
   },
   {
@@ -1190,6 +1224,8 @@ export const __internals_for_tests = {
   compressSkillsInSystemPrompt,
   MIN_STABLE_CANDIDATE_LENGTH,
   SKILL_COMPRESSION_MIN_COUNT,
+  NO_PROMPT_REWRITE_ENV,
+  isEnabledEnv,
   // OpenAI-family cache-key helpers
   addOpenAIPromptCacheKey,
   clampPromptCacheKey,
@@ -1202,6 +1238,7 @@ export const __internals_for_tests = {
   isOpenAIFamilyToken,
   describeMissingOpenAIFamilyProxyCompat,
   isOfficialOpenAIBaseUrl,
+  buildOpenAIProxyCompatWarningText,
   getModelIdNameTokenValues,
   getAssistantMessageModelTokenValues,
   getCompat,
@@ -1421,6 +1458,14 @@ export default function (pi: ExtensionAPI) {
       }
     }
 
+    // Global opt-out: PI_CACHE_OPTIMIZER_NO_PROMPT_REWRITE=1 bypasses all
+    // prompt mutations below (session-overview churn strip, skill compression,
+    // and stable-prefix reordering). Footer stats and the OpenAI
+    // prompt_cache_key fallback remain active.
+    if (isEnabledEnv(process.env[NO_PROMPT_REWRITE_ENV])) {
+      return {};
+    }
+
     // Step 1: strip per-turn churn from <session-overview>.
     // Removing RECENT COMMITS, Working directory status, and
     // Journal line count makes more of the session-overview stable

package/package.json

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