pi-cache-optimizer 2.8.11 → 2.8.12

package/README.md

@@ -25,6 +25,7 @@ Pi extension for improving provider-side KV / prompt cache hit rates. It keeps s
 - [Auto-repair with `/cache-optimizer fix`](#auto-repair-with-cache-optimizer-fix)
 - [DeepSeek protocol safety and rollback](#deepseek-protocol-safety-and-rollback)
 - [Footer stats](#footer-stats)
+- [Native virtual models (Pi 0.99+)](#native-virtual-models-pi-099)
 - [For router / virtual-channel extension authors](#for-router--virtual-channel-extension-authors)
 - [Uninstall](#uninstall)
 - [Verify effect](#verify-effect)
@@ -42,6 +43,7 @@ Pi extension for improving provider-side KV / prompt cache hit rates. It keeps s
 - Shows current conversation-session provider/model footer stats by default; `total` aggregates all valid local shards for the exact provider/model.
 - 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.
 - Includes disabled-by-default deterministic ordering for verified built-in tool payloads.
+- Supports Pi 0.99+ native virtual models (`pi.registerVirtualModel()`): request hooks, footer stats, and diagnostics act on the physical model each request is routed to.
 
 Caching is provider-side and best-effort. Third-party proxies and router extensions can still hide cache usage, reject unsupported parameters, or route requests across multiple upstreams.
 
@@ -61,7 +63,7 @@ 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).
 
-This extension requires Pi 0.82+ and is validated against Pi 0.87.1. It uses the official Pi package types directly for type-checking, along with extension hooks, `getAgentDir()`, and prompt options shared by those versions; it does not depend on Pi 0.83+ APIs such as `ctx.scopedModels` or the bundled TypeBox 1.3 aliases.
+This extension requires Pi 0.82+ and is validated against Pi 0.99.2. It uses the official Pi package types directly for type-checking, along with extension hooks, `getAgentDir()`, and prompt options shared by those versions; it does not depend on Pi 0.83+ APIs such as `ctx.scopedModels` or the bundled TypeBox 1.3 aliases. Native virtual model support and codemode nested-call coalescing activate only on Pi 0.99+ hosts that produce them; older hosts keep the previous behavior.
 
 ## Commands
 
@@ -134,7 +136,7 @@ The explicit setting is stored in `pi-cache-optimizer-config.json` under Pi's ag
 
 ## Per-model `prompt_cache_key` opt-out
 
-Some OpenAI-compatible endpoints reject `prompt_cache_key` with HTTP 400 even though the same field is valid for other providers. Pi 0.87.1 has no native `supportsPromptCacheKey` compat field; do **not** add that unknown field to `models.json`. `supportsLongCacheRetention` is not an equivalent switch and should not be used for this purpose.
+Some OpenAI-compatible endpoints reject `prompt_cache_key` with HTTP 400 even though the same field is valid for other providers. Pi 0.99.2 has no native `supportsPromptCacheKey` compat field; do **not** add that unknown field to `models.json`. `supportsLongCacheRetention` is not an equivalent switch and should not be used for this purpose.
 
 When the extension observes an explicit field-level `prompt_cache_key` unsupported error for the exact provider/model, ordinary `/cache-optimizer fix` offers a confirmed model-scoped repair. Value-validation failures and conditional restrictions such as “not allowed when temperature is set” do not qualify. If concurrent responses from different models cannot be correlated because Pi provides no request ID, header-only evidence is ignored unless the finalized assistant message supplies exact provider/model identity. If you already know that the endpoint rejects the field, use the explicit command:
 
@@ -148,7 +150,7 @@ The preview explains that the setting is stored in the extension-owned `pi-cache
 
 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.84.1 also fixes built-in Fireworks compatibility for models that reject `prompt_cache_retention`; the extension avoids provider-name special cases and resolves exact provider/model compat from `models.json` plus the runtime model. 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 effective `supportsLongCacheRetention: true` opt-in in `models.json`; otherwise strip it before sending. Pi 0.87.1 has no native `supportsPromptCacheKey` compat field, so the per-model key opt-out is stored in this extension's `pi-cache-optimizer-config.json` instead of `models.json`. The extension config is independent of Pi's compat precedence and only affects the exact provider/model listed there.
+Pi 0.84.1 also fixes built-in Fireworks compatibility for models that reject `prompt_cache_retention`; the extension avoids provider-name special cases and resolves exact provider/model compat from `models.json` plus the runtime model. 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 effective `supportsLongCacheRetention: true` opt-in in `models.json`; otherwise strip it before sending. Pi 0.99.2 has no native `supportsPromptCacheKey` compat field, so the per-model key opt-out is stored in this extension's `pi-cache-optimizer-config.json` instead of `models.json`. The extension config is independent of Pi's compat precedence and only affects the exact provider/model listed there.
 
 For real proxies, start with session affinity:
 
@@ -174,7 +176,7 @@ Notes:
 
 - `sendSessionAffinityHeaders: true` is the safe default when your proxy supports sticky routing.
 - `supportsLongCacheRetention: true` is optional. Add it only when the endpoint explicitly supports OpenAI long prompt cache retention.
-- Do not add `supportsPromptCacheKey` to `models.json`: Pi 0.87.1 does not define that compat field. Use `/cache-optimizer fix prompt-cache-key` to store an exact provider/model omit rule in the extension-owned config; it removes both key spellings, including a key supplied by Pi.
+- Do not add `supportsPromptCacheKey` to `models.json`: Pi 0.99.2 does not define that compat field. Use `/cache-optimizer fix prompt-cache-key` to store an exact provider/model omit rule in the extension-owned config; it removes both key spellings, including a key supplied by Pi.
 - If you see `400 Unsupported parameter: prompt_cache_retention`, remove/avoid `supportsLongCacheRetention` for that channel. Keep `sendSessionAffinityHeaders` if supported. The extension detects the explicit error from response headers or the finalized assistant error message and strips the parameter from subsequent requests in the current process.
 - Use `/cache-optimizer compat` or `/cache-optimizer doctor` to see model-specific advice.
 - DeepSeek model names select the `DS cache` adapter only; they do not prove a reasoning wire protocol. Generic cache/routing advice remains active for absent or non-DeepSeek formats. DeepSeek replay advice is shown only when effective `compat.thinkingFormat: "deepseek"` is explicitly configured; it never treats `thinkingFormat` as a missing fix key.
@@ -358,6 +360,16 @@ 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.
 
+## Native virtual models (Pi 0.99+)
+
+Pi 0.99 lets extensions register virtual models with `pi.registerVirtualModel()`. While one is selected, `ctx.model` stays the virtual model (`api: "pi-virtual"`) and Pi routes every request to a physical model. This extension follows the physical model automatically; router authors do not need the protocol below.
+
+- Request hooks read the dispatched model id from the provider payload and match it against physical models with configured credentials. The `prompt_cache_key` fallback, `prompt_cache_retention` safety, Anthropic TTL repair, and per-model `prompt_cache_key` omit rules then apply to that physical model. If several credentialed providers share the id and would be treated differently, the extension does not guess; identity-dependent request changes are skipped.
+- Footer stats and `/cache-optimizer doctor`, `compat`, `stats`, `reset`, and `fix` use the physical model that answered last on the current session branch, matching Pi's own routed-model display and context limits. Doctor and compat name both the virtual selection and that physical model.
+- Before Pi routes the first request, the footer stays empty and diagnostics ask you to send a prompt first.
+- Prompt rewriting is skipped for virtual selections: Pi picks the physical model after the system prompt is built, and a reordered prompt must not reach a safety-filtered Codex route.
+- The session-affinity header bridge is skipped as well, because Pi builds request headers before the payload exists. Pi still sends the physical model's own configured affinity headers.
+
 ## 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.

package/README.zh-CN.md

@@ -25,6 +25,7 @@
 - [使用 `/cache-optimizer fix` 自动修复](#使用-cache-optimizer-fix-自动修复)
 - [DeepSeek 协议安全与回滚](#deepseek-协议安全与回滚)
 - [Footer 统计](#footer-统计)
+- [原生虚拟模型（Pi 0.99+）](#原生虚拟模型pi-099)
 - [Router / Virtual-channel 扩展作者指南](#router--virtual-channel-扩展作者指南)
 - [卸载](#卸载)
 - [验证效果](#验证效果)
@@ -42,6 +43,7 @@
 - Footer 默认显示当前 conversation session 的 provider/model 统计；`total` 可聚合同一精确 provider/model 的所有有效本地 shard。
 - 通过版本化全局协议（`Symbol.for("pi.routing.registry.v1")` 与 `Symbol.for("pi.cache.hints.v1")`）支持可选的 router extension 集成，而不导入任何 router 包。
 - 提供默认关闭的确定性排序，用于已验证的 Pi 内置工具 payload。
+- 支持 Pi 0.99+ 原生虚拟模型（`pi.registerVirtualModel()`）：请求 hook、footer 统计和诊断都作用于每次请求实际路由到的物理模型。
 
 缓存是 provider 侧的 best-effort 行为。第三方代理和 router extension 仍可能隐藏缓存 usage、拒绝不支持的参数，或把请求路由到多个上游。
 
@@ -61,7 +63,7 @@ pi remove npm:pi-deepseek-cache-optimizer && pi install npm:pi-cache-optimizer
 
 Pi 0.79.7 及之后，`pi update` 默认只更新 Pi 本体。若要更新已安装的 Pi package（包括本扩展），请运行 `pi update --extensions`（只更新 packages）或 `pi update --all`（Pi 与 packages 一起更新）。
 
-本扩展要求 Pi 0.82+，并已使用 Pi 0.87.1 验证。TypeScript 校验直接使用官方 Pi package 类型，同时只使用这些版本共有的 extension hooks、`getAgentDir()` 和 prompt options；不依赖 Pi 0.83+ 专有 API（例如 `ctx.scopedModels` 或 bundled TypeBox 1.3 aliases）。
+本扩展要求 Pi 0.82+，并已使用 Pi 0.99.2 验证。TypeScript 校验直接使用官方 Pi package 类型，同时只使用这些版本共有的 extension hooks、`getAgentDir()` 和 prompt options；不依赖 Pi 0.83+ 专有 API（例如 `ctx.scopedModels` 或 bundled TypeBox 1.3 aliases）。原生虚拟模型支持与 codemode 嵌套工具调用合并只在会产生它们的 Pi 0.99+ 上生效，较早版本保持原有行为。
 
 ## 命令
 
@@ -134,7 +136,7 @@ Footer 默认使用 `session`，避免另一个并行 Pi 终端使用相同 prov
 
 ## 按模型关闭 `prompt_cache_key`
 
-某些 OpenAI-compatible endpoint 会因 `prompt_cache_key` 返回 HTTP 400，但同一个字段对其他 provider 可能有效。Pi 0.87.1 没有原生的 `supportsPromptCacheKey` compat 字段，**不要**把这个未知字段加入 `models.json`。`supportsLongCacheRetention` 也不是等价开关，不应借用来实现此目的。
+某些 OpenAI-compatible endpoint 会因 `prompt_cache_key` 返回 HTTP 400，但同一个字段对其他 provider 可能有效。Pi 0.99.2 没有原生的 `supportsPromptCacheKey` compat 字段，**不要**把这个未知字段加入 `models.json`。`supportsLongCacheRetention` 也不是等价开关，不应借用来实现此目的。
 
 当扩展观察到精确 provider/model 对 `prompt_cache_key` 的明确字段级拒绝后，普通 `/cache-optimizer fix` 会提供经过确认的模型级修复。参数值校验失败，以及“设置 temperature 时不允许”这类条件限制都不构成证据。若不同模型的响应并发交错，而 Pi 又没有提供 request ID，扩展会忽略无法安全关联的 response-header 证据；只有最终 assistant message 提供精确 provider/model 身份时才恢复归因。如果你已经确定 endpoint 不支持该字段，可以主动执行：
 
@@ -148,7 +150,7 @@ Footer 默认使用 `session`，避免另一个并行 Pi 终端使用相同 prov
 
 LiteLLM / OneAPI / NewAPI / 类 OpenRouter 渠道等第三方 `openai-completions` 代理，常会把同一个 session 分散到多个上游后端，导致 provider 侧 prompt cache 被拆散。
 
-Pi 0.84.1 还修复了内置 Fireworks 渠道对拒绝 `prompt_cache_retention` 的模型兼容性；本扩展不按 provider 名称增加特殊分支，而是结合 `models.json` 与 runtime model，按精确 provider/model 解析有效 compat。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` 时保留，否则发送前移除。Pi 0.87.1 没有原生的 `supportsPromptCacheKey` compat 字段，因此按模型关闭 key 的策略保存在本扩展的 `pi-cache-optimizer-config.json` 中，而不是 `models.json`。扩展配置独立于 Pi 的 compat 优先级，只影响其中列出的精确 provider/model。
+Pi 0.84.1 还修复了内置 Fireworks 渠道对拒绝 `prompt_cache_retention` 的模型兼容性；本扩展不按 provider 名称增加特殊分支，而是结合 `models.json` 与 runtime model，按精确 provider/model 解析有效 compat。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` 时保留，否则发送前移除。Pi 0.99.2 没有原生的 `supportsPromptCacheKey` compat 字段，因此按模型关闭 key 的策略保存在本扩展的 `pi-cache-optimizer-config.json` 中，而不是 `models.json`。扩展配置独立于 Pi 的 compat 优先级，只影响其中列出的精确 provider/model。
 
 对真正的代理，建议先启用 session affinity：
 
@@ -174,7 +176,7 @@ Pi 0.84.1 还修复了内置 Fireworks 渠道对拒绝 `prompt_cache_retention`
 
 - `sendSessionAffinityHeaders: true` 是安全默认项，前提是你的代理支持 sticky routing。
 - `supportsLongCacheRetention: true` 是可选项。只有 endpoint 明确支持 OpenAI long prompt cache retention 时才添加。
-- 不要把 `supportsPromptCacheKey` 加入 `models.json`：Pi 0.87.1 没有定义这个 compat 字段。请使用 `/cache-optimizer fix prompt-cache-key` 在扩展自有配置中保存精确 provider/model 的 omit 规则；它会移除两种 key 写法，包括 Pi 提供的 key。
+- 不要把 `supportsPromptCacheKey` 加入 `models.json`：Pi 0.99.2 没有定义这个 compat 字段。请使用 `/cache-optimizer fix prompt-cache-key` 在扩展自有配置中保存精确 provider/model 的 omit 规则；它会移除两种 key 写法，包括 Pi 提供的 key。
 - 如果出现 `400 Unsupported parameter: prompt_cache_retention`，请为该渠道移除 / 避免 `supportsLongCacheRetention`；如支持，可保留 `sendSessionAffinityHeaders`。扩展会从响应头或最终 assistant error message 中识别这条明确错误，并在当前进程的后续请求中移除该参数。
 - 使用 `/cache-optimizer compat` 或 `/cache-optimizer doctor` 查看当前模型的具体建议。
 - DeepSeek 模型名只用于选择 `DS cache` adapter，不能证明 reasoning wire protocol。缺少或使用非 DeepSeek format 时仍保留通用缓存 / 路由建议；只有 effective `compat.thinkingFormat: "deepseek"` 被明确配置时，才显示 DeepSeek replay 建议，且不会把 `thinkingFormat` 列为缺失修复项。
@@ -357,6 +359,16 @@ Pi 0.79+ 已内置 footer `CH` 标记，用于显示最近一次 prompt cache hi
 
 Adapter 选择只看模型 id/name（以及 message_end 时 assistant message 的 model/name）。仅使用 OpenAI-shaped API 不会被当作 OpenAI-family，除非模型 id/name 匹配受支持的家族。
 
+## 原生虚拟模型（Pi 0.99+）
+
+Pi 0.99 允许扩展通过 `pi.registerVirtualModel()` 注册虚拟模型。选中虚拟模型时，`ctx.model` 保持为虚拟模型（`api: "pi-virtual"`），而 Pi 会把每次请求路由到某个物理模型。本扩展会自动跟随该物理模型，router 作者无需接入下文的协议。
+
+- 请求 hook 从 provider payload 中读取实际派发的模型 id，并在已配置凭证的物理模型中匹配。`prompt_cache_key` fallback、`prompt_cache_retention` 安全规则、Anthropic TTL 修复以及按模型关闭 `prompt_cache_key` 的规则都按该物理模型生效。如果多个已配置凭证的 provider 共用同一个 id 且处理方式不同，扩展不会猜测，而是跳过依赖模型身份的请求修改。
+- Footer 统计以及 `/cache-optimizer doctor`、`compat`、`stats`、`reset`、`fix` 使用当前会话分支上最近一次应答的物理模型，与 Pi 自身显示的路由模型和 context 上限一致。doctor 与 compat 会同时标出虚拟选择和该物理模型。
+- 在 Pi 路由第一个请求之前，footer 保持为空，诊断会提示先发送一个 prompt。
+- 虚拟选择不做 prompt 改写：Pi 在构建 system prompt 之后才决定物理模型，重排后的 prompt 不应被送到有安全过滤的 Codex 路由。
+- Session-affinity header 桥接同样跳过，因为 Pi 在 payload 生成之前就构造请求 header。Pi 仍会发送物理模型自身配置的 affinity header。
+
 ## Router / Virtual-channel 扩展作者指南
 
 如果你的 Pi 扩展提供虚拟 routing provider（例如 `router/auto`、`router/smart`，或会转发到真实上游的 profile/channel），本扩展可以为真实上游 provider/model 显示缓存统计，而不是把统计记到虚拟外壳上。集成是可选、版本化的，并且**不需要导入本包**。

package/index.ts

@@ -212,6 +212,8 @@ type PromptCacheKeyConfigReceiptSnapshot = {
 };
 const PI_ROUTING_REGISTRY_SYMBOL = Symbol.for("pi.routing.registry.v1");
 const PI_CACHE_HINTS_SYMBOL = Symbol.for("pi.cache.hints.v1");
+// Model API that Pi 0.99+ assigns to native virtual models (VIRTUAL_MODEL_API).
+const PI_VIRTUAL_MODEL_API = "pi-virtual";
 const PI_CACHE_HINTS_OWNER_SYMBOL = Symbol.for("pi.cache.optimizer.hints-owner.v1");
 const ANTHROPIC_TTL_FALLBACK_SYMBOL = Symbol.for("pi.cache.optimizer.anthropic-ttl-fallback.v1");
 const REASONING_PROTOCOL_FALLBACK_SYMBOL = Symbol.for("pi.cache.optimizer.reasoning-protocol-fallback.v1");
@@ -1397,6 +1399,9 @@ function resolveRouteModel(
   model: PiModel | undefined,
   ctx?: ContextWithOptionalModelRegistry,
 ): PiModel | undefined {
+  const nativeVirtualRoute = resolveNativeVirtualRouteModel(model, ctx);
+  if (nativeVirtualRoute) return nativeVirtualRoute;
+
   const snapshot = resolveActiveRouteSnapshot(model, ctx);
   if (!snapshot) return undefined;
 
@@ -1407,7 +1412,171 @@ function resolveRouteModel(
 
 function isVirtualRoutingModel(model: PiModel | undefined, ctx?: Pick<ExtensionContext, "sessionManager">): boolean {
   if (!model) return false;
-  return isRouterModel(model) || !!getRoutingRegistry()?.getRouter(model.provider) || !!resolveActiveRouteSnapshot(model, ctx);
+  return isNativeVirtualModel(model) || isRouterModel(model) || !!getRoutingRegistry()?.getRouter(model.provider) || !!resolveActiveRouteSnapshot(model, ctx);
+}
+
+// Pi 0.99+ native virtual models (`pi.registerVirtualModel()`). `ctx.model`
+// stays the virtual selection while Pi dispatches every request to a physical
+// model; only assistant messages and the provider payload name that model.
+// Older Pi hosts never produce this API, so every native-virtual path is inert.
+type NativeVirtualDispatch = { provider: string; id: string; api: string };
+
+function isNativeVirtualModel(model: { api?: unknown } | undefined): boolean {
+  return model?.api === PI_VIRTUAL_MODEL_API;
+}
+
+function readSessionBranch(ctx: Pick<ExtensionContext, "sessionManager"> | undefined): unknown[] {
+  try {
+    const manager = ctx?.sessionManager as { getBranch?: () => unknown } | undefined;
+    if (typeof manager?.getBranch !== "function") return [];
+    const branch = manager.getBranch();
+    return Array.isArray(branch) ? branch : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Physical models that answered on the current session branch, newest first:
+ * the latest successful response (Pi's `request.previous`) and the latest
+ * response of any outcome (a failed attempt that a retry may reuse). The
+ * catalog id in `message.model` is preferred over the echoed `responseModel`
+ * because it is the id Pi dispatched and the registry knows.
+ */
+function findNativeVirtualDispatches(ctx: Pick<ExtensionContext, "sessionManager"> | undefined): {
+  latestSuccessful?: NativeVirtualDispatch;
+  latestAny?: NativeVirtualDispatch;
+} {
+  const branch = readSessionBranch(ctx);
+  let latestSuccessful: NativeVirtualDispatch | undefined;
+  let latestAny: NativeVirtualDispatch | undefined;
+  for (let index = branch.length - 1; index >= 0 && !latestSuccessful; index--) {
+    const entry = asRecord(branch[index]);
+    if (entry?.type !== "message") continue;
+    const message = getAssistantRecord(entry.message);
+    if (!message || isNativeVirtualModel(message)) continue;
+    const dispatch = nativeVirtualDispatchFromMessage(message);
+    if (!dispatch) continue;
+    latestAny ??= dispatch;
+    if (message.stopReason !== "error" && message.stopReason !== "aborted") latestSuccessful = dispatch;
+  }
+  return { latestSuccessful, latestAny };
+}
+
+function nativeVirtualDispatchFromMessage(message: unknown): NativeVirtualDispatch | undefined {
+  const record = getAssistantRecord(message);
+  if (!record || isNativeVirtualModel(record)) return undefined;
+  const provider = firstNonEmptyString(record.provider);
+  const id = firstNonEmptyString(record.model, record.responseModel);
+  return provider && id ? { provider, id, api: firstNonEmptyString(record.api) ?? "" } : undefined;
+}
+
+function nativeVirtualDispatchToModel(
+  dispatch: NativeVirtualDispatch,
+  ctx?: ContextWithOptionalModelRegistry,
+): PiModel {
+  // A virtual model hides a same-id physical model in the catalog, so a
+  // registry hit that is itself virtual is not physical metadata.
+  const registered = findModelInRegistry(ctx?.modelRegistry, dispatch.provider, dispatch.id);
+  const model = registered && !isNativeVirtualModel(registered)
+    ? registered
+    : ({
+      provider: dispatch.provider,
+      id: dispatch.id,
+      name: dispatch.id,
+      api: dispatch.api,
+      baseUrl: "",
+      reasoning: false,
+      input: ["text"],
+      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+      contextWindow: 0,
+      maxTokens: 0,
+      [ROUTED_FALLBACK_MODEL_SYMBOL]: true,
+    } as PiModel);
+  return applyConfiguredTransportToModel(model, readEffectiveCompatConfig());
+}
+
+/**
+ * Physical model behind a native virtual selection for pre-request UX (footer,
+ * doctor, compat, stats, reset, fix): the model that answered last on this
+ * session branch, matching Pi's own routed-model display and context limits.
+ */
+function resolveNativeVirtualRouteModel(
+  model: PiModel | undefined,
+  ctx?: ContextWithOptionalModelRegistry,
+): PiModel | undefined {
+  if (!isNativeVirtualModel(model)) return undefined;
+  const { latestSuccessful, latestAny } = findNativeVirtualDispatches(ctx);
+  const dispatch = latestSuccessful ?? latestAny;
+  return dispatch ? nativeVirtualDispatchToModel(dispatch, ctx) : undefined;
+}
+
+function getProviderPayloadModelId(payload: unknown): string | undefined {
+  const record = asRecord(payload);
+  // Pi's built-in transports put the dispatched catalog id in `model`
+  // (OpenAI, Anthropic, Google, Mistral) or `modelId` (Bedrock Converse).
+  return firstNonEmptyString(record?.model, record?.modelId);
+}
+
+function physicalModelsWithId(candidates: readonly PiModel[] | undefined, id: string): PiModel[] {
+  return (candidates ?? []).filter((candidate) => candidate.id === id && !isNativeVirtualModel(candidate));
+}
+
+/**
+ * Physical model of one native-virtual request. `before_provider_request`
+ * carries only the payload and `ctx.model` stays virtual, so the payload's
+ * dispatched model id is matched against credentialed physical models (a
+ * router may only route to those). A unique provider match wins. An id shared
+ * by several credentialed providers is used only when every candidate gets the
+ * same request treatment (`requestPolicyKey`); the identity then stays
+ * ambiguous so response evidence is never pinned to a guessed provider.
+ * Differing policies return undefined so identity-dependent request mutations
+ * fail closed. Without a credentialed match, the sticky branch candidates and
+ * then the full catalog are consulted.
+ */
+function resolveNativeVirtualRequestModel(
+  model: PiModel | undefined,
+  payload: unknown,
+  ctx?: ContextWithOptionalModelRegistry,
+  requestPolicyKey?: (candidate: PiModel) => string,
+): { model: PiModel; identityAmbiguous: boolean } | undefined {
+  if (!isNativeVirtualModel(model)) return undefined;
+  const payloadModelId = getProviderPayloadModelId(payload);
+  if (!payloadModelId) return undefined;
+  const config = readEffectiveCompatConfig();
+  // null: no candidate; undefined: ambiguous with differing request policies.
+  const pick = (matches: PiModel[]): { model: PiModel; identityAmbiguous: boolean } | undefined | null => {
+    if (matches.length === 0) return null;
+    const configured = matches.map((candidate) => applyConfiguredTransportToModel(candidate, config));
+    if (new Set(configured.map((candidate) => candidate.provider)).size === 1) {
+      return { model: configured[0], identityAmbiguous: false };
+    }
+    const policies = requestPolicyKey ? new Set(configured.map(requestPolicyKey)) : undefined;
+    return policies?.size === 1 ? { model: configured[0], identityAmbiguous: true } : undefined;
+  };
+  try {
+    const credentialed = pick(physicalModelsWithId(ctx?.modelRegistry?.getAvailable?.(), payloadModelId));
+    if (credentialed !== null) return credentialed;
+
+    const { latestSuccessful, latestAny } = findNativeVirtualDispatches(ctx);
+    for (const dispatch of [latestSuccessful, latestAny]) {
+      if (dispatch?.id === payloadModelId) {
+        return { model: nativeVirtualDispatchToModel(dispatch, ctx), identityAmbiguous: false };
+      }
+    }
+
+    return pick(physicalModelsWithId(ctx?.modelRegistry?.getAll?.(), payloadModelId)) ?? undefined;
+  } catch {
+    // Registry access is optional input; never fail the provider request hook.
+    return undefined;
+  }
+}
+
+function describeNativeVirtualRouteNote(selected: PiModel | undefined, effective: PiModel | undefined): string | undefined {
+  if (!selected || !isNativeVirtualModel(selected)) return undefined;
+  // Without a routed response, the not-applicable text explains the state.
+  if (!effective || isNativeVirtualModel(effective)) return undefined;
+  return `🔀 Native virtual model ${modelKey(selected)} → latest routed physical model ${modelKey(effective)}. The diagnostics below apply to that physical model; Pi may route later requests elsewhere.`;
 }
 
 function isCacheHintsServiceV1(value: unknown): value is PiCacheHintsV1 {
@@ -2589,11 +2758,13 @@ function isPiBuiltInLlamaCppModel(model: PiModel | undefined): boolean {
   // 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.
+  // supportsUsageInStreaming is deliberately not part of the fingerprint: Pi
+  // 0.82.x sets it false and Pi 0.83+ sets it true after fixing streamed usage,
+  // and it carries no routing or cache configuration.
   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
@@ -2602,7 +2773,7 @@ function isPiBuiltInLlamaCppModel(model: PiModel | undefined): boolean {
 }
 
 function shouldInjectOpenAIPromptCacheKeyForModel(model: PiModel | undefined): boolean {
-  // Pi 0.87.1 has no native supportsPromptCacheKey compat field. Per-model
+  // Pi 0.99.2 has no native supportsPromptCacheKey compat field. Per-model
   // opt-out is owned by this extension's promptCacheKey.omit configuration;
   // this helper only exposes the transport API gate for fixture consumers.
   return isOpenAICompatibleApi(model?.api);
@@ -3445,6 +3616,22 @@ function snapshotProviderRequestModel(model: PiModel | undefined): PiModel | und
   } as PiModel;
 }
 
+// Some provider requests never produce a finalized assistant message: Pi's
+// prompt-cache warming (0.86+) replays a request with maxTokens: 1 outside the
+// agent loop, so message_end never consumes its lifecycle record. Cap the
+// process-local list and drop the oldest completed record first.
+const MAX_PROVIDER_REQUEST_STATES = 32;
+
+function pruneProviderRequestStates<T extends { responseReceived: boolean }>(
+  states: T[],
+  max = MAX_PROVIDER_REQUEST_STATES,
+): void {
+  while (states.length > max) {
+    const completed = states.findIndex((state) => state.responseReceived);
+    states.splice(completed >= 0 ? completed : 0, 1);
+  }
+}
+
 function keyForModelExt(model: { provider: string; id: string }): string {
   return `${model.provider}/${model.id}`;
 }
@@ -5271,6 +5458,9 @@ const CACHE_PROVIDER_ADAPTERS: CacheProviderAdapter[] = [
 ];
 
 function selectAdapterForModel(model: PiModel | undefined): CacheProviderAdapter | undefined {
+  // A native virtual selection has no cache identity of its own; stats always
+  // belong to the physical model it routed to.
+  if (isNativeVirtualModel(model)) return undefined;
   return CACHE_PROVIDER_ADAPTERS.find((adapter) => adapter.matchesModel(model));
 }
 
@@ -6642,6 +6832,13 @@ function describeRouterChannelDiagnostics(model: PiModel): string[] {
 function getCompatCheckNotApplicableLines(model: PiModel): string[] {
   const api = lower(model.api);
 
+  if (isNativeVirtualModel(model)) {
+    return [
+      "ℹ️ Compat check not applicable for this model.",
+      "   Native virtual model: Pi routes each request to a physical model and none has answered on this session branch yet. Send a prompt, then rerun to diagnose the physical model that answered.",
+    ];
+  }
+
   if (isMistralConversationsApi(api)) {
     return [
       "ℹ️ Compat check not applicable for this model.",
@@ -10212,6 +10409,16 @@ export const __internals_for_tests = {
   applyConfiguredTransportToModel,
   resolveRouteModel,
   isVirtualRoutingModel,
+  PI_VIRTUAL_MODEL_API,
+  isNativeVirtualModel,
+  findNativeVirtualDispatches,
+  resolveNativeVirtualRouteModel,
+  resolveNativeVirtualRequestModel,
+  getProviderPayloadModelId,
+  getCompatCheckNotApplicableLines,
+  describeNativeVirtualRouteNote,
+  pruneProviderRequestStates,
+  MAX_PROVIDER_REQUEST_STATES,
   installCacheHintsService,
   getCacheHintsService,
   markOptimizerOwnedCacheHintsService,
@@ -10347,6 +10554,8 @@ export default function (pi: ExtensionAPI) {
     model: PiModel;
     responseReceived: boolean;
     correlationAmbiguous: boolean;
+    // A native virtual request whose dispatched id matched several providers.
+    identityAmbiguous?: boolean;
   };
   const providerRequestStates: ProviderRequestState[] = [];
   let shardCreatedAt = Date.now();
@@ -10878,6 +11087,24 @@ export default function (pi: ExtensionAPI) {
     );
   }
 
+  /**
+   * Request treatment that before_provider_request derives from a model's
+   * identity. A native virtual request whose dispatched id matches several
+   * credentialed providers is resolved only when this key agrees for all of
+   * them, so no provider-specific decision is applied on a guess.
+   */
+  function requestPolicyKey(model: PiModel): string {
+    const key = modelKey(model);
+    return JSON.stringify([
+      model.api ?? "",
+      isOfficialOpenAIBaseUrl(model),
+      hasExplicitLongRetentionOptIn(model),
+      promptCacheRetention400Models.has(key),
+      anthropicTtlOrderErrorModels.has(key),
+      isPromptCacheKeyOmittedForModel(model),
+    ]);
+  }
+
   pi.on("session_start", async (event, ctx) => {
     if (runtimeOptimizerEnabled) requestLongCacheRetention();
     await restoreCacheStats(event.reason, ctx);
@@ -10892,7 +11119,10 @@ export default function (pi: ExtensionAPI) {
     await publishStatus(ctx);
   });
 
-  pi.on("tool_execution_end", async (_event, ctx) => {
+  pi.on("tool_execution_end", async (event, ctx) => {
+    // Pi 0.99+ codemode scripts run nested tool calls in parallel; the calling
+    // tool's own end event follows them, so one refresh covers the batch.
+    if (isNonEmptyString((event as { parentToolCallId?: unknown } | undefined)?.parentToolCallId)) return;
     await refreshShardAggregate();
     await publishStatus(ctx);
   });
@@ -10965,6 +11195,13 @@ export default function (pi: ExtensionAPI) {
     if (model && isResponsesPromptRewriteBypassApi(model.api)) {
       return {};
     }
+    // Pi 0.99+ native virtual selections pick the physical model per request,
+    // after this system prompt is built, so the bypass above cannot be decided
+    // here. A route may reach the safety-filtered Codex backend; keep Pi's
+    // prompt byte-for-byte instead of reordering it.
+    if (isNativeVirtualModel(_ctx.model)) {
+      return {};
+    }
 
     if (!runtimeOptimizerEnabled) return {};
 
@@ -11043,6 +11280,10 @@ export default function (pi: ExtensionAPI) {
   });
 
   pi.on("before_provider_headers", (event, ctx) => {
+    // Pi transforms headers before the payload exists and passes no model, so a
+    // native virtual request's physical model is unknown here. Fail closed; Pi
+    // core still sends the physical model's own configured affinity headers.
+    if (isNativeVirtualModel(ctx.model)) return;
     const requestModel = resolveRouteModel(ctx.model, ctx) ?? ctx.model;
     addEffectiveSessionAffinityHeaders(
       event.headers,
@@ -11052,12 +11293,24 @@ export default function (pi: ExtensionAPI) {
   });
 
   pi.on("before_provider_request", (event, ctx) => {
-    const requestModel = resolveRouteModel(ctx.model, ctx) ?? ctx.model;
+    // A native virtual selection keeps ctx.model virtual; resolve the physical
+    // model from the dispatched payload. Unresolved requests keep the virtual
+    // model, which fails every identity-dependent mutation closed.
+    const nativeVirtualRequest = resolveNativeVirtualRequestModel(ctx.model, event.payload, ctx, requestPolicyKey);
+    const requestModel = nativeVirtualRequest?.model ?? resolveRouteModel(ctx.model, ctx) ?? ctx.model;
     // Request-local identity is also needed by the always-on Anthropic TTL
     // validity repair, so retain the credential-blind snapshot even while the
     // optional runtime optimizer features are disabled.
     const snapshot = snapshotProviderRequestModel(requestModel);
-    if (snapshot) providerRequestStates.push({ model: snapshot, responseReceived: false, correlationAmbiguous: false });
+    if (snapshot) {
+      providerRequestStates.push({
+        model: snapshot,
+        responseReceived: false,
+        correlationAmbiguous: false,
+        identityAmbiguous: isNativeVirtualModel(ctx.model) && (!nativeVirtualRequest || nativeVirtualRequest.identityAmbiguous),
+      });
+      pruneProviderRequestStates(providerRequestStates);
+    }
     let requestPayload: unknown = event.payload;
     let toolOrderChanged = false;
 
@@ -11143,7 +11396,12 @@ export default function (pi: ExtensionAPI) {
       }
     }
     if (responseState) responseState.responseReceived = true;
-    const model = responseState?.model ?? (pendingStates.length === 0 ? (resolveRouteModel(ctx.model, ctx) ?? ctx.model) : undefined);
+    // A native virtual request whose physical provider could not be pinned
+    // records no model-scoped header evidence; finalized assistant messages
+    // still carry exact provider/model identity.
+    const model = responseState
+      ? (responseState.identityAmbiguous ? undefined : responseState.model)
+      : (pendingStates.length === 0 && !isNativeVirtualModel(ctx.model) ? (resolveRouteModel(ctx.model, ctx) ?? ctx.model) : undefined);
     if (!runtimeOptimizerEnabled || !model) return;
 
     // Keep only the category, never the provider's complete error text. This
@@ -11252,9 +11510,10 @@ export default function (pi: ExtensionAPI) {
           : (completedIndex >= 0 ? completedIndex : (contextIndex >= 0 ? contextIndex : 0));
         const state = providerRequestStates.splice(index, 1)[0];
         if (!state) return { model: undefined, ambiguous: false };
+        const ambiguous = (state.correlationAmbiguous || state.identityAmbiguous === true) && explicitIndex < 0;
         return {
-          model: state.correlationAmbiguous && explicitIndex < 0 ? undefined : state.model,
-          ambiguous: state.correlationAmbiguous && explicitIndex < 0,
+          model: ambiguous ? undefined : state.model,
+          ambiguous,
         };
       })()
       : { model: undefined, ambiguous: false };
@@ -11342,7 +11601,18 @@ export default function (pi: ExtensionAPI) {
       }
     }
 
-    const adapter = selectAdapterForAssistantMessage(event.message, ctx.model);
+    // A native virtual selection keeps ctx.model virtual, while the finalized
+    // message names the physical catalog model Pi dispatched. Resolve that
+    // model from the registry so adapter tokens, the stats key, and the footer
+    // compat marker use the same physical identity as the pre-request UX.
+    const nativeVirtualDispatch = isNativeVirtualModel(ctx.model)
+      ? nativeVirtualDispatchFromMessage(event.message)
+      : undefined;
+    const nativeVirtualMessageModel = nativeVirtualDispatch
+      ? nativeVirtualDispatchToModel(nativeVirtualDispatch, ctx)
+      : undefined;
+
+    const adapter = selectAdapterForAssistantMessage(event.message, nativeVirtualMessageModel ?? ctx.model);
     if (!adapter) return;
 
     // Skip stats for error/aborted messages (network retries, user aborts).
@@ -11372,6 +11642,7 @@ export default function (pi: ExtensionAPI) {
     // the active model id. Virtual routing providers keep message-local
     // identity (router correctness).
     statsModel = consolidateDirectProviderStatsModel(statsModel, ctx.model, ctx);
+    if (nativeVirtualMessageModel) statsModel = nativeVirtualMessageModel;
     let routedModelChanged = false;
     if (isVirtualRoutingModel(ctx.model, ctx) && statsModel && !isVirtualRoutingModel(statsModel, ctx)) {
       const nextRoutedModel: PersistedRoutedModelRef = {
@@ -11486,9 +11757,8 @@ export default function (pi: ExtensionAPI) {
         const statsState = model ? cacheStatsTotalsByModel[modelKey(model)] : undefined;
         const samples = sk ? getRecentSamples(sk) : [];
         const lowHitLines = buildLowHitDiagnosis(model, adapter, statsState, samples);
-        const fullDiagnosis = lowHitLines.length > 0
-          ? diagnosis + "\n" + lowHitLines.join("\n")
-          : diagnosis;
+        const routeNote = describeNativeVirtualRouteNote(selectedModel, model);
+        const fullDiagnosis = [routeNote, diagnosis, ...lowHitLines].filter((line) => line !== undefined).join("\n");
         cmdCtx.ui.notify(fullDiagnosis, "info");
       } else if (subcommand === "stats") {
         const aggregate = await refreshShardAggregate();
@@ -11539,13 +11809,15 @@ export default function (pi: ExtensionAPI) {
           return;
         }
         const compatResult = buildCompatDiagnosis(model);
+        const compatRouteNote = describeNativeVirtualRouteNote(selectedModel, model);
+        const withRouteNote = (text: string): string => compatRouteNote ? `${compatRouteNote}\n${text}` : text;
         if (compatResult) {
-          cmdCtx.ui.notify(compatResult, "warning");
+          cmdCtx.ui.notify(withRouteNote(compatResult), "warning");
         } else {
           cmdCtx.ui.notify(
-            isAdaptiveThinkingCompatApplicable(model) || isDeepSeekCompatCheckApplicable(model) || isCompatCheckApplicable(model)
+            withRouteNote(isAdaptiveThinkingCompatApplicable(model) || isDeepSeekCompatCheckApplicable(model) || isCompatCheckApplicable(model)
               ? "✅ Compat fully configured."
-              : getCompatCheckNotApplicableLines(model).join("\n"),
+              : getCompatCheckNotApplicableLines(model).join("\n")),
             "info",
           );
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-cache-optimizer",
-  "version": "2.8.11",
+  "version": "2.8.12",
   "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",
@@ -35,8 +35,8 @@
     "check": "npm run typecheck && npm test && npm run check:diff && npm run check:pack"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.87.1",
-    "@earendil-works/pi-server": "0.87.1",
+    "@earendil-works/pi-coding-agent": "^0.99.2",
+    "@earendil-works/pi-server": "0.99.2",
     "@types/node": "^22.0.0",
     "jiti": "^2.7.0",
     "typescript": "^5.8.3"