pi-cache-optimizer 2.6.6 → 2.6.7

package/README.md

@@ -20,6 +20,7 @@ Pi extension for improving provider-side KV / prompt cache hit rates. It keeps s
 - [Anthropic adaptive thinking models](#anthropic-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)
 - [Uninstall](#uninstall)
 - [Verify effect](#verify-effect)
 - [License](#license)
@@ -51,6 +52,8 @@ pi remove npm:pi-deepseek-cache-optimizer && pi install npm:pi-cache-optimizer
 
 Run `/reload` in Pi after install/update/remove so extension hooks refresh.
 
+On Pi 0.79.7 and newer, `pi update` updates Pi itself only. To update installed Pi packages such as this extension, run `pi update --extensions` (packages only) or `pi update --all` (Pi + packages).
+
 ## Commands
 
 | Command | Effect |
@@ -213,7 +216,7 @@ If only one model should change, use `modelOverrides`:
 
 Stats are read-only local counters stored at `~/.pi/agent/pi-cache-optimizer-stats.json` and scoped by Pi session + provider/model. They contain only dates and numeric counters — no API keys, prompts, payloads, headers, responses, or model output.
 
-For virtual routing providers, completed assistant message metadata is authoritative: if the message carries real upstream `provider`, `model` / `responseModel`, `api`, and usage, stats are attributed to that upstream provider/model instead of the virtual router shell. Router extensions may also publish a live route adapter under `Symbol.for("pi.routing.registry.v1")` so footer, doctor, compat, and reset flows can resolve the current upstream before the final assistant message exists. The cache optimizer also exposes query-scoped prompt/cache hints via `Symbol.for("pi.cache.hints.v1")` for routers that forward to inner `streamSimple` calls. Both protocols are optional and versioned; no router package import is required.
+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/session-scoped counters plus proxy compat diagnostics.
 
 Example footer:
 
@@ -227,6 +230,113 @@ Supported footer labels include: DS, Claude, OpenAI, Gemini, Kimi, Qwen, GLM, Mi
 
 Adapter selection uses only model id/name (plus assistant message model/name on message end). Generic OpenAI-shaped APIs are not treated as OpenAI-family unless the model id/name matches a supported family.
 
+## For router / virtual-channel extension authors
+
+If your Pi extension provides a virtual routing provider (for example `router/auto`, `router/smart`, or a profile/channel that forwards to a real upstream), this extension can show cache stats for the real upstream provider/model instead of the virtual shell. Integration is optional, versioned, and does **not** require importing this package.
+
+### Minimum integration: final assistant message metadata
+
+For seamless final cache-stat attribution, relay the real upstream identity on completed assistant messages:
+
+```ts
+{
+  role: "assistant",
+  provider: "anthropic",              // real upstream provider
+  responseModel: "claude-opus-4-8",   // or model: "..."
+  api: "anthropic-messages",          // upstream Pi API id when known
+  usage: {
+    input: 1200,       // Pi-normalized uncached input tokens, if available
+    cacheRead: 8000,   // tokens read from provider prompt cache
+    cacheWrite: 500,   // tokens newly written to provider prompt cache
+  },
+}
+```
+
+`message_end` treats these assistant-message fields as authoritative. If `provider` + `model`/`responseModel` + cache usage are present, stats update the upstream bucket even when the active model is still `router/auto`. If upstream usage does not expose cache fields, leave them absent/zero; this extension will not fake cache hits.
+
+### Optional: live route registry for pre-response UX
+
+Final message metadata is enough for post-response stats. For pre-response flows — footer display before the first response, `/cache-optimizer doctor`, `/cache-optimizer compat`, `/cache-optimizer reset`, and OpenAI-compatible `prompt_cache_key` fallback — register a live route adapter under `Symbol.for("pi.routing.registry.v1")`.
+
+Protocol shape:
+
+```ts
+type PiRouteSnapshot = {
+  virtualProvider: string;
+  virtualModelId: string;
+  provider: string;
+  modelId: string;
+  api?: string;
+  canonicalModelId?: string;
+  routeLabel?: string;
+  status?: "planned" | "trying" | "selected" | "success" | "failed";
+  sessionIdHash?: string;
+  requestId?: string;
+  timestamp: number;
+};
+
+type PiRouterAdapterV1 = {
+  virtualProvider: string;
+  resolveActiveRoute(
+    virtualModelId: string,
+    hint?: { sessionIdHash?: string; requestId?: string },
+  ): PiRouteSnapshot | undefined;
+  resolveCandidateRoutes?(virtualModelId: string): PiRouteSnapshot[];
+  subscribe?(listener: (event: PiRouteSnapshot) => void): () => void;
+};
+```
+
+Registration pattern:
+
+```ts
+const ROUTING = Symbol.for("pi.routing.registry.v1");
+const registry = (globalThis as Record<symbol, unknown>)[ROUTING] as
+  | { version: 1; registerRouter(adapter: PiRouterAdapterV1): () => void }
+  | undefined;
+
+registry?.registerRouter({
+  virtualProvider: "router",
+  resolveActiveRoute(virtualModelId, hint) {
+    return {
+      virtualProvider: "router",
+      virtualModelId,
+      provider: "deepseek",
+      modelId: "deepseek-v4",
+      api: "openai-completions",
+      sessionIdHash: hint?.sessionIdHash,
+      timestamp: Date.now(),
+    };
+  },
+});
+```
+
+Do not overwrite an existing registry. If your extension loads before this optimizer, retry registration on `session_start` or create the same V1 registry shape only if no registry exists.
+
+### Optional: query-scoped cache hints
+
+Routers that forward to an inner Pi request path can read query-scoped hints from `Symbol.for("pi.cache.hints.v1")`:
+
+```ts
+const CACHE_HINTS = Symbol.for("pi.cache.hints.v1");
+const hints = (globalThis as Record<symbol, any>)[CACHE_HINTS]?.getHints?.({
+  sessionIdHash,
+  virtualProvider: "router",
+  virtualModelId: "auto",
+  upstreamProvider: "deepseek",
+  upstreamModelId: "deepseek-v4",
+  api: "openai-completions",
+});
+```
+
+When the query matches the current session/route, `hints` may contain `systemPrompt`, `promptCacheKey`, and `cacheRetention: "long"`. Treat these as advisory and sensitive: do not log them, do not expose prompt text, and do not overwrite an existing request-level `prompt_cache_key` / `promptCacheKey`.
+
+### Security and correctness rules
+
+- Do not import `pi-cache-optimizer`; use `Symbol.for(...)` discovery only.
+- Do not expose API keys, prompts, payloads, headers, response bodies, or model output in route snapshots or logs.
+- Use assistant-message metadata for final attribution; live registry data is advisory and may be stale by response time.
+- Preserve truthful usage. Missing cache usage should show as 0/under-reported, not as synthetic hits.
+
 ## Uninstall
 
 ```bash

package/README.zh-CN.md

@@ -20,6 +20,7 @@
 - [Anthropic adaptive thinking 模型](#anthropic-adaptive-thinking-模型)
 - [使用 `/cache-optimizer fix` 自动修复](#使用-cache-optimizer-fix-自动修复)
 - [Footer 统计](#footer-统计)
+- [Router / Virtual-channel 扩展作者指南](#router--virtual-channel-扩展作者指南)
 - [卸载](#卸载)
 - [验证效果](#验证效果)
 - [License](#license)
@@ -51,6 +52,8 @@ pi remove npm:pi-deepseek-cache-optimizer && pi install npm:pi-cache-optimizer
 
 安装、更新或移除后，在 Pi 中运行 `/reload`，让 extension hooks 刷新。
 
+Pi 0.79.7 及之后，`pi update` 默认只更新 Pi 本体。若要更新已安装的 Pi package（包括本扩展），请运行 `pi update --extensions`（只更新 packages）或 `pi update --all`（Pi 与 packages 一起更新）。
+
 ## 命令
 
 | 命令 | 作用 |
@@ -213,7 +216,7 @@ Provider 级最小 override：
 
 统计是只读本地计数，保存在 `~/.pi/agent/pi-cache-optimizer-stats.json`，按 Pi session + provider/model 隔离。文件只包含日期和数字计数，不包含 API key、prompt、payload、headers、响应或模型输出。
 
-对于虚拟 routing provider，最终 assistant message 的 metadata 是权威来源：如果 message 携带真实上游 `provider`、`model` / `responseModel`、`api` 和 usage，统计会归因到真实上游 provider/model，而不是虚拟 router 外壳。Router extension 也可以在 `Symbol.for("pi.routing.registry.v1")` 下发布 live route adapter，让 footer、doctor、compat 和 reset 在最终 assistant message 出现前解析当前上游。本扩展还通过 `Symbol.for("pi.cache.hints.v1")` 暴露按查询过滤的 prompt/cache hints，供转发到内部 `streamSimple` 的 router 使用。两个协议都是可选、版本化的；不需要导入任何 router 包。
+Pi 0.79+ 已内置 footer `CH` 标记，用于显示最近一次 prompt cache hit rate。本扩展在此基础上补充持久化的 provider/model/session-scoped 计数，以及代理 compat 诊断。
 
 示例 footer：
 
@@ -227,6 +230,113 @@ OpenAI cache 3/10 · 0.002M/0.005M tok (40%) ⚠️ compat
 
 Adapter 选择只看模型 id/name（以及 message_end 时 assistant message 的 model/name）。仅使用 OpenAI-shaped API 不会被当作 OpenAI-family，除非模型 id/name 匹配受支持的家族。
 
+## Router / Virtual-channel 扩展作者指南
+
+如果你的 Pi 扩展提供虚拟 routing provider（例如 `router/auto`、`router/smart`，或会转发到真实上游的 profile/channel），本扩展可以为真实上游 provider/model 显示缓存统计，而不是把统计记到虚拟外壳上。集成是可选、版本化的，并且**不需要导入本包**。
+
+### 最小集成：最终 assistant message metadata
+
+要无缝获得最终缓存统计归因，请在完成的 assistant message 上透传真实上游身份：
+
+```ts
+{
+  role: "assistant",
+  provider: "anthropic",              // 真实上游 provider
+  responseModel: "claude-opus-4-8",   // 或 model: "..."
+  api: "anthropic-messages",          // 已知时填写上游 Pi API id
+  usage: {
+    input: 1200,       // Pi-normalized 未缓存 input tokens，如可用
+    cacheRead: 8000,   // 从 provider prompt cache 读取的 tokens
+    cacheWrite: 500,   // 本次新写入 provider prompt cache 的 tokens
+  },
+}
+```
+
+`message_end` 会把这些 assistant-message 字段视为权威来源。只要存在 `provider` + `model`/`responseModel` + cache usage，即使 active model 仍是 `router/auto`，统计也会更新真实上游桶。如果上游 usage 没有 cache 字段，请保持缺失或为 0；本扩展不会伪造 cache hit。
+
+### 可选：用于预响应 UX 的实时路由注册表
+
+最终 message metadata 足以支持响应后的统计。若要支持响应前流程——首次响应前的 footer 显示、`/cache-optimizer doctor`、`/cache-optimizer compat`、`/cache-optimizer reset` 和 OpenAI-compatible `prompt_cache_key` fallback——请在 `Symbol.for("pi.routing.registry.v1")` 下注册 live route adapter。
+
+协议形状：
+
+```ts
+type PiRouteSnapshot = {
+  virtualProvider: string;
+  virtualModelId: string;
+  provider: string;
+  modelId: string;
+  api?: string;
+  canonicalModelId?: string;
+  routeLabel?: string;
+  status?: "planned" | "trying" | "selected" | "success" | "failed";
+  sessionIdHash?: string;
+  requestId?: string;
+  timestamp: number;
+};
+
+type PiRouterAdapterV1 = {
+  virtualProvider: string;
+  resolveActiveRoute(
+    virtualModelId: string,
+    hint?: { sessionIdHash?: string; requestId?: string },
+  ): PiRouteSnapshot | undefined;
+  resolveCandidateRoutes?(virtualModelId: string): PiRouteSnapshot[];
+  subscribe?(listener: (event: PiRouteSnapshot) => void): () => void;
+};
+```
+
+注册模式：
+
+```ts
+const ROUTING = Symbol.for("pi.routing.registry.v1");
+const registry = (globalThis as Record<symbol, unknown>)[ROUTING] as
+  | { version: 1; registerRouter(adapter: PiRouterAdapterV1): () => void }
+  | undefined;
+
+registry?.registerRouter({
+  virtualProvider: "router",
+  resolveActiveRoute(virtualModelId, hint) {
+    return {
+      virtualProvider: "router",
+      virtualModelId,
+      provider: "deepseek",
+      modelId: "deepseek-v4",
+      api: "openai-completions",
+      sessionIdHash: hint?.sessionIdHash,
+      timestamp: Date.now(),
+    };
+  },
+});
+```
+
+不要覆盖已有 registry。如果你的扩展比本优化器更早加载，请在 `session_start` 时重试注册，或仅在 registry 不存在时创建同样的 V1 registry 形状。
+
+### 可选：按查询过滤的缓存提示
+
+会转发到内部 Pi 请求路径的 router，可以从 `Symbol.for("pi.cache.hints.v1")` 读取按查询过滤的提示：
+
+```ts
+const CACHE_HINTS = Symbol.for("pi.cache.hints.v1");
+const hints = (globalThis as Record<symbol, any>)[CACHE_HINTS]?.getHints?.({
+  sessionIdHash,
+  virtualProvider: "router",
+  virtualModelId: "auto",
+  upstreamProvider: "deepseek",
+  upstreamModelId: "deepseek-v4",
+  api: "openai-completions",
+});
+```
+
+当查询匹配当前 session/route 时，`hints` 可能包含 `systemPrompt`、`promptCacheKey` 和 `cacheRetention: "long"`。这些提示是参考信息且可能敏感：不要记录日志，不要暴露 prompt 文本，也不要覆盖已有 request-level `prompt_cache_key` / `promptCacheKey`。
+
+### 安全与正确性规则
+
+- 不要导入 `pi-cache-optimizer`；只使用 `Symbol.for(...)` 发现协议。
+- 不要在 route snapshot 或日志中暴露 API key、prompt、payload、headers、response body 或模型输出。
+- 最终归因使用 assistant-message metadata；live registry 只是参考信息，到响应完成时可能已经过期。
+- 保持 usage 真实。缺失 cache usage 时应该显示 0 或低报，而不是合成命中。
+
 ## 卸载
 
 ```bash

package/package.json

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