pi-cache-optimizer 2.6.17 → 2.6.18

package/README.md

@@ -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)
@@ -32,7 +32,7 @@ Pi extension for improving provider-side KV / prompt cache hit rates. It keeps s
 - 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.
 - 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.
 
@@ -109,9 +109,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 +151,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.
 

package/README.zh-CN.md

@@ -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-扩展作者指南)
@@ -32,7 +32,7 @@
 - 在 Pi / provider compat 支持时请求长缓存保留。
 - 对 `openai-completions` / `openai-responses` 请求，在没有有效 key 时使用 Pi session id 补 `prompt_cache_key`。
 - 对缺少缓存 / 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 包。
 
@@ -109,9 +109,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 +151,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`。
 

package/index.ts

@@ -142,12 +142,13 @@ const ORION_MODEL_PATTERN = /(^|[\/\s:_-])orion($|[\-_.:\/\s])/i;
 
 type CacheCompat = {
   sendSessionAffinityHeaders?: boolean;
-  sendSessionIdHeader?: boolean;
+  sessionAffinityFormat?: "openai" | "openai-nosession" | "openrouter";
   supportsLongCacheRetention?: boolean;
   thinkingFormat?: string;
   requiresReasoningContentOnAssistantMessages?: boolean;
   cacheControlFormat?: string;
   forceAdaptiveThinking?: boolean;
+  allowEmptySignature?: boolean;
 };
 
 type CacheStats = {
@@ -1159,8 +1160,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 +1200,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 +1211,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 +1226,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 +1238,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).`,
     "",
   ];
@@ -2177,11 +2217,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) {
@@ -2214,9 +2250,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 +2279,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.");
   }
@@ -3256,15 +3286,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");
       }
     }
@@ -3930,16 +3959,16 @@ function isPromptCacheRetention400Applicable(model: PiModel): boolean {
 /**
  * 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;
   return getCompat(model).sendSessionAffinityHeaders === true;
 }
 
@@ -5290,7 +5319,6 @@ function deepEqualIgnoringKeys(a: unknown, b: unknown, extraKeys: string[]): boo
  */
 const PROVIDER_LEVEL_SAFE_COMPAT_KEYS = new Set<string>([
   "sendSessionAffinityHeaders",
-  "sendSessionIdHeader",
   "supportsLongCacheRetention",
 ]);
 
@@ -5304,9 +5332,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 +5358,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);
@@ -5935,6 +5972,8 @@ export const __internals_for_tests = {
   buildFixSuggestion,
   // Adaptive thinking compat helpers
   isAdaptiveGenerationModel,
+  isKimiCodingAdaptiveModel,
+  isKimiCodingEmptySignatureModel,
   isAdaptiveThinkingCompatApplicable,
   describeMissingAdaptiveThinkingCompat,
   buildAdaptiveThinkingCompatSuggestion,

package/package.json

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