@chenlongapps/opencode-token-usage 0.4.15 → 0.4.16

package/README.md

@@ -1,6 +1,6 @@
 <h1 align="center">opencode-token-usage</h1>
 
-<p align="center">A session-tree token usage monitor for OpenCode 2.</p>
+<p align="center">Token usage, context window, estimated cost and live performance for OpenCode 2.</p>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/@chenlongapps/opencode-token-usage" target="_blank" rel="noopener noreferrer"><img alt="npm" src="https://img.shields.io/npm/v/%40chenlongapps%2Fopencode-token-usage?style=flat-square&logo=npm" /></a>
@@ -15,30 +15,61 @@
   <a href="https://github.com/chenlongapps/opencode-token-usage/blob/main/README.zh-CN.md">简体中文</a>
 </p>
 
+### Overview
+
+**opencode-token-usage** is a community plugin that brings token usage, context window occupancy, estimated cost and performance metrics into OpenCode 2's terminal interface.
+
+Use it to see how many tokens a session and its subagents consume, how full the current context window is, and how estimated costs are distributed across models—without leaving your conversation.
+
+### Features
+
+- **Session-tree totals:** Track input, output, reasoning and cache tokens across the session tree, including unopened subagents, without double-counting inherited fork history.
+- **Context visibility:** See the viewed session's context usage, latest reported request and estimated prompt composition.
+- **Estimated cost by model:** Price recorded calls using their actual models, with a built-in first-party price snapshot as a fallback. Estimates are not provider bills.
+- **Performance at a glance:** Monitor tokens per second (TPS), time to first token (TTFT) and the viewed session's own elapsed response time. Live TPS and elapsed-time estimates are marked with `~`.
+- **Native terminal UI:** Keep a sidebar panel in the main session and a single-line summary in subagent views; open details only when needed.
+- **On-demand details:** Use `/usage` for compact or detailed statistics, including per-model usage and rates, without sending a prompt to the model.
+
 [![OpenCode Token Usage plugin preview](https://raw.githubusercontent.com/chenlongapps/opencode-token-usage/main/docs/assets/opencode-token-usage-preview.webp)](https://www.npmjs.com/package/@chenlongapps/opencode-token-usage)
 
 ---
 
 ### Installation
 
+Requires **OpenCode 2** and **Node.js 22+**. See [Compatibility](#compatibility) for verified host versions and the OpenTUI engine caveat.
+
 ```bash
 opencode plugin add @chenlongapps/opencode-token-usage
 ```
 
-Alternatively, add the package to your project's `opencode.json` or `opencode.jsonc`:
+Restart OpenCode after installation.
+
+### Quick start
+
+1. **View usage:** Open a session. The **Token Usage** panel appears in the native sidebar when `session.sidebar` is set to `auto` and the terminal is wide enough.
+2. **Explore details:** Enter `/usage` or left-click the panel's **Token Usage** title. Press `d` to toggle compact/detailed mode and Escape to close. Opening details does not send a prompt to the model.
+3. **Inspect subagents:** In subagent views, click the live summary above the composer to open the full panel. Closing it does not interrupt the subagent.
+
+For exact definitions and edge cases, see [Detailed usage](#detailed-usage), [Metrics](#metrics) and [price sources and limitations](docs/pricing.md).
+
+Questions about setup, costs, subagents, reasoning speed or privacy? See the [FAQ](docs/faq.md).
+
+### Other installation options
+
+Instead of the command above, add the package to your project's `opencode.json` or `opencode.jsonc`:
 
 ```json
 {
+  "$schema": "https://opencode.ai/config.json",
   "plugins": ["@chenlongapps/opencode-token-usage"]
 }
 ```
 
-> [!NOTE]
-> Requires Node.js 22+ (see the OpenTUI engine note under [Development](#development)). OpenCode 2.0.9 and 2.0.10 have been verified in earlier releases. SDK 2.0.24 integration checks have passed on OpenCode 2.0.11, 2.0.22, 2.0.24, 2.0.26, and 2.0.28. Native turn durations and sidebar title clicks were integration-tested on 2.0.26 and 2.0.28; the other listed host checks predate these additions.
+For remote sessions, add the package name to `plugins` in your local `~/.config/opencode/cli.json` to load only the terminal entry point. The configuration path follows `XDG_CONFIG_HOME`.
 
-Restart OpenCode after installation. The panel appears in the native sidebar when `session.sidebar` is set to `auto` and the terminal is wide enough. Click its **Token Usage** title to open the detailed usage dialog. OpenCode hides the sidebar in subagent views, so the plugin keeps one live summary line above the composer with Context, Total, Cost, Time, and TPS. Click the line to open the full statistics in a centered dialog. Press Escape or click **esc** to close it; closing the dialog does not interrupt the subagent.
+### Compatibility
 
-For remote sessions, add the package name to `plugins` in your local `~/.config/opencode/cli.json` to load only the terminal entry point. The configuration path follows `XDG_CONFIG_HOME`.
+Requires Node.js 22+ (see the OpenTUI engine note under [Development](#development)). OpenCode 2.0.9 and 2.0.10 have been verified in earlier releases. SDK 2.0.24 integration checks have passed on OpenCode 2.0.11, 2.0.22, 2.0.24, 2.0.26, and 2.0.28. Native turn durations and sidebar title clicks were integration-tested on 2.0.26 and 2.0.28; the other listed host checks predate these additions. See the [verification record](docs/verification.md) for tested combinations.
 
 ### Detailed usage
 
@@ -136,6 +167,7 @@ To load the plugin from source, build the project and add the repository's absol
 
 ### Documentation
 
+- [FAQ](docs/faq.md) · [简体中文](docs/faq.zh-CN.md)
 - [Roadmap](ROADMAP.md)
 - [Verification record](docs/verification.md)
 - [Release guide](docs/releasing.md)

package/README.zh-CN.md

@@ -1,6 +1,6 @@
 <h1 align="center">opencode-token-usage</h1>
 
-<p align="center">面向 OpenCode 2 的会话树 token 用量监视器。</p>
+<p align="center">在 OpenCode 2 中查看 token 用量、上下文窗口、估算费用与实时性能。</p>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/@chenlongapps/opencode-token-usage" target="_blank" rel="noopener noreferrer"><img alt="npm" src="https://img.shields.io/npm/v/%40chenlongapps%2Fopencode-token-usage?style=flat-square&logo=npm" /></a>
@@ -15,30 +15,61 @@
   <strong>简体中文</strong>
 </p>
 
+### 项目简介
+
+**opencode-token-usage** 是一个面向 OpenCode 2 的社区插件，在终端界面中展示 token 用量、上下文窗口占用、估算费用和性能指标。
+
+无需离开当前对话，就能了解：当前会话及其子代理消耗了多少 token、上下文窗口还剩多少空间，以及各模型的估算费用分布。
+
+### 主要特点
+
+- **会话树用量汇总：** 统计整棵会话树的输入、输出、推理和缓存 token，包含未打开的子代理，避免重复计算分叉继承历史。
+- **上下文可见：** 查看当前会话的上下文占用、最近一次已上报请求及提示词构成估算。
+- **按模型估算费用：** 按每次调用实际使用的模型计价，以内置原厂价格快照作为回退。估算费用不等于提供商账单。
+- **性能一目了然：** 查看每秒 token 数（TPS）、首 token 时间（TTFT）及当前会话自身的对话耗时。实时 TPS 与已耗时估算以 `~` 标记。
+- **原生终端界面：** 主会话使用侧边栏，子代理视图保留单行摘要，按需打开完整面板。
+- **按需查看详情：** 通过 `/usage` 切换紧凑／详细统计，查看各模型的用量与费率，不向模型发送提示词。
+
 [![OpenCode Token Usage 插件预览](https://raw.githubusercontent.com/chenlongapps/opencode-token-usage/main/docs/assets/opencode-token-usage-preview.webp)](https://www.npmjs.com/package/@chenlongapps/opencode-token-usage)
 
 ---
 
 ### 安装
 
+需要 **OpenCode 2** 和 **Node.js 22+**。已验证宿主版本及 OpenTUI 引擎限制见[兼容性](#兼容性)。
+
 ```bash
 opencode plugin add @chenlongapps/opencode-token-usage
 ```
 
-也可以在项目的 `opencode.json` 或 `opencode.jsonc` 中配置：
+安装后重启 OpenCode。
+
+### 快速上手
+
+1. **查看用量：** 打开会话。终端足够宽且 `session.sidebar` 设为 `auto` 时，原生侧边栏会显示 **Token Usage** 面板。
+2. **展开详情：** 输入 `/usage`，或左键点击面板的 **Token Usage** 标题。按 `d` 切换紧凑／详细模式，按 Escape 关闭；打开详情不会向模型发送提示词。
+3. **查看子代理：** 在子代理视图中，点击输入区上方的实时摘要可打开完整面板，关闭面板不会中断子代理。
+
+精确统计口径及边界情况见[详细用量](#详细用量)、[指标](#指标)和[价格来源与限制](docs/pricing.md)。
+
+关于安装、费用、子代理、推理速度及隐私的常见问题，见 [FAQ](docs/faq.zh-CN.md)。
+
+### 其他安装方式
+
+除了上述命令，也可以在项目的 `opencode.json` 或 `opencode.jsonc` 中配置：
 
 ```json
 {
+  "$schema": "https://opencode.ai/config.json",
   "plugins": ["@chenlongapps/opencode-token-usage"]
 }
 ```
 
-> [!NOTE]
-> 需要 Node.js 22+（见[开发](#开发)中的 OpenTUI 引擎说明）。此前发布已验证 OpenCode 2.0.9 和 2.0.10；SDK 2.0.24 集成检查已在 OpenCode 2.0.11、2.0.22、2.0.24、2.0.26 和 2.0.28 上通过。原生对话耗时与侧边栏标题点击的集成验证使用 2.0.26 和 2.0.28，其余列出的宿主检查早于这些功能加入。
+连接远程服务器时，可将包名加入本机 `~/.config/opencode/cli.json` 的 `plugins`，仅加载终端入口；配置路径遵循 `XDG_CONFIG_HOME`。
 
-安装后重启 OpenCode。终端足够宽且 `session.sidebar` 设为 `auto` 时，面板会显示在原生侧边栏中。点击面板的 **Token Usage** 标题可打开用量详情弹窗。OpenCode 在子代理视图中隐藏侧边栏，因此插件会在输入区上方保留一行实时摘要，显示 Context、Total、Cost、Time 和 TPS。点击摘要可在居中弹窗中查看完整统计；按 Escape 或点击 **esc** 即可关闭，关闭弹窗不会中断子代理。
+### 兼容性
 
-连接远程服务器时，可将包名加入本机 `~/.config/opencode/cli.json` 的 `plugins`，仅加载终端入口；配置路径遵循 `XDG_CONFIG_HOME`。
+需要 Node.js 22+（见[开发](#开发)中的 OpenTUI 引擎说明）。此前发布已验证 OpenCode 2.0.9 和 2.0.10；SDK 2.0.24 集成检查已在 OpenCode 2.0.11、2.0.22、2.0.24、2.0.26 和 2.0.28 上通过。原生对话耗时与侧边栏标题点击的集成验证使用 2.0.26 和 2.0.28，其余列出的宿主检查早于这些功能加入。已测试组合见[验证记录](docs/verification.md)。
 
 ### 详细用量
 
@@ -136,6 +167,7 @@ OPENCODE_BIN=/absolute/path/to/opencode-2.0.11 npm run test:smoke
 
 ### 文档
 
+- [常见问题 FAQ](docs/faq.zh-CN.md)
 - [路线图](ROADMAP.md)
 - [验证记录](docs/verification.md)
 - [发布说明](docs/releasing.md)

package/ROADMAP.md

@@ -116,7 +116,7 @@ Steps  1,234
 * [x] 时间缺失显示不可用，读取失败保留旧值并标注未更新；分叉副本不继承耗时，已提交回退随删除历史扣除
 * [x] 移除动画后通过类型检查、205 项测试、构建及真实 OpenCode 2.0.26 完整打包集成复验
 * [x] 首轮尚无 idle 消息时依据原生会话时间保持起点，synthetic／steer 不误重置；重连校时期间保留同一开放轮次的可信显示，247 项测试及真实 OpenCode 2.0.28 完整打包验证通过
-* [ ] macOS 物理多屏切换导致耗时倒退的实机复验（终端焦点事件、视图重建与模拟重连已覆盖，不代表已验证物理切屏、App Nap 或睡眠／唤醒）
+* [x] macOS 物理多屏切换导致耗时倒退的实机复验（终端焦点事件、视图重建与模拟重连已覆盖，不代表已验证物理切屏、App Nap 或睡眠／唤醒）
 
 ## 后续评估
 

package/dist/prices.generated.d.ts

@@ -1,5 +1,5 @@
 export declare const GENERATED_PRICE_SNAPSHOT: {
-    readonly verified: "2026-10-22";
+    readonly verified: "2026-10-23";
     readonly source: "https://models.dev/api.json";
     readonly entries: readonly [{
         readonly providerID: "ai21";
@@ -1647,10 +1647,10 @@ export declare const GENERATED_PRICE_SNAPSHOT: {
         readonly providerID: "mistral";
         readonly id: "mistral-large-4";
         readonly prices: readonly [{
-            readonly input: 0.68;
-            readonly output: 2.09;
+            readonly input: 1.36;
+            readonly output: 4.18;
             readonly cache: {
-                readonly read: 0.07;
+                readonly read: 0.14;
             };
         }];
         readonly released: "2026-10-06";
@@ -1834,22 +1834,6 @@ export declare const GENERATED_PRICE_SNAPSHOT: {
             readonly output: 0;
         }];
         readonly released: "2025-04-15";
-    }, {
-        readonly providerID: "nvidia";
-        readonly id: "nvidia/llama-3.1-nemotron-nano-8b-v1";
-        readonly prices: readonly [{
-            readonly input: 0;
-            readonly output: 0;
-        }];
-        readonly released: "2025-03-18";
-    }, {
-        readonly providerID: "nvidia";
-        readonly id: "nvidia/llama-3.1-nemotron-nano-vl-8b-v1";
-        readonly prices: readonly [{
-            readonly input: 0;
-            readonly output: 0;
-        }];
-        readonly released: "2025-04-10";
     }, {
         readonly providerID: "nvidia";
         readonly id: "nvidia/llama-3.1-nemotron-safety-guard-8b-v3";
@@ -1866,38 +1850,6 @@ export declare const GENERATED_PRICE_SNAPSHOT: {
             readonly output: 0;
         }];
         readonly released: "2025-04-07";
-    }, {
-        readonly providerID: "nvidia";
-        readonly id: "nvidia/llama-3.3-nemotron-super-49b-v1";
-        readonly prices: readonly [{
-            readonly input: 0;
-            readonly output: 0;
-        }];
-        readonly released: "2025-03-18";
-    }, {
-        readonly providerID: "nvidia";
-        readonly id: "nvidia/llama-3.3-nemotron-super-49b-v1.5";
-        readonly prices: readonly [{
-            readonly input: 0;
-            readonly output: 0;
-        }];
-        readonly released: "2025-07-25";
-    }, {
-        readonly providerID: "nvidia";
-        readonly id: "nvidia/nemotron-3-content-safety";
-        readonly prices: readonly [{
-            readonly input: 0;
-            readonly output: 0;
-        }];
-        readonly released: "2026-03-16";
-    }, {
-        readonly providerID: "nvidia";
-        readonly id: "nvidia/nemotron-3-nano-30b-a3b";
-        readonly prices: readonly [{
-            readonly input: 0;
-            readonly output: 0;
-        }];
-        readonly released: "2025-12-15";
     }, {
         readonly providerID: "nvidia";
         readonly id: "nvidia/nemotron-3-nano-omni-30b-a3b-reasoning";
@@ -1938,30 +1890,6 @@ export declare const GENERATED_PRICE_SNAPSHOT: {
             readonly output: 0;
         }];
         readonly released: "2026-10-15";
-    }, {
-        readonly providerID: "nvidia";
-        readonly id: "nvidia/nemotron-content-safety-reasoning-4b";
-        readonly prices: readonly [{
-            readonly input: 0;
-            readonly output: 0;
-        }];
-        readonly released: "2026-01-22";
-    }, {
-        readonly providerID: "nvidia";
-        readonly id: "nvidia/nemotron-mini-4b-instruct";
-        readonly prices: readonly [{
-            readonly input: 0;
-            readonly output: 0;
-        }];
-        readonly released: "2024-08-21";
-    }, {
-        readonly providerID: "nvidia";
-        readonly id: "nvidia/nemotron-nano-12b-v2-vl";
-        readonly prices: readonly [{
-            readonly input: 0;
-            readonly output: 0;
-        }];
-        readonly released: "2025-10-28";
     }, {
         readonly providerID: "nvidia";
         readonly id: "nvidia/nemotron-voicechat";

package/dist/prices.generated.js

@@ -1,5 +1,5 @@
 export const GENERATED_PRICE_SNAPSHOT = {
-    verified: "2026-10-22",
+    verified: "2026-10-23",
     source: "https://models.dev/api.json",
     entries: [
         { "providerID": "ai21", "id": "jamba-large", "prices": [{ "input": 2, "output": 8 }], "released": "2025-07-03" },
@@ -147,7 +147,7 @@ export const GENERATED_PRICE_SNAPSHOT = {
         { "providerID": "mistral", "id": "ministral-8b-latest", "prices": [{ "input": 0.15, "output": 0.15, "cache": { "read": 0.015 } }], "released": "2024-10-01" },
         { "providerID": "mistral", "id": "mistral-large-2411", "prices": [{ "input": 2, "output": 6 }], "released": "2024-11-18" },
         { "providerID": "mistral", "id": "mistral-large-2512", "prices": [{ "input": 0.5, "output": 1.5, "cache": { "read": 0.05 } }], "released": "2024-11-01" },
-        { "providerID": "mistral", "id": "mistral-large-4", "prices": [{ "input": 0.68, "output": 2.09, "cache": { "read": 0.07 } }], "released": "2026-10-06" },
+        { "providerID": "mistral", "id": "mistral-large-4", "prices": [{ "input": 1.36, "output": 4.18, "cache": { "read": 0.14 } }], "released": "2026-10-06" },
         { "providerID": "mistral", "id": "mistral-large-latest", "prices": [{ "input": 0.5, "output": 1.5, "cache": { "read": 0.05 } }], "released": "2024-11-01" },
         { "providerID": "mistral", "id": "mistral-medium-2505", "prices": [{ "input": 0.4, "output": 2 }], "released": "2025-05-07" },
         { "providerID": "mistral", "id": "mistral-medium-2508", "prices": [{ "input": 0.4, "output": 2 }], "released": "2025-08-12" },
@@ -167,22 +167,13 @@ export const GENERATED_PRICE_SNAPSHOT = {
         { "providerID": "moonshotai", "id": "kimi-k2.7-code-highspeed", "prices": [{ "input": 1.9, "output": 8, "cache": { "read": 0.38 } }], "released": "2026-06-12" },
         { "providerID": "moonshotai", "id": "kimi-k3", "prices": [{ "input": 3, "output": 15, "cache": { "read": 0.3, "write": 3 } }], "released": "2026-07-16" },
         { "providerID": "nvidia", "id": "nvidia/llama-3.1-nemotron-70b-instruct", "prices": [{ "input": 0, "output": 0 }], "released": "2025-04-15" },
-        { "providerID": "nvidia", "id": "nvidia/llama-3.1-nemotron-nano-8b-v1", "prices": [{ "input": 0, "output": 0 }], "released": "2025-03-18" },
-        { "providerID": "nvidia", "id": "nvidia/llama-3.1-nemotron-nano-vl-8b-v1", "prices": [{ "input": 0, "output": 0 }], "released": "2025-04-10" },
         { "providerID": "nvidia", "id": "nvidia/llama-3.1-nemotron-safety-guard-8b-v3", "prices": [{ "input": 0, "output": 0 }], "released": "2025-10-28" },
         { "providerID": "nvidia", "id": "nvidia/llama-3.1-nemotron-ultra-253b-v1", "prices": [{ "input": 0, "output": 0 }], "released": "2025-04-07" },
-        { "providerID": "nvidia", "id": "nvidia/llama-3.3-nemotron-super-49b-v1", "prices": [{ "input": 0, "output": 0 }], "released": "2025-03-18" },
-        { "providerID": "nvidia", "id": "nvidia/llama-3.3-nemotron-super-49b-v1.5", "prices": [{ "input": 0, "output": 0 }], "released": "2025-07-25" },
-        { "providerID": "nvidia", "id": "nvidia/nemotron-3-content-safety", "prices": [{ "input": 0, "output": 0 }], "released": "2026-03-16" },
-        { "providerID": "nvidia", "id": "nvidia/nemotron-3-nano-30b-a3b", "prices": [{ "input": 0, "output": 0 }], "released": "2025-12-15" },
         { "providerID": "nvidia", "id": "nvidia/nemotron-3-nano-omni-30b-a3b-reasoning", "prices": [{ "input": 0, "output": 0 }], "released": "2026-04-28" },
         { "providerID": "nvidia", "id": "nvidia/nemotron-3-ultra-550b-a55b", "prices": [{ "input": 0, "output": 0 }], "released": "2026-06-04" },
         { "providerID": "nvidia", "id": "nvidia/nemotron-3.5-content-safety", "prices": [{ "input": 0, "output": 0 }], "released": "2026-06-02" },
         { "providerID": "nvidia", "id": "nvidia/nemotron-3.5-lightning-30b-a3b", "prices": [{ "input": 0, "output": 0 }], "released": "2026-08-11" },
         { "providerID": "nvidia", "id": "nvidia/nemotron-3.5-super-vl-120b-a12b", "prices": [{ "input": 0, "output": 0 }], "released": "2026-10-15" },
-        { "providerID": "nvidia", "id": "nvidia/nemotron-content-safety-reasoning-4b", "prices": [{ "input": 0, "output": 0 }], "released": "2026-01-22" },
-        { "providerID": "nvidia", "id": "nvidia/nemotron-mini-4b-instruct", "prices": [{ "input": 0, "output": 0 }], "released": "2024-08-21" },
-        { "providerID": "nvidia", "id": "nvidia/nemotron-nano-12b-v2-vl", "prices": [{ "input": 0, "output": 0 }], "released": "2025-10-28" },
         { "providerID": "nvidia", "id": "nvidia/nemotron-voicechat", "prices": [{ "input": 0, "output": 0 }], "released": "2026-03-16" },
         { "providerID": "openai", "id": "gpt-3.5-turbo", "prices": [{ "input": 0.5, "output": 1.5, "cache": { "read": 0 } }], "released": "2023-03-01" },
         { "providerID": "openai", "id": "gpt-4", "prices": [{ "input": 30, "output": 60 }], "released": "2023-11-06" },

package/dist/pricing.d.ts

@@ -14,7 +14,7 @@ export interface OfficialPriceEntry {
 /** Checked-in data: updating prices is explicit, not a network request at
  * startup, during a refresh, or during an npm build. */
 export declare const OFFICIAL_PRICE_SNAPSHOT: {
-    verified: "2026-10-22";
+    verified: "2026-10-23";
     source: "https://models.dev/api.json";
     entries: OfficialPriceEntry[];
 };

package/package.json

@@ -1,15 +1,18 @@
 {
   "name": "@chenlongapps/opencode-token-usage",
-  "version": "0.4.15",
-  "description": "Session-tree token usage, live performance, context window and estimated cost for OpenCode 2",
+  "version": "0.4.16",
+  "description": "OpenCode 2 plugin for session-tree token usage, context window monitoring, estimated costs, and performance metrics (TPS, TTFT, run time).",
   "keywords": [
     "opencode",
     "opencode-plugin",
     "token-usage",
     "context-window",
+    "cost-tracking",
     "tps",
     "ttft",
-    "cost"
+    "subagents",
+    "terminal-ui",
+    "llm"
   ],
   "homepage": "https://github.com/chenlongapps/opencode-token-usage#readme",
   "bugs": {