pi-cache-optimizer 2.8.13 → 2.8.15

package/README.md

@@ -92,10 +92,25 @@ The interactive `/cache-optimizer` menu includes `Footer mode`, where you can ch
 | Env var | Effect |
 |---|---|
 | `PI_CACHE_OPTIMIZER_NO_PROMPT_REWRITE=1` | Disable prompt mutations only; footer stats and cache-key fallback remain active. |
+| `PI_CACHE_OPTIMIZER_VIRTUAL_REWRITE=1` | Explicitly allow native virtual prompt rewriting only when the routing registry exposes a non-Responses, non-Codex candidate chain. Unknown or incomplete routes remain unchanged. |
 | `PI_CACHE_OPTIMIZER_NO_SKILL_COMPRESSION=1` | Keep Pi's verbose skill XML. |
 | `PI_CACHE_OPTIMIZER_NO_OPENAI_CACHE_KEY=1` | Disable the OpenAI-compatible `prompt_cache_key` fallback. Preferred explicit opt-out. |
 | `PI_CACHE_OPTIMIZER_OPENAI_CACHE_KEY=0` | Disable the same fallback via the legacy inverse switch. Values `0`, `false`, `no`, or `off` disable it. |
 
+Persistent feature settings are managed under the Pi agent directory by the native command interface. They take precedence over their corresponding environment variables:
+
+```text
+/cache-optimizer config prompt-rewrite on|off
+/cache-optimizer config virtual-rewrite on|off
+/cache-optimizer config skill-compression on|off
+/cache-optimizer config openai-cache-key on|off
+/cache-optimizer config tool-order on|off
+/cache-optimizer config footer-mode total|session|process
+/cache-optimizer config reset
+```
+
+`config reset` removes persistent feature overrides while preserving the existing footer mode and model-specific prompt-cache-key settings. These commands do not modify shell startup files or `PI_CACHE_RETENTION`; `enable` and `disable` remain current-process runtime switches.
+
 ## Opt-in deterministic tool ordering
 
 `PI_CACHE_OPTIMIZER_TOOL_ORDER=1` enables deterministic ordering for verified tool definitions in Pi's built-in OpenAI Completions, Anthropic, Google, and Bedrock payload shapes. Truthy values are `1`, `true`, `yes`, or `on` (case-insensitive). The feature is off by default, process-local, and suppressed by `/cache-optimizer disable`.
@@ -367,12 +382,14 @@ Pi 0.99 lets extensions register virtual models with `pi.registerVirtualModel()`
 - 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.
+- Prompt rewriting is skipped for virtual selections by default: Pi picks the physical model after the system prompt is built, and a reordered prompt must not reach a safety-filtered Codex route. `PI_CACHE_OPTIMIZER_VIRTUAL_REWRITE=1` is an explicit opt-in only when the routing registry exposes a complete candidate chain and every candidate is a known non-Responses, non-Codex transport; unknown or incomplete routes remain unchanged.
 - 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.
+If your Pi extension provides a virtual routing provider (for example [`pi-router`](https://github.com/jiangge/pi-router)'s `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.
+
+For [`pi-router`](https://github.com/jiangge/pi-router), use a current release that implements `pi.routing.registry.v1`. Direct `router/*` selections continue to use the normal prompt optimizer. When a native Pi 0.99+ virtual model is routed through a registry-aware router, the optional `PI_CACHE_OPTIMIZER_VIRTUAL_REWRITE=1` path inspects the router's candidate chain before rewriting; candidates using OpenAI Responses/Codex APIs, incomplete metadata, and unavailable route information fail closed.
 
 ### Minimum integration: final assistant message metadata
 

package/README.zh-CN.md

@@ -92,10 +92,25 @@ Pi 0.79.7 及之后，`pi update` 默认只更新 Pi 本体。若要更新已安
 | 环境变量 | 作用 |
 |---|---|
 | `PI_CACHE_OPTIMIZER_NO_PROMPT_REWRITE=1` | 只关闭 prompt 改写；footer 统计和 cache-key fallback 仍启用。 |
+| `PI_CACHE_OPTIMIZER_VIRTUAL_REWRITE=1` | 显式允许原生 virtual prompt 改写，但仅当 routing registry 暴露的候选链不包含 Responses/Codex 时生效。路由未知或信息不完整时仍保持原 prompt。 |
 | `PI_CACHE_OPTIMIZER_NO_SKILL_COMPRESSION=1` | 保留 Pi 原始 verbose skill XML。 |
 | `PI_CACHE_OPTIMIZER_NO_OPENAI_CACHE_KEY=1` | 关闭 OpenAI-compatible `prompt_cache_key` fallback。推荐使用这个显式 opt-out。 |
 | `PI_CACHE_OPTIMIZER_OPENAI_CACHE_KEY=0` | 通过旧的反向开关关闭同一个 fallback。取值 `0`、`false`、`no`、`off` 时关闭。 |
 
+持久化 feature 配置由 Pi agent 目录中的原生命令管理，并且优先于对应环境变量：
+
+```text
+/cache-optimizer config prompt-rewrite on|off
+/cache-optimizer config virtual-rewrite on|off
+/cache-optimizer config skill-compression on|off
+/cache-optimizer config openai-cache-key on|off
+/cache-optimizer config tool-order on|off
+/cache-optimizer config footer-mode total|session|process
+/cache-optimizer config reset
+```
+
+`config reset` 会移除持久化 feature 覆盖，同时保留现有 footer mode 和按模型配置的 prompt-cache-key 设置。这些命令不会修改 shell 启动文件或 `PI_CACHE_RETENTION`；`enable` 和 `disable` 仍然是当前进程的运行时开关。
+
 ## Opt-in 确定性工具排序
 
 `PI_CACHE_OPTIMIZER_TOOL_ORDER=1` 会对 Pi 内置 OpenAI Completions、Anthropic、Google 与 Bedrock payload 中已验证的工具定义进行确定性排序。Truthy 取值为（不区分大小写）`1`、`true`、`yes` 或 `on`。该能力默认关闭、仅在当前进程生效，并会被 `/cache-optimizer disable` 抑制。
@@ -366,12 +381,14 @@ Pi 0.99 允许扩展通过 `pi.registerVirtualModel()` 注册虚拟模型。选
 - 请求 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 路由。
+- 虚拟选择默认不做 prompt 改写：Pi 在构建 system prompt 之后才决定物理模型，重排后的 prompt 不应被送到有安全过滤的 Codex 路由。只有设置 `PI_CACHE_OPTIMIZER_VIRTUAL_REWRITE=1` 且 routing registry 暴露完整候选链、所有候选都是已知的非 Responses / 非 Codex transport 时，才允许改写；路由未知或信息不完整时仍保持原 prompt。
 - Session-affinity header 桥接同样跳过，因为 Pi 在 payload 生成之前就构造请求 header。Pi 仍会发送物理模型自身配置的 affinity header。
 
 ## Router / Virtual-channel 扩展作者指南
 
-如果你的 Pi 扩展提供虚拟 routing provider（例如 `router/auto`、`router/smart`，或会转发到真实上游的 profile/channel），本扩展可以为真实上游 provider/model 显示缓存统计，而不是把统计记到虚拟外壳上。集成是可选、版本化的，并且**不需要导入本包**。
+如果你的 Pi 扩展提供虚拟 routing provider（例如 [`pi-router`](https://github.com/jiangge/pi-router) 的 `router/auto`、`router/smart`，或会转发到真实上游的 profile/channel），本扩展可以为真实上游 provider/model 显示缓存统计，而不是把统计记到虚拟外壳上。集成是可选、版本化的，并且**不需要导入本包**。
+
+对于 [`pi-router`](https://github.com/jiangge/pi-router)，请使用实现 `pi.routing.registry.v1` 的较新版本。直接选择 `router/*` 模型时仍使用普通 prompt optimizer；当 Pi 0.99+ 原生 virtual model 通过支持该 registry 的 router 路由时，可选的 `PI_CACHE_OPTIMIZER_VIRTUAL_REWRITE=1` 会先检查 router candidate chain 再决定是否改写。候选包含 OpenAI Responses/Codex API、元数据不完整或路由信息不可用时，会 fail closed。
 
 ### 最小集成：最终 assistant message metadata
 

package/index.ts

@@ -131,6 +131,7 @@ 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 VIRTUAL_REWRITE_ENV = "PI_CACHE_OPTIMIZER_VIRTUAL_REWRITE";
 const TOOL_ORDER_ENV = "PI_CACHE_OPTIMIZER_TOOL_ORDER";
 const FOOTER_MODE_ENV = "PI_CACHE_OPTIMIZER_FOOTER_MODE";
 type FooterStatsMode = "session" | "total" | "process";
@@ -179,6 +180,7 @@ type PersistedCacheOptimizerConfigV1 = {
   version: 1;
   footerMode?: FooterStatsMode;
 };
+type PersistedCacheOptimizerFeature = "promptRewrite" | "virtualRewrite" | "skillCompression" | "openAICacheKey" | "toolOrder";
 type PersistedCacheOptimizerConfigV2 = {
   version: 2;
   footerMode?: FooterStatsMode;
@@ -186,7 +188,13 @@ type PersistedCacheOptimizerConfigV2 = {
     omit?: string[];
   };
 };
-type PersistedCacheOptimizerConfig = PersistedCacheOptimizerConfigV1 | PersistedCacheOptimizerConfigV2;
+type PersistedCacheOptimizerConfigV3 = {
+  version: 2 | 3;
+  footerMode?: FooterStatsMode;
+  promptCacheKey?: { omit?: string[] };
+  features?: Partial<Record<PersistedCacheOptimizerFeature, boolean>>;
+};
+type PersistedCacheOptimizerConfig = PersistedCacheOptimizerConfigV1 | PersistedCacheOptimizerConfigV2 | PersistedCacheOptimizerConfigV3;
 type PromptCacheKeyConfigReceipt = {
   version: 2;
   kind: "pi-cache-optimizer-config-receipt";
@@ -922,7 +930,7 @@ function compressSkillsInSystemPrompt(
   prompt: string,
   opts: BuildSystemPromptOptions,
 ): string {
-  if (isEnabledEnv(process.env[NO_SKILL_COMPRESSION_ENV])) return prompt;
+  if (!featureEnabled("skillCompression", NO_SKILL_COMPRESSION_ENV, true)) return prompt;
   if (!opts.skills || opts.skills.length === 0) return prompt;
 
   const visible = opts.skills.filter((skill) => !skill.disableModelInvocation);
@@ -1334,6 +1342,43 @@ function resolveActiveRouteSnapshot(
   }
 }
 
+function resolveNativeVirtualCandidateModels(
+  model: PiModel | undefined,
+  ctx?: ContextWithOptionalModelRegistry,
+): PiModel[] | undefined {
+  if (!isNativeVirtualModel(model)) return undefined;
+  const adapter = model ? getRoutingRegistry()?.getRouter(model.provider) : undefined;
+  if (!adapter?.resolveCandidateRoutes) return undefined;
+
+  try {
+    const rawSnapshots = adapter.resolveCandidateRoutes(model.id);
+    if (!Array.isArray(rawSnapshots) || rawSnapshots.length === 0) return undefined;
+    const candidates: PiModel[] = [];
+    for (const rawSnapshot of rawSnapshots) {
+      const snapshot = parseRouteSnapshot(rawSnapshot, model.provider, model.id);
+      if (!snapshot) return undefined;
+      const candidate = findModelInRegistry(ctx?.modelRegistry, snapshot.provider, snapshot.modelId)
+        ?? routeSnapshotToPiModel(snapshot, model);
+      if (!isNonEmptyString(candidate.api)) return undefined;
+      candidates.push(candidate);
+    }
+    return candidates;
+  } catch {
+    return undefined;
+  }
+}
+
+function canRewriteNativeVirtualPrompt(
+  model: PiModel | undefined,
+  ctx?: ContextWithOptionalModelRegistry,
+): boolean {
+  if (!isNativeVirtualModel(model) || !featureEnabled("virtualRewrite", VIRTUAL_REWRITE_ENV, false)) return false;
+  const candidates = resolveNativeVirtualCandidateModels(model, ctx);
+  return !!candidates?.length && candidates.every((candidate) =>
+    candidate.api === "openai-completions" || candidate.api === "anthropic-messages",
+  ) && candidates.every((candidate) => !isResponsesPromptRewriteBypassApi(candidate.api));
+}
+
 function routeSnapshotToPiModel(snapshot: PiRouteSnapshot, fallback?: PiModel): PiModel {
   const sameIdentity = fallback?.provider === snapshot.provider && fallback?.id === snapshot.modelId;
   return {
@@ -2044,8 +2089,18 @@ function isEnabledEnv(value: string | undefined): boolean {
   return normalized === "1" || normalized === "true" || normalized === "yes" || normalized === "on";
 }
 
+function featureEnabled(feature: PersistedCacheOptimizerFeature, envName: string, defaultValue: boolean): boolean {
+  const configured = (persistedCacheOptimizerConfig as PersistedCacheOptimizerConfigV3).features?.[feature];
+  if (configured !== undefined) return configured;
+  if (feature === "virtualRewrite") return isEnabledEnv(process.env[envName]);
+  if (feature === "promptRewrite" || feature === "skillCompression" || feature === "openAICacheKey") {
+    return !isEnabledEnv(process.env[envName]);
+  }
+  return isEnabledEnv(process.env[envName]) || defaultValue;
+}
+
 function isToolOrderEnabled(env: MutableEnv = process.env): boolean {
-  return runtimeOptimizerEnabled && isEnabledEnv(env[TOOL_ORDER_ENV]);
+  return runtimeOptimizerEnabled && featureEnabled("toolOrder", TOOL_ORDER_ENV, false);
 }
 
 function parseFooterStatsMode(value: unknown): FooterStatsMode | undefined {
@@ -2071,8 +2126,17 @@ const CACHE_OPTIMIZER_COMMANDS = [
   "fix",
   "rollback",
 ] as const;
-const CACHE_OPTIMIZER_CONFIG_ARGUMENTS = ["footer-mode"] as const;
+const CACHE_OPTIMIZER_CONFIG_ARGUMENTS = ["footer-mode", "prompt-rewrite", "virtual-rewrite", "skill-compression", "openai-cache-key", "tool-order", "reset"] as const;
+const CACHE_OPTIMIZER_FEATURE_COMMANDS = ["prompt-rewrite", "virtual-rewrite", "skill-compression", "openai-cache-key", "tool-order"] as const;
+const CACHE_OPTIMIZER_FEATURE_VALUES = ["on", "off"] as const;
 const CACHE_OPTIMIZER_FOOTER_MODES = ["total", "session", "process"] as const;
+const FEATURE_COMMAND_MAP: Record<string, PersistedCacheOptimizerFeature> = {
+  "prompt-rewrite": "promptRewrite",
+  "virtual-rewrite": "virtualRewrite",
+  "skill-compression": "skillCompression",
+  "openai-cache-key": "openAICacheKey",
+  "tool-order": "toolOrder",
+};
 const CACHE_OPTIMIZER_STATS_ARGUMENTS = ["all", "contributors"] as const;
 const CACHE_OPTIMIZER_FIX_ARGUMENTS = ["prompt-cache-key"] as const;
 
@@ -2144,19 +2208,28 @@ function getCacheOptimizerArgumentCompletions(argumentPrefix: string): CommandCo
   if (parts.length === 3 && parts[1].toLowerCase() === "footer-mode") {
     return filterCommandCompletionItems(CACHE_OPTIMIZER_FOOTER_MODES, parts[2], "config footer-mode");
   }
+  if (parts.length === 3 && CACHE_OPTIMIZER_FEATURE_COMMANDS.includes(parts[1] as typeof CACHE_OPTIMIZER_FEATURE_COMMANDS[number])) {
+    return filterCommandCompletionItems(CACHE_OPTIMIZER_FEATURE_VALUES, parts[2], `config ${parts[1]}`);
+  }
 
   return null;
 }
 
 function parsePersistedCacheOptimizerConfig(value: unknown): PersistedCacheOptimizerConfig | undefined {
   const record = asRecord(value);
-  if (!record || (record.version !== 1 && record.version !== 2)) return undefined;
-  const allowedTopLevel = new Set(record.version === 1 ? ["version", "footerMode"] : ["version", "footerMode", "promptCacheKey"]);
+  if (!record || (record.version !== 1 && record.version !== 2 && record.version !== 3)) return undefined;
+  const allowedTopLevel = new Set(record.version === 1 ? ["version", "footerMode"] : record.version === 2 ? ["version", "footerMode", "promptCacheKey"] : ["version", "footerMode", "promptCacheKey", "features"]);
   if (Object.keys(record).some((key) => !allowedTopLevel.has(key))) return undefined;
   const footerMode = parseFooterStatsMode(record.footerMode);
   if (record.footerMode !== undefined && !footerMode) return undefined;
   if (record.version === 1) return { version: 1, ...(footerMode ? { footerMode } : {}) };
 
+  const rawFeatures = record.version === 3 ? record.features : undefined;
+  if (rawFeatures !== undefined && !asRecord(rawFeatures)) return undefined;
+  const featuresRecord = asRecord(rawFeatures);
+  const featureNames = new Set<PersistedCacheOptimizerFeature>(["promptRewrite", "virtualRewrite", "skillCompression", "openAICacheKey", "toolOrder"]);
+  if (featuresRecord && Object.keys(featuresRecord).some((key) => !featureNames.has(key as PersistedCacheOptimizerFeature) || typeof featuresRecord[key] !== "boolean")) return undefined;
+
   const rawPromptCacheKey = record.promptCacheKey;
   if (rawPromptCacheKey !== undefined && !asRecord(rawPromptCacheKey)) return undefined;
   const promptCacheKey = asRecord(rawPromptCacheKey);
@@ -2166,20 +2239,25 @@ function parsePersistedCacheOptimizerConfig(value: unknown): PersistedCacheOptim
   const stringOmit = omit as string[] | undefined;
   const uniqueOmit = stringOmit ? [...new Set(stringOmit.map((value) => value.trim()))].sort() : undefined;
   return {
-    version: 2,
+    version: record.version === 3 ? 3 : 2,
     ...(footerMode ? { footerMode } : {}),
     ...(uniqueOmit && uniqueOmit.length > 0 ? { promptCacheKey: { omit: uniqueOmit } } : {}),
-  };
+    ...(featuresRecord ? { features: Object.fromEntries(Object.entries(featuresRecord)) as Partial<Record<PersistedCacheOptimizerFeature, boolean>> } : {}),
+  } as PersistedCacheOptimizerConfigV3;
 }
 
-function normalizePersistedCacheOptimizerConfig(value: PersistedCacheOptimizerConfig | undefined): PersistedCacheOptimizerConfigV2 {
+function normalizePersistedCacheOptimizerConfig(value: PersistedCacheOptimizerConfig | undefined): PersistedCacheOptimizerConfigV3 {
   if (!value) return { version: 2 };
-  return value.version === 2
-    ? value
-    : { version: 2, ...(value.footerMode ? { footerMode: value.footerMode } : {}) };
+  const features = value.version === 3 ? value.features : undefined;
+  return {
+    version: features ? 3 : 2,
+    ...(value.footerMode ? { footerMode: value.footerMode } : {}),
+    ...(value.version !== 1 && value.promptCacheKey ? { promptCacheKey: value.promptCacheKey } : {}),
+    ...(features ? { features } : {}),
+  };
 }
 
-function readPersistedCacheOptimizerConfig(configPath: string = CONFIG_FILE_PATH): PersistedCacheOptimizerConfigV2 {
+function readPersistedCacheOptimizerConfig(configPath: string = CONFIG_FILE_PATH): PersistedCacheOptimizerConfigV3 {
   try {
     return normalizePersistedCacheOptimizerConfig(parsePersistedCacheOptimizerConfig(JSON.parse(readFileSync(configPath, "utf8"))));
   } catch (error) {
@@ -2193,7 +2271,7 @@ function readPersistedFooterMode(configPath: string = CONFIG_FILE_PATH): FooterS
 }
 
 async function writePersistedCacheOptimizerConfigUnlocked(
-  config: PersistedCacheOptimizerConfigV2,
+  config: PersistedCacheOptimizerConfig | PersistedCacheOptimizerConfigV3,
   configPath: string,
 ): Promise<void> {
   await mkdir(dirname(configPath), { recursive: true });
@@ -2223,7 +2301,7 @@ async function writePersistedCacheOptimizerConfigUnlocked(
 }
 
 async function writePersistedCacheOptimizerConfig(
-  config: PersistedCacheOptimizerConfigV2,
+  config: PersistedCacheOptimizerConfig | PersistedCacheOptimizerConfigV3,
   configPath: string = CONFIG_FILE_PATH,
 ): Promise<void> {
   await withModelsJsonTransactionLock(() => writePersistedCacheOptimizerConfigUnlocked(config, configPath));
@@ -2233,14 +2311,14 @@ async function writePersistedFooterModeUnlocked(
   mode: FooterStatsMode,
   configPath: string,
 ): Promise<void> {
-  let version: 1 | 2 = 1;
+  let version: 1 | 2 | 3 = 1;
   let raw: PersistedCacheOptimizerConfig | undefined;
   let targetExists = false;
   try {
     raw = parsePersistedCacheOptimizerConfig(JSON.parse(readFileSync(configPath, "utf8")));
     targetExists = true;
     if (!raw) throw new Error("invalid footer config schema");
-    version = raw.version === 2 ? 2 : 1;
+    version = raw.version === 3 ? 3 : raw.version === 2 ? 2 : 1;
   } catch (error) {
     if (getErrorCode(error) !== "ENOENT") throw new Error("invalid footer config schema");
   }
@@ -2263,7 +2341,7 @@ async function writePersistedFooterModeUnlocked(
     }
     return;
   }
-  await writePersistedCacheOptimizerConfigUnlocked({ ...current, version: 2, footerMode: mode }, configPath);
+  await writePersistedCacheOptimizerConfigUnlocked({ ...current, version: 3, footerMode: mode } as PersistedCacheOptimizerConfigV3, configPath);
 }
 
 async function writePersistedFooterMode(
@@ -2273,6 +2351,17 @@ async function writePersistedFooterMode(
   await withModelsJsonTransactionLock(() => writePersistedFooterModeUnlocked(mode, configPath));
 }
 
+async function writePersistedFeature(feature: PersistedCacheOptimizerFeature, enabled: boolean): Promise<void> {
+  const current = readPersistedCacheOptimizerConfig();
+  const next: PersistedCacheOptimizerConfigV3 = {
+    ...current,
+    version: 3,
+    features: { ...(current.features ?? {}), [feature]: enabled },
+  };
+  await writePersistedCacheOptimizerConfig(next);
+  setPersistedCacheOptimizerConfig(readPersistedCacheOptimizerConfig());
+}
+
 function configReceiptBackupPath(receipt: PromptCacheKeyConfigReceipt, receiptPath: string = CONFIG_RECEIPT_PATH): string {
   return join(dirname(receiptPath), receipt.backupFile);
 }
@@ -2665,7 +2754,7 @@ function isDisabledEnv(value: string | undefined): boolean {
 
 function shouldInjectOpenAIPromptCacheKey(): boolean {
   if (!runtimeOptimizerEnabled) return false;
-  if (isEnabledEnv(process.env[NO_OPENAI_CACHE_KEY_ENV])) return false;
+  if (!featureEnabled("openAICacheKey", NO_OPENAI_CACHE_KEY_ENV, true)) return false;
   if (isDisabledEnv(process.env[OPENAI_CACHE_KEY_ENV])) return false;
   return true;
 }
@@ -2687,7 +2776,9 @@ function getOptimizerRuntimeModeLines(): string[] {
   const state = runtimeOptimizerEnabled ? "enabled" : "disabled";
   const lines: string[] = [];
   lines.push(`Runtime state: ${state}`);
-  lines.push(`• Prompt rewrite: ${runtimeOptimizerEnabled && !isEnabledEnv(process.env[NO_PROMPT_REWRITE_ENV]) ? "on" : "off"}`);
+  lines.push(`• Prompt rewrite: ${runtimeOptimizerEnabled && featureEnabled("promptRewrite", NO_PROMPT_REWRITE_ENV, true) ? "on" : "off"}`);
+  lines.push(`• Native virtual rewrite: ${featureEnabled("virtualRewrite", VIRTUAL_REWRITE_ENV, false) ? "opt-in" : "off"}`);
+  lines.push(`• Skill compression: ${featureEnabled("skillCompression", NO_SKILL_COMPRESSION_ENV, true) ? "on" : "off"}`);
   lines.push(`• Deterministic tool ordering: ${isToolOrderEnabled() ? "on (verified built-in payloads, opt-in)" : "off"}`);
   lines.push(`• OpenAI prompt_cache_key fallback: ${shouldInjectOpenAIPromptCacheKey() ? "on" : "off"}`);
   lines.push(`• Footer cache stats: on${runtimeOptimizerEnabled ? "" : " (comparison mode)"}`);
@@ -2695,7 +2786,7 @@ function getOptimizerRuntimeModeLines(): string[] {
   lines.push(`• ${PI_CACHE_RETENTION_ENV}: ${process.env[PI_CACHE_RETENTION_ENV] ?? "(unset)"}`);
   if (!runtimeOptimizerEnabled) {
     lines.push("This is a current-process switch. Run /reload or restart Pi to return to startup behavior.");
-  } else if (isEnabledEnv(process.env[NO_PROMPT_REWRITE_ENV]) || !shouldInjectOpenAIPromptCacheKey()) {
+  } else if (!featureEnabled("promptRewrite", NO_PROMPT_REWRITE_ENV, true) || !shouldInjectOpenAIPromptCacheKey()) {
     lines.push("Some features are still disabled by environment variables.");
   }
   return lines;
@@ -2782,12 +2873,12 @@ function shouldInjectOpenAIPromptCacheKeyForModel(model: PiModel | undefined): b
   return isOpenAICompatibleApi(model?.api);
 }
 
-function isPromptCacheKeyOmittedForModel(model: PiModel | undefined, config: PersistedCacheOptimizerConfigV2 = persistedCacheOptimizerConfig): boolean {
+function isPromptCacheKeyOmittedForModel(model: PiModel | undefined, config: PersistedCacheOptimizerConfig | PersistedCacheOptimizerConfigV3 = persistedCacheOptimizerConfig): boolean {
   if (!model || !isOpenAICompatibleApi(model.api)) return false;
-  return config.promptCacheKey?.omit?.includes(modelKey(model)) === true;
+  return "promptCacheKey" in config && config.promptCacheKey?.omit?.includes(modelKey(model)) === true;
 }
 
-function setPersistedCacheOptimizerConfig(config: PersistedCacheOptimizerConfigV2): void {
+function setPersistedCacheOptimizerConfig(config: PersistedCacheOptimizerConfig | PersistedCacheOptimizerConfigV3): void {
   persistedCacheOptimizerConfig = normalizePersistedCacheOptimizerConfig(config);
   persistedFooterStatsMode = persistedCacheOptimizerConfig.footerMode;
 }
@@ -10160,6 +10251,8 @@ export const __internals_for_tests = {
   normalizeAnthropicCacheControlTtlOrder,
   isPiBuiltInLlamaCppModel,
   isResponsesPromptRewriteBypassApi,
+  canRewriteNativeVirtualPrompt,
+  VIRTUAL_REWRITE_ENV,
   isMistralConversationsApi,
   isOpenAIFamilyModel,
   isOpenAIFamilyAssistantMessage,
@@ -11202,7 +11295,7 @@ export default function (pi: ExtensionAPI) {
     // 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)) {
+    if (isNativeVirtualModel(_ctx.model) && !canRewriteNativeVirtualPrompt(_ctx.model, _ctx)) {
       return {};
     }
 
@@ -11212,7 +11305,7 @@ export default function (pi: ExtensionAPI) {
     // prompt mutations below (session-overview churn strip, skill compression,
     // and stable-prefix reordering). Footer stats and the OpenAI
     // prompt_cache_key fallback remain active.
-    if (isEnabledEnv(process.env[NO_PROMPT_REWRITE_ENV])) return {};
+    if (!featureEnabled("promptRewrite", NO_PROMPT_REWRITE_ENV, true)) return {};
 
     // Step 1: strip per-turn churn from <session-overview>.
     // Removing RECENT COMMITS, Working directory status, and
@@ -11781,10 +11874,34 @@ export default function (pi: ExtensionAPI) {
       } else if (subcommand === "config") {
         const configKey = commandParts[1];
         const requestedMode = commandParts[2];
+        const feature = configKey ? FEATURE_COMMAND_MAP[configKey] : undefined;
+        if (feature && (requestedMode === "on" || requestedMode === "off")) {
+          try {
+            await writePersistedFeature(feature, requestedMode === "on");
+            lastStatusText = undefined;
+            await publishStatus(cmdCtx, model);
+            cmdCtx.ui.notify(`✅ ${configKey} set to ${requestedMode}. Persistent config overrides its environment variable.`, "info");
+          } catch (error) {
+            cmdCtx.ui.notify(`❌ Could not update ${configKey}: ${error instanceof Error ? error.message : String(error)}`, "error");
+          }
+          return;
+        }
+        if (configKey === "reset") {
+          try {
+            await writePersistedCacheOptimizerConfig({ version: 2, footerMode: persistedFooterStatsMode, promptCacheKey: persistedCacheOptimizerConfig.promptCacheKey });
+            setPersistedCacheOptimizerConfig(readPersistedCacheOptimizerConfig());
+            cmdCtx.ui.notify("✅ Feature configuration reset. Environment variables now apply again.", "info");
+          } catch (error) {
+            cmdCtx.ui.notify(`❌ Could not reset feature configuration: ${error instanceof Error ? error.message : String(error)}`, "error");
+          }
+          return;
+        }
         if (configKey !== "footer-mode" || !requestedMode || !["session", "total", "process"].includes(requestedMode)) {
           const resolved = resolveFooterStatsMode(persistedFooterStatsMode);
           cmdCtx.ui.notify(
             `Usage: /cache-optimizer config footer-mode total|session|process\n` +
+            `       /cache-optimizer config prompt-rewrite|virtual-rewrite|skill-compression|openai-cache-key|tool-order on|off\n` +
+            `       /cache-optimizer config reset\n` +
             `Current footer mode: ${resolved.mode} (${resolved.source})`,
             "info",
           );
@@ -12601,7 +12718,9 @@ export default function (pi: ExtensionAPI) {
         diagnosis.push("  stats all — Show detailed totals for every model across all local sessions");
         diagnosis.push("  stats contributors — Show per-session contributors for the active model");
         diagnosis.push("  compat  — Show compat suggestion with edit location");
+        diagnosis.push("  config prompt-rewrite|virtual-rewrite|skill-compression|openai-cache-key|tool-order on|off — Persist feature settings");
         diagnosis.push("  config footer-mode total|session|process — Persist the footer stats mode");
+        diagnosis.push("  config reset — Remove persistent feature overrides");
         diagnosis.push("  fix     — Auto-fix compat issues (writes models.json or extension config, requires UI)");
         diagnosis.push("  fix prompt-cache-key — Explicitly omit prompt_cache_key for the active model");
         diagnosis.push("  rollback — Undo the latest confirmed fix (requires UI confirmation)");

package/package.json

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