pi-cache-optimizer 2.6.17 → 2.6.20

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
 
@@ -17,7 +17,7 @@ Pi extension for improving provider-side KV / prompt cache hit rates. It keeps s
 - [Commands](#commands)
 - [Persistent opt-out](#persistent-opt-out)
 - [OpenAI-compatible proxy setup](#openai-compatible-proxy-setup)
-- [Anthropic adaptive thinking models](#anthropic-adaptive-thinking-models)
+- [Adaptive thinking models](#adaptive-thinking-models)
 - [Auto-repair with `/cache-optimizer fix`](#auto-repair-with-cache-optimizer-fix)
 - [Footer stats](#footer-stats)
 - [For router / virtual-channel extension authors](#for-router--virtual-channel-extension-authors)
@@ -30,9 +30,9 @@ 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 Anthropic adaptive thinking models (opus-4.6+, sonnet-4.6+ including Sonnet 5, fable-5+) missing `forceAdaptiveThinking: true` compat.
+- 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.
 - Supports optional router-extension integration through versioned global protocols (`Symbol.for("pi.routing.registry.v1")` and `Symbol.for("pi.cache.hints.v1")`) without importing router packages.
 
@@ -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
 {
@@ -109,9 +113,9 @@ 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's `doctor` and `compat` commands only advise; they do not modify `models.json`.
 
-## Anthropic adaptive thinking models
+## Adaptive thinking models
 
-Claude models from opus-4.6 / sonnet-4.6 (including Sonnet 5) / fable-5 onwards require `forceAdaptiveThinking: true` in compat. Without it, Pi sends the legacy thinking format and Anthropic rejects the request.
+Claude models from opus-4.6 / sonnet-4.6 (including Sonnet 5) / fable-5 onwards require `forceAdaptiveThinking: true` in compat. Kimi Coding K3 (`k3`) and `kimi-for-coding` also use adaptive thinking and need `allowEmptySignature: true` so replayed empty-signature thinking blocks remain valid. Without the required compat, Pi may send a legacy thinking payload or replay thinking incorrectly.
 
 Pi's built-in catalog already sets this flag for official models. Custom channels in `models.json` that override these models must include the flag:
 
@@ -151,15 +155,36 @@ Or use model-level override:
 }
 ```
 
+For Kimi Coding K3 custom channels, use model-level compat when the provider contains mixed models:
+
+```json
+{
+  "providers": {
+    "your-kimi-coding-channel": {
+      "modelOverrides": {
+        "k3": {
+          "compat": {
+            "forceAdaptiveThinking": true,
+            "allowEmptySignature": true
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+Pi 0.80.9+ already includes Kimi K3 in built-in Kimi Coding, Moonshot AI / China, OpenRouter, and Vercel AI Gateway catalogs. The Moonshot/OpenRouter variants use their OpenAI-compatible transport and continue through the normal Kimi footer/proxy path; the adaptive compat above applies only to `anthropic-messages` Kimi Coding channels.
+
 `/cache-optimizer doctor` and `/cache-optimizer compat` detect missing flags and show copyable JSON.
 
 ## Auto-repair with `/cache-optimizer fix`
 
 **v2.6.0+** adds a `fix` subcommand that can auto-repair safe compat issues:
 
-- Anthropic adaptive thinking (`forceAdaptiveThinking: true`)
+- Adaptive thinking (`forceAdaptiveThinking: true`; Kimi Coding K3 / `kimi-for-coding` also `allowEmptySignature: true`)
 - DeepSeek Pi Mono reasoning compat (`thinkingFormat: "deepseek"`, `requiresReasoningContentOnAssistantMessages: true`)
-- OpenAI-compatible proxy session affinity (`sendSessionAffinityHeaders: true` for `openai-completions`, `sendSessionIdHeader: true` for `openai-responses`)
+- OpenAI-compatible proxy session affinity (`sendSessionAffinityHeaders: true` for `openai-completions`). Pi 0.80.7+ controls `openai-responses` header shape with `sessionAffinityFormat` and auto-detects its default; this extension no longer writes the removed `sendSessionIdHeader` field.
 
 **Scope:** only the currently active model. Other channels require switching models and running `fix` again.
 
@@ -178,7 +203,7 @@ Or use model-level override:
 
 ### 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:
 
@@ -214,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.
 
@@ -343,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` 会在展示交互式预览、风险提示并得到明确确认后写入，且会先创建带时间戳的自动备份。
 
 ## 目录
 
@@ -17,7 +17,7 @@
 - [命令](#命令)
 - [持久 Opt-out](#持久-opt-out)
 - [OpenAI-compatible 代理配置](#openai-compatible-代理配置)
-- [Anthropic adaptive thinking 模型](#anthropic-adaptive-thinking-模型)
+- [Adaptive thinking 模型](#adaptive-thinking-模型)
 - [使用 `/cache-optimizer fix` 自动修复](#使用-cache-optimizer-fix-自动修复)
 - [Footer 统计](#footer-统计)
 - [Router / Virtual-channel 扩展作者指南](#router--virtual-channel-扩展作者指南)
@@ -30,9 +30,9 @@
 - 将稳定的 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 代理给出一次性提醒。
-- 检测 Anthropic adaptive thinking 模型（opus-4.6+、sonnet-4.6+ 含 Sonnet 5、fable-5+）是否缺少 `forceAdaptiveThinking: true` compat。
+- 检测 Claude（opus-4.6+、sonnet-4.6+ 含 Sonnet 5、fable-5+）以及 Kimi Coding K3 / `kimi-for-coding` 自定义渠道的 adaptive-thinking compat。
 - 为支持的模型家族显示可跨 Pi 进程 / 终端重启延续的 provider/model footer 缓存统计。
 - 通过版本化全局协议（`Symbol.for("pi.routing.registry.v1")` 与 `Symbol.for("pi.cache.hints.v1")`）支持可选的 router extension 集成，而不导入任何 router 包。
 
@@ -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
 {
@@ -109,9 +113,9 @@ LiteLLM / OneAPI / NewAPI / 类 OpenRouter 渠道等第三方 `openai-completion
 - 对 DeepSeek 模型，Pi Mono 指南期望在支持时同时设置 `compat.requiresReasoningContentOnAssistantMessages: true` 和 `compat.thinkingFormat: "deepseek"`，再配合缓存 / session-affinity 相关 compat。
 - 本扩展的 `doctor` 和 `compat` 命令只给建议，不会修改 `models.json`。
 
-## Anthropic adaptive thinking 模型
+## Adaptive thinking 模型
 
-Claude 从 opus-4.6 / sonnet-4.6（含 Sonnet 5）/ fable-5 开始需要在 compat 中设置 `forceAdaptiveThinking: true`。缺少此 flag 时，Pi 会发送旧版 thinking 格式，Anthropic 会拒绝请求。
+Claude 从 opus-4.6 / sonnet-4.6（含 Sonnet 5）/ fable-5 开始需要在 compat 中设置 `forceAdaptiveThinking: true`。Kimi Coding K3（`k3`）和 `kimi-for-coding` 也使用 adaptive thinking，并需要 `allowEmptySignature: true`，以正确重放空 signature 的 thinking block。缺少这些 compat 时，Pi 可能发送旧版 thinking payload 或错误重放 thinking。
 
 Pi 内置 catalog 已为官方模型设置此 flag。`models.json` 中覆盖这些模型的自定义渠道必须包含该 flag：
 
@@ -151,15 +155,36 @@ Pi 内置 catalog 已为官方模型设置此 flag。`models.json` 中覆盖这
 }
 ```
 
+Kimi Coding K3 自定义渠道如果包含混合模型，建议使用模型级 compat：
+
+```json
+{
+  "providers": {
+    "your-kimi-coding-channel": {
+      "modelOverrides": {
+        "k3": {
+          "compat": {
+            "forceAdaptiveThinking": true,
+            "allowEmptySignature": true
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+Pi 0.80.9+ 已在内置 Kimi Coding、Moonshot AI / 中国区、OpenRouter 和 Vercel AI Gateway catalog 中加入 Kimi K3。Moonshot/OpenRouter 变体使用 OpenAI-compatible transport，继续走普通 Kimi footer / proxy 路径；上面的 adaptive compat 只适用于 `anthropic-messages` Kimi Coding 渠道。
+
 `/cache-optimizer doctor` 和 `/cache-optimizer compat` 会检测缺失的 flag 并显示可复制的 JSON。
 
 ## 使用 `/cache-optimizer fix` 自动修复
 
 **v2.6.0+** 新增 `fix` 子命令，可自动修复安全的 compat 问题：
 
-- Anthropic adaptive thinking（`forceAdaptiveThinking: true`）
+- Adaptive thinking（`forceAdaptiveThinking: true`；Kimi Coding K3 / `kimi-for-coding` 还包括 `allowEmptySignature: true`）
 - DeepSeek Pi Mono reasoning compat（`thinkingFormat: "deepseek"`、`requiresReasoningContentOnAssistantMessages: true`）
-- OpenAI-compatible proxy session affinity（`openai-completions` 用 `sendSessionAffinityHeaders: true`，`openai-responses` 用 `sendSessionIdHeader: true`）
+- OpenAI-compatible proxy session affinity（`openai-completions` 使用 `sendSessionAffinityHeaders: true`）。Pi 0.80.7+ 使用 `sessionAffinityFormat` 控制 `openai-responses` header 形式并自动检测默认值；本扩展不再写入已移除的 `sendSessionIdHeader`。
 
 **范围：** 仅当前 active model。其他渠道需切换模型后再次运行 `fix`。
 
@@ -178,7 +203,7 @@ Pi 内置 catalog 已为官方模型设置此 flag。`models.json` 中覆盖这
 
 ### 没有 `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：
 
@@ -214,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 诊断。
 
@@ -343,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,13 +143,20 @@ 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;
-  sendSessionIdHeader?: boolean;
+  sessionAffinityFormat?: "openai" | "openai-nosession" | "openrouter";
   supportsLongCacheRetention?: boolean;
   thinkingFormat?: string;
   requiresReasoningContentOnAssistantMessages?: boolean;
   cacheControlFormat?: string;
   forceAdaptiveThinking?: boolean;
+  allowEmptySignature?: boolean;
 };
 
 type CacheStats = {
@@ -979,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`.
+ * Return a platform-friendly display path for Pi's agent directory.
  *
- * 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.
+ * 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 {
@@ -1098,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";
@@ -1159,8 +1216,38 @@ function isAdaptiveGenerationModel(model: PiModel | undefined): boolean {
   return tokens.some((t) => ADAPTIVE_OPUS_PATTERN.test(t) || ADAPTIVE_SONNET_PATTERN.test(t) || ADAPTIVE_FABLE_PATTERN.test(t));
 }
 
+function isKimiCodingAdaptiveModel(model: PiModel | undefined): boolean {
+  if (!model) return false;
+  const provider = lower(model.provider);
+  const baseUrl = lower(model.baseUrl);
+  const isKimiCodingChannel = provider.includes("kimi-coding") || baseUrl.includes("api.kimi.com/coding");
+  if (!isKimiCodingChannel) return false;
+
+  const tokens = getModelIdNameTokenValues(model);
+  return tokens.some((token) =>
+    token === "k3"
+    || token.includes("kimi-k3")
+    || token.includes("kimi k3")
+    || token.includes("kimi-for-coding")
+    || token.includes("kimi for coding")
+  );
+}
+
+function isKimiCodingEmptySignatureModel(model: PiModel | undefined): boolean {
+  if (!isKimiCodingAdaptiveModel(model)) return false;
+  return getModelIdNameTokenValues(model).some((token) =>
+    token === "k3"
+    || token === "kimi-k3"
+    || token.startsWith("kimi-k3-")
+    || token === "kimi k3"
+    || token === "kimi-for-coding"
+    || token === "kimi for coding"
+  );
+}
+
 function isAdaptiveThinkingCompatApplicable(model: PiModel): boolean {
-  return lower(model.api) === "anthropic-messages" && isAdaptiveGenerationModel(model);
+  return lower(model.api) === "anthropic-messages"
+    && (isAdaptiveGenerationModel(model) || isKimiCodingAdaptiveModel(model));
 }
 
 function describeMissingAdaptiveThinkingCompat(model: PiModel): string[] {
@@ -1169,6 +1256,9 @@ function describeMissingAdaptiveThinkingCompat(model: PiModel): string[] {
   if (compat.forceAdaptiveThinking !== true) {
     missing.push("forceAdaptiveThinking");
   }
+  if (isKimiCodingEmptySignatureModel(model) && compat.allowEmptySignature !== true) {
+    missing.push("allowEmptySignature");
+  }
   return missing;
 }
 
@@ -1177,6 +1267,9 @@ function buildAdaptiveThinkingCompatSuggestion(missing: string[]): Record<string
   if (missing.includes("forceAdaptiveThinking")) {
     suggestion.forceAdaptiveThinking = true;
   }
+  if (missing.includes("allowEmptySignature")) {
+    suggestion.allowEmptySignature = true;
+  }
   return suggestion;
 }
 
@@ -1189,6 +1282,9 @@ function appendAdaptiveThinkingCompatAdviceLines(lines: string[], missing: strin
   lines.push("- forceAdaptiveThinking: true tells Pi to use adaptive thinking format");
   lines.push("  (thinking: {type: 'adaptive'}) instead of legacy budget tokens format.");
   lines.push("  Without this flag, Pi sends legacy thinking which adaptive-only upstreams reject.");
+  if (missing.includes("allowEmptySignature")) {
+    lines.push("- allowEmptySignature: true preserves Kimi Coding K3 thinking blocks whose replay signature is empty.");
+  }
   appendCredentialSafeProviderGuidance(lines, placement, suggestion);
 }
 
@@ -1198,8 +1294,8 @@ function buildAdaptiveThinkingCompatWarningText(key: string, missing: string[]):
   const modelId = slashIdx > 0 ? key.slice(slashIdx + 1) : undefined;
   const modelsJsonPath = getModelsJsonDisplayPath();
   const lines: string[] = [
-    `💡 pi-cache-optimizer: ${key} is an adaptive-generation Claude model but merged compat lacks ${missing.join(" and ")}.`,
-    `Without this flag, Pi sends legacy thinking format that may be rejected by the upstream.`,
+    `💡 pi-cache-optimizer: ${key} is an adaptive-generation model but merged compat lacks ${missing.join(" and ")}.`,
+    `Without the required compat, Pi may send legacy thinking or replay thinking blocks incorrectly.`,
     `Edit ${modelsJsonPath} -> providers["${providerLabel}"] -> compat (at the same level as baseUrl/api/apiKey/models).`,
     "",
   ];
@@ -1991,6 +2087,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");
@@ -2018,6 +2115,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");
@@ -2177,11 +2275,7 @@ function describeMissingDeepSeekCompat(model: PiModel): string[] {
   if (compat.supportsLongCacheRetention !== true) {
     missing.push("supportsLongCacheRetention");
   }
-  if (model.api === "openai-responses") {
-    if (compat.sendSessionIdHeader !== true) {
-      missing.push("sendSessionIdHeader");
-    }
-  } else if (compat.sendSessionAffinityHeaders !== true) {
+  if (model.api !== "openai-responses" && compat.sendSessionAffinityHeaders !== true) {
     missing.push("sendSessionAffinityHeaders");
   }
   if (compat.requiresReasoningContentOnAssistantMessages !== true) {
@@ -2195,7 +2289,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[] {
@@ -2214,9 +2308,6 @@ function buildDeepSeekCompatSuggestion(missing: string[]): Record<string, unknow
   if (missing.includes("supportsLongCacheRetention")) {
     suggestion.supportsLongCacheRetention = true;
   }
-  if (missing.includes("sendSessionIdHeader")) {
-    suggestion.sendSessionIdHeader = true;
-  }
   if (missing.includes("sendSessionAffinityHeaders")) {
     suggestion.sendSessionAffinityHeaders = true;
   }
@@ -2246,9 +2337,6 @@ function appendDeepSeekCompatAdviceLines(lines: string[], missing: string[], pla
   if (missing.includes("sendSessionAffinityHeaders")) {
     lines.push("- sendSessionAffinityHeaders: recommended for OpenAI-compatible DeepSeek proxies when supported; it helps keep one Pi session on the same upstream/backend.");
   }
-  if (missing.includes("sendSessionIdHeader")) {
-    lines.push("- sendSessionIdHeader: recommended for OpenAI Responses-compatible DeepSeek proxies when supported.");
-  }
   if (missing.includes("supportsLongCacheRetention")) {
     lines.push("- supportsLongCacheRetention: enable for DeepSeek-compatible endpoints that support long cache retention.");
   }
@@ -2285,7 +2373,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;
@@ -2307,7 +2395,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 (
@@ -3256,15 +3344,14 @@ function notifyCacheCompatIfNeeded(
   if (!model) return;
 
   // Native anthropic-messages adaptive thinking compat check.
-  // The Claude adapter's warningText only fires for OpenAI-compatible APIs,
-  // so native anthropic-messages models need a separate check.
-  if (lower(model.api) === "anthropic-messages" && isAdaptiveGenerationModel(model)) {
-    const compat = getCompat(model);
-    if (compat.forceAdaptiveThinking !== true) {
+  // Adapter warningText only fires for OpenAI-compatible APIs, so native
+  // Anthropic and Kimi Coding adaptive models need a separate check.
+  if (isAdaptiveThinkingCompatApplicable(model)) {
+    const missing = describeMissingAdaptiveThinkingCompat(model);
+    if (missing.length > 0) {
       const key = `adaptive-thinking:${modelKey(model)}`;
       if (!warnedModels.has(key)) {
         warnedModels.add(key);
-        const missing = describeMissingAdaptiveThinkingCompat(model);
         ctx.ui.notify(buildAdaptiveThinkingCompatWarningText(modelKey(model), missing), "warning");
       }
     }
@@ -3918,28 +4005,30 @@ 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;
 }
 
 /**
  * Whether the 403 sendSessionAffinityHeaders diagnostic applies to a model.
  *
- * Pi's openai-completions / openai-responses adapters send three custom HTTP
- * headers (session_id, x-client-request-id, x-session-affinity) when
- * `sendSessionAffinityHeaders` is enabled. Some third-party proxies / CDNs /
- * WAFs block these custom headers and return HTTP 403 "Your request was
- * blocked". This guard returns true only for OpenAI-compatible APIs whose
- * merged compat currently enables session-affinity headers, so the 403
- * monitoring and doctor/fix paths can advise disabling the flag.
+ * Pi's openai-completions adapter sends custom HTTP headers (session_id,
+ * x-client-request-id, x-session-affinity) when `sendSessionAffinityHeaders`
+ * is enabled. Some third-party proxies / CDNs / WAFs block these headers and
+ * return HTTP 403 "Your request was blocked". Pi 0.80.7+ no longer uses this
+ * flag for openai-responses; Responses header shape is controlled by
+ * `sessionAffinityFormat`. This guard therefore applies only to
+ * openai-completions, where doctor/fix can safely advise disabling the flag.
  */
 function isSessionAffinity403Applicable(model: PiModel): boolean {
-  if (!isOpenAICompatibleApi(model.api)) return false;
+  if (!isOpenAICompatibleProxyApi(model.api)) return false;
+  if (isPiBuiltInLlamaCppModel(model)) return false;
   return getCompat(model).sendSessionAffinityHeaders === true;
 }
 
@@ -3956,6 +4045,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;
 }
 
@@ -3997,6 +4087,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") ||
@@ -5290,7 +5387,6 @@ function deepEqualIgnoringKeys(a: unknown, b: unknown, extraKeys: string[]): boo
  */
 const PROVIDER_LEVEL_SAFE_COMPAT_KEYS = new Set<string>([
   "sendSessionAffinityHeaders",
-  "sendSessionIdHeader",
   "supportsLongCacheRetention",
 ]);
 
@@ -5304,9 +5400,10 @@ function syntheticModelForId(providerLabel: string, id: string): PiModel {
  * Strategy (auto-detect, prefer provider level when safe):
  * - Channel-capability keys (session affinity / long retention) are always
  *   provider-safe.
- * - Model-behavior keys (forceAdaptiveThinking, thinkingFormat, ...) are
- *   provider-safe ONLY when every sibling model in the provider also matches
- *   the same detection (all adaptive-generation / all DeepSeek-like).
+ * - 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 /
+ *   Kimi Coding adaptive / DeepSeek-like).
  * - Single-model providers: provider level is equivalent — prefer it.
  * - Any unsafe key → fall back to model level (single write, smallest blast radius).
  */
@@ -5329,10 +5426,18 @@ function decideFixPlacement(
     if (PROVIDER_LEVEL_SAFE_COMPAT_KEYS.has(key)) continue;
 
     if (key === "forceAdaptiveThinking") {
-      const allAdaptive = siblings.every((id) => isAdaptiveGenerationModel(syntheticModelForId(providerLabel, id)));
+      const allAdaptive = siblings.every((id) => {
+        const sibling = syntheticModelForId(providerLabel, id);
+        return isAdaptiveGenerationModel(sibling) || isKimiCodingAdaptiveModel(sibling);
+      });
       if (!allAdaptive) unsafeKeys.push(key);
       continue;
     }
+    if (key === "allowEmptySignature") {
+      const allKimiCodingAdaptive = siblings.every((id) => isKimiCodingAdaptiveModel(syntheticModelForId(providerLabel, id)));
+      if (!allKimiCodingAdaptive) unsafeKeys.push(key);
+      continue;
+    }
     if (key === "thinkingFormat" || key === "requiresReasoningContentOnAssistantMessages") {
       const allDeepSeek = siblings.every((id) => isDeepSeekLikeModel(syntheticModelForId(providerLabel, id)));
       if (!allDeepSeek) unsafeKeys.push(key);
@@ -5708,8 +5813,10 @@ export const __internals_for_tests = {
   hasEffectivePromptCacheKey,
   isNonEmptyString,
   shouldInjectOpenAIPromptCacheKey,
+  shouldInjectOpenAIPromptCacheKeyForModel,
   isOpenAICompatibleApi,
   isOpenAICompatibleProxyApi,
+  isPiBuiltInLlamaCppModel,
   isResponsesPromptRewriteBypassApi,
   isMistralConversationsApi,
   isOpenAIFamilyModel,
@@ -5849,6 +5956,7 @@ export const __internals_for_tests = {
   modelKey,
   consolidateDirectProviderStatsModel,
   // Platform-friendly path helpers
+  getAgentDirDisplayPath,
   getModelsJsonDisplayPath,
   buildProviderCompatOverride,
   buildModelCompatOverride,
@@ -5935,6 +6043,8 @@ export const __internals_for_tests = {
   buildFixSuggestion,
   // Adaptive thinking compat helpers
   isAdaptiveGenerationModel,
+  isKimiCodingAdaptiveModel,
+  isKimiCodingEmptySignatureModel,
   isAdaptiveThinkingCompatApplicable,
   describeMissingAdaptiveThinkingCompat,
   buildAdaptiveThinkingCompatSuggestion,
@@ -6443,6 +6553,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)
@@ -6528,7 +6642,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) {
@@ -6589,7 +6707,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.17",
+  "version": "2.6.20",
   "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",