pi-cache-optimizer 2.6.15 → 2.6.17

package/README.md

@@ -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+, fable-5+) missing `forceAdaptiveThinking: true` compat.
+- Detects Anthropic adaptive thinking models (opus-4.6+, sonnet-4.6+ including Sonnet 5, fable-5+) missing `forceAdaptiveThinking: true` compat.
 - 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.
 
@@ -111,7 +111,7 @@ Notes:
 
 ## Anthropic adaptive thinking models
 
-Claude models from opus-4.6 / sonnet-4.6 / 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. Without it, Pi sends the legacy thinking format and Anthropic rejects the request.
 
 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:
 
@@ -126,7 +126,7 @@ Pi's built-in catalog already sets this flag for official models. Custom channel
         "forceAdaptiveThinking": true
       },
       "models": [
-        { "id": "claude-opus-4-8", "name": "Claude Opus 4.8" }
+        { "id": "claude-sonnet-5", "name": "Claude Sonnet 5" }
       ]
     }
   }
@@ -140,7 +140,7 @@ Or use model-level override:
   "providers": {
     "your-claude-channel": {
       "modelOverrides": {
-        "claude-opus-4-8": {
+        "claude-sonnet-5": {
           "compat": {
             "forceAdaptiveThinking": true
           }

package/README.zh-CN.md

@@ -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+、fable-5+）是否缺少 `forceAdaptiveThinking: true` compat。
+- 检测 Anthropic adaptive thinking 模型（opus-4.6+、sonnet-4.6+ 含 Sonnet 5、fable-5+）是否缺少 `forceAdaptiveThinking: true` compat。
 - 为支持的模型家族显示可跨 Pi 进程 / 终端重启延续的 provider/model footer 缓存统计。
 - 通过版本化全局协议（`Symbol.for("pi.routing.registry.v1")` 与 `Symbol.for("pi.cache.hints.v1")`）支持可选的 router extension 集成，而不导入任何 router 包。
 
@@ -111,7 +111,7 @@ LiteLLM / OneAPI / NewAPI / 类 OpenRouter 渠道等第三方 `openai-completion
 
 ## Anthropic adaptive thinking 模型
 
-Claude 从 opus-4.6 / sonnet-4.6 / fable-5 开始需要在 compat 中设置 `forceAdaptiveThinking: true`。缺少此 flag 时，Pi 会发送旧版 thinking 格式，Anthropic 会拒绝请求。
+Claude 从 opus-4.6 / sonnet-4.6（含 Sonnet 5）/ fable-5 开始需要在 compat 中设置 `forceAdaptiveThinking: true`。缺少此 flag 时，Pi 会发送旧版 thinking 格式，Anthropic 会拒绝请求。
 
 Pi 内置 catalog 已为官方模型设置此 flag。`models.json` 中覆盖这些模型的自定义渠道必须包含该 flag：
 
@@ -126,7 +126,7 @@ Pi 内置 catalog 已为官方模型设置此 flag。`models.json` 中覆盖这
         "forceAdaptiveThinking": true
       },
       "models": [
-        { "id": "claude-opus-4-8", "name": "Claude Opus 4.8" }
+        { "id": "claude-sonnet-5", "name": "Claude Sonnet 5" }
       ]
     }
   }
@@ -140,7 +140,7 @@ Pi 内置 catalog 已为官方模型设置此 flag。`models.json` 中覆盖这
   "providers": {
     "your-claude-channel": {
       "modelOverrides": {
-        "claude-opus-4-8": {
+        "claude-sonnet-5": {
           "compat": {
             "forceAdaptiveThinking": true
           }

package/index.ts

@@ -1143,14 +1143,14 @@ function isGeminiLikeAssistantMessage(message: unknown, model: PiModel | undefin
  *
  * Adaptive-generation models (from pi-ai built-in catalog) include:
  *   claude-opus-4-6, claude-opus-4-7, claude-opus-4-8 (also dotted 4.6/4.7/4.8)
- *   claude-sonnet-4-6
+ *   claude-sonnet-4-6, claude-sonnet-5
  *   claude-fable-5
  *
  * We match broadly: opus >= 4-6, sonnet >= 4-6, fable >= 5.
  * Ids may carry date-stamp or size suffixes like "[1M]".
  */
-const ADAPTIVE_OPUS_PATTERN = /(^|[\/\s:_-])(opus-4[.-][6-9]|opus-4-[1-9][0-9])($|[-_.:\/\s\[])/i;
-const ADAPTIVE_SONNET_PATTERN = /(^|[\/\s:_-])(sonnet-4[.-][6-9]|sonnet-4-[1-9][0-9])($|[-_.:\/\s\[])/i;
+const ADAPTIVE_OPUS_PATTERN = /(^|[\/\s:_-])(opus-4[.-][6-9]|opus-4-[1-9][0-9]|opus-([5-9]|[1-9][0-9]))($|[-_.:\/\s\[])/i;
+const ADAPTIVE_SONNET_PATTERN = /(^|[\/\s:_-])(sonnet-4[.-][6-9]|sonnet-4-[1-9][0-9]|sonnet-([5-9]|[1-9][0-9]))($|[-_.:\/\s\[])/i;
 const ADAPTIVE_FABLE_PATTERN = /(^|[\/\s:_-])fable-([5-9]|[1-9][0-9])($|[-_.:\/\s\[])/i;
 
 function isAdaptiveGenerationModel(model: PiModel | undefined): boolean {
@@ -3943,6 +3943,22 @@ function isSessionAffinity403Applicable(model: PiModel): boolean {
   return getCompat(model).sendSessionAffinityHeaders === true;
 }
 
+/**
+ * Whether an OpenAI SDK header/User-Agent 403 diagnostic applies.
+ *
+ * Some third-party OpenAI-compatible proxies/CDNs/WAFs allow a plain curl
+ * request but block the OpenAI JS SDK's default request fingerprint, especially
+ * its `User-Agent: OpenAI/JS ...` and `X-Stainless-*` headers. This is distinct
+ * from session-affinity header blocking: it applies when session-affinity
+ * headers are NOT enabled but the model still uses a non-official
+ * OpenAI-compatible proxy transport.
+ */
+function isOpenAISdkHeader403Applicable(model: PiModel): boolean {
+  if (!isOpenAICompatibleProxyApi(model.api)) return false;
+  if (isOfficialOpenAIBaseUrl(model)) return false;
+  return getCompat(model).sendSessionAffinityHeaders !== true;
+}
+
 /**
  * Detect router / channel profiles from a PiModel and return diagnostic notes.
  *
@@ -4140,7 +4156,7 @@ function getCompatCheckNotApplicableLines(model: PiModel): string[] {
   return ["ℹ️ Compat check not applicable for this model."];
 }
 
-function buildDoctorDiagnosis(model: PiModel, options: { promptCacheRetention400?: boolean; sessionAffinity403?: boolean } = {}): string {
+function buildDoctorDiagnosis(model: PiModel, options: { promptCacheRetention400?: boolean; sessionAffinity403?: boolean; openAISdkHeader403?: boolean } = {}): string {
   const lines: string[] = [];
   lines.push(`Provider: ${model.provider}`);
   lines.push(`Model:    ${model.id}`);
@@ -4216,6 +4232,20 @@ function buildDoctorDiagnosis(model: PiModel, options: { promptCacheRetention400
       lines.push("   (session_id, x-client-request-id, x-session-affinity) and return 403. If you");
       lines.push("   see 403 errors, run /cache-optimizer fix to set sendSessionAffinityHeaders: false.");
     }
+  } else if (isOpenAISdkHeader403Applicable(model)) {
+    lines.push("");
+    if (options.openAISdkHeader403) {
+      lines.push("⚠️  A 403 response was observed while sendSessionAffinityHeaders is not enabled.");
+      lines.push("   The proxy/CDN may be blocking the OpenAI JS SDK request fingerprint");
+      lines.push("   (for example User-Agent: OpenAI/JS ... or X-Stainless-* headers). This");
+      lines.push("   is provider/WAF-specific; /cache-optimizer fix will not auto-write headers.");
+      lines.push(`   Manual workaround: add a provider-level headers.User-Agent override in ${getModelsJsonDisplayPath()}`);
+      lines.push("   only after testing the value with the affected provider.");
+    } else {
+      lines.push("ℹ️ If 403 persists after disabling sendSessionAffinityHeaders, some CDNs/WAFs");
+      lines.push("   may block the OpenAI JS SDK User-Agent / X-Stainless-* headers. Test the");
+      lines.push("   provider manually before adding a provider-level headers.User-Agent override.");
+    }
   }
 
   // ── Router/channel diagnostics ──
@@ -4408,12 +4438,19 @@ function buildCompatDiagnosis(model: PiModel): string | undefined {
       if (isPromptCacheRetention400Applicable(model)) {
         lines.push(getPromptCacheRetentionUnsupportedHint());
       }
-      // Advisory for 403 session-affinity header blocking (only when enabled).
+      // Advisory for 403 session-affinity header blocking (only when enabled),
+      // or OpenAI SDK header/User-Agent blocking after session affinity is disabled.
       if (isSessionAffinity403Applicable(model)) {
         lines.push(
           "ℹ️ Session affinity headers are enabled. If you see 403 \"blocked\" errors,",
           "   the proxy/CDN may be blocking Pi's custom headers. Set sendSessionAffinityHeaders: false.",
         );
+      } else if (isOpenAISdkHeader403Applicable(model)) {
+        lines.push(
+          "ℹ️ If 403 persists with sendSessionAffinityHeaders disabled, the proxy/CDN may",
+          "   be blocking the OpenAI JS SDK User-Agent / X-Stainless-* headers. Test a",
+          "   provider-level headers.User-Agent override manually; /fix does not auto-write it.",
+        );
       }
       appendOptionalOpenAIProxyCompatAdviceLines(lines, optionalOpenAIProxyCompat);
     } else {
@@ -5692,6 +5729,7 @@ export const __internals_for_tests = {
   isCompatCheckApplicable,
   isPromptCacheRetention400Applicable,
   isSessionAffinity403Applicable,
+  isOpenAISdkHeader403Applicable,
   hasPromptCacheRetentionUnsupportedSignal,
   // Non-GPT OpenAI-compatible model detection
   isKimiLikeModel,
@@ -5910,6 +5948,8 @@ export default function (pi: ExtensionAPI) {
   const warnedPromptCacheRetention400Models = new Set<string>();
   const sendSessionAffinityHeaders403Models = new Set<string>();
   const warnedSendSessionAffinityHeaders403Models = new Set<string>();
+  const openAISdkHeader403Models = new Set<string>();
+  const warnedOpenAISdkHeader403Models = new Set<string>();
   let cacheStatsByModel: Record<string, CacheStats> = {};
   let cacheStatsTotalsByModel: Record<string, CacheStats> = {};
   let cacheStatsLegacyFamily: Partial<Record<CacheProviderId, CacheStats>> = emptyAllCacheStats();
@@ -6576,28 +6616,42 @@ export default function (pi: ExtensionAPI) {
       return;
     }
 
-    // ── 403: sendSessionAffinityHeaders blocked by CDN/WAF ──
-    //
-    // Pi's openai-completions/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 403. We record a
-    // one-time per-session notification and surface it in doctor/fix so the
-    // user can disable the flag for the blocked model.
+    // ── 403: proxy/CDN/WAF blocking ──
     if (event.status === 403) {
-      if (!isSessionAffinity403Applicable(model)) return;
-
       const key403 = modelKey(model);
-      sendSessionAffinityHeaders403Models.add(key403);
-      if (warnedSendSessionAffinityHeaders403Models.has(key403)) return;
-      warnedSendSessionAffinityHeaders403Models.add(key403);
-      ctx.ui.notify(
-        `⚠️ ${LOG_PREFIX}: ${key403} returned HTTP 403 while sendSessionAffinityHeaders is enabled. ` +
-        `The proxy/CDN may be blocking Pi's custom session-affinity headers (session_id, x-client-request-id, x-session-affinity). ` +
-        `Run /cache-optimizer doctor for details and /cache-optimizer fix to set sendSessionAffinityHeaders: false.`,
-        "warning",
-      );
-      return;
+
+      // Case 1: Pi's custom session-affinity headers are enabled. Offer the
+      // existing safe compat fix (`sendSessionAffinityHeaders: false`).
+      if (isSessionAffinity403Applicable(model)) {
+        sendSessionAffinityHeaders403Models.add(key403);
+        if (warnedSendSessionAffinityHeaders403Models.has(key403)) return;
+        warnedSendSessionAffinityHeaders403Models.add(key403);
+        ctx.ui.notify(
+          `⚠️ ${LOG_PREFIX}: ${key403} returned HTTP 403 while sendSessionAffinityHeaders is enabled. ` +
+          `The proxy/CDN may be blocking Pi's custom session-affinity headers (session_id, x-client-request-id, x-session-affinity). ` +
+          `Run /cache-optimizer doctor for details and /cache-optimizer fix to set sendSessionAffinityHeaders: false.`,
+          "warning",
+        );
+        return;
+      }
+
+      // Case 2: session-affinity headers are already absent/disabled, but the
+      // provider still returns 403. Some CDNs/WAFs block the OpenAI JS SDK
+      // default request fingerprint (User-Agent: OpenAI/JS ... or
+      // X-Stainless-* headers). This is provider-specific; do NOT auto-fix by
+      // writing a User-Agent because the right value depends on the endpoint.
+      if (isOpenAISdkHeader403Applicable(model)) {
+        openAISdkHeader403Models.add(key403);
+        if (warnedOpenAISdkHeader403Models.has(key403)) return;
+        warnedOpenAISdkHeader403Models.add(key403);
+        ctx.ui.notify(
+          `⚠️ ${LOG_PREFIX}: ${key403} returned HTTP 403 even though sendSessionAffinityHeaders is not enabled. ` +
+          `The proxy/CDN may be blocking the OpenAI JS SDK User-Agent / X-Stainless-* headers. ` +
+          `Run /cache-optimizer doctor for manual diagnostic guidance; /cache-optimizer fix will not auto-write User-Agent headers.`,
+          "warning",
+        );
+        return;
+      }
     }
   });
 
@@ -6720,7 +6774,7 @@ export default function (pi: ExtensionAPI) {
           cmdCtx.ui.notify("No active model selected. Select a model first with /model or pi --model.", "warning");
           return;
         }
-        const diagnosis = buildDoctorDiagnosis(model, { promptCacheRetention400: promptCacheRetention400Models.has(modelKey(model)), sessionAffinity403: sendSessionAffinityHeaders403Models.has(modelKey(model)) });
+        const diagnosis = buildDoctorDiagnosis(model, { promptCacheRetention400: promptCacheRetention400Models.has(modelKey(model)), sessionAffinity403: sendSessionAffinityHeaders403Models.has(modelKey(model)), openAISdkHeader403: openAISdkHeader403Models.has(modelKey(model)) });
         const adapter = selectAdapterForModel(model);
         const sk = model ? sessionModelKey(model) : undefined;
         const statsState = model ? cacheStatsTotalsByModel[modelKey(model)] : undefined;
@@ -7141,7 +7195,7 @@ export default function (pi: ExtensionAPI) {
             if (!model) {
               cmdCtx.ui.notify("No active model selected. Select a model first with /model or pi --model.", "warning");
             } else {
-              const diagnosis = buildDoctorDiagnosis(model, { promptCacheRetention400: promptCacheRetention400Models.has(modelKey(model)), sessionAffinity403: sendSessionAffinityHeaders403Models.has(modelKey(model)) });
+              const diagnosis = buildDoctorDiagnosis(model, { promptCacheRetention400: promptCacheRetention400Models.has(modelKey(model)), sessionAffinity403: sendSessionAffinityHeaders403Models.has(modelKey(model)), openAISdkHeader403: openAISdkHeader403Models.has(modelKey(model)) });
               const adapter = selectAdapterForModel(model);
               const sk = model ? sessionModelKey(model) : undefined;
               const statsState = model ? cacheStatsTotalsByModel[modelKey(model)] : undefined;

package/package.json

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