pi-cache-optimizer 2.6.5 → 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)
@@ -33,8 +34,9 @@ Pi extension for improving provider-side KV / prompt cache hit rates. It keeps s
 - 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.
 - Shows session-scoped 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.
 
-Caching is provider-side and best-effort. Third-party proxies can still hide cache usage, reject unsupported parameters, or route requests across multiple upstreams.
+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.
 
 ## Install
 
@@ -50,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 |
@@ -212,6 +216,8 @@ 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.
 
+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:
 
 ```text
@@ -224,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)
@@ -33,8 +34,9 @@
 - 对缺少缓存 / session-affinity compat 的第三方 OpenAI-compatible 代理给出一次性提醒。
 - 检测 Anthropic adaptive thinking 模型（opus-4.6+、sonnet-4.6+、fable-5+）是否缺少 `forceAdaptiveThinking: true` compat。
 - 为支持的模型家族显示按 session 隔离的底部缓存统计。
+- 通过版本化全局协议（`Symbol.for("pi.routing.registry.v1")` 与 `Symbol.for("pi.cache.hints.v1")`）支持可选的 router extension 集成，而不导入任何 router 包。
 
-缓存是 provider 侧的 best-effort 行为。第三方代理仍可能隐藏缓存 usage、拒绝不支持的参数，或把请求路由到多个上游。
+缓存是 provider 侧的 best-effort 行为。第三方代理和 router extension 仍可能隐藏缓存 usage、拒绝不支持的参数，或把请求路由到多个上游。
 
 ## 安装
 
@@ -50,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 一起更新）。
+
 ## 命令
 
 | 命令 | 作用 |
@@ -212,6 +216,8 @@ Provider 级最小 override：
 
 统计是只读本地计数，保存在 `~/.pi/agent/pi-cache-optimizer-stats.json`，按 Pi session + provider/model 隔离。文件只包含日期和数字计数，不包含 API key、prompt、payload、headers、响应或模型输出。
 
+Pi 0.79+ 已内置 footer `CH` 标记，用于显示最近一次 prompt cache hit rate。本扩展在此基础上补充持久化的 provider/model/session-scoped 计数，以及代理 compat 诊断。
+
 示例 footer：
 
 ```text
@@ -224,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/index.ts

@@ -71,6 +71,8 @@ const NO_OPENAI_CACHE_KEY_ENV = "PI_CACHE_OPTIMIZER_NO_OPENAI_CACHE_KEY";
 const OPENAI_PROMPT_CACHE_KEY_MAX_LENGTH = 64;
 const NO_SKILL_COMPRESSION_ENV = "PI_CACHE_OPTIMIZER_NO_SKILL_COMPRESSION";
 const NO_PROMPT_REWRITE_ENV = "PI_CACHE_OPTIMIZER_NO_PROMPT_REWRITE";
+const PI_ROUTING_REGISTRY_SYMBOL = Symbol.for("pi.routing.registry.v1");
+const PI_CACHE_HINTS_SYMBOL = Symbol.for("pi.cache.hints.v1");
 
 let runtimeOptimizerEnabled = true;
 
@@ -168,6 +170,80 @@ type PersistedRoutedModelRef = {
   name?: string;
 };
 
+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 PiRouteResolveHint = {
+  sessionIdHash?: string;
+  requestId?: string;
+};
+
+type PiRouterAdapterV1 = {
+  virtualProvider: string;
+  resolveActiveRoute(
+    virtualModelId: string,
+    hint?: PiRouteResolveHint,
+  ): PiRouteSnapshot | undefined;
+  resolveCandidateRoutes?(virtualModelId: string): PiRouteSnapshot[];
+  subscribe?(listener: (event: PiRouteSnapshot) => void): () => void;
+};
+
+type PiRoutingRegistryV1 = {
+  version: 1;
+  registerRouter(adapter: PiRouterAdapterV1): () => void;
+  getRouter(virtualProvider: string): PiRouterAdapterV1 | undefined;
+};
+
+type PiCacheHintsInput = {
+  sessionIdHash?: string;
+  virtualProvider?: string;
+  virtualModelId?: string;
+  upstreamProvider?: string;
+  upstreamModelId?: string;
+  api?: string;
+};
+
+type PiCacheHintsOutput = {
+  systemPrompt?: string;
+  promptCacheKey?: string;
+  cacheRetention?: "long";
+};
+
+type PiCacheHintSnapshot = PiCacheHintsInput & PiCacheHintsOutput & {
+  timestamp: number;
+};
+
+type PiCacheHintsV1 = {
+  version: 1;
+  getHints(input: PiCacheHintsInput): PiCacheHintsOutput | undefined;
+};
+
+type ProtocolGlobal = typeof globalThis & Record<symbol, unknown> & {
+  __piCacheOptimizerRouter?: unknown;
+  __piCacheOptimizerCacheKey__?: unknown;
+};
+
+type ModelRegistryLike = {
+  find?(provider: string, modelId: string): PiModel | undefined;
+  getAvailable?(): PiModel[];
+  getAll?(): PiModel[];
+};
+
+type ContextWithOptionalModelRegistry = Pick<ExtensionContext, "sessionManager"> & {
+  modelRegistry?: ModelRegistryLike;
+};
+
 type CacheStatsState = {
   statsByModel: Record<string, CacheStats>;
   legacyFamily: Partial<Record<CacheProviderId, CacheStats>>;
@@ -636,6 +712,210 @@ function hashSessionId(sessionId: string): string {
   return createHash("sha256").update(sessionId).digest("hex").slice(0, 16);
 }
 
+function getProtocolGlobal(): ProtocolGlobal {
+  return globalThis as ProtocolGlobal;
+}
+
+function firstNonEmptyString(...values: unknown[]): string | undefined {
+  for (const value of values) {
+    if (isNonEmptyString(value)) return value.trim();
+  }
+  return undefined;
+}
+
+function sessionHashFromContext(ctx: Pick<ExtensionContext, "sessionManager">): string | undefined {
+  const sessionId = ctx.sessionManager.getSessionId();
+  return sessionId ? hashSessionId(sessionId) : undefined;
+}
+
+function isPiRouterAdapterV1(value: unknown): value is PiRouterAdapterV1 {
+  const record = asRecord(value);
+  return !!record && isNonEmptyString(record.virtualProvider) && typeof record.resolveActiveRoute === "function";
+}
+
+function isRoutingRegistryV1(value: unknown): value is PiRoutingRegistryV1 {
+  const record = asRecord(value);
+  return !!record && record.version === 1 && typeof record.registerRouter === "function" && typeof record.getRouter === "function";
+}
+
+function createRoutingRegistry(): PiRoutingRegistryV1 {
+  const routers = new Map<string, PiRouterAdapterV1>();
+  return {
+    version: 1,
+    registerRouter(adapter: PiRouterAdapterV1): () => void {
+      if (!isPiRouterAdapterV1(adapter)) return () => undefined;
+      const key = adapter.virtualProvider.trim();
+      routers.set(key, adapter);
+      return () => {
+        if (routers.get(key) === adapter) routers.delete(key);
+      };
+    },
+    getRouter(virtualProvider: string): PiRouterAdapterV1 | undefined {
+      return routers.get(virtualProvider);
+    },
+  };
+}
+
+function getRoutingRegistry(): PiRoutingRegistryV1 | undefined {
+  const candidate = getProtocolGlobal()[PI_ROUTING_REGISTRY_SYMBOL];
+  return isRoutingRegistryV1(candidate) ? candidate : undefined;
+}
+
+function ensureRoutingRegistry(): PiRoutingRegistryV1 {
+  const existing = getRoutingRegistry();
+  if (existing) return existing;
+
+  const created = createRoutingRegistry();
+  getProtocolGlobal()[PI_ROUTING_REGISTRY_SYMBOL] = created;
+  return created;
+}
+
+function parseRouteStatus(value: unknown): PiRouteSnapshot["status"] | undefined {
+  return value === "planned" || value === "trying" || value === "selected" || value === "success" || value === "failed"
+    ? value
+    : undefined;
+}
+
+function parseRouteSnapshot(
+  value: unknown,
+  fallbackVirtualProvider?: string,
+  fallbackVirtualModelId?: string,
+): PiRouteSnapshot | undefined {
+  const record = asRecord(value);
+  if (!record) return undefined;
+
+  const virtualProvider = firstNonEmptyString(record.virtualProvider, fallbackVirtualProvider);
+  const virtualModelId = firstNonEmptyString(record.virtualModelId, record.virtualModel, fallbackVirtualModelId);
+  const provider = firstNonEmptyString(record.provider, record.upstreamProvider, record.targetProvider);
+  const modelId = firstNonEmptyString(record.modelId, record.upstreamModelId, record.targetModelId, record.responseModel);
+  if (!virtualProvider || !virtualModelId || !provider || !modelId) return undefined;
+
+  const timestamp = getNumber(record.timestamp) ?? Date.now();
+  return {
+    virtualProvider,
+    virtualModelId,
+    provider,
+    modelId,
+    api: firstNonEmptyString(record.api),
+    canonicalModelId: firstNonEmptyString(record.canonicalModelId),
+    routeLabel: firstNonEmptyString(record.routeLabel, record.label),
+    status: parseRouteStatus(record.status),
+    sessionIdHash: firstNonEmptyString(record.sessionIdHash),
+    requestId: firstNonEmptyString(record.requestId),
+    timestamp,
+  };
+}
+
+function resolveActiveRouteSnapshot(
+  model: PiModel | undefined,
+  ctx?: Pick<ExtensionContext, "sessionManager">,
+): PiRouteSnapshot | undefined {
+  if (!model) return undefined;
+  const hint: PiRouteResolveHint | undefined = ctx ? { sessionIdHash: sessionHashFromContext(ctx) } : undefined;
+
+  const adapter = getRoutingRegistry()?.getRouter(model.provider);
+  if (adapter) {
+    try {
+      const snapshot = parseRouteSnapshot(
+        adapter.resolveActiveRoute(model.id, hint),
+        model.provider,
+        model.id,
+      );
+      if (snapshot) return snapshot;
+    } catch (error) {
+      console.warn(`${LOG_PREFIX}: routing registry adapter failed`, error);
+    }
+  }
+
+  // Temporary migration shim for the prototype global used by early router PRs.
+  // New integrations should use Symbol.for("pi.routing.registry.v1") instead.
+  const legacy = getProtocolGlobal().__piCacheOptimizerRouter;
+  if (!legacy || !lower(model.provider).includes("router")) return undefined;
+  try {
+    if (typeof legacy === "function") {
+      return parseRouteSnapshot(legacy(model.provider, model.id, hint), model.provider, model.id);
+    }
+    const legacyRecord = asRecord(legacy);
+    const resolver = legacyRecord?.resolveActiveRoute;
+    if (typeof resolver === "function") {
+      return parseRouteSnapshot(resolver.call(legacy, model.id, hint), model.provider, model.id);
+    }
+    return parseRouteSnapshot(legacy, model.provider, model.id);
+  } catch (error) {
+    console.warn(`${LOG_PREFIX}: legacy routing global failed`, error);
+    return undefined;
+  }
+}
+
+function routeSnapshotToPiModel(snapshot: PiRouteSnapshot, fallback?: PiModel): PiModel {
+  return {
+    ...(fallback ?? {}),
+    id: snapshot.modelId,
+    name: snapshot.canonicalModelId ?? snapshot.modelId,
+    provider: snapshot.provider,
+    api: snapshot.api ?? fallback?.api ?? "",
+    baseUrl: fallback?.baseUrl ?? "",
+    reasoning: fallback?.reasoning ?? false,
+    input: fallback?.input ?? ["text"],
+    cost: fallback?.cost ?? { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: fallback?.contextWindow ?? 0,
+    maxTokens: fallback?.maxTokens ?? 0,
+    compat: fallback?.compat,
+  } as PiModel;
+}
+
+function findModelInRegistry(registry: ModelRegistryLike | undefined, provider: string, id: string): PiModel | undefined {
+  const found = registry?.find?.(provider, id);
+  if (found) return found;
+
+  const available = registry?.getAvailable?.() ?? [];
+  const availableMatch = available.find((candidate) => candidate.provider === provider && candidate.id === id);
+  if (availableMatch) return availableMatch;
+
+  const all = registry?.getAll?.() ?? [];
+  return all.find((candidate) => candidate.provider === provider && candidate.id === id);
+}
+
+function resolveRouteModel(
+  model: PiModel | undefined,
+  ctx?: ContextWithOptionalModelRegistry,
+): PiModel | undefined {
+  const snapshot = resolveActiveRouteSnapshot(model, ctx);
+  if (!snapshot) return undefined;
+
+  return findModelInRegistry(ctx?.modelRegistry, snapshot.provider, snapshot.modelId)
+    ?? routeSnapshotToPiModel(snapshot, model);
+}
+
+function isVirtualRoutingModel(model: PiModel | undefined, ctx?: Pick<ExtensionContext, "sessionManager">): boolean {
+  if (!model) return false;
+  return isRouterModel(model) || !!getRoutingRegistry()?.getRouter(model.provider) || !!resolveActiveRouteSnapshot(model, ctx);
+}
+
+function isCacheHintsServiceV1(value: unknown): value is PiCacheHintsV1 {
+  const record = asRecord(value);
+  return !!record && record.version === 1 && typeof record.getHints === "function";
+}
+
+function getCacheHintsService(): PiCacheHintsV1 | undefined {
+  const candidate = getProtocolGlobal()[PI_CACHE_HINTS_SYMBOL];
+  return isCacheHintsServiceV1(candidate) ? candidate : undefined;
+}
+
+function installCacheHintsService(service: PiCacheHintsV1): () => void {
+  const globals = getProtocolGlobal();
+  const previous = globals[PI_CACHE_HINTS_SYMBOL];
+  globals[PI_CACHE_HINTS_SYMBOL] = service;
+  return () => {
+    if (globals[PI_CACHE_HINTS_SYMBOL] !== service) return;
+    if (previous === undefined) {
+      delete globals[PI_CACHE_HINTS_SYMBOL];
+    } else {
+      globals[PI_CACHE_HINTS_SYMBOL] = previous;
+    }
+  };
+}
+
 /**
  * Build a session-scoped stats key from a session hash + provider/id.
  * Pure function (no closure dependency) for use by tests and internals.
@@ -1403,10 +1683,10 @@ function modelFromAssistantMessage(message: unknown, fallback: PiModel | undefin
   const record = getAssistantRecord(message);
   if (!record) return fallback;
 
-  const id = lower(record.responseModel) || lower(record.model) || fallback?.id;
-  const provider = lower(record.provider) || fallback?.provider;
-  const api = lower(record.api) || fallback?.api;
-  if (!id || !provider || !api) return fallback;
+  const id = firstNonEmptyString(record.responseModel, record.model, fallback?.id);
+  const provider = firstNonEmptyString(record.provider, fallback?.provider);
+  const api = firstNonEmptyString(record.api, fallback?.api) ?? "";
+  if (!id || !provider) return fallback;
 
   return {
     ...(fallback ?? {}),
@@ -2886,7 +3166,10 @@ function selectAdapterForModel(model: PiModel | undefined): CacheProviderAdapter
 }
 
 function selectAdapterForAssistantMessage(message: unknown, model: PiModel | undefined): CacheProviderAdapter | undefined {
-  const responseModel = isRouterModel(model) ? modelFromAssistantMessage(message, model) : model;
+  // Assistant message metadata is request-local and authoritative for virtual
+  // routing providers. Use it first for every model; direct providers normally
+  // echo the same provider/model and therefore remain unchanged.
+  const responseModel = modelFromAssistantMessage(message, model);
   return CACHE_PROVIDER_ADAPTERS.find((adapter) => adapter.matchesAssistantMessage(message, responseModel));
 }
 
@@ -3161,7 +3444,7 @@ function buildExactRouterStatusEntry(
   sessionHash: string | undefined,
   statsByModel: Record<string, CacheStats>,
   lastRoutedModel: PersistedRoutedModelRef | undefined,
-): { adapter: CacheProviderAdapter; stats: CacheStats } | undefined {
+): { model: PiModel; adapter: CacheProviderAdapter; stats: CacheStats } | undefined {
   if (!sessionHash || !lastRoutedModel) return undefined;
 
   const model = routedModelRefToPiModel(lastRoutedModel);
@@ -3169,7 +3452,7 @@ function buildExactRouterStatusEntry(
   if (!adapter) return undefined;
 
   const key = makeSessionModelKey(sessionHash, lastRoutedModel.provider, lastRoutedModel.id);
-  return { adapter, stats: statsByModel[key] ?? emptyCacheStats() };
+  return { model, adapter, stats: statsByModel[key] ?? emptyCacheStats() };
 }
 
 function parsePersistedCacheStats(value: unknown): CacheStatsState | undefined {
@@ -5062,6 +5345,18 @@ export const __internals_for_tests = {
   parsePersistedRoutedModelRef,
   routedModelRefToPiModel,
   buildExactRouterStatusEntry,
+  // Routing-provider protocol helpers
+  PI_ROUTING_REGISTRY_SYMBOL,
+  PI_CACHE_HINTS_SYMBOL,
+  ensureRoutingRegistry,
+  getRoutingRegistry,
+  parseRouteSnapshot,
+  resolveActiveRouteSnapshot,
+  routeSnapshotToPiModel,
+  resolveRouteModel,
+  isVirtualRoutingModel,
+  installCacheHintsService,
+  getCacheHintsService,
   // Persistence helpers (for reload/reset tests)
   mergeCacheSessions,
   mergeLastRoutedModels,
@@ -5109,6 +5404,7 @@ export default function (pi: ExtensionAPI) {
   let currentSessionHash = "";
   let currentSessionHashSet = false;
   let lastActualRoutedModel: PersistedRoutedModelRef | undefined;
+  let latestCacheHint: PiCacheHintSnapshot | undefined;
   const PERSIST_DEBOUNCE_MS = 2000;
   /** In-memory recent usage samples per model key (not persisted, cleared on reload). */
   const recentSamplesByModelKey = new Map<string, CacheUsageSample[]>();
@@ -5123,6 +5419,28 @@ export default function (pi: ExtensionAPI) {
     }
   }
 
+  const uninstallCacheHintsService = installCacheHintsService({
+    version: 1,
+    getHints(input: PiCacheHintsInput): PiCacheHintsOutput | undefined {
+      if (!runtimeOptimizerEnabled || isEnabledEnv(process.env[NO_PROMPT_REWRITE_ENV])) return undefined;
+      const hint = latestCacheHint;
+      if (!hint) return undefined;
+      if (input.sessionIdHash && hint.sessionIdHash && input.sessionIdHash !== hint.sessionIdHash) return undefined;
+      if (input.virtualProvider && hint.virtualProvider && input.virtualProvider !== hint.virtualProvider) return undefined;
+      if (input.virtualModelId && hint.virtualModelId && input.virtualModelId !== hint.virtualModelId) return undefined;
+      if (input.upstreamProvider && hint.upstreamProvider && input.upstreamProvider !== hint.upstreamProvider) return undefined;
+      if (input.upstreamModelId && hint.upstreamModelId && input.upstreamModelId !== hint.upstreamModelId) return undefined;
+      if (input.api && hint.api && input.api !== hint.api) return undefined;
+
+      return {
+        systemPrompt: hint.systemPrompt,
+        promptCacheKey: hint.promptCacheKey,
+        cacheRetention: hint.cacheRetention,
+      };
+    },
+  });
+  void uninstallCacheHintsService;
+
   /**
    * Build a session-scoped stats key from the current session hash + model key.
    * Returns `${sessionHash}:${provider}/${id}`.
@@ -5206,6 +5524,13 @@ export default function (pi: ExtensionAPI) {
     return created;
   }
 
+  function resetStatsForModel(model: PiModel): void {
+    const sk = sessionModelKey(model);
+    delete cacheStatsByModel[sk];
+    recentSamplesByModelKey.delete(sk);
+    lastStatusText = undefined;
+  }
+
   function resetCurrentSessionStats(): void {
     const prefix = `${currentSessionHash || "_nosession"}:`;
     for (const key of Object.keys(cacheStatsByModel)) {
@@ -5214,6 +5539,7 @@ export default function (pi: ExtensionAPI) {
     for (const key of Array.from(recentSamplesByModelKey.keys())) {
       if (key.startsWith(prefix)) recentSamplesByModelKey.delete(key);
     }
+    lastActualRoutedModel = undefined;
     lastStatusText = undefined;
   }
 
@@ -5380,9 +5706,13 @@ export default function (pi: ExtensionAPI) {
     syncSessionHash(ctx);
     await rollOverStatsIfNeeded(ctx);
 
-    const adapter = selectAdapterForModel(model);
+    const routedModel = resolveRouteModel(model, ctx);
+    const displayModel = routedModel ?? model;
+    const adapter = selectAdapterForModel(displayModel);
+    const activeIsVirtualRoute = !!routedModel || isVirtualRoutingModel(model, ctx);
     let statusText: string | undefined;
-    if (!adapter && isRouterModel(model)) {
+
+    if (!adapter && !routedModel && activeIsVirtualRoute) {
       // On model_select (existing footer), keep the existing cache footer
       // visible instead of clearing it. On session_start (no footer yet
       // after reload/fresh start), restore the exact last actual routed model
@@ -5405,8 +5735,8 @@ export default function (pi: ExtensionAPI) {
     if (adapter) {
       // Display session-scoped stats. A model that has never been used
       // in this session shows 0/0. The message_end hook populates
-      // cacheStatsByModel[sessionModelKey(model)] on first use.
-      const sk = model ? sessionModelKey(model) : undefined;
+      // cacheStatsByModel[sessionModelKey(displayModel)] on first use.
+      const sk = displayModel ? sessionModelKey(displayModel) : undefined;
       const stats = sk ? cacheStatsByModel[sk] : undefined;
       const statsText = formatCacheStats(adapter, stats ?? emptyCacheStats());
       statusText = runtimeOptimizerEnabled ? statsText : `Cache Optimizer disabled · ${statsText}`;
@@ -5443,12 +5773,12 @@ export default function (pi: ExtensionAPI) {
     // Re-evaluated on every status update so the marker persists through stats
     // changes and day rollovers. Redundant setStatus calls are blocked by the
     // `lastStatusText` early return above.
-    if (runtimeOptimizerEnabled && statusText !== undefined && model) {
+    if (runtimeOptimizerEnabled && statusText !== undefined && displayModel) {
       // Only show ⚠️ compat when there are safe-fixable missing compat keys.
       // Optional/advisory-only flags (e.g. supportsLongCacheRetention on generic
       // OpenAI-compatible proxies) do NOT trigger the marker — the doctor/compat
       // commands still mention them as optional guidance.
-      if (buildFixSuggestion(model) !== undefined) {
+      if (buildFixSuggestion(displayModel) !== undefined) {
         statusText = statusText + " ⚠️ compat";
       }
     }
@@ -5459,18 +5789,26 @@ export default function (pi: ExtensionAPI) {
     ctx.ui.setStatus(STATUS_KEY, statusText);
   }
 
+  ensureRoutingRegistry();
+
   pi.on("session_start", async (event, ctx) => {
     await restoreCacheStats(event.reason, ctx);
-    if (runtimeOptimizerEnabled) notifyCacheCompatIfNeeded(ctx.model, ctx, warnedModels);
+    if (runtimeOptimizerEnabled) notifyCacheCompatIfNeeded(resolveRouteModel(ctx.model, ctx) ?? ctx.model, ctx, warnedModels);
     await publishStatus(ctx);
   });
 
   pi.on("model_select", async (event, ctx) => {
-    if (runtimeOptimizerEnabled) notifyCacheCompatIfNeeded(event.model, ctx, warnedModels);
+    if (runtimeOptimizerEnabled) notifyCacheCompatIfNeeded(resolveRouteModel(event.model, ctx) ?? event.model, ctx, warnedModels);
     await publishStatus(ctx, event.model);
   });
 
   pi.on("before_agent_start", async (event, _ctx) => {
+    latestCacheHint = undefined;
+    const routeSnapshot = resolveActiveRouteSnapshot(_ctx.model, _ctx);
+    const routedModel = routeSnapshot
+      ? findModelInRegistry(_ctx.modelRegistry, routeSnapshot.provider, routeSnapshot.modelId) ?? routeSnapshotToPiModel(routeSnapshot, _ctx.model)
+      : undefined;
+
     // ────────────────────────────────────────────────────────────────
     // OpenAI Responses-family bypass (codex-responses + responses + azure responses)
     //
@@ -5497,7 +5835,7 @@ export default function (pi: ExtensionAPI) {
     // compression, reorder) for these APIs. Third-party providers
     // that use openai-completions are unaffected.
     // ────────────────────────────────────────────────────────────────
-    const model = _ctx.model;
+    const model = routedModel ?? _ctx.model;
     if (model && isResponsesPromptRewriteBypassApi(model.api)) {
       return {};
     }
@@ -5535,7 +5873,27 @@ export default function (pi: ExtensionAPI) {
     // ships to the provider.
     const optimized = optimizeSystemPrompt(compressedPrompt, event.systemPromptOptions);
 
+    const promptCacheKey = getSessionPromptCacheKey(_ctx);
+    const cacheRetention = process.env[PI_CACHE_RETENTION_ENV] === LONG_CACHE_RETENTION_VALUE ? LONG_CACHE_RETENTION_VALUE : undefined;
+    const publishHint = (systemPrompt: string): void => {
+      latestCacheHint = {
+        sessionIdHash: currentSessionHashSet ? currentSessionHash : sessionHashFromContext(_ctx),
+        virtualProvider: routeSnapshot?.virtualProvider ?? _ctx.model?.provider,
+        virtualModelId: routeSnapshot?.virtualModelId ?? _ctx.model?.id,
+        upstreamProvider: routeSnapshot?.provider ?? model?.provider,
+        upstreamModelId: routeSnapshot?.modelId ?? model?.id,
+        api: model?.api,
+        systemPrompt,
+        promptCacheKey,
+        cacheRetention,
+        timestamp: Date.now(),
+      };
+      const globals = getProtocolGlobal();
+      globals.__piCacheOptimizerCacheKey__ = promptCacheKey;
+    };
+
     if (optimized.changed && optimized.systemPrompt.trim().length > 0) {
+      publishHint(optimized.systemPrompt);
       return { systemPrompt: optimized.systemPrompt };
     }
 
@@ -5544,24 +5902,28 @@ export default function (pi: ExtensionAPI) {
     // the volume cut even when reorder is a no-op (e.g., short sessions
     // where no stable candidate is long enough).
     if (compressedPrompt !== strippedPrompt && compressedPrompt.trim().length > 0) {
+      publishHint(compressedPrompt);
       return { systemPrompt: compressedPrompt };
     }
     if (strippedPrompt !== event.systemPrompt && strippedPrompt.trim().length > 0) {
+      publishHint(strippedPrompt);
       return { systemPrompt: strippedPrompt };
     }
 
+    publishHint(event.systemPrompt);
     return {};
   });
 
   pi.on("before_provider_request", (event, ctx) => {
     if (!shouldInjectOpenAIPromptCacheKey()) return undefined;
-    if (!isOpenAICompatibleApi(ctx.model?.api)) return undefined;
+    const requestModel = resolveRouteModel(ctx.model, ctx) ?? ctx.model;
+    if (!isOpenAICompatibleApi(requestModel?.api)) return undefined;
 
     return addOpenAIPromptCacheKey(event.payload, getSessionPromptCacheKey(ctx));
   });
 
   pi.on("after_provider_response", (event, ctx) => {
-    const model = ctx.model;
+    const model = resolveRouteModel(ctx.model, ctx) ?? ctx.model;
     if (!runtimeOptimizerEnabled || !model) return;
     if (event.status !== 400) return;
     if (!isPromptCacheRetention400Applicable(model)) return;
@@ -5586,9 +5948,12 @@ export default function (pi: ExtensionAPI) {
 
     const usage = adapter.normalizeUsage(event.message);
 
-    const statsModel = isRouterModel(ctx.model) ? modelFromAssistantMessage(event.message, ctx.model) : ctx.model;
+    // Completed message metadata is request-local and authoritative for virtual
+    // routing providers. Use it whenever it supplies provider/model identity;
+    // fall back to the active context model for direct providers.
+    const statsModel = modelFromAssistantMessage(event.message, ctx.model) ?? ctx.model;
     let routedModelChanged = false;
-    if (isRouterModel(ctx.model) && statsModel && !isRouterModel(statsModel)) {
+    if (isVirtualRoutingModel(ctx.model, ctx) && statsModel && !isVirtualRoutingModel(statsModel, ctx)) {
       const nextRoutedModel: PersistedRoutedModelRef = {
         provider: statsModel.provider,
         id: statsModel.id,
@@ -5651,7 +6016,8 @@ export default function (pi: ExtensionAPI) {
     description: "Diagnose Pi cache configuration",
     handler: async (args: string, cmdCtx) => {
       syncSessionHash(cmdCtx);
-      const model = cmdCtx.model;
+      const selectedModel = cmdCtx.model;
+      const model = resolveRouteModel(selectedModel, cmdCtx as unknown as ExtensionContext) ?? selectedModel;
       const subcommand = args.trim().toLowerCase().split(/\s+/)[0] || "help";
 
       if (subcommand === "enable") {
@@ -5719,14 +6085,12 @@ export default function (pi: ExtensionAPI) {
           return;
         }
 
-        const sk = sessionModelKey(model);
         const displayKey = modelKey(model);
 
-        // Reset session-scoped stats for the active model.
-        delete cacheStatsByModel[sk];
-
-        // Clear recent samples for this session+model key.
-        recentSamplesByModelKey.delete(sk);
+        // Reset session-scoped stats for the effective active model. If the
+        // selected model is a virtual router and the protocol exposes a live
+        // route, this clears the real upstream bucket, not the router shell.
+        resetStatsForModel(model);
 
         // Persist immediately.
         await flushPersistCacheStats(cmdCtx as unknown as ExtensionContext);
@@ -6069,10 +6433,8 @@ export default function (pi: ExtensionAPI) {
               if (!adapter) {
                 cmdCtx.ui.notify("ℹ️ Active model does not match a cache adapter. No stats to reset.", "info");
               } else {
-                const sk = sessionModelKey(model);
                 const displayKey = modelKey(model);
-                delete cacheStatsByModel[sk];
-                recentSamplesByModelKey.delete(sk);
+                resetStatsForModel(model);
                 await flushPersistCacheStats(cmdCtx as unknown as ExtensionContext);
                 await publishStatus(cmdCtx as unknown as ExtensionContext, model);
                 cmdCtx.ui.notify(

package/package.json

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