pi-cache-optimizer 2.4.9 → 2.5.1

package/README.md

@@ -104,25 +104,10 @@ This extension is pure Node.js — no shell exec, no native bindings, no platfor
 
 State files under `~/.pi/agent/` are resolved via Node's `os.homedir()`, so on Windows the path automatically expands to `C:\Users\<you>\.pi\agent\...`. The extension's compat warnings, `/cache-optimizer doctor`, and `/cache-optimizer compat` show the platform-appropriate path automatically (`~/.pi/agent/models.json` on Linux/macOS, `%USERPROFILE%\.pi\agent\models.json` on Windows). All shell snippets in this README are bash, matching the shell Pi runs in on every supported platform; no PowerShell or `cmd.exe` translation is needed when commands are executed inside (or for) Pi.
 
-## Quickstart
-
-1. (Optional but recommended) Read the official Pi + DeepSeek onboarding guide: [`pi_mono.zh-CN.md`](https://github.com/deepseek-ai/awesome-deepseek-agent/blob/main/docs/pi_mono.zh-CN.md). It covers Pi installation and core configuration.
-2. Install this extension:
-
-   ```bash
-   pi install npm:pi-cache-optimizer
-   ```
-
-3. Export your DeepSeek API key in the same shell where you run `pi` (if you use a DeepSeek model):
-
-   ```bash
-   export DEEPSEEK_API_KEY='...'
-   ```
-
-   This extension never reads, stores, or prints the key value.
-
 ## Install
 
+Install and configure Pi first, then install this extension:
+
 ```bash
 pi install npm:pi-cache-optimizer
 ```
@@ -254,11 +239,30 @@ Stats rules:
 - Stats are persisted in a small local JSON state file at `~/.pi/agent/pi-cache-optimizer-stats.json`. Earlier 1.x releases used `~/.pi/agent/deepseek-cache-optimizer-stats.json`; on first run after upgrade the old file is read once, copied into the new path, and best-effort deleted. The file stores only counters and the local day; it does not store API keys, prompts, messages, headers, or model output.
 - Existing v1 state files from DeepSeek-only releases are migrated into the DeepSeek adapter counters automatically.
 
-Reset behavior:
-
-- Pi restarts do **not** clear stats; the persisted counters are restored.
-- `/reload` / extension reload resets the persisted counters because Pi exposes `session_start` with reason `reload`.
-- Crossing the local natural-day boundary resets counters on the next status update or supported-provider response.
+Session scope:
+
+- Stats are now scoped per Pi session + provider/model, not global.
+- Each Pi process (session) starts with fresh counters. Different sessions using the
+  same provider/model do not share footer statistics or reset effects.
+- Within the same Pi session, stats accumulate normally for each provider/model.
+- Pi restarts start fresh stats for the new session.
+- `/reload` does **not** clear accumulated session-scoped stats; it only clears transient
+  in-memory data (recent samples, integrity notification state).
+- Crossing the local natural-day boundary resets counters on the next status update or
+  supported-provider response.
+- Persisted stats are stored under an opaque session hash key (SHA-256 hash of session id)
+  so that different sessions' data is isolated on disk. Raw session ids are never logged,
+  displayed, or written to the stats file.
+
+> **Concurrent-write caveat**: Stats are persisted atomically (write-temp then rename),
+> but multiple Pi processes reading and writing simultaneously can still experience
+> a lost-update window (the classic read-modify-write race). The implementation
+> preserves sequential operation semantics (each write replaces only the current
+> session's data and re-appends other sessions from the previous read), but does
+> **not** guarantee concurrent-safety across processes. If you run multiple Pi
+> instances using the same `models.json` with different provider/model IDs, their
+> stats files may occasionally overwrite each other's session data. This affects
+> only the on-disk persistence; in-memory counters per process remain correct.
 
 ## Suggested compat config
 
@@ -307,13 +311,35 @@ The extension registers a Pi command `/cache-optimizer` for interactive diagnosi
                                     and low-hit cause diagnosis
 /cache-optimizer stats         — show active model stats bucket and recent trend
 /cache-optimizer compat        — show compat suggestion with edit instructions
+/cache-optimizer reset         — reset local session stats for the current model
+                                  (does not affect upstream provider prompt cache)
 ```
 
 When run without arguments, `/cache-optimizer` shows an interactive selection menu
-(Doctor / Stats / Compat / Cancel) when the Pi UI supports it (`ctx.ui.select`). In
-non-interactive terminals, it falls back to text help with current model compat
+(Doctor / Stats / Compat / Reset / Cancel) when the Pi UI supports it (`ctx.ui.select`).
+In non-interactive terminals, it falls back to text help with current model compat
 status.
 
+### `/cache-optimizer reset`
+
+Resets only the current Pi session's stats bucket for the active provider/model.
+Clears today's request counters (hit/total), cached token counts, and recent trend
+samples for that model. Other provider/model buckets within the same session are
+unaffected, and other sessions' data is preserved.
+
+```text
+Provider: otokapi
+Model: gpt-5.5
+
+✅ Reset local session cache stats for "otokapi/gpt-5.5".
+   Upstream provider prompt cache was not modified.
+   New requests will start a fresh stats bucket for this Pi session.
+```
+
+If no active model is selected, a warning is shown. If the active model does not
+match a cache adapter (footer stats are not shown for it), a friendly no-op message
+is displayed instead.
+
 ### `/cache-optimizer doctor`
 
 Displays the active model's provider, model id, name, API type, base URL, current

package/README.zh-CN.md

@@ -107,25 +107,10 @@ Generic OpenAI-compatible 代理**不会**仅因为使用 OpenAI 形状 API 或
 
 状态文件 `~/.pi/agent/` 通过 Node 的 `os.homedir()` 解析，所以在 Windows 上会自动展开为 `C:\Users\<你>\.pi\agent\...`。扩展的 compat 提醒、`/cache-optimizer doctor` 和 `/cache-optimizer compat` 会自动显示适合当前平台的路径（Linux/macOS 上显示 `~/.pi/agent/models.json`，Windows 上显示 `%USERPROFILE%\.pi\agent\models.json`）。本文档中所有 shell 命令均使用 bash 语法，与 Pi 在每个受支持平台下运行的 shell 一致；只要在 Pi 内（或为 Pi 而执行）运行，就**不需要**改写为 PowerShell 或 `cmd.exe` 形式。
 
-## 快速开始
-
-1. （可选但推荐）先读一遍官方 Pi + DeepSeek 接入指南：[`pi_mono.zh-CN.md`](https://github.com/deepseek-ai/awesome-deepseek-agent/blob/main/docs/pi_mono.zh-CN.md)。它讲了 Pi 安装与基础配置。
-2. 安装本扩展：
-
-   ```bash
-   pi install npm:pi-cache-optimizer
-   ```
-
-3. 如果使用 DeepSeek 模型，请在运行 `pi` 的同一个 shell 中导出 DeepSeek API key：
-
-   ```bash
-   export DEEPSEEK_API_KEY='...'
-   ```
-
-   本扩展**不会**读取、存储或打印 key 的值。
-
 ## 安装
 
+请先安装并配置好 Pi，然后安装本扩展：
+
 ```bash
 pi install npm:pi-cache-optimizer
 ```
@@ -249,11 +234,48 @@ Gemini cache 1/2 · 0.18M/0.50M tok (36%)
 - 统计会持久化到本地小 JSON 文件：`~/.pi/agent/pi-cache-optimizer-stats.json`。早期 1.x 版本使用 `~/.pi/agent/deepseek-cache-optimizer-stats.json`；首次运行新版时会从旧路径读一次、复制到新路径、然后 best-effort 删除旧文件。该文件只保存计数器和本地日期，不保存 API key、prompt、消息内容、headers 或模型输出。
 - DeepSeek-only 旧版本的 v1 状态文件会自动迁移到 DeepSeek adapter 计数器。
 
-重置规则：
+## 统计桶隔离（Session-scoped）
+
+- 统计现在按 Pi session + provider/model 隔离，不再全局聚合。
+- 每个 Pi 进程（session）从零开始计数。不同 session 对同一 provider/model 的统计不共享。
+- 同一 Pi session 中，同一 provider/model 的统计正常累积。
+- Pi 进程重新启动时，新的 session 从头开始统计。
+- `/reload` **不会**清空累计的 session-scoped 统计；只清除临时内存状态（recent samples、integrity notification）。
+- 跨过本地自然日时，下一次状态更新或受支持 provider 响应时会自动按本地日期清零。
+- 持久化统计文件使用不透明的 session hash key（SHA-256 哈希后的 session id）来隔离不同 session 的数据。原始 session id 不会写入文件。
+
+> **并发写入说明**：统计以原子方式持久化（写 temp 文件再 rename），但多个 Pi 进程同时读写仍然存在 lost-update 窗口（经典的 read-modify-write 竞态）。实现中尽可能保留顺序语义（每次写入只替换当前 session 的数据，其他 session 的数据从前次读取追加），但**不保证**跨进程并发安全。如果同时运行多个 Pi 实例使用不同 provider/model，统计文件偶尔可能覆盖彼此 session 的数据。这只影响磁盘持久化；每个进程的内存统计始终正确。
+
+## 诊断命令
+
+扩展注册了 Pi 命令 `/cache-optimizer` 用于交互式诊断。
+
+```
+/cache-optimizer              — 交互菜单（无 UI 时显示文字帮助）
+/cache-optimizer doctor        — 显示 provider、model、API、base URL、compat 状态
+                                   及低命中原因诊断
+/cache-optimizer stats         — 显示当前模型的 stats 桶和近期趋势
+/cache-optimizer compat        — 显示 compat 建议和编辑说明
+/cache-optimizer reset         — 重置当前 Pi session 中当前模型的本地统计
+                                  （不影响上游 provider prompt cache）
+```
+
+不带参数时，当 Pi UI 支持时（`ctx.ui.select` 可用），`/cache-optimizer` 会显示交互选择菜单（Doctor / Stats / Compat / Reset / Cancel）。在非交互终端中，会回退到文字帮助和当前模型 compat 状态。
 
-- Pi 重启**不会**清零统计；扩展会恢复已持久化的计数器。
-- `/reload` / extension reload 会清零并覆盖持久化计数器，因为 Pi 会暴露 `session_start` 的 `reason: "reload"`。
-- 长时间运行跨过本地自然日时，会在下一次状态更新或受支持 provider 响应统计前自动按本地日期清零。
+### `/cache-optimizer reset`
+
+仅重置当前 Pi session 中活跃 provider/model 的统计桶。清除今日请求计数（命中/总数）、缓存 token 计数和近期趋势样本。同一 session 中其他 provider/model 的桶不受影响，其他 session 的数据也不受影响。
+
+```text
+Provider: otokapi
+Model: gpt-5.5
+
+✅ 已重置 "otokapi/gpt-5.5" 的本地 session 缓存统计。
+   上游 provider prompt cache 未被修改。
+   新的请求将为这个 Pi session 重新开始统计。
+```
+
+如果没有选中的模型，显示警告。如果当前模型不匹配缓存的 adapter（不显示底部统计），则显示友好的无操作提示。
 
 ## 建议的 compat 配置
 
@@ -291,97 +313,6 @@ Gemini cache 1/2 · 0.18M/0.50M tok (36%)
 
 > 提醒：只有在 endpoint 或代理明确支持时，才建议启用 session-affinity headers 或 cache-control compat。
 
-## 诊断命令
-
-扩展注册了 Pi 命令 `/cache-optimizer` 用于交互式诊断。
-
-```
-/cache-optimizer              — 交互菜单（无 UI 时显示文字帮助）
-/cache-optimizer doctor        — 显示 provider、model、API、base URL、compat 状态
-                                   及低命中原因诊断
-/cache-optimizer stats         — 显示当前模型的 stats 桶和近期趋势
-/cache-optimizer compat        — 显示 compat 建议和编辑说明
-```
-
-不带参数时，当 Pi UI 支持时（`ctx.ui.select` 可用），`/cache-optimizer` 会显示交互选择菜单（Doctor / Stats / Compat / Cancel）。在非交互终端中，会回退到文字帮助和当前模型 compat 状态。
-
-### `/cache-optimizer doctor`
-
-显示当前模型的 provider、model id、名称、API 类型、base URL、当前 `compat` 标志以及缺少的缓存/session-affinity 标志。如果缺少标志，还会显示可复制的 JSON 片段和精确编辑位置。
-
-输出中还会包含 "Cache diagnosis"（缓存诊断）章节，按优先级分析低命中原因：
-1. **缺少 compat 标志** — 缺少启用 prompt 缓存和 session-affinity 路由的标志。
-2. **路由/渠道风险** — 多后端路由可能导致缓存分散到不同上游实例。
-3. **缺少 usage 字段** — 代理可能未返回 prompt 层级的使用情况字段，导致 footer 低估命中率。
-4. **近期趋势低** — 当今日缓存命中率低于 30% 时，诊断提示代理路由不稳定或 prompt 前缀变化。
-
-对于已完整配置但命中率仍低的模型，诊断会重点提示粘性路由和上游缓存使用验证，而非 compat 标志。
-
-### `/cache-optimizer stats`
-
-显示当前模型的 stats 桶（`provider/modelId`），今日请求计数（命中/总数）、缓存输入令牌 vs 总输入令牌及命中率百分比。同时显示近期趋势摘要（最近 10 条和最近 30 条样本）：
-
-```text
-Model key: otokapi/gpt-5.5
-Adapter:   OpenAI cache
-
-── Today ──
-Requests:      3 hit / 10 total · 30%
-Cached tokens: 0.0015M / 0.005M input · 30%
-
-── Recent trend ──
-Recent 10/10: 3/10 hits · 30% tok cached
-Recent 10/10: 3/10 hits · 30% tok cached
-```
-
-如果当前模型没有匹配的 adapter，显示友好提示。如果尚未记录样本，趋势显示 "no samples"。
-
-如果所有 compat 标志都已配置且适用（第三方 `openai-completions` 代理），输出显示 `✅ Compat fully configured.`。对于不适用 compat 检查的模型（官方 OpenAI、非 `openai-completions` API、custom transport），显示 `ℹ️ Compat check not applicable for this model.`：
-
-```text
-Provider: otokapi
-Model:    gpt-5.5
-API:      openai-completions
-Base URL: https://otokapi.example.com/v1
-Compat:   {}
-⚠️  Missing compat flags: supportsLongCacheRetention, sendSessionAffinityHeaders
-Edit ~/.pi/agent/models.json -> providers["otokapi"] -> compat (same level as baseUrl/api/apiKey/models):
-{
-  "supportsLongCacheRetention": true,
-  "sendSessionAffinityHeaders": true
-}
-```
-
-### `/cache-optimizer compat`
-
-显示当前模型的 compat 建议，包括文件路径、provider 路径和可复制 JSON 片段。当没有缺失的 compat 标志时，如果模型是适用的第三方代理则显示 `✅ Compat fully configured.`，否则显示 `ℹ️ Compat check not applicable for this model.`。
-
-当模型通过已知的路由器/通道代理（OpenRouter、Vercel AI Gateway、LiteLLM、OneAPI/NewAPI/VoAPI 或通用第三方 OpenAI-compatible 代理）时，`doctor` 和 `compat` 子命令都会附加路由/通道诊断信息和建议。
-
-### 路由/通道诊断
-
-对于通过非官方 base URL 使用 OpenAI-compatible API（`openai-completions` 或 `openai-responses`）的模型，扩展会从 `provider`、`baseUrl` 和 `compat` 元数据中检测常见的路由/通道代理模式：
-
-| 类型 | 检测方式 | 建议 |
-|------|----------|------|
-| **OpenRouter** | baseUrl 或 provider 包含 `openrouter`/`openrouter.ai` | 在 compat 中用 `openRouterRouting.only` 或 `.order` 固定上游 provider |
-| **Vercel AI Gateway** | baseUrl 包含 `ai-gateway.vercel.sh` 或 provider 包含 `vercel` | 在 compat 中用 `vercelGatewayRouting.only` 或 `.order` 固定上游 |
-| **LiteLLM / OneAPI / NewAPI / VoAPI** | baseUrl 或 provider 包含 `litellm`、`oneapi`/`one-api`、`newapi`/`new-api`、`voapi`/`vo-api` | 确保每 session 固定路由，转发 `prompt_cache_key` + session-affinity headers，返回缓存用量字段 |
-| **通用第三方代理** | 任何非官方 base URL 的 `openai-completions` 模型，且不匹配以上类型 | 通用建议：验证单上游路由、转发 `prompt_cache_key` + session-affinity headers、返回缓存用量 |
-
-这些诊断**仅用于建议**。它们不参与 adapter selection（仍基于 id/name）、不参与 `prompt_cache_key` 注入、不参与 footer 统计、也不做任何自动化配置修改。检测仅使用 Pi 暴露的元数据（`provider`、`api`、`baseUrl`、`compat`），不会读取或暴露 API key、prompt、payload、headers 或模型输出。
-
-官方 OpenAI（`api.openai.com`）和 custom transport（`kiro-api`、`anthropic-messages`、`bedrock-converse-stream`）不会触发路由/通道诊断。
-
-### 安全说明
-
-命令只读取 Pi 通过 `ctx.model` 暴露的元数据：provider、id、name、api、baseUrl、compat。它**不会**读取或暴露：
-- API key 或环境密钥
-- 请求/响应 payload
-- Prompt 或模型输出
-- HTTP headers
-- `~/.pi/agent/models.json` 的原始内容
-
 ## 原理
 
 Provider 缓存通常依赖精确或近似精确的前缀匹配。Pi 的 system prompt 包含跨会话稳定的内容（工具定义、技能、规范），也包含每次变化的动态内容（git status、当前任务）。

package/index.ts

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
@@ -135,6 +136,19 @@ type PersistedCacheStatsV3 = {
   legacyFamily: Partial<Record<CacheProviderId, CacheStats>>;
 };
 
+/**
+ * V4 format: session-scoped stats buckets.
+ * Each Pi process/session gets its own stats isolated by a hashed session id.
+ *
+ * sessions: sessionHash → modelKey (provider/id) → CacheStats
+ * legacyFamily: unchanged from v3 (migration/fallback when ctx.model is unknown)
+ */
+type PersistedCacheStatsV4 = {
+  version: 4;
+  sessions: Record<string, Record<string, CacheStats>>;
+  legacyFamily: Partial<Record<CacheProviderId, CacheStats>>;
+};
+
 type UsageSnapshot = {
   cacheRead: number;
   cacheWrite: number;
@@ -562,6 +576,32 @@ function getSessionPromptCacheKey(ctx: ExtensionContext): string | undefined {
   return clampPromptCacheKey(ctx.sessionManager.getSessionId());
 }
 
+/**
+ * Hash a session id for use as a non-reversible opaque scope key.
+ * Returns a 16-character hex string (64 bits of SHA-256 digest prefix)
+ * suitable for scoping stats buckets without exposing the raw session id.
+ */
+function hashSessionId(sessionId: string): string {
+  return createHash("sha256").update(sessionId).digest("hex").slice(0, 16);
+}
+
+/**
+ * Build a session-scoped stats key from a session hash + provider/id.
+ * Pure function (no closure dependency) for use by tests and internals.
+ */
+function makeSessionModelKey(sessionHash: string, provider: string, id: string): string {
+  return `${sessionHash}:${provider}/${id}`;
+}
+
+/**
+ * Extract the user-facing model key from a session-scoped key.
+ * "abc123:otokapi/gpt-5.5" → "otokapi/gpt-5.5"
+ */
+function modelKeyFromSessionKey(sessionModelKey: string): string {
+  const idx = sessionModelKey.indexOf(":");
+  return idx >= 0 ? sessionModelKey.slice(idx + 1) : sessionModelKey;
+}
+
 function asRecord(value: unknown): UnknownRecord | undefined {
   if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
   return value as UnknownRecord;
@@ -2651,7 +2691,39 @@ function parsePersistedCacheStats(value: unknown): CacheStatsState | undefined {
   const record = asRecord(value);
   if (!record) return undefined;
 
-  // version 3: model-scoped stats + legacy family fallback
+  // version 4: session-scoped stats + legacy family fallback
+  if (record.version === 4) {
+    const legacyFamily: Partial<Record<CacheProviderId, CacheStats>> = {};
+    const rawFamily = asRecord(record.legacyFamily);
+    if (rawFamily) {
+      for (const id of CACHE_PROVIDER_IDS) {
+        const stats = parseCacheStats(rawFamily[id]);
+        if (stats) legacyFamily[id] = stats;
+      }
+    }
+
+    // Collect all session entries into statsByModel with session-hash-prefixed keys
+    // (e.g. "abc123:otokapi/gpt-5.5") so that writePersistedCacheStats can later
+    // reconstruct individual sessions from the flat key format and other sessions'
+    // data is not silently lost on round-trip.
+    const statsByModel: Record<string, CacheStats> = {};
+    const rawSessions = asRecord(record.sessions);
+    if (rawSessions) {
+      for (const [sessionHash, modelMap] of Object.entries(rawSessions)) {
+        const parsedMap = asRecord(modelMap);
+        if (parsedMap) {
+          for (const [modelKey, val] of Object.entries(parsedMap)) {
+            const parsed = parseCacheStats(val);
+            if (parsed) statsByModel[`${sessionHash}:${modelKey}`] = parsed;
+          }
+        }
+      }
+    }
+
+    return { statsByModel, legacyFamily };
+  }
+
+  // version 3: migrate to v4 semantics by wrapping statsByModel into sessions
   if (record.version === 3) {
     const statsByModel: Record<string, CacheStats> = {};
     const rawModelMap = asRecord(record.statsByModel);
@@ -2736,11 +2808,122 @@ async function readPersistedCacheStats(): Promise<CacheStatsState | undefined> {
   return undefined;
 }
 
-async function writePersistedCacheStats(state: CacheStatsState): Promise<void> {
+/**
+ * The closure-internal writer. Since the closure has access to currentSessionHash,
+ * it passes the hash and statsByModel here. This function wraps them in the v4
+ * sessions format, combining with any previously-persisted sessions for safety.
+ *
+ * When called from the closure, `state.statsByModel` contains only the current
+ * session's entries (keyed by `${sessionHash}:${provider}/${id}`). We extract
+ * the model-key-only entries and store them under the session hash.
+ */
+/**
+ * Merge in-memory stats state into an existing sessions map for persistence.
+ *
+ * When `currentSessionHash` is provided (explicit hash mode):
+ *   - Current-session entries are extracted from `state.statsByModel` (keys
+ *     prefixed with `currentSessionHash:`) and written under the session hash.
+ *   - The transitional legacy `_nosession` bucket is DELETED — its entries
+ *     were already consumed and migrated into memory by `restoreCacheStats`.
+ *     Keeping `_nosession` on disk would allow resurrection of reset stats
+ *     on the next reload (the reset-undo bug).
+ *   - Other real session hashes are preserved intact.
+ *
+ * When `currentSessionHash` is undefined (no-hash mode):
+ *   - Keys with a hash prefix (`hash:provider/model`) are grouped under their
+ *     respective session hashes.
+ *   - Keys without a hash prefix (legacy v3) are grouped under `_nosession` so
+ *     `restoreCacheStats` can migrate them on the next load before the session
+ *     id is known.
+ *
+ * Pure function (no I/O) — suitable for unit tests without touching the real
+ * state file at `~/.pi/agent/pi-cache-optimizer-stats.json`.
+ */
+function mergeCacheSessions(
+  existingSessions: Record<string, Record<string, CacheStats>>,
+  state: CacheStatsState,
+  currentSessionHash?: string,
+): Record<string, Record<string, CacheStats>> {
+  // Deep-copy to avoid mutating the caller's object.
+  const sessions: Record<string, Record<string, CacheStats>> = {};
+  for (const [hash, models] of Object.entries(existingSessions)) {
+    sessions[hash] = { ...models };
+  }
+
+  if (currentSessionHash !== undefined) {
+    // Explicit hash mode: extract this session's data from state.statsByModel.
+    // When the session has no entries (e.g. after reset of sole bucket), this
+    // still sets an empty map, ensuring the deleted bucket does not return.
+    const prefix = `${currentSessionHash}:`;
+    const currentModelStats: Record<string, CacheStats> = {};
+    for (const [fullKey, stats] of Object.entries(state.statsByModel)) {
+      if (fullKey.startsWith(prefix)) {
+        currentModelStats[fullKey.slice(prefix.length)] = stats;
+      }
+    }
+    sessions[currentSessionHash] = currentModelStats;
+
+    // _nosession is a transitional legacy migration bucket — once we write
+    // under an authoritative session hash, those entries have already been
+    // consumed and migrated into memory by restoreCacheStats. Delete to
+    // prevent resurrection of reset stats on the next reload.
+    delete sessions["_nosession"];
+  } else {
+    // No-hash mode: group entries by their existing hash prefix to avoid
+    // collapsing multiple sessions into one bucket. Keys without a hash
+    // prefix (legacy v3) go under "_nosession" so restoreCacheStats can
+    // migrate them to the current session on next load.
+    const nosessionMap: Record<string, CacheStats> = {};
+    for (const [fullKey, stats] of Object.entries(state.statsByModel)) {
+      const idx = fullKey.indexOf(":");
+      if (idx >= 0) {
+        const hash = fullKey.slice(0, idx);
+        const modelKey = fullKey.slice(idx + 1);
+        if (!sessions[hash]) sessions[hash] = {};
+        sessions[hash][modelKey] = stats;
+      } else {
+        // Key without hash prefix (legacy v3) — group under _nosession.
+        nosessionMap[fullKey] = stats;
+      }
+    }
+    if (Object.keys(nosessionMap).length > 0) {
+      sessions["_nosession"] = nosessionMap;
+    }
+  }
+
+  return sessions;
+}
+
+async function writePersistedCacheStats(state: CacheStatsState, currentSessionHash?: string): Promise<void> {
   await mkdir(STATE_DIR, { recursive: true });
-  const payload: PersistedCacheStatsV3 = {
-    version: 3,
-    statsByModel: state.statsByModel,
+
+  // Read existing file to preserve other sessions' data.
+  let existingSessions: Record<string, Record<string, CacheStats>> = {};
+  try {
+    const raw = await readFile(STATE_FILE_PATH, "utf8");
+    const parsed = parsePersistedCacheStats(JSON.parse(raw));
+    if (parsed) {
+      // Reconstruct sessions from statsByModel keys.
+      // Each key has form `${hash}:${provider}/${id}`; group by hash.
+      for (const [fullKey, stats] of Object.entries(parsed.statsByModel)) {
+        const idx = fullKey.indexOf(":");
+        if (idx >= 0) {
+          const hash = fullKey.slice(0, idx);
+          const modelKey = fullKey.slice(idx + 1);
+          if (!existingSessions[hash]) existingSessions[hash] = {};
+          existingSessions[hash][modelKey] = stats;
+        }
+      }
+    }
+  } catch {
+    // Ignore read errors (file may not exist yet).
+  }
+
+  const sessions = mergeCacheSessions(existingSessions, state, currentSessionHash);
+
+  const payload: PersistedCacheStatsV4 = {
+    version: 4,
+    sessions,
     legacyFamily: state.legacyFamily,
   };
   const tempPath = `${STATE_FILE_PATH}.${process.pid}.${Date.now()}.tmp`;
@@ -3294,6 +3477,17 @@ export const __internals_for_tests = {
   formatTokenM,
   hasMissingUsageFields,
   keyForModelExt,
+  // Session-scoped helpers
+  hashSessionId,
+  makeSessionModelKey,
+  modelKeyFromSessionKey,
+  // Persistence helpers (for reload/reset tests)
+  mergeCacheSessions,
+  writePersistedCacheStats,
+  readPersistedCacheStats,
+  STATE_FILE_PATH,
+  LEGACY_STATE_FILE_PATH,
+  STATE_DIR,
 };
 
 export default function (pi: ExtensionAPI) {
@@ -3304,10 +3498,31 @@ export default function (pi: ExtensionAPI) {
   let persistenceWarningShown = false;
   let persistTimer: ReturnType<typeof setTimeout> | null = null;
   let integrityNotificationShown = false;
+  let currentSessionId = "";
+  let currentSessionHash = "";
+  let currentSessionHashSet = false;
   const PERSIST_DEBOUNCE_MS = 2000;
   /** In-memory recent usage samples per model key (not persisted, cleared on reload). */
   const recentSamplesByModelKey = new Map<string, CacheUsageSample[]>();
 
+  /**
+   * Build a session-scoped stats key from the current session hash + model key.
+   * Returns `${sessionHash}:${provider}/${id}`.
+   */
+  function sessionModelKey(model: { provider: string; id: string }): string {
+    const hash = currentSessionHash || "_nosession";
+    return `${hash}:${model.provider}/${model.id}`;
+  }
+
+  /**
+   * Extract the user-facing model key from a session-scoped key.
+   * "abc123:otokapi/gpt-5.5" → "otokapi/gpt-5.5"
+   */
+  function modelKeyFromSessionScoped(sKey: string): string {
+    const idx = sKey.indexOf(":");
+    return idx >= 0 ? sKey.slice(idx + 1) : sKey;
+  }
+
   function recordRecentSample(modelKeyStr: string, usage: UsageSnapshot, missingUsageFields: boolean): void {
     let samples = recentSamplesByModelKey.get(modelKeyStr);
     if (!samples) {
@@ -3342,7 +3557,7 @@ export default function (pi: ExtensionAPI) {
   /** Look up active stats for a model, falling back to legacy family. */
   function getStatsForModel(model: PiModel | undefined, adapter: CacheProviderAdapter): CacheStats {
     if (model) {
-      const key = modelKey(model);
+      const key = sessionModelKey(model);
       const existing = cacheStatsByModel[key];
       if (existing) return existing;
     }
@@ -3369,7 +3584,7 @@ export default function (pi: ExtensionAPI) {
 
   async function persistCacheStats(ctx?: ExtensionContext): Promise<void> {
     try {
-      await writePersistedCacheStats(getCacheStatsState());
+      await writePersistedCacheStats(getCacheStatsState(), currentSessionHashSet ? currentSessionHash : undefined);
     } catch (error) {
       console.warn(`${LOG_PREFIX}: failed to persist cache stats`, error);
       if (!persistenceWarningShown) {
@@ -3435,20 +3650,80 @@ export default function (pi: ExtensionAPI) {
   }
 
   async function restoreCacheStats(reason: string, ctx: ExtensionContext): Promise<void> {
+    // Set session id on first load and on reload (same session).
+    const sid = ctx.sessionManager.getSessionId();
+    if (sid && (sid !== currentSessionId || !currentSessionHashSet)) {
+      currentSessionId = sid;
+      currentSessionHash = hashSessionId(sid);
+      currentSessionHashSet = true;
+    }
+
     if (reason === "reload") {
-      cacheStatsByModel = {};
-      cacheStatsLegacyFamily = emptyAllCacheStats();
+      // /reload: preserve session-scoped stats (same session hash).
+      // Pi extension reload creates a fresh closure, so cacheStatsByModel
+      // starts empty. Read persisted data and filter for current session.
       lastStatusText = undefined;
-      // Reset integrity diagnostics on reload
       lastPromptIntegrityWarningAt = 0;
       integrityNotificationShown = false;
       clearRecentSamples();
-      await flushPersistCacheStats(ctx);
+
+      const persisted = await readPersistedCacheStats();
+      if (persisted && currentSessionHash) {
+        const prefix = `${currentSessionHash}:`;
+        const filteredModelStats: Record<string, CacheStats> = {};
+        for (const [fullKey, stats] of Object.entries(persisted.statsByModel)) {
+          if (fullKey.startsWith(prefix)) {
+            // Current session's data
+            filteredModelStats[fullKey] = stats;
+          } else if (!fullKey.includes(":")) {
+            // Legacy v3-style key without session hash — migrate to current session
+            filteredModelStats[`${currentSessionHash}:${fullKey}`] = stats;
+          } else if (fullKey.startsWith("_nosession:")) {
+            // _nosession migration remnant from old-path v4 write — migrate to current session
+            filteredModelStats[`${currentSessionHash}:${fullKey.slice("_nosession:".length)}`] = stats;
+          }
+        }
+        cacheStatsByModel = filteredModelStats;
+        cacheStatsLegacyFamily = persisted.legacyFamily;
+      } else if (persisted) {
+        cacheStatsByModel = persisted.statsByModel;
+        cacheStatsLegacyFamily = persisted.legacyFamily;
+      } else {
+        cacheStatsByModel = {};
+        cacheStatsLegacyFamily = emptyAllCacheStats();
+      }
+
+      await rollOverStatsIfNeeded(ctx);
       return;
     }
 
+    // First load / process start: read persisted stats and filter for
+    // this session's entries. If the session has no persisted data yet,
+    // start fresh.
     const persisted = await readPersistedCacheStats();
-    if (persisted) {
+    if (persisted && currentSessionHash) {
+      const prefix = `${currentSessionHash}:`;
+      const filteredModelStats: Record<string, CacheStats> = {};
+      for (const [fullKey, stats] of Object.entries(persisted.statsByModel)) {
+        if (fullKey.startsWith(prefix)) {
+          // Current session's data — load it.
+          filteredModelStats[fullKey] = stats;
+        } else if (!fullKey.includes(":")) {
+          // Legacy v3-style key without session hash (e.g. "otokapi/gpt-5.5").
+          // Migrate to current session by prefixing with the session hash.
+          filteredModelStats[`${currentSessionHash}:${fullKey}`] = stats;
+        } else if (fullKey.startsWith("_nosession:")) {
+          // _nosession migration remnant from old-path v4 write — migrate to current session
+          filteredModelStats[`${currentSessionHash}:${fullKey.slice("_nosession:".length)}`] = stats;
+        }
+        // Other sessions' entries are preserved in the file but not loaded
+        // into memory; they'll be rewritten on next persist.
+      }
+      cacheStatsByModel = filteredModelStats;
+      cacheStatsLegacyFamily = persisted.legacyFamily;
+    } else if (persisted) {
+      // Persisted data exists but no session hash set yet.
+      // This shouldn't normally happen — use the data as-is.
       cacheStatsByModel = persisted.statsByModel;
       cacheStatsLegacyFamily = persisted.legacyFamily;
     } else {
@@ -3465,13 +3740,11 @@ export default function (pi: ExtensionAPI) {
     const adapter = selectAdapterForModel(model);
     let statusText: string | undefined;
     if (adapter) {
-      // Display only per-model scoped stats. A model that has never been
-      // used in this session shows 0/0 rather than falling back to legacy
-      // family aggregated stats (which could span different providers with
-      // the same model-family name). The message_end hook populates
-      // cacheStatsByModel[key] on first use with that model.
-      const key = model ? modelKey(model) : undefined;
-      const stats = key ? cacheStatsByModel[key] : undefined;
+      // 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;
+      const stats = sk ? cacheStatsByModel[sk] : undefined;
       statusText = formatCacheStats(adapter, stats ?? emptyCacheStats());
     }
 
@@ -3629,22 +3902,22 @@ export default function (pi: ExtensionAPI) {
 
     // Record recent sample (even when usage is missing, for trend diagnosis)
     if (ctx.model) {
-      const key = modelKey(ctx.model);
+      const sk = sessionModelKey(ctx.model);
       const missingFields = usage === undefined || (usage.cacheRead === 0 && usage.cacheWrite === 0 && usage.totalInput === 0)
         ? true
         : hasMissingUsageFields(event.message, adapter);
-      recordRecentSample(key, usage ?? { cacheRead: 0, cacheWrite: 0, totalInput: 0 }, missingFields);
+      recordRecentSample(sk, usage ?? { cacheRead: 0, cacheWrite: 0, totalInput: 0 }, missingFields);
     }
 
     if (!usage) return;
 
     await rollOverStatsIfNeeded(ctx);
 
-    // Update stats scoped to the active model (provider/id key).
+    // Update stats scoped to current session + active model.
     // Falls back to legacy family when ctx.model is undefined.
     if (ctx.model) {
-      const key = modelKey(ctx.model);
-      addUsageToCacheStats(getOrCreateStatsByModelKey(key), usage);
+      const sk = sessionModelKey(ctx.model);
+      addUsageToCacheStats(getOrCreateStatsByModelKey(sk), usage);
     } else {
       addUsageToCacheStats(getStatsForModel(undefined, adapter), usage);
     }
@@ -3660,6 +3933,7 @@ export default function (pi: ExtensionAPI) {
   //             with low-hit diagnosis
   //   stats   — show active model stats bucket, recent trend, usage
   //   compat  — show compat suggestion with file path
+  //   reset   — reset current session model stats bucket (local only)
   //   (no args) — interactive menu (with UI) or help summary
   // ────────────────────────────────────────────────────────────────
   pi.registerCommand("cache-optimizer", {
@@ -3675,8 +3949,9 @@ export default function (pi: ExtensionAPI) {
         }
         const diagnosis = buildDoctorDiagnosis(model);
         const adapter = selectAdapterForModel(model);
-        const statsState = model ? cacheStatsByModel[modelKey(model)] : undefined;
-        const samples = model ? getRecentSamples(modelKey(model)) : [];
+        const sk = model ? sessionModelKey(model) : undefined;
+        const statsState = sk ? cacheStatsByModel[sk] : undefined;
+        const samples = sk ? getRecentSamples(sk) : [];
         const lowHitLines = buildLowHitDiagnosis(model, adapter, statsState, samples);
         const fullDiagnosis = lowHitLines.length > 0
           ? diagnosis + "\n" + lowHitLines.join("\n")
@@ -3688,9 +3963,9 @@ export default function (pi: ExtensionAPI) {
           return;
         }
         const adapter = selectAdapterForModel(model);
-        const key = model ? modelKey(model) : undefined;
-        const statsState = key ? cacheStatsByModel[key] : undefined;
-        const samples = model ? getRecentSamples(modelKey(model)) : [];
+        const sk = model ? sessionModelKey(model) : undefined;
+        const statsState = sk ? cacheStatsByModel[sk] : undefined;
+        const samples = sk ? getRecentSamples(sk) : [];
         const output = buildStatsOutput(model, adapter, statsState, samples);
         cmdCtx.ui.notify(output, "info");
       } else if (subcommand === "compat") {
@@ -3709,6 +3984,38 @@ export default function (pi: ExtensionAPI) {
             "info",
           );
         }
+      } else if (subcommand === "reset") {
+        if (!model) {
+          cmdCtx.ui.notify("No active model selected. Select a model first with /model or pi --model.", "warning");
+          return;
+        }
+        const adapter = selectAdapterForModel(model);
+        if (!adapter) {
+          cmdCtx.ui.notify("ℹ️ Active model does not match a cache adapter. No stats to reset.", "info");
+          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);
+
+        // Persist immediately.
+        await flushPersistCacheStats(cmdCtx as unknown as ExtensionContext);
+
+        // Update footer to show 0/0.
+        await publishStatus(cmdCtx as unknown as ExtensionContext, model);
+
+        cmdCtx.ui.notify(
+          `✅ Reset local session cache stats for "${displayKey}". ` +
+          "Upstream provider prompt cache was not modified. " +
+          "New requests will start a fresh stats bucket for this Pi session.",
+          "info",
+        );
       } else {
         // Try interactive selection menu when UI supports it
         if (cmdCtx.hasUI) {
@@ -3716,6 +4023,7 @@ export default function (pi: ExtensionAPI) {
             "🩺 Doctor — Show current model cache configuration",
             "📊 Stats — Show active model stats bucket and trend",
             "⚙️  Compat — Show compat suggestion with edit instructions",
+            "🔄 Reset — Reset local session stats for current model",
             "❌ Cancel",
           ];
           const choice = await cmdCtx.ui.select("Cache Optimizer", menuOptions);
@@ -3725,8 +4033,9 @@ export default function (pi: ExtensionAPI) {
             } else {
               const diagnosis = buildDoctorDiagnosis(model);
               const adapter = selectAdapterForModel(model);
-              const statsState = model ? cacheStatsByModel[modelKey(model)] : undefined;
-              const samples = model ? getRecentSamples(modelKey(model)) : [];
+              const sk = model ? sessionModelKey(model) : undefined;
+              const statsState = sk ? cacheStatsByModel[sk] : undefined;
+              const samples = sk ? getRecentSamples(sk) : [];
               const lowHitLines = buildLowHitDiagnosis(model, adapter, statsState, samples);
               const fullDiagnosis = lowHitLines.length > 0
                 ? diagnosis + "\n" + lowHitLines.join("\n")
@@ -3738,9 +4047,9 @@ export default function (pi: ExtensionAPI) {
               cmdCtx.ui.notify("No active model selected. Select a model first with /model or pi --model.", "warning");
             } else {
               const adapter = selectAdapterForModel(model);
-              const key = model ? modelKey(model) : undefined;
-              const statsState = key ? cacheStatsByModel[key] : undefined;
-              const samples = model ? getRecentSamples(modelKey(model)) : [];
+              const sk = model ? sessionModelKey(model) : undefined;
+              const statsState = sk ? cacheStatsByModel[sk] : undefined;
+              const samples = sk ? getRecentSamples(sk) : [];
               const output = buildStatsOutput(model, adapter, statsState, samples);
               cmdCtx.ui.notify(output, "info");
             }
@@ -3760,6 +4069,27 @@ export default function (pi: ExtensionAPI) {
                 );
               }
             }
+          } else if (choice === menuOptions[3]) {
+            if (!model) {
+              cmdCtx.ui.notify("No active model selected. Select a model first with /model or pi --model.", "warning");
+            } else {
+              const adapter = selectAdapterForModel(model);
+              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);
+                await flushPersistCacheStats(cmdCtx as unknown as ExtensionContext);
+                await publishStatus(cmdCtx as unknown as ExtensionContext, model);
+                cmdCtx.ui.notify(
+                  `✅ Reset local session cache stats for "${displayKey}". ` +
+                  "Upstream provider prompt cache was not modified.",
+                  "info",
+                );
+              }
+            }
           }
           // choice === "cancel" or undefined → no action
           return;
@@ -3771,16 +4101,18 @@ export default function (pi: ExtensionAPI) {
         diagnosis.push("  doctor  — Show current model/provider/api/baseUrl/compat and low-hit diagnosis");
         diagnosis.push("  stats   — Show active model stats bucket and recent trend");
         diagnosis.push("  compat  — Show compat suggestion with edit location");
+        diagnosis.push("  reset   — Reset local session stats for current model (does not affect upstream)");
         diagnosis.push("");
         if (model) {
+          const displayKey = modelKey(model);
           const missing = describeMissingOpenAICompatibleProxyCompat(model);
           if (missing.length > 0) {
-            diagnosis.push(`⚠️  Active model "${modelKey(model)}" missing compat: ${missing.join(", ")}`);
+            diagnosis.push(`⚠️  Active model "${displayKey}" missing compat: ${missing.join(", ")}`);
             diagnosis.push('Run "/cache-optimizer compat" for edit instructions.');
           } else if (isCompatCheckApplicable(model)) {
-            diagnosis.push(`✅ Active model "${modelKey(model)}": compat fully configured.`);
+            diagnosis.push(`✅ Active model "${displayKey}": compat fully configured.`);
           } else {
-            diagnosis.push(`ℹ️ Active model "${modelKey(model)}": compat check not applicable.`);
+            diagnosis.push(`ℹ️ Active model "${displayKey}": compat check not applicable.`);
           }
         } else {
           diagnosis.push("No active model selected.");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-cache-optimizer",
-  "version": "2.4.9",
+  "version": "2.5.1",
   "description": "Pi extension that improves provider-side KV/prompt cache hit rates (DeepSeek, OpenAI, Claude, Gemini) by reordering the system prompt, requesting long retention, and showing footer cache stats. Renamed from pi-deepseek-cache-optimizer.",
   "keywords": [
     "pi-package",