opencode-cache-hit 0.1.0 → 0.2.0

package/AGENTS.md

@@ -40,8 +40,9 @@ After moving or renaming exports: run full `bun test`; `tests/module-load.test.t
 ## Configuration
 
 - Example: [cache-hit.config.example.json](cache-hit.config.example.json) — **included in npm** `files`.
-- Runtime: `cache-hit.config.json` beside package root (`CONFIG_PATH` in `load-config.ts`); **not** published; gitignored.
+- Runtime: `~/.config/opencode/cache-hit.json` (preferred) or `cache-hit.config.json` beside package root (legacy fallback); **not** published; gitignored.
 - Defaults: [src/plugin-config.ts](src/plugin-config.ts).
+- Timeline log dir default: `~/.local/share/opencode/logs/cache-hit/`. Supports `~/` expansion in `timeline.dir`.
 
 ## npm publish
 

package/CONTRIBUTING.md

@@ -16,25 +16,41 @@ Coding agents: [AGENTS.md](AGENTS.md).
 
 After `bun install`, a **pre-push** hook runs `bun test` (skip with `git push --no-verify`). **CI** (GitHub Actions on `main` and PRs) runs the same tests on the server.
 
-## Configuration file (local)
+## Configuration file
 
-The plugin reads **`cache-hit.config.json`** from the package root (`PLUGIN_ROOT`, same directory as `index.tsx`). Code defaults apply if the file is missing.
+The plugin reads config from two locations (priority order):
+
+1. **XDG**: `~/.config/opencode/cache-hit.json` (preferred — persists across plugin updates)
+2. **Legacy**: `cache-hit.config.json` beside plugin root (backward compatible)
+
+The XDG path is recommended for npm global installs; the legacy path still works for local installs and existing setups.
 
 | File | In npm tarball? | Purpose |
 |------|-----------------|--------|
 | `cache-hit.config.example.json` | **Yes** | Template; copy and edit |
-| `cache-hit.config.json` | **No** | Your overrides (gitignored here) |
-| `logs/` | **No** | Timeline output when enabled |
+| `cache-hit.config.json` | **No** | Legacy plugin-root overrides |
+| `logs/` | **No** | Timeline output (default: `~/.local/share/opencode/logs/cache-hit/`) |
 
-After OpenCode installs the package (npm or cache):
+After installing:
 
 ```bash
-cd ~/.cache/opencode/packages/opencode-cache-hit@latest
-cp cache-hit.config.example.json cache-hit.config.json
+cp cache-hit.config.example.json ~/.config/opencode/cache-hit.json
 # edit, then restart OpenCode
 ```
 
-For a **local path** in `tui.json`, put `cache-hit.config.json` in that folder (e.g. `~/.config/opencode/plugins/opencode-cache-hit/`).
+For a **local path** plugin in `~/.config/opencode/plugins/opencode-cache-hit/`, placing `cache-hit.config.json` in that folder also works (matches the legacy fallback).
+
+## Versioning
+
+Follow [Semantic Versioning](https://semver.org/):
+
+| Change | Bump | Example |
+|--------|------|---------|
+| Bug fix (backward-compatible) | **patch** | `0.1.0` → `0.1.1` |
+| New feature (backward-compatible) | **minor** | `0.1.0` → `0.2.0` |
+| Breaking change | **major** | `0.2.0` → `1.0.0` |
+
+Default changes (rate, paths) accompanied by new features → minor. Pure bugfixes only → patch.
 
 ## Publishing to npm
 

package/README.md

@@ -19,7 +19,9 @@ Roadmap items (sidebar Timeline section, metric windows, nested sub-agents) are
 
 ## Acknowledgments
 
-This plugin is **not** part of opencode-visual-cache. Its sidebar layout, panel components (`src/tui-panel/`), and coexistence patterns are **heavily inspired by** [opencode-visual-cache](https://www.npmjs.com/package/opencode-visual-cache). visual-cache focuses on **main-session context / token distribution**; cache-hit focuses on **per-turn metrics and sub-agent totals**. We recommend installing both.
+This plugin is **not** part of opencode-visual-cache. Its sidebar layout, panel components (`src/tui-panel/`), and coexistence patterns are **heavily inspired by** [opencode-visual-cache](https://www.npmjs.com/package/opencode-visual-cache). visual-cache focuses on **main-session context / token distribution**; cache-hit focuses on **per-turn metrics and sub-agent totals**.
+
+The **cache TTL** feature (elapsed time display with color-coded status) is inspired by [opencode-cache-timer](https://github.com/nero-sensei/opencode-cache-timer) by nero-sensei. The original plugin provides a standalone sidebar countdown for prompt cache expiration; this plugin integrates the concept directly into the cache-hit panel.
 
 ## Screenshots
 
@@ -29,7 +31,7 @@ This plugin is **not** part of opencode-visual-cache. Its sidebar layout, panel
 
 - **Cache hit rate**: session total + **per-turn** rate with trend (↑ / ↓ / `-`) on the main block
 - **Token breakdown**: cache read / write / miss / output (aligned rows with visual-cache)
-- **Cost**: session cost with multi-currency config (`USD`, `CNY`, `EUR`, `GBP`, `JPY`)
+- **Cost**: session cost with multi-currency config (`USD`, `CNY`, `EUR`, `GBP`, `JPY`); per-million rates and cache savings from provider config
 - **Sub-agents**: **Agents** section rolls up **child sessions only** (scope labeled in UI)
 - **Main + Agents**: main block always shown; **Agents** section when sub-agents exist (foldable)
 - **Collapsible sections**: Detail / Model (and Agents); theme-adaptive hit bar colors
@@ -44,8 +46,8 @@ This plugin is **not** part of opencode-visual-cache. Its sidebar layout, panel
 |---|----------------|-------------------|
 | Main session context / token **distribution** estimate | Yes | No — use visual-cache |
 | Per-role token breakdown (system / tools / …) | Yes | No |
-| Cache **savings** estimate | Yes | No |
-| Model **per-million** pricing from provider | Yes | Model name + session cost only |
+| Cache **savings** estimate | Yes | Yes (from provider pricing) |
+| Model **per-million** pricing from provider | Yes | Yes (from SDK provider config) |
 | **Slash commands** (`/cache-lang`, `/cache-currency`, …) | Yes | Config file only |
 | Fold state in `api.kv` | Yes | In-session (not persisted) |
 | Loaded **skills** panel | Yes | No |
@@ -57,7 +59,9 @@ This plugin is **not** part of opencode-visual-cache. Its sidebar layout, panel
 
 ### Option A: OpenCode command palette (recommended)
 
-`Ctrl+P` → **install plugin** → `opencode-cache-hit@latest` (when published) or your local path.
+`Ctrl+P` → type **install plugin** → press `Tab` to switch scope to **global** (default is local) → type `opencode-cache-hit@latest` → press Enter.
+
+Global plugins install to `~/.cache/opencode/packages/opencode-cache-hit@latest/`. Create config at `~/.config/opencode/cache-hit.json`:
 
 ### Option B: Manual
 
@@ -146,11 +150,53 @@ Per assistant turn → JSONL. [docs/en/timeline.md](docs/en/timeline.md) · [中
 ```bash
 LOG=~/.config/opencode/plugins/opencode-cache-hit/logs/timeline-$(date +%Y-%m-%d).jsonl
 tail -f "$LOG"
+# time fields are ISO 8601 strings with local timezone (e.g. "2024-05-30T08:00:00.000+08:00")
 jq -r 'select(.rootSessionId=="YOUR_ROOT") | [.created,.scope,.hitPercent,.cost]|@tsv' "$LOG"
 ```
 
 Retention details: [Rotation and retention](docs/en/timeline.md#rotation-and-retention). Charts: [scripts/README.md](scripts/README.md).
 
+### Cache TTL (`cacheTTL`, default on)
+
+Shows how long the prompt cache has been alive. Color changes when exceeding TTL:
+
+- Green: elapsed < TTL
+- Yellow: TTL ≤ elapsed < 2×TTL
+- Red: elapsed ≥ 2×TTL
+
+```json
+"cacheTTL": {
+  "enabled": true,
+  "providers": {
+    "anthropic": "5m",
+    "openai": "5m",
+    "deepseek": "2h",
+    "google": "1h"
+  }
+}
+```
+
+| Field | Default | Meaning |
+|-------|---------|---------|
+| `enabled` | `true` | Master switch |
+| `providers` | `{}` | TTL per provider (or `provider:model`). Human-readable: `30s`, `5m`, `1.5h` |
+
+**Built-in defaults** (used when provider not in config):
+
+| Provider | Default TTL | Source |
+|----------|-------------|--------|
+| anthropic | 5 min | [Anthropic docs](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) |
+| openai | 5 min | [OpenAI docs](https://platform.openai.com/docs/guides/prompt-caching) |
+| deepseek | 2 hours | [DeepSeek docs](https://api-docs.deepseek.com/guides/kv_cache) |
+| google | 1 hour | [Google docs](https://ai.google.dev/api/caching) |
+| xai | 5 min | [xAI docs](https://docs.x.ai/developers/advanced-api-usage/prompt-caching) |
+| minimax | 5 min | [MiniMax docs](https://platform.minimax.io/docs/api-reference/text-prompt-caching) |
+| xiaomi | 5 min | Implicit caching |
+| qwen | 5 min | Implicit caching |
+| moonshot | 5 min | Implicit caching |
+
+**Default TTL**: 5 minutes for all providers not listed above. Color changes based on elapsed time vs TTL: green (< TTL), yellow (TTL-2x TTL), red (≥ 2x TTL).
+
 ## Updating
 
 OpenCode may [cache plugins at first install](https://github.com/anomalyco/opencode/issues/6774) and not auto-refresh npm versions.

package/README.zh-CN.md

@@ -24,7 +24,7 @@ OpenCode **TUI 侧边栏插件**：展示 prompt cache 命中率、token 用量
 - visual-cache：主 session **上下文 / token 分布预估**
 - cache-hit：**按轮次指标、成本、子 agent 汇总**
 
-建议两个插件一起安装。
+**缓存存活时间**功能（显示已存活时间 + 颜色状态）借鉴自 [opencode-cache-timer](https://github.com/nero-sensei/opencode-cache-timer)（作者：nero-sensei）。原插件提供独立的侧边栏倒计时；本插件将该概念直接集成到缓存命中面板中。
 
 ## 截图
 
@@ -46,7 +46,7 @@ OpenCode **TUI 侧边栏插件**：展示 prompt cache 命中率、token 用量
 
 - **命中率**：会话累计 + 主块**单轮**命中率与趋势
 - **Token 明细**：缓存读/写/未命中/输出
-- **费用**：多币种配置（`USD` / `CNY` / `EUR` / `GBP` / `JPY`）
+- **费用**：多币种配置（`USD` / `CNY` / `EUR` / `GBP` / `JPY`）；从 provider 配置读取百万 token 单价及缓存节省
 - **子 agent**：**Agents** 段仅汇总**子 session**（UI 有范围提示）
 - **主 session + Agents**：主块始终显示；有子 agent 时出现可折叠的 **Agents** 段
 - **可选时间轴**：按天 JSONL 落盘
@@ -58,7 +58,8 @@ OpenCode **TUI 侧边栏插件**：展示 prompt cache 命中率、token 用量
 | | visual-cache | cache-hit |
 |---|----------------|-----------|
 | 主 session 上下文 / Token **分布**估算 | 有 | 无 |
-| 按角色 Token 分布、缓存**节省**、百万 token **单价** | 有 | 无 |
+| 按角色 Token 分布 | 有 | 无 |
+| 缓存**节省**、百万 token **单价** | 有 | 有（读 provider 配置） |
 | **斜杠命令**改配置 | 有 | 仅配置文件 |
 | **子 agent** 汇总 | 无 | **有** |
 | 按次 **JSONL** | 无 | 可选 |
@@ -80,7 +81,9 @@ OpenCode **TUI 侧边栏插件**：展示 prompt cache 命中率、token 用量
 
 ## 安装
 
-**方式一：** `Ctrl+P` → install plugin → `opencode-cache-hit@latest`（发布后）或本地路径。
+**方式一：** `Ctrl+P` → 输入 **install plugin** → 按 `Tab` 将范围切换为 **global**（默认是 local）→ 输入 `opencode-cache-hit@latest` → 回车。
+
+全局插件安装到 `~/.cache/opencode/packages/opencode-cache-hit@latest/`。在 `~/.config/opencode/cache-hit.json` 创建配置：
 
 **方式二：** 编辑 `~/.config/opencode/tui.json` / `tui.jsonc`：
 
@@ -153,6 +156,7 @@ OpenCode **TUI 侧边栏插件**：展示 prompt cache 命中率、token 用量
 ```fish
 set log ~/.config/opencode/plugins/opencode-cache-hit/logs/timeline-(date +%Y-%m-%d).jsonl
 tail -f $log
+# 时间字段为 ISO 8601 含本地时区（如 "2024-05-30T08:00:00.000+08:00"）
 jq -r 'select(.rootSessionId=="YOUR_ROOT") | [.created,.scope,.hitPercent,.cost]|@tsv' $log
 ```
 

package/cache-hit.config.example.json

@@ -2,14 +2,14 @@
   "$comment": "lang: en | zh | auto (system locale). Default en.",
   "currency": "CNY",
   "costUnit": "USD",
-  "rate": 7.2,
+  "rate": 6.77,
   "display": {
     "lang": "en",
     "panelBorder": true
   },
   "timeline": {
     "enabled": false,
-    "dir": "",
+    "dir": "~/.local/share/opencode/logs/cache-hit",
     "flushIncomplete": false,
     "logSummaryMessages": true,
     "maxMemoryRows": 50,
@@ -18,5 +18,10 @@
     "retainRotated": 5,
     "maxAgeDays": 30,
     "maxLogFiles": 20
+  },
+  "cacheTTL": {
+    "enabled": true,
+    "providers": {
+    }
   }
 }

package/docs/en/design.md

@@ -43,8 +43,8 @@ flowchart TB
 ## Cost model
 
 - OpenCode: `msg.cost` accumulates assistant messages using **USD** list prices from `opencode.json`.
-- Plugin: `createCostFormatter(loadPluginConfig().cost)`; default `costUnit: USD` → `currency: CNY`, `rate: 7.2`.
-- Config file: `cache-hit.config.json` at plugin root (`load-config.ts`); defaults in `plugin-config.ts`.
+- Plugin: `createCostFormatter(loadPluginConfig().cost)`; default `costUnit: USD` → `currency: CNY`, `rate: 6.77`.
+- Config file: `~/.config/opencode/cache-hit.json` (preferred) or `cache-hit.config.json` at plugin root (legacy). Defaults in `plugin-config.ts`.
 
 ## Runtime architecture
 
@@ -184,9 +184,13 @@ Sum input and cache.read over assistant messages
 - `computePerCallHitTrend`: one rate per assistant turn; skip `summary: true`.
 - Display the **last** non-summary turn; compare to previous for ↑ / ↓ / `-`.
 
-**Combined Hit**
+**Pricing & Saved**
 
-- Shown only when main block is visible, sub-agents exist, and combined vs session total differs by ≥ 0.05%.
+- Provider pricing is read from `api.state.provider` (SDK runtime data, not hardcoded).
+- `computePricing` looks up per-million rates by `providerID` + `modelID`; computes `saved = (inputRate - cacheReadRate) * cacheRead / 1M`.
+- Main session: **Saved** row in Detail section; per-million rates (`/M in`, `/M cache`, `/M out`) in Model section.
+- Agents section: **Saved** row sums savings across all child sessions (`computeSubsSaved`).
+- All pricing rows hidden when rates are unavailable or saved is zero.
 
 ## Time fields (OpenCode SDK v2)
 

package/docs/en/timeline.md

@@ -36,14 +36,14 @@ flowchart LR
 ```typescript
 export type LlmCallRecord = {
   schema: 1
-  recordedAt: number       // local write time (ms)
+  recordedAt: string       // ISO 8601 with local timezone offset
   sessionId: string
   rootSessionId: string    // main session; differs for child scope
   scope: "main" | "child"
   messageKey: string
   modelId: string
-  created: number
-  completedAt?: number
+  created: string
+  completedAt?: string
   durationMs?: number
   isComplete: boolean
   input: number
@@ -81,14 +81,14 @@ Module: `src/timeline/records.ts` — `buildCallRecords(sessionId, rootSessionId
 **Default layout**
 
 ```
-~/.config/opencode/plugins/opencode-cache-hit/logs/
+~/.local/share/opencode/logs/cache-hit/
   timeline-2026-05-31.jsonl       # one active file per local calendar day
   timeline-2026-05-31.jsonl.1     # size rotation backup for that day
 ```
 
 All main and child sessions for a day share one file; filter by `rootSessionId` / `sessionId` / `scope`. A new date gets a new filename at midnight.
 
-Optional `dir` (e.g. `~/.local/share/opencode/cache-hit/logs/`).
+Optional `dir` (e.g. `~/my-logs/`). Supports `~/` expansion to home directory.
 
 **Legacy**: older builds used `<rootSessionId>.jsonl` per main session; not migrated automatically.
 
@@ -116,7 +116,7 @@ Example values above; code defaults below (`enabled: false`, rotation `0` except
 | Field | Code default | Description |
 |-------|--------------|-------------|
 | `enabled` | `false` | No IO when off |
-| `dir` | `""` | Empty → plugin `logs/` |
+| `dir` | `""` | Empty → `~/.local/share/opencode/logs/cache-hit` |
 | `flushIncomplete` | `false` | Write only completed turns |
 | `logSummaryMessages` | `true` | Include summary rows (flagged) |
 | `maxMemoryRows` | `50` | In-memory rows for future UI |
@@ -200,8 +200,9 @@ sequenceDiagram
 ### Phase 1 — disk only (current)
 
 ```bash
-LOG=~/.config/opencode/plugins/opencode-cache-hit/logs/timeline-$(date +%Y-%m-%d).jsonl
+LOG=~/.local/share/opencode/logs/cache-hit/timeline-$(date +%Y-%m-%d).jsonl
 tail -f "$LOG"
+# time fields are ISO 8601 strings with local timezone (e.g. "2024-05-30T08:00:00.000+08:00")
 jq -r 'select(.rootSessionId=="YOUR_ROOT") | [.created,.scope,.hitPercent,.cost]|@tsv' "$LOG"
 ```
 
@@ -249,5 +250,5 @@ bun scripts/plot-hit-rate.ts "$LOG" --by-root -o /tmp/hit-multi.svg
 ## Example line
 
 ```json
-{"schema":1,"recordedAt":1717000000000,"sessionId":"sess_main","rootSessionId":"sess_main","scope":"main","messageKey":"sess_main:1716999990000:deepseek/v4","modelId":"deepseek/v4","created":1716999990000,"completedAt":1717000000000,"durationMs":10000,"isComplete":true,"input":1200,"output":80,"reasoning":0,"cacheRead":38000,"cacheWrite":0,"cost":0.012,"hitPercent":96.9,"skippedForHit":false}
+{"schema":1,"recordedAt":"2024-05-30T08:00:00.000+08:00","sessionId":"sess_main","rootSessionId":"sess_main","scope":"main","messageKey":"sess_main:1716999990000:deepseek/v4","modelId":"deepseek/v4","created":"2024-05-30T07:59:50.000+08:00","completedAt":"2024-05-30T08:00:00.000+08:00","durationMs":10000,"isComplete":true,"input":1200,"output":80,"reasoning":0,"cacheRead":38000,"cacheWrite":0,"cost":0.012,"hitPercent":96.9,"skippedForHit":false}
 ```

package/docs/zh-CN/design.md

@@ -43,8 +43,8 @@ flowchart TB
 ## 成本模型
 
 - OpenCode：`msg.cost` = 按 `opencode.json` 中**美元**单价对 assistant 消息累加。
-- 插件：`createCostFormatter(loadPluginConfig().cost)`；默认 `costUnit: USD` → `currency: CNY`，`rate: 7.2`。
-- 配置路径：插件根目录 `cache-hit.config.json`（`load-config.ts`）；缺省见 `plugin-config.ts` 的 `DEFAULT_PLUGIN_CONFIG`。
+- 插件：`createCostFormatter(loadPluginConfig().cost)`；默认 `costUnit: USD` → `currency: CNY`，`rate: 6.77`。
+- 配置路径：优先 `~/.config/opencode/cache-hit.json`，兜底插件根目录 `cache-hit.config.json`。缺省见 `plugin-config.ts` 的 `DEFAULT_PLUGIN_CONFIG`。
 
 ## 运行时架构
 
@@ -185,9 +185,13 @@ flowchart TD
 - `computePerCallHitTrend(messages)`：每条 assistant 一轮命中率；`summary: true` 跳过。
 - 展示**最后一条**非 summary 轮的命中率；与前一条比较得趋势（↑ / ↓ / `-`）。
 
-**Combined Hit**
+**单价与节省（Pricing & Saved）**
 
-- 存在子 agent 且与会话累计命中率差异 ≥ 0.05% 时显示（主+子合并口径）。
+- Provider 单价从 `api.state.provider`（SDK 运行时数据）读取，非硬编码。
+- `computePricing` 根据 `providerID` + `modelID` 查找百万 token 单价；计算 `saved = (inputRate - cacheReadRate) * cacheRead / 1M`。
+- 主 session：Detail 段展示 **Saved** 行；Model 段展示百万 token 单价（`/M 输入`、`/M 缓存`、`/M 输出`）。
+- Agents 段：**Saved** 行汇总所有子 session 的节省金额（`computeSubsSaved`）。
+- 单价不可用或节省为零时，所有 pricing 行隐藏。
 
 ## 时间字段（OpenCode SDK v2）
 

package/docs/zh-CN/timeline.md

@@ -37,8 +37,8 @@ flowchart LR
 /** 单条记录；JSONL 一行一个 */
 export type LlmCallRecord = {
   schema: 1
-  /** 写入时间（本机 ms），非 LLM 时间 */
-  recordedAt: number
+  /** 写入时间（ISO 8601，含时区），非 LLM 时间 */
+  recordedAt: string
   /** 所属 session */
   sessionId: string
   /** 主 session id；子 session 时与 sessionId 不同 */
@@ -47,8 +47,8 @@ export type LlmCallRecord = {
   /** OpenCode message id；SDK 若无则用稳定合成键，见下文 */
   messageKey: string
   modelId: string
-  created: number
-  completedAt?: number
+  created: string
+  completedAt?: string
   durationMs?: number
   isComplete: boolean
   input: number
@@ -101,14 +101,14 @@ export function buildCallRecords(
 **默认路径（可配置）**
 
 ```
-~/.config/opencode/plugins/opencode-cache-hit/logs/
+~/.local/share/opencode/logs/cache-hit/
   timeline-2026-05-31.jsonl       # 按本地日历日一个活跃文件
   timeline-2026-05-31.jsonl.1     # 当日超过 rotateMaxBytes 时链式备份
 ```
 
 所有主/子 session 的调用写入**同一天**的同一文件；用行内 `rootSessionId` / `sessionId` / `scope` 筛某场对话。跨日自动切到新文件名。
 
-`dir` 非空时可改到例如 `~/.local/share/opencode/cache-hit/logs/`。
+`dir` 非空时可改到例如 `~/my-logs/`，支持 `~/` 展开为 home 目录。
 
 推荐 **JSONL** 第一期：实现简单、`tail -f` / `jq` 友好；SQLite 留给第二期索引查询。
 
@@ -138,7 +138,7 @@ export function buildCallRecords(
 | 字段 | 代码默认 | 说明 |
 |------|----------|------|
 | `enabled` | `false` | 关闭时零 IO，不影响侧栏 |
-| `dir` | `""` | 空则用插件目录下 `logs/` |
+| `dir` | `""` | 空则用 `~/.local/share/opencode/logs/cache-hit` |
 | `flushIncomplete` | `false` | 是否在未完成时写 JSONL |
 | `logSummaryMessages` | `true` | 是否记录 summary 行 |
 | `maxMemoryRows` | `50` | TUI 内存中保留条数（全量仍可从文件读） |
@@ -228,8 +228,9 @@ sequenceDiagram
 - 文档示例：
 
 ```bash
-LOG=~/.config/opencode/plugins/opencode-cache-hit/logs/timeline-$(date +%Y-%m-%d).jsonl
+LOG=~/.local/share/opencode/logs/cache-hit/timeline-$(date +%Y-%m-%d).jsonl
 tail -f $LOG
+# 时间字段为 ISO 8601 含本地时区（如 "2024-05-30T08:00:00.000+08:00"）
 jq -r 'select(.rootSessionId=="YOUR_ROOT") | [.created,.scope,.hitPercent,.cost]|@tsv' $LOG
 ```
 
@@ -293,7 +294,7 @@ bun scripts/plot-hit-rate.ts $LOG --by-root -o /tmp/hit-multi.svg
 ## 示例 JSONL 行
 
 ```json
-{"schema":1,"recordedAt":1717000000000,"sessionId":"sess_main","rootSessionId":"sess_main","scope":"main","messageKey":"sess_main:1716999990000:deepseek/v4","modelId":"deepseek/v4","created":1716999990000,"completedAt":1717000000000,"durationMs":10000,"isComplete":true,"input":1200,"output":80,"reasoning":0,"cacheRead":38000,"cacheWrite":0,"cost":0.012,"hitPercent":96.9,"skippedForHit":false}
+{"schema":1,"recordedAt":"2024-05-30T08:00:00.000+08:00","sessionId":"sess_main","rootSessionId":"sess_main","scope":"main","messageKey":"sess_main:1716999990000:deepseek/v4","modelId":"deepseek/v4","created":"2024-05-30T07:59:50.000+08:00","completedAt":"2024-05-30T08:00:00.000+08:00","durationMs":10000,"isComplete":true,"input":1200,"output":80,"reasoning":0,"cacheRead":38000,"cacheWrite":0,"cost":0.012,"hitPercent":96.9,"skippedForHit":false}
 ```
 
 ---

package/package.json

@@ -1,10 +1,9 @@
 {
   "name": "opencode-cache-hit",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "OpenCode TUI sidebar: prompt cache hit rate, tokens & cost with sub-agent rollup. Works with opencode-visual-cache; optional per-call JSONL timeline.",
   "type": "module",
   "license": "MIT",
-  "author": "zhumengzhu <mengzhu.loveyou@gmail.com>",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/zhumengzhu/opencode-cache-hit.git"

package/scripts/README.md

@@ -14,7 +14,7 @@ python3 -c "import json,sys; r=[json.loads(x) for x in open(sys.argv[1]) if x.st
 bun -e "const t=await Bun.file(process.argv[1]).text();const rows=t.trim().split('\n').filter(Boolean).map(l=>JSON.parse(l));const h=rows.map(r=>r.hitPercent).filter((p):p is number=>p!=null);console.log(rows.length+' calls, avg hit '+(h.reduce((a,b)=>a+b,0)/h.length).toFixed(1)+'%')" logs/timeline-2026-05-31.jsonl
 ```
 
-Export TSV for spreadsheets:
+Export TSV for spreadsheets (time fields are ISO 8601 strings):
 
 ```bash
 jq -r 'select(.hitPercent!=null) | [.completedAt,.scope,.hitPercent,.cost]|@tsv' logs/timeline-2026-05-31.jsonl

package/scripts/plot-hit-rate.ts

@@ -10,8 +10,8 @@
 type Row = {
   rootSessionId?: string
   scope?: string
-  created?: number
-  completedAt?: number
+  created?: string
+  completedAt?: string
   hitPercent?: number | null
   skippedForHit?: boolean
 }
@@ -57,7 +57,8 @@ async function loadRecords(path: string, root?: string): Promise<Row[]> {
 }
 
 function timeOf(r: Row): number {
-  return r.completedAt ?? r.created ?? 0
+  const ts = r.completedAt ?? r.created
+  return ts ? new Date(ts).getTime() : 0
 }
 
 function groupByRoot(rows: Row[]): Map<string, Row[]> {

package/src/agents-view.tsx

@@ -3,9 +3,10 @@ import { For, Show } from "solid-js"
 import { TokenDetailRows } from "./cache-hit-rows.tsx"
 import type { CacheHitMetrics } from "./use-cache-hit-metrics.ts"
 import { aggregateSubAgents } from "./stats.ts"
+import { computeSubsSaved } from "./pricing.ts"
 import { formatTokenCount } from "./format-tokens.ts"
 import { TuiMetricRow, truncateVisual, type PanelLayout } from "./tui-panel/index.ts"
-import type { SubAgentSummary } from "./types.ts"
+import type { ProviderInfo, SubAgentSummary } from "./types.ts"
 
 function agentRowLabel(id: string, gauge: number): string {
   const tail = id.length > 10 ? id.slice(-8) : id
@@ -20,14 +21,27 @@ function subHasActivity(sub: SubAgentSummary): boolean {
 export function AgentsView(props: {
   m: CacheHitMetrics
   layout: PanelLayout
+  providers: ReadonlyArray<ProviderInfo>
   formatCost: (n: number) => string
 }) {
   const { m, layout } = props
   const total = () => aggregateSubAgents(m.subs())
 
+  const subsSaved = () => computeSubsSaved(m.subs(), props.providers)
+
   return (
     <>
-      <TokenDetailRows pal={m.pal()} layout={layout} t={m.t()} snap={total()} />
+      <TokenDetailRows pal={m.pal()} layout={layout} t={m.t()} snap={total()}>
+        <Show when={subsSaved() > 0}>
+          <TuiMetricRow
+            pal={m.pal()}
+            layout={layout}
+            label={m.t().saved}
+            value={props.formatCost(subsSaved())}
+            fg={m.pal().success}
+          />
+        </Show>
+      </TokenDetailRows>
       <Show when={total().cost > 0}>
         <TuiMetricRow
           pal={m.pal()}

package/src/cache-ttl-view.tsx

@@ -0,0 +1,133 @@
+/**
+ * Cache TTL elapsed time display.
+ * Inspired by opencode-cache-timer (https://github.com/nero-sensei/opencode-cache-timer)
+ * by nero-sensei.
+ */
+/** @jsxImportSource @opentui/solid */
+import { createMemo, createSignal, onCleanup, Show, type Accessor } from "solid-js"
+import type { AssistantMessage } from "./types.ts"
+import type { CacheTTLConfig } from "./plugin-config.ts"
+import { parseDuration } from "./plugin-config.ts"
+import type { PanelPalette, PanelLayout } from "./tui-panel/index.ts"
+import { TuiMetricRow } from "./tui-panel/index.ts"
+
+const SECOND = 1000
+const MINUTE = 60 * SECOND
+const HOUR = 60 * MINUTE
+
+const DEFAULT_TTL_MS = 5 * MINUTE
+
+const BUILT_IN_TTL: Record<string, number> = {
+  anthropic: 5 * MINUTE,
+  openai: 5 * MINUTE,
+  deepseek: 2 * HOUR,
+  google: 1 * HOUR,
+  xai: 5 * MINUTE,
+  minimax: 5 * MINUTE,
+  xiaomi: 5 * MINUTE,
+  qwen: 5 * MINUTE,
+  moonshot: 5 * MINUTE,
+}
+
+function findLastCacheActivity(messages: Accessor<AssistantMessage[]>): AssistantMessage | null {
+  const msgs = messages()
+  for (let i = msgs.length - 1; i >= 0; i--) {
+    const m = msgs[i]
+    if (
+      m.role === "assistant" &&
+      m.time?.completed !== undefined &&
+      ((m.tokens?.cache?.read ?? 0) > 0 || (m.tokens?.cache?.write ?? 0) > 0)
+    ) {
+      return m
+    }
+  }
+  return null
+}
+
+function getTTL(
+  providerID: string,
+  modelID: string,
+  config: CacheTTLConfig,
+): number {
+  const userProviders = config.providers
+  const specific = userProviders[`${providerID}:${modelID}`]
+  if (specific !== undefined) {
+    const parsed = parseDuration(specific)
+    if (parsed !== null) return parsed
+  }
+  const userProvider = userProviders[providerID]
+  if (userProvider !== undefined) {
+    const parsed = parseDuration(userProvider)
+    if (parsed !== null) return parsed
+  }
+  const builtIn = BUILT_IN_TTL[providerID]
+  if (builtIn !== undefined) return builtIn
+  return DEFAULT_TTL_MS
+}
+
+function formatElapsed(ms: number): string {
+  if (ms <= 0) return "0s"
+  const totalSeconds = Math.floor(ms / 1000)
+  const hours = Math.floor(totalSeconds / 3600)
+  const minutes = Math.floor((totalSeconds % 3600) / 60)
+  const seconds = totalSeconds % 60
+  if (hours > 0) return `${hours}h ${minutes}m`
+  if (minutes > 0) return `${minutes}m ${seconds}s`
+  return `${seconds}s`
+}
+
+export function CacheTTLView(props: {
+  messages: Accessor<AssistantMessage[]>
+  config: CacheTTLConfig
+  pal: PanelPalette
+  layout: PanelLayout
+  label: string
+}) {
+  const [now, setNow] = createSignal(Date.now())
+  const tick = setInterval(() => setNow(Date.now()), 1000)
+  onCleanup(() => clearInterval(tick))
+
+  const lastCache = createMemo(() => findLastCacheActivity(props.messages))
+
+  const ttlMs = createMemo(() => {
+    const m = lastCache()
+    if (!m || !m.providerID) return DEFAULT_TTL_MS
+    return getTTL(m.providerID, m.modelID ?? "", props.config)
+  })
+
+  const elapsed = createMemo(() => {
+    const m = lastCache()
+    if (!m || m.time.completed === undefined) return null
+    return now() - m.time.completed
+  })
+
+  const statusIcon = createMemo(() => {
+    const e = elapsed()
+    const ttl = ttlMs()
+    if (e === null) return ""
+    if (e < ttl) return "●"
+    if (e < ttl * 2) return "◐"
+    return "○"
+  })
+
+  const statusColor = createMemo(() => {
+    const e = elapsed()
+    const ttl = ttlMs()
+    if (e === null) return props.pal.textMuted
+    if (e < ttl) return props.pal.success
+    if (e < ttl * 2) return props.pal.warning
+    return props.pal.error
+  })
+
+  return (
+    <Show when={elapsed() !== null}>
+      <TuiMetricRow
+        pal={props.pal}
+        layout={props.layout}
+        label={props.label}
+        value={`${statusIcon()} ${formatElapsed(elapsed()!)}`}
+        fg={statusColor()}
+      />
+    </Show>
+  )
+}