@chenlongapps/opencode-token-usage 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 opencode-token-usage contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,133 @@
+# opencode-token-usage
+
+面向 **OpenCode 2** 的 token 用量插件，当前版本 **0.2.1**。SDK 依赖固定为 2.0.9，宿主已验证 2.0.9、2.0.10 和 2.0.11。在原生 TUI 侧边栏追加用量面板，统计当前会话所在的整棵会话树，包括未打开的子代理，并显示性能指标与当前查看会话的上下文占用。
+
+## 预览
+
+```text
+Token Usage
+Context        9,810 / 128,000 (7.7%)
+Input                          54,200
+Output                          6,800
+Reasoning                       4,100
+Cache Read                     31,700
+Cache Write                     1,300
+Cache Rate                      36.4%
+Total                          98,100
+Cost                            $0.21
+
+TPS                         48.7 tok/s
+TTFT                              2.7s
+```
+
+示例费用使用每百万 token 的 Input / Output / Cache Read / Cache Write 单价 $2 / $8 / $0.2 / $3。实际价格与上下文上限取自当前查看会话的活动模型。
+
+## 安装
+
+需要 Node.js 22+ 和 OpenCode **2.0.9、2.0.10 或 2.0.11**。更高版本的 OpenCode 尚未验证；npm SDK 依赖仍锁定为 2.0.9。
+
+将 npm 包加入项目的 `opencode.json` 或 `opencode.jsonc`，保留已有插件：
+
+```json
+{
+  "plugins": ["@chenlongapps/opencode-token-usage"]
+}
+```
+
+OpenCode 会下载并加载主插件与 TUI 入口。需要固定版本时可写成 `@chenlongapps/opencode-token-usage@0.2.1`。重启 OpenCode 并进入会话后，面板会追加到原生侧边栏；侧边栏的显示与宽度由宿主管理，终端需要足够宽，并且 CLI 设置 `session.sidebar` 为 `auto`。
+
+OpenCode 2.0.9–2.0.11 在子代理视图中强制隐藏侧边栏，因此插件通过 `session.composer.top` 在输入区上方显示同一完整面板。进入子代理仍统计整棵会话树，费用、上下文用量与上限改用该子代理的消息和活动模型。
+
+连接远程服务器时，可把相同 npm 包名加入本机 `~/.config/opencode/cli.json` 的 `plugins`，仅加载终端入口。配置路径遵循 `XDG_CONFIG_HOME`，没有项目级 `cli.json`。
+
+### 从源码运行
+
+在此仓库中执行：
+
+```bash
+npm ci
+npm run typecheck
+npm test
+npm run build
+```
+
+将仓库的绝对路径加入目标项目的 `opencode.json` 或 `opencode.jsonc`，保留已有插件：
+
+```json
+{
+  "plugins": ["/absolute/path/opencode-token-usage"]
+}
+```
+
+然后在目标项目运行 `opencode`。根目录的 `index.js` 和 `tui.js` 转发到编译产物，适配 2.0.9–2.0.11 的本地目录发现方式。也可先验证独立打包产物：
+
+```bash
+npm pack
+npm install --prefix /absolute/path/local-plugins ./chenlongapps-opencode-token-usage-0.2.1.tgz
+```
+
+此时配置的插件路径为 `/absolute/path/local-plugins/node_modules/@chenlongapps/opencode-token-usage`。包包含编译后的 ESM 和类型声明，无需在使用时编译 JSX。
+
+## 统计口径
+
+- 沿当前会话的 `parentID` 找到根，再分页读取所有后代及其完整消息。进入子代理仍显示同一棵树的累计用量。
+- 统计服务端上报的 assistant 和 compaction 消息，包括压缩前历史及失败消息中已记录的用量。不根据文本长度估算 token，不计入没有关联消息的标题生成用量。
+- 按会话和消息 ID 保存快照，每次成功刷新替换旧值，重复事件不会累加两次。分叉会话属于独立会话树；继承历史只归原始来源，其副本不重复计费。分叉副本识别依据 OpenCode 2.0.9 的 ID 生成规则。
+- `Input` 不含缓存读取或写入；`Output` 不含 `Reasoning`。
+- `Total = Input + Output + Reasoning + Cache Read + Cache Write`。
+- `Cache Rate = Cache Read ÷ (Input + Cache Read + Cache Write)`；保留一位小数，分母为零时显示 `0.0%`。
+- `Cache Write` 和 `Cost` 仅在值大于零时显示。空会话保留其他统计行并显示零；首次读取显示 `Loading…` 和 `—`，首次失败显示 `Unavailable`。刷新失败保留上次完整结果，标注 `Not updated` 并自动重试。
+
+### 性能指标
+
+`TPS` 统计整棵会话树的模型生成速度，token 口径为 Output + Reasoning。已完成消息使用服务端记录的 `time.created → time.streamed` 总时长和真实 token 加权计算，即 `Σ(Output + Reasoning) ÷ Σ流式时长`。有活动生成时优先显示实时估算：合并所有活动流的 UTF-8 增量，按约 4 字节/token 换算并以 `~` 标记；完成刷新后自动替换为精确值。流式增量不会触发完整历史扫描。
+
+`TTFT` 是整棵会话树中可测 assistant step 从请求发出到首个模型输出的算术平均值。首输出包括文本、推理和工具输入增量。插件运行期间使用实时事件精确记录；加载历史时仅使用带可靠创建时间的首个 reasoning 或 tool 内容。纯文本历史没有首 token 时间戳，因此不以完成时间伪造样本，也不会拉低平均值。没有可用样本时隐藏对应性能行。
+
+### 上下文用量
+
+`Context` 是面板的第一行（状态提示之后），只反映**当前查看会话本身**，不随子树累计：取该会话中最后一条带 `tokens` 的 assistant 消息的五类 token 之和，并且只搜索最后一次 `completed` 压缩之后的消息——与 OpenCode 侧边栏显示的口径一致。正在运行或失败的压缩不重置窗口；压缩刚结束而尚无新回复时隐藏该行，不回退到压缩前的数值。正在生成、尚无用量的最后一条消息会被跳过，沿用上一条有上报的消息。
+
+上限取当前查看会话活动模型的 `limit.context`，与 `Cost` 使用同一解析规则，因此切换模型后百分比立即更新。模型没有可用上限（缺失、为零、非有限值）或尚无用量的会话隐藏 `Context` 行。行内格式为 `已用 / 上限 (百分比%)`，百分比保留一位小数，用量超过上限时显示真实值。当前版本不显示进度条。
+
+### 估算费用
+
+`Cost` 是按**当前查看会话的活动模型**重新估算的全树费用，不是提供商账单，也不累加历史消息中保存的 `cost`。它不使用每条消息自身记录的模型：同一会话里即使多条消息由不同模型生成，也统一按查看时活动模型的价格档位推算，因此混合模型会话的金额**不等于**按各消息实际模型计费之和——它回答的是"把这棵树按当前模型重跑一遍会花多少"。未选定模型时使用该会话位置的默认模型，切换模型后重新计算。
+
+每条消息分别使用其传入 token 数（Input + Cache Read + Cache Write）选择价格档位：严格超过阈值才进入该档，多个档位适用时取最高阈值，否则用基础档。Output 和 Reasoning 都使用输出单价，最后合计各条消息的费用。
+
+没有模型价格或适用档位时按 OpenCode 官方计费实现回退为 **0**。合法的免费模型也按其实际价格计算；价格请求失败会显示未更新状态。这里的“默认价格”并非内置的公开价格目录。
+
+数字使用千位逗号分组并显示为四舍五入后的整数；例如 `1200 → 1,200`、`125000 → 125,000`、`1500000 → 1,500,000`。美元保留两位小数，正数不足一美分显示 `<$0.01`。
+
+## 开发与验证
+
+```bash
+npm run typecheck
+npm test
+npm run build
+npm run test:smoke
+```
+
+`test:smoke` 需要本机 OpenCode 2.0.9、2.0.10 或 2.0.11、Python 3、可用的本地端口及 npm 网络访问。它打包并安装真实产物，在临时目录启动隔离的 OpenCode 服务和真实 TUI，通过带延迟的本地模拟提供商检查加载、实时 TPS 与 TTFT、完成后精确 TPS、用量与上下文刷新、真实子代理累计及模型切换。不会修改现有 OpenCode 配置或使用付费模型。终端捕获和测试记录保留在输出的临时路径。
+
+维护者的首次发布、Trusted Publishing 和后续版本流程见 [npm 发布说明](https://github.com/chenlongapps/opencode-token-usage/blob/main/docs/releasing.md)。
+
+2026-09-20 已通过类型检查、29 项自动化测试、构建和上述真实集成验证，详见 [验证记录](docs/verification.md)。
+
+架构：`usage.ts` 处理统计、上下文与格式化，`performance.ts` 处理 TPS、TTFT 与流式事件，`source.ts` 对接 v2 客户端和分页，`controller.ts` 合并刷新、隔离旧请求与处理失败，`tui.tsx` 渲染侧边栏。流式增量只更新内存中的性能指标；用量、会话和模型事件仍通过合并刷新重新分页扫描会话树，以保证历史完整性。超大历史的增量读取优化留待后续版本。
+
+紧凑模式、`/usage` 和公开价格目录尚未实现，详见 [ROADMAP.md](ROADMAP.md)。
+
+## 接口依据
+
+- [OpenCode 2 CLI 插件接口](https://opencode.ai/v2/docs/build/plugins/cli/)
+- [OpenCode 2 插件加载](https://opencode.ai/v2/docs/build/plugins/)
+- [CLI 设置](https://opencode.ai/v2/docs/cli/config/)
+- [TokenUsage 定义](https://github.com/anomalyco/opencode/blob/v2/packages/schema/src/token-usage.ts)
+- [官方计费实现](https://github.com/anomalyco/opencode/blob/v2/packages/core/src/session/usage.ts)
+- [分叉历史投影](https://github.com/anomalyco/opencode/blob/v2/packages/core/src/session/projector.ts)
+
+## 许可证
+
+[MIT](LICENSE)

package/ROADMAP.md

@@ -0,0 +1,77 @@
+# opencode-token-usage 路线图
+
+为 **OpenCode 2** 提供轻量级、实时的 token 用量监视器。勾选项表示已实现且通过相应验证；未来版本的示例仅用于说明设计。
+
+## v0.1.0 — 核心用量与基础侧边栏
+
+目标：提供可本地安装的完整会话树用量面板，不包含 npm 发布。
+
+* [x] OpenCode 2.0.9 主插件与 `./tui` 入口集成
+* [x] 向原生 `sidebar.content` 追加基础面板，保留宿主内容
+* [x] 子代理视图使用 `session.composer.top` 显示完整面板，适配宿主隐藏侧边栏的行为
+* [x] 检测当前会话，沿 `parentID` 汇总根会话及所有后代
+* [x] 分页读取完整消息，包括压缩前历史和未打开的子代理
+* [x] 快照替换与继承历史去重，防止重复累计
+* [x] 显示 Input、Output、Reasoning、Cache Read、Cache Write
+* [x] 显示缓存命中率 Cache Rate
+* [x] 显示五类 token 的总量 Total
+* [x] 按当前查看会话的活动模型估算 Cost，支持模型切换
+* [x] 未选模型时使用所在位置的默认模型；缺失适用价格按 0 并标注
+* [x] 按每条消息的传入 token 数选择价格阶梯
+* [x] 数字使用千位逗号分组：`1200 → 1,200`、`125000 → 125,000`、`1500000 → 1,500,000`
+* [x] 空会话保留基础统计行并显示零；零值 Cache Write 与 Cost 隐藏
+* [x] 消息用量上报后合并刷新，切换会话时隔离旧请求
+* [x] 加载、不可用、未更新与失败恢复状态
+* [x] 实际打包产物在 OpenCode 2.0.9 和 2.0.10 中验证加载、显示、刷新与子代理累计
+
+预览及安装说明见 [README.md](README.md)，验证结果见 [验证记录](docs/verification.md)。
+
+## v0.2.0 — 上下文用量
+
+目标：让上下文消耗情况清晰可见。
+
+* [x] 读取活动模型的上下文窗口大小
+* [x] 显示已用 / 最大上下文
+* [x] 显示上下文用量百分比
+* [x] 处理上下文限制未知的模型
+* [x] 在模型切换后同步更新上下文指标
+
+```text
+Context  72,400 / 128,000 (56.6%)
+```
+
+上下文行显示在面板第一行；百分比与用量同行，进度条留待后续版本。
+
+## v0.2.1 — TPS、TTFT的显示
+
+目标：提供更直观的性能指标。
+
+* [x] 显示实时 TPS（每秒 token 处理量）
+* [x] 显示平均 TTFT（首 token 处理时间）
+
+```text
+TPS  48.7 tok/s
+TTFT  2.7s
+```
+
+## v0.3.0 — 公开价格目录
+
+目标：提供可查询的价格目录，便于用户了解不同模型的计费档位。
+
+* [ ] 构建公开价格目录，包含模型、价格档位及阈值
+<!-- TODO -->
+
+## v0.4.0 — 用量命令
+
+目标：按需提供比侧边栏更详细的 token 信息。
+
+* [ ] 添加 `/usage`
+* [ ] 显示当前会话及会话树统计
+* [ ] 显示 token 明细与上下文用量
+* [ ] 显示模型和价格信息
+* [ ] 显示估算费用明细
+
+## 后续评估
+
+* [ ] 公开价格目录与更新策略
+* [ ] 首次 npm 发布（包元数据、CI、OIDC 发布工作流与本地验证已完成，待账号认证并发布到 registry）

package/dist/controller.d.ts

@@ -0,0 +1,44 @@
+import type { UsageSource } from "./source.js";
+import type { PerformanceSummary } from "./performance.js";
+import type { ContextUsage, Summary } from "./usage.js";
+export interface UsageState {
+    status: "loading" | "ready" | "stale" | "unavailable";
+    summary?: Summary;
+    context?: ContextUsage | undefined;
+    performance?: PerformanceSummary;
+    model?: string;
+}
+export interface UsageEvent {
+    type: string;
+    data: unknown;
+    id?: string;
+    created?: number;
+}
+export type Subscribe = (listener: (event: UsageEvent) => void) => () => void;
+/** Owns snapshot refreshes and throttled in-memory performance updates for one mounted panel. */
+export declare class UsageController {
+    private readonly source;
+    private readonly publish;
+    private readonly delay;
+    private readonly retryDelay;
+    private readonly performanceDelay;
+    private state;
+    private snapshot;
+    private sessionID;
+    private generation;
+    private request;
+    private timer;
+    private retry;
+    private performanceTimer;
+    private pending;
+    private disposed;
+    private unsubscribe;
+    private readonly performance;
+    constructor(source: UsageSource, subscribe: Subscribe, publish: (state: UsageState) => void, delay?: number, retryDelay?: number, performanceDelay?: number);
+    select(sessionID: string): void;
+    refresh(): void;
+    dispose(): void;
+    private update;
+    private refreshPerformance;
+    private run;
+}

package/dist/controller.js

@@ -0,0 +1,152 @@
+import { loadSnapshot, uniqueMessages, viewedMessages } from "./source.js";
+import { PerformanceTracker } from "./performance.js";
+import { contextUsage, summarize } from "./usage.js";
+const performanceEvents = new Set([
+    "session.step.started", "session.step.streamed", "session.step.ended", "session.step.failed",
+    "session.text.delta", "session.reasoning.delta", "session.tool.input.delta",
+]);
+const sessionEvents = new Set([
+    "session.created", "session.deleted", "session.forked", "session.moved",
+    "session.model.selected", "session.agent.selected", "session.step.ended", "session.step.failed",
+    "session.compaction.ended", "session.compaction.failed", "session.message.content.updated",
+    "session.usage.recorded", "session.usage.updated", "session.revert.committed",
+    "session.execution.succeeded", "session.execution.failed", "session.execution.interrupted",
+]);
+const globalEvents = new Set([
+    "server.connected", "model.updated", "provider.updated", "models-dev.refreshed",
+    "config.updated", "location.shutdown",
+]);
+/** Owns snapshot refreshes and throttled in-memory performance updates for one mounted panel. */
+export class UsageController {
+    source;
+    publish;
+    delay;
+    retryDelay;
+    performanceDelay;
+    state = { status: "loading" };
+    snapshot;
+    sessionID;
+    generation = 0;
+    request;
+    timer;
+    retry;
+    performanceTimer;
+    pending = false;
+    disposed = false;
+    unsubscribe;
+    performance = new PerformanceTracker();
+    constructor(source, subscribe, publish, delay = 80, retryDelay = 3_000, performanceDelay = 100) {
+        this.source = source;
+        this.publish = publish;
+        this.delay = delay;
+        this.retryDelay = retryDelay;
+        this.performanceDelay = performanceDelay;
+        this.unsubscribe = subscribe(event => {
+            const data = (event.data && typeof event.data === "object" ? event.data : {});
+            if (event.type === "session.created")
+                this.performance.addSession(data.sessionID, data.parentID);
+            if (performanceEvents.has(event.type) && this.performance.handle(event))
+                this.refreshPerformance();
+            if (globalEvents.has(event.type))
+                return this.refresh();
+            if (!sessionEvents.has(event.type))
+                return;
+            if (!this.snapshot || event.type === "session.created" || event.type === "session.forked"
+                || data.sessionID === this.sessionID || (data.sessionID && this.snapshot.sessions.has(data.sessionID)))
+                this.refresh();
+        });
+    }
+    select(sessionID) {
+        if (this.disposed || sessionID === this.sessionID)
+            return;
+        this.generation++;
+        this.request?.abort();
+        this.request = undefined;
+        clearTimeout(this.timer);
+        clearTimeout(this.retry);
+        clearTimeout(this.performanceTimer);
+        this.timer = undefined;
+        this.performanceTimer = undefined;
+        this.pending = false;
+        this.snapshot = undefined;
+        this.sessionID = sessionID;
+        this.update({ status: "loading" });
+        void this.run();
+    }
+    refresh() {
+        if (this.disposed || !this.sessionID)
+            return;
+        clearTimeout(this.retry);
+        if (this.request) {
+            this.pending = true;
+            return;
+        }
+        // Fixed window, rather than resetting on every event: streams cannot starve refreshes.
+        if (this.timer)
+            return;
+        this.timer = setTimeout(() => { this.timer = undefined; void this.run(); }, this.delay);
+    }
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        this.generation++;
+        this.request?.abort();
+        clearTimeout(this.timer);
+        clearTimeout(this.retry);
+        clearTimeout(this.performanceTimer);
+        this.unsubscribe();
+    }
+    update(state) { this.state = state; this.publish(state); }
+    refreshPerformance() {
+        if (this.disposed || !this.snapshot || this.performanceTimer)
+            return;
+        this.performanceTimer = setTimeout(() => {
+            this.performanceTimer = undefined;
+            if (this.disposed || !this.snapshot || !this.state.summary)
+                return;
+            this.update({ ...this.state, performance: this.performance.summary(uniqueMessages(this.snapshot)) });
+        }, this.performanceDelay);
+    }
+    async run() {
+        if (this.disposed || !this.sessionID)
+            return;
+        const generation = this.generation;
+        const request = new AbortController();
+        this.request = request;
+        try {
+            const signal = AbortSignal.any([request.signal, AbortSignal.timeout(30_000)]);
+            const snapshot = await loadSnapshot(this.source, this.sessionID, signal);
+            if (this.disposed || generation !== this.generation)
+                return;
+            this.snapshot = snapshot;
+            const messages = [...uniqueMessages(snapshot)];
+            this.performance.setTree(snapshot.rootID, snapshot.sessions.keys());
+            this.performance.reconcile(messages);
+            clearTimeout(this.performanceTimer);
+            this.performanceTimer = undefined;
+            this.update({
+                status: "ready",
+                summary: summarize(messages, snapshot.model.prices),
+                context: contextUsage(viewedMessages(snapshot), snapshot.model.context),
+                performance: this.performance.summary(messages),
+                model: snapshot.model.label,
+            });
+        }
+        catch {
+            if (this.disposed || generation !== this.generation)
+                return;
+            this.update({ ...this.state, status: this.state.summary ? "stale" : "unavailable" });
+            this.retry = setTimeout(() => this.refresh(), this.retryDelay);
+        }
+        finally {
+            if (generation === this.generation && !this.disposed) {
+                this.request = undefined;
+                if (this.pending) {
+                    this.pending = false;
+                    this.refresh();
+                }
+            }
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import { Plugin } from "@opencode/plugin";
+declare const _default: Plugin.Plugin;
+export default _default;

package/dist/index.js

@@ -0,0 +1,5 @@
+import { Plugin } from "@opencode/plugin";
+export default Plugin.define({
+    id: "opencode-token-usage",
+    setup() { },
+});

package/dist/performance.d.ts

@@ -0,0 +1,33 @@
+import type { UsageMessage } from "./usage.js";
+export interface PerformanceSummary {
+    tps?: number;
+    tpsEstimated?: boolean;
+    /** Average time to first token, in milliseconds. */
+    ttft?: number;
+}
+export interface FirstTokenObservation {
+    messageID: string;
+    sessionID: string;
+    started: number;
+    first: number;
+}
+export interface PerformanceEvent {
+    type: string;
+    data: unknown;
+    id?: string;
+    created?: number;
+}
+/** Exact completed-run TPS and the average of only measurable TTFT samples. */
+export declare function historicalPerformance(messages: Iterable<UsageMessage>, observations?: Iterable<FirstTokenObservation>): PerformanceSummary;
+/** Tracks ephemeral streaming events without fetching the full session tree. */
+export declare class PerformanceTracker {
+    private rootID;
+    private sessions;
+    private active;
+    private observed;
+    setTree(rootID: string, sessionIDs: Iterable<string>): void;
+    addSession(sessionID: string | undefined, parentID: string | undefined): void;
+    handle(event: PerformanceEvent): boolean;
+    reconcile(messages: Iterable<UsageMessage>): void;
+    summary(messages: Iterable<UsageMessage>): PerformanceSummary;
+}

package/dist/performance.js

@@ -0,0 +1,172 @@
+import { normalize } from "./usage.js";
+const finite = (value) => typeof value === "number" && Number.isFinite(value);
+function historicalFirst(message) {
+    const started = message.time?.created;
+    if (!finite(started))
+        return undefined;
+    for (const part of message.content ?? []) {
+        if (part.type === "text") {
+            if (part.text)
+                return undefined;
+            continue;
+        }
+        if (part.type === "reasoning") {
+            if (!part.text)
+                continue;
+            const first = part.time?.created;
+            return finite(first) && first >= started ? first - started : undefined;
+        }
+        if (part.type === "tool") {
+            const first = part.time?.created;
+            return finite(first) && first >= started ? first - started : undefined;
+        }
+    }
+    return undefined;
+}
+/** Exact completed-run TPS and the average of only measurable TTFT samples. */
+export function historicalPerformance(messages, observations = []) {
+    const observed = new Map();
+    for (const sample of observations) {
+        if (finite(sample.started) && finite(sample.first) && sample.first >= sample.started)
+            observed.set(sample.messageID, sample);
+    }
+    let output = 0;
+    let duration = 0;
+    let ttft = 0;
+    let ttftSamples = 0;
+    const messagesSeen = new Set();
+    for (const message of messages) {
+        if (message.type !== "assistant")
+            continue;
+        messagesSeen.add(message.id);
+        const created = message.time?.created;
+        const streamed = message.time?.streamed;
+        const tokens = normalize(message.tokens);
+        const generated = tokens.output + tokens.reasoning;
+        if (finite(created) && finite(streamed) && streamed > created && generated > 0) {
+            output += generated;
+            duration += streamed - created;
+        }
+        const runtime = observed.get(message.id);
+        const sample = runtime ? runtime.first - runtime.started : historicalFirst(message);
+        if (sample !== undefined && finite(sample) && sample >= 0) {
+            ttft += sample;
+            ttftSamples++;
+        }
+    }
+    // A live first-token event can arrive before the refreshed message snapshot.
+    for (const sample of observed.values()) {
+        if (messagesSeen.has(sample.messageID))
+            continue;
+        ttft += sample.first - sample.started;
+        ttftSamples++;
+    }
+    const result = {};
+    if (duration > 0)
+        result.tps = output / (duration / 1_000);
+    if (ttftSamples > 0)
+        result.ttft = ttft / ttftSamples;
+    return result;
+}
+/** Tracks ephemeral streaming events without fetching the full session tree. */
+export class PerformanceTracker {
+    rootID;
+    sessions = new Set();
+    active = new Map();
+    observed = new Map();
+    setTree(rootID, sessionIDs) {
+        if (this.rootID !== rootID) {
+            this.active.clear();
+            this.observed.clear();
+            this.rootID = rootID;
+        }
+        this.sessions = new Set(sessionIDs);
+        for (const [id, step] of this.active)
+            if (!this.sessions.has(step.sessionID))
+                this.active.delete(id);
+        for (const [id, sample] of this.observed)
+            if (!this.sessions.has(sample.sessionID))
+                this.observed.delete(id);
+    }
+    addSession(sessionID, parentID) {
+        if (sessionID && parentID && this.sessions.has(parentID))
+            this.sessions.add(sessionID);
+    }
+    handle(event) {
+        const data = (event.data && typeof event.data === "object" ? event.data : {});
+        const sessionID = typeof data.sessionID === "string" ? data.sessionID : undefined;
+        const messageID = typeof data.assistantMessageID === "string" ? data.assistantMessageID : undefined;
+        if (!sessionID || !messageID || !this.sessions.has(sessionID))
+            return false;
+        if (event.type === "session.step.started") {
+            if (!finite(data.started))
+                return false;
+            if (this.active.has(messageID))
+                return false;
+            this.active.set(messageID, {
+                messageID, sessionID, started: data.started, bytes: 0, events: new Set(),
+            });
+            return false;
+        }
+        const step = this.active.get(messageID);
+        if (!step)
+            return false;
+        if (event.type === "session.step.streamed") {
+            if (!finite(event.created) || event.created < step.started)
+                return false;
+            step.streamed = event.created;
+            return step.bytes > 0;
+        }
+        if (event.type === "session.step.ended" || event.type === "session.step.failed") {
+            return false;
+        }
+        if (event.type !== "session.text.delta" && event.type !== "session.reasoning.delta"
+            && event.type !== "session.tool.input.delta")
+            return false;
+        if (typeof data.delta !== "string" || data.delta.length === 0 || !finite(event.created) || event.created < step.started)
+            return false;
+        if (event.id && step.events.has(event.id))
+            return false;
+        if (event.id)
+            step.events.add(event.id);
+        step.bytes += new TextEncoder().encode(data.delta).byteLength;
+        step.last = Math.max(step.last ?? event.created, event.created);
+        if (step.first === undefined) {
+            step.first = event.created;
+            this.observed.set(messageID, { messageID, sessionID, started: step.started, first: event.created });
+        }
+        return true;
+    }
+    reconcile(messages) {
+        const represented = new Set();
+        for (const message of messages) {
+            if (message.type === "assistant" && (message.tokens || message.time?.streamed !== undefined
+                || message.time?.completed !== undefined))
+                represented.add(message.id);
+        }
+        for (const [id, step] of this.active) {
+            if (represented.has(id))
+                this.active.delete(id);
+        }
+    }
+    summary(messages) {
+        const samples = [...this.observed.values()].filter(sample => this.sessions.has(sample.sessionID));
+        const result = historicalPerformance(messages, samples);
+        let bytes = 0;
+        let duration = 0;
+        for (const step of this.active.values()) {
+            if (!this.sessions.has(step.sessionID) || step.bytes <= 0)
+                continue;
+            const last = step.streamed ?? step.last;
+            if (!finite(last) || last <= step.started)
+                continue;
+            bytes += step.bytes;
+            duration += last - step.started;
+        }
+        if (bytes > 0 && duration > 0) {
+            result.tps = (bytes / 4) / (duration / 1_000);
+            result.tpsEstimated = true;
+        }
+        return result;
+    }
+}

package/dist/source.d.ts

@@ -0,0 +1,35 @@
+import type { OpenCodeClient, SessionInfo } from "@opencode/client";
+import type { Price, UsageMessage } from "./usage.js";
+export type Session = Pick<SessionInfo, "id" | "parentID" | "fork" | "model" | "location">;
+export interface Page<T> {
+    data: T[];
+    cursor: {
+        next?: string | null;
+        previous?: string | null;
+    };
+}
+/** Active model of the viewed session: price tiers, display label and context window. */
+export interface ActiveModel {
+    label: string;
+    prices: readonly Price[];
+    context?: number | undefined;
+}
+export interface UsageSource {
+    session(id: string, signal: AbortSignal): Promise<Session>;
+    children(id: string, cursor: string | undefined, signal: AbortSignal): Promise<Page<Session>>;
+    messages(id: string, cursor: string | undefined, signal: AbortSignal): Promise<Page<UsageMessage>>;
+    model(session: Session, signal: AbortSignal): Promise<ActiveModel>;
+}
+export declare function createSource(client: OpenCodeClient): UsageSource;
+export declare function pages<T>(read: (cursor?: string) => Promise<Page<T>>, signal: AbortSignal): Promise<T[]>;
+export interface Snapshot {
+    rootID: string;
+    viewedID: string;
+    sessions: Map<string, Session>;
+    messages: Map<string, Map<string, UsageMessage>>;
+    model: ActiveModel;
+}
+export declare function loadSnapshot(source: UsageSource, sessionID: string, signal: AbortSignal): Promise<Snapshot>;
+/** History of the viewed session only, in API order (`order: "asc"`). */
+export declare function viewedMessages(snapshot: Snapshot): readonly UsageMessage[];
+export declare function uniqueMessages(snapshot: Snapshot): Iterable<UsageMessage>;

package/dist/source.js

@@ -0,0 +1,95 @@
+export function createSource(client) {
+    return {
+        session: (sessionID, signal) => client.session.get({ sessionID }, { signal }),
+        children: (parentID, cursor, signal) => client.session.list(cursor ? { cursor } : { parentID, order: "asc", limit: 100 }, { signal }),
+        // Unlike session.context(), message.list() includes pre-compaction history.
+        messages: (sessionID, cursor, signal) => client.message.list(cursor ? { sessionID, cursor } : { sessionID, order: "asc", limit: 100 }, { signal }),
+        async model(session, signal) {
+            const input = { location: session.location };
+            const selected = session.model;
+            const model = selected
+                ? (await client.model.list(input, { signal })).data.find(m => m.providerID === selected.providerID && m.id === selected.id)
+                : (await client.model.default(input, { signal })).data;
+            return {
+                label: model ? `${model.providerID}/${model.id}` : selected ? `${selected.providerID}/${selected.id}` : "Default model",
+                prices: model?.cost ?? [],
+                context: model?.limit?.context,
+            };
+        },
+    };
+}
+export async function pages(read, signal) {
+    const result = [];
+    const seen = new Set();
+    let cursor;
+    do {
+        signal.throwIfAborted();
+        const page = await read(cursor);
+        signal.throwIfAborted();
+        result.push(...page.data);
+        cursor = page.cursor.next ?? undefined;
+        if (cursor && seen.has(cursor))
+            throw new Error("Repeated pagination cursor");
+        if (cursor)
+            seen.add(cursor);
+    } while (cursor);
+    return result;
+}
+export async function loadSnapshot(source, sessionID, signal) {
+    const viewed = await source.session(sessionID, signal);
+    let root = viewed;
+    const ancestors = new Set();
+    while (root.parentID) {
+        if (ancestors.has(root.id))
+            throw new Error("Cyclic session ancestry");
+        ancestors.add(root.id);
+        signal.throwIfAborted();
+        root = await source.session(root.parentID, signal);
+    }
+    const sessions = new Map([[root.id, root]]);
+    const messages = new Map();
+    // Breadth-first discovery includes unopened descendants, with bounded parallelism.
+    const queue = [root];
+    for (let index = 0; index < queue.length; index++) {
+        const session = queue[index];
+        const [children, history] = await Promise.all([
+            pages(cursor => source.children(session.id, cursor, signal), signal),
+            pages(cursor => source.messages(session.id, cursor, signal), signal),
+        ]);
+        messages.set(session.id, new Map(history.map(message => [message.id, message])));
+        for (const child of children) {
+            if (child.parentID !== session.id)
+                throw new Error("Unexpected child session");
+            if (!sessions.has(child.id)) {
+                sessions.set(child.id, child);
+                queue.push(child);
+            }
+        }
+    }
+    if (!sessions.has(viewed.id))
+        throw new Error("Session tree changed during refresh");
+    const model = await source.model(viewed, signal);
+    signal.throwIfAborted();
+    return { rootID: root.id, viewedID: viewed.id, sessions, messages, model };
+}
+/** History of the viewed session only, in API order (`order: "asc"`). */
+export function viewedMessages(snapshot) {
+    return [...(snapshot.messages.get(snapshot.viewedID)?.values() ?? [])];
+}
+export function* uniqueMessages(snapshot) {
+    const seen = new Set();
+    for (const [sessionID, messages] of snapshot.messages) {
+        const session = snapshot.sessions.get(sessionID);
+        for (const message of messages.values()) {
+            // 2.0.9 projectFork copies history with IDs `${forkMessageID}_${sourceSeq}`.
+            // Those calls belong to the source session, even though the copy has a new ID.
+            // A fork is a separate root (fork.sessionID is not parentID).
+            if (session.fork && /_\d+$/.test(message.id))
+                continue;
+            if (seen.has(message.id))
+                continue;
+            seen.add(message.id);
+            yield message;
+        }
+    }
+}

package/dist/tui.d.ts

@@ -0,0 +1,3 @@
+import { Plugin } from "@opencode/plugin/tui";
+declare const _default: Plugin.Definition;
+export default _default;

package/dist/tui.js

@@ -0,0 +1,146 @@
+import { createComponent as _$createComponent } from "@opentui/solid";
+import { effect as _$effect } from "@opentui/solid";
+import { insert as _$insert } from "@opentui/solid";
+import { createTextNode as _$createTextNode } from "@opentui/solid";
+import { insertNode as _$insertNode } from "@opentui/solid";
+import { setProp as _$setProp } from "@opentui/solid";
+import { createElement as _$createElement } from "@opentui/solid";
+import { Plugin } from "@opencode/plugin/tui";
+import { createEffect, createMemo, createSignal, For, onCleanup, Show } from "solid-js";
+import { UsageController } from "./controller.js";
+import { createSource } from "./source.js";
+import { usageRows } from "./usage.js";
+function UsagePanel(props) {
+  const [state, setState] = createSignal({
+    status: "loading"
+  });
+  const controller = new UsageController(createSource(props.context.client), listener => props.context.data.listen(({
+    details
+  }) => listener(details)), setState);
+  const unregister = props.register(controller);
+  createEffect(() => controller.select(props.sessionID));
+  onCleanup(() => {
+    controller.dispose();
+    unregister();
+  });
+  const rows = createMemo(() => usageRows(state().summary, state().context, state().performance));
+  const performanceStart = createMemo(() => rows().findIndex(([label]) => label === "TPS" || label === "TTFT"));
+  const status = () => ({
+    loading: "Loading…",
+    ready: "",
+    stale: "Not updated · retrying…",
+    unavailable: "Unavailable · retrying…"
+  })[state().status];
+  return (() => {
+    var _el$ = _$createElement("box"),
+      _el$2 = _$createElement("text"),
+      _el$3 = _$createElement("b");
+    _$insertNode(_el$, _el$2);
+    _$setProp(_el$, "flexDirection", "column");
+    _$setProp(_el$, "marginTop", 1);
+    _$setProp(_el$, "flexShrink", 0);
+    _$insertNode(_el$2, _el$3);
+    _$insertNode(_el$3, _$createTextNode(`Token Usage`));
+    _$insert(_el$, _$createComponent(Show, {
+      get when() {
+        return state().status !== "ready";
+      },
+      get children() {
+        var _el$5 = _$createElement("text");
+        _$insert(_el$5, status);
+        _$effect(_$p => _$setProp(_el$5, "fg", props.context.theme.text.muted, _$p));
+        return _el$5;
+      }
+    }), null);
+    _$insert(_el$, _$createComponent(For, {
+      get each() {
+        return rows();
+      },
+      children: (row, index) => (() => {
+        var _el$6 = _$createElement("box"),
+          _el$7 = _$createElement("text"),
+          _el$8 = _$createElement("text");
+        _$insertNode(_el$6, _el$7);
+        _$insertNode(_el$6, _el$8);
+        _$setProp(_el$6, "flexDirection", "row");
+        _$setProp(_el$6, "justifyContent", "space-between");
+        _$insert(_el$7, () => row[0]);
+        _$insert(_el$8, () => row[1]);
+        _$effect(_p$ => {
+          var _v$ = index() === performanceStart() ? 1 : 0,
+            _v$2 = props.context.theme.text.muted,
+            _v$3 = props.context.theme.text.muted;
+          _v$ !== _p$.e && (_p$.e = _$setProp(_el$6, "marginTop", _v$, _p$.e));
+          _v$2 !== _p$.t && (_p$.t = _$setProp(_el$7, "fg", _v$2, _p$.t));
+          _v$3 !== _p$.a && (_p$.a = _$setProp(_el$8, "fg", _v$3, _p$.a));
+          return _p$;
+        }, {
+          e: undefined,
+          t: undefined,
+          a: undefined
+        });
+        return _el$6;
+      })()
+    }), null);
+    _$effect(_$p => _$setProp(_el$2, "fg", props.context.theme.text.base, _$p));
+    return _el$;
+  })();
+}
+export default Plugin.define({
+  id: "opencode-token-usage.tui",
+  setup(context) {
+    const controllers = new Set();
+    const register = controller => {
+      controllers.add(controller);
+      return () => {
+        controllers.delete(controller);
+      };
+    };
+    const remove = context.ui.slot({
+      append: "sidebar.content",
+      render: props => _$createComponent(UsagePanel, {
+        context: context,
+        get sessionID() {
+          return props.sessionID;
+        },
+        register: register
+      })
+    });
+    // 2.0.9 SessionFrame never mounts the sidebar for a child session.
+    // Keep the same full panel visible through the supported composer slot.
+    const removeChild = context.ui.slot({
+      append: "session.composer.top",
+      render: props => _$createComponent(Show, {
+        get when() {
+          return context.data.session.get(props.sessionID)?.parentID;
+        },
+        get children() {
+          var _el$9 = _$createElement("box"),
+            _el$0 = _$createElement("box");
+          _$insertNode(_el$9, _el$0);
+          _$setProp(_el$9, "flexDirection", "row");
+          _$setProp(_el$9, "justifyContent", "flex-end");
+          _$setProp(_el$9, "paddingRight", 2);
+          _$setProp(_el$9, "flexShrink", 0);
+          _$setProp(_el$0, "width", 36);
+          _$setProp(_el$0, "maxWidth", "100%");
+          _$setProp(_el$0, "flexDirection", "column");
+          _$insert(_el$0, _$createComponent(UsagePanel, {
+            context: context,
+            get sessionID() {
+              return props.sessionID;
+            },
+            register: register
+          }));
+          return _el$9;
+        }
+      })
+    });
+    return () => {
+      for (const controller of controllers) controller.dispose();
+      controllers.clear();
+      remove();
+      removeChild();
+    };
+  }
+});

package/dist/usage.d.ts

@@ -0,0 +1,92 @@
+import type { PerformanceSummary } from "./performance.js";
+export interface Tokens {
+    input: number;
+    output: number;
+    reasoning: number;
+    cache: {
+        read: number;
+        write: number;
+    };
+}
+export interface TokenInput {
+    input?: number;
+    output?: number;
+    reasoning?: number;
+    cache?: {
+        read?: number;
+        write?: number;
+    };
+}
+export interface Price {
+    tier?: {
+        type: "context";
+        size: number;
+    };
+    input?: number;
+    output?: number;
+    cache?: {
+        read?: number;
+        write?: number;
+    };
+}
+export interface UsageMessage {
+    id: string;
+    type: string;
+    status?: string;
+    tokens?: TokenInput;
+    time?: {
+        created: number;
+        streamed?: number;
+        completed?: number;
+    };
+    content?: readonly UsageContent[];
+}
+export type UsageContent = {
+    type: "text";
+    text: string;
+} | {
+    type: "reasoning";
+    text: string;
+    time?: {
+        created: number;
+        completed?: number;
+    };
+} | {
+    type: "tool";
+    time: {
+        created: number;
+        ran?: number;
+        completed?: number;
+    };
+} | {
+    type: string;
+    text?: string;
+    time?: {
+        created: number;
+        completed?: number;
+    };
+};
+export declare function normalize(tokens?: TokenInput): Tokens;
+export declare const incoming: (t: Tokens) => number;
+export declare const total: (t: Tokens) => number;
+export declare function estimate(tokens: Tokens, prices?: readonly Price[]): {
+    cost: number;
+    defaultPrice: boolean;
+};
+export declare function summarize(messages: Iterable<UsageMessage>, prices?: readonly Price[]): {
+    tokens: Tokens;
+    total: number;
+    cacheRate: number;
+    cost: number;
+    defaultPrice: boolean;
+};
+export type Summary = ReturnType<typeof summarize>;
+export interface ContextUsage {
+    used: number;
+    limit: number;
+    percent: number;
+}
+export declare function contextUsage(messages: readonly UsageMessage[], limit?: number): ContextUsage | undefined;
+export declare function formatTokens(value: number): string;
+export declare const formatCost: (value: number) => string;
+export declare function usageRows(summary?: Summary, context?: ContextUsage, performance?: PerformanceSummary): readonly (readonly [string, string])[];

package/dist/usage.js

@@ -0,0 +1,89 @@
+const safe = (n) => n !== undefined && Number.isFinite(n) ? Math.max(0, n) : 0;
+export function normalize(tokens) {
+    return {
+        input: safe(tokens?.input), output: safe(tokens?.output), reasoning: safe(tokens?.reasoning),
+        cache: { read: safe(tokens?.cache?.read), write: safe(tokens?.cache?.write) },
+    };
+}
+export const incoming = (t) => t.input + t.cache.read + t.cache.write;
+export const total = (t) => incoming(t) + t.output + t.reasoning;
+// Matches OpenCode 2.0.9 SessionUsage.calculateCost: thresholds are exclusive.
+export function estimate(tokens, prices = []) {
+    const tier = prices.filter(p => p.tier && incoming(tokens) > p.tier.size)
+        .sort((a, b) => b.tier.size - a.tier.size)[0];
+    const price = tier ?? prices.find(p => !p.tier);
+    const rates = [price?.input, price?.output, price?.cache?.read, price?.cache?.write];
+    return {
+        cost: (tokens.input * safe(rates[0]) + (tokens.output + tokens.reasoning) * safe(rates[1])
+            + tokens.cache.read * safe(rates[2]) + tokens.cache.write * safe(rates[3])) / 1_000_000,
+        defaultPrice: rates.some(rate => rate === undefined || !Number.isFinite(rate) || rate < 0),
+    };
+}
+export function summarize(messages, prices = []) {
+    const tokens = normalize();
+    let cost = 0;
+    let defaultPrice = prices.length === 0;
+    for (const message of messages) {
+        if ((message.type !== "assistant" && message.type !== "compaction") || !message.tokens)
+            continue;
+        const t = normalize(message.tokens);
+        tokens.input += t.input;
+        tokens.output += t.output;
+        tokens.reasoning += t.reasoning;
+        tokens.cache.read += t.cache.read;
+        tokens.cache.write += t.cache.write;
+        const value = estimate(t, prices);
+        cost += value.cost;
+        defaultPrice ||= value.defaultPrice;
+    }
+    return { tokens, total: total(tokens), cacheRate: incoming(tokens) ? tokens.cache.read / incoming(tokens) : 0, cost, defaultPrice };
+}
+const usableLimit = (value) => value !== undefined && Number.isFinite(value) && value > 0;
+// Matches the OpenCode 2.0.10 sidebar: the last assistant message with tokens that follows
+// the last completed compaction carries the current context size. Running or failed
+// compactions do not reset it, and a last message without usage hides the row entirely
+// instead of falling back to pre-compaction history.
+export function contextUsage(messages, limit) {
+    if (!usableLimit(limit))
+        return undefined;
+    let boundary = -1;
+    for (let index = messages.length - 1; index >= 0; index--) {
+        const message = messages[index];
+        if (message.type === "compaction" && message.status === "completed") {
+            boundary = index;
+            break;
+        }
+    }
+    for (let index = messages.length - 1; index > boundary; index--) {
+        const message = messages[index];
+        if (message.type !== "assistant" || !message.tokens)
+            continue;
+        const used = total(normalize(message.tokens));
+        return used > 0 ? { used, limit, percent: used / limit * 100 } : undefined;
+    }
+    return undefined;
+}
+export function formatTokens(value) {
+    return Math.round(safe(value)).toLocaleString("en-US");
+}
+export const formatCost = (value) => value > 0 && value < 0.01 ? "<$0.01" : `$${safe(value).toFixed(2)}`;
+export function usageRows(summary, context, performance) {
+    const t = summary?.tokens;
+    const number = (value) => value === undefined ? "—" : formatTokens(value);
+    const rows = [];
+    if (context)
+        rows.push(["Context", `${formatTokens(context.used)} / ${formatTokens(context.limit)} (${context.percent.toFixed(1)}%)`]);
+    rows.push(["Input", number(t?.input)], ["Output", number(t?.output)], ["Reasoning", number(t?.reasoning)], ["Cache Read", number(t?.cache.read)]);
+    if (t && t.cache.write > 0)
+        rows.push(["Cache Write", number(t.cache.write)]);
+    rows.push(["Cache Rate", summary ? `${(summary.cacheRate * 100).toFixed(1)}%` : "—"], ["Total", number(summary?.total)]);
+    if (summary && summary.cost > 0)
+        rows.push(["Cost", formatCost(summary.cost)]);
+    if (performance?.tps !== undefined && Number.isFinite(performance.tps)) {
+        rows.push(["TPS", `${performance.tpsEstimated ? "~" : ""}${Math.max(0, performance.tps).toFixed(1)} tok/s`]);
+    }
+    if (performance?.ttft !== undefined && Number.isFinite(performance.ttft)) {
+        rows.push(["TTFT", `${(Math.max(0, performance.ttft) / 1_000).toFixed(1)}s`]);
+    }
+    return rows;
+}

package/docs/verification.md

@@ -0,0 +1,114 @@
+# 验证记录
+
+## v0.2.1（TPS 与 TTFT）
+
+验证日期：2026-09-20。环境：macOS、Node.js v22.23.2、npm 10.9.8、OpenCode v2.0.11；插件 SDK 依赖为 2.0.9。
+
+### 自动化检查
+
+| 检查 | 结果 |
+| --- | --- |
+| `npm run typecheck` | 通过 |
+| `npm test` | 29 项通过 |
+| `npm run build` | 通过，输出 ESM 与类型声明，包括 `dist/performance.js` |
+| `npm pack --dry-run` | 通过，`@chenlongapps/opencode-token-usage@0.2.1` 包含 19 个文件，压缩后约 20 KB |
+| `npm publish --dry-run` | 通过，完整执行 `prepublishOnly`、`prepack` 并确认 public access；未写入 registry |
+| `npm run test:smoke` | 通过，使用实际 `chenlongapps-opencode-token-usage-0.2.1.tgz` 安装产物 |
+
+npm 发布前检查确认无作用域名称 `opencode-token-usage` 已由其他作者占用，因此本项目使用尚未注册且与 GitHub 仓库所有者一致的 `@chenlongapps/opencode-token-usage`。包元数据、公开 registry、GitHub Actions CI、Trusted Publishing/OIDC 发布工作流与首次发布说明已配置；首次实际发布仍需 `chenlongapps` npm scope 的账号权限与双因素认证。`npm audit` 报告 2 个 low、11 个 moderate、0 个 high、0 个 critical，均来自固定的 OpenCode 2.0.9 / OpenTUI / OpenTelemetry 依赖链，当前锁定版本下没有可直接应用的完整修复。
+
+新增测试覆盖：已完成 assistant 的 Output + Reasoning / 流式总时长加权 TPS；无效时间、零输出与 compaction 排除；reasoning/tool 历史 TTFT、纯文本历史不伪造样本、运行期样本覆盖历史；文本、推理、工具输入三类流式增量；UTF-8 字节估算、重复事件去重、并发活动流合并；无关会话忽略、新建子代理即时纳入、切换会话树清理；流式更新不读取数据源，完成后从估算 TPS 收敛到精确 TPS；性能行位于用量与费用之后，与前一组间隔一行，并保持格式与缺失隐藏。
+
+### 真实 OpenCode 集成
+
+`scripts/smoke.mjs` 使用带固定延迟的本地 OpenAI 兼容流，在真实 OpenCode 服务和 160 × 54 TUI 中验证：
+
+- 空会话隐藏 TPS、TTFT、Context、Cache Write 与 Cost，不显示伪零性能值。
+- 第一段文本到达时，面板显示 `TPS ~2.4 tok/s` 与 `TTFT 0.4s`；`~` 明确表示按 UTF-8 字节估算的活动流速度。
+- assistant 完成并刷新快照后，TPS 自动变为无 `~` 的 `62.9 tok/s`。打包产物的 `historicalPerformance` 返回 62.893… tok/s，且同屏 OpenCode 自带消息状态也显示 62.9 tok/s。
+- 行顺序为 Context、五类 token、Cache Rate、Total、Cost、空行、TPS、TTFT；Cost 隐藏时仍在最后一条用量行后空一行。原有上下文、真实子代理全树累计与模型切换测试继续通过。
+- 安装包包含 `dist/performance.js` 及其类型声明；结果文件记录宿主版本 2.0.11、Total 5,080 和性能值。
+- scoped 包安装在 `node_modules/@chenlongapps/opencode-token-usage` 后，根入口、TUI 入口和所有运行时断言均通过。
+
+### 口径与验证边界
+
+- 精确 TPS 沿用 OpenCode 2 当前口径：全树可用 assistant 样本的 `Σ(Output + Reasoning) ÷ Σ(time.streamed - time.created)`；compaction 不参与。活动生成优先显示 UTF-8 增量按 4 字节/token 换算的估计值，多个活动流先合并 token 与时长再相除，最多每 100ms 发布一次且不触发完整快照读取。
+- TTFT 从 `session.step.started.data.started` 到首个 `session.text.delta`、`session.reasoning.delta` 或 `session.tool.input.delta`。运行期样本可精确测量；历史 reasoning/tool 内容可使用自身 `time.created`，纯文本历史缺少首 token 时间，故不纳入平均。
+- 2.0.11 的事件字段、流式显示、精确 TPS、子代理事件归属与打包加载已通过上述真实测试。SDK 仍固定 2.0.9；升级 SDK 或宿主到更高版本时仍需重新核对 step/delta 时间语义、compaction 排序和分叉副本规则。
+- 实时 TPS 是近似展示，中文、emoji、工具 JSON 等不同 UTF-8 字节分布会影响 4 字节/token 的误差；完成后以服务端真实 token 与时间替换。
+
+## v0.2.0（上下文用量）
+
+验证日期：2026-09-20。环境：macOS、Node.js v22.23.2、npm 10.9.8、OpenCode v2.0.10；插件 SDK 依赖为 2.0.9。
+
+### 自动化检查
+
+| 检查 | 结果 |
+| --- | --- |
+| `npm run typecheck` | 通过 |
+| `npm test` | 23 项通过 |
+| `npm run build` | 通过，输出 ESM 与类型声明 |
+| `npm run test:smoke` | 通过，使用实际 `.tgz` 安装产物 |
+
+新增测试覆盖：上下文取五类 token 之和、压缩边界（`completed` 重置窗口，`running` 与 `failed` 不重置）、跳过没有上报用量的消息、未知上限（缺失、零、负数、NaN、Infinity）隐藏、百分比超过 100%、上下文行位于面板第一行且百分比同行；视图消息顺序与被查看会话隔离；模型切换后重新读取上限；刷新失败时保留上次上下文并标注未更新。
+
+### 真实 OpenCode 集成
+
+`scripts/smoke.mjs` 沿用 v0.1.0 的隔离方式，并新增上下文断言：
+
+- 空会话：面板保持 Input、Output、Reasoning、Cache Read、Cache Rate、Total 六行零值，不出现 `/ 128,000`、Context 行、Cache Write 与 Cost。
+- 首条 assistant 完成后：`Context  1,270 / 128,000 (1.0%)`，且该行出现在 `Input` 行之上（终端逐行比对行号）。同一时刻宿主自带侧边栏为 `Context 1,270 tokens 1% used`，用量与插件一致（宿主百分比取整，插件保留一位小数）。
+- 子代理视图：树的累计 `Total 5,080`，而上下文仍为 `1,270 / 128,000 (1.0%)`，确认上下文只反映被查看会话、不随子树累计。
+- 切换到 `usage-test/large`（夹具上限 32,000）后无需新消息即同步：`Context 1,270 / 32,000 (4.0%)`。
+- 打包产物导出的 `contextUsage` / `viewedMessages` 直接断言为 `used 1270`、`limit 128000`、`percent 1.0`。
+
+### 接口适配与验证边界
+
+- 上下文口径参照 OpenCode 2.0.10 打包产物的侧边栏实现（`Ws`/`S6`）：最后一次 `completed` 压缩之后、最后一条带 `tokens` 的 assistant 消息的五类 token 之和。SDK 依赖仍为 2.0.9，2.0.9 宿主未单独核对这一显示算法。
+- 宿主 `Ws` 还使用 `session.revert` 作为搜索上界；本版本不读取 revert 状态，回退会话的取值可能与宿主不同。
+- 分母使用被查看会话的**活动模型**，而不是产生该用量的消息自身记录的模型；会话中途切换模型后两者可能不同。
+- Cost 与上下文上限使用同一活动模型解析规则，同样不使用消息自身记录的 `model` 字段：混合模型会话的 Cost 按查看时活动模型统一重算，不等于各模型实际账单之和。真实集成只验证了单夹具模型下的价格重算，混合模型的失真未单独断言。
+- 不显示进度条，上下文百分比与用量同行；行值加标签约 31 字符，窄侧边栏可能换行，响应式布局留待 v0.3.0。
+- 夹具 `usage-test/large` 的上下文上限改为 32,000 以便观测模型切换，`usage-test/small` 保持 128,000。
+
+## v0.1.0
+
+验证日期：2026-09-19。环境：macOS、Node.js v22.23.2、npm 10.9.8、OpenCode v2.0.10；插件 SDK 依赖为 2.0.9。
+
+### 自动化检查
+
+| 检查 | 结果 |
+| --- | --- |
+| `npm run typecheck` | 通过 |
+| `npm test` | 18 项通过 |
+| `npm run build` | 通过，输出 ESM 与类型声明 |
+| `npm run test:smoke` | 通过，使用实际 `.tgz` 安装产物 |
+
+单元及组件逻辑测试覆盖五类 token、零值和缺失字段、缓存命中率、逗号分组与四舍五入边界、普通及缓存价格、推理费用、价格阶梯的严格阈值、免费模型、缺失价格、模型重算、多层后代、历史分页、compaction、继承历史去重、重复事件、请求隔离、卸载、读取失败与恢复。
+
+游标适配还有独立回归测试：后续消息页不得重新传入 `order`；子会话游标自身包含 `parentID` 过滤条件。
+
+### 真实 OpenCode 集成
+
+`scripts/smoke.mjs` 在独立临时目录中执行 `npm pack` 与 `npm install`，使用安装后的根目录入口加载插件。真实 OpenCode 服务通过本地 OpenAI 兼容模拟端点生成消息，并调用内置 subagent 工具创建子代理。推理返回是固定测试数据，不是付费模型响应。
+
+Python 3 为真实 TUI 提供 160 × 54 的伪终端，终端输出经 xterm 解析后进行断言并保存文本和 ANSI 捕获。
+
+已验证：
+
+- 主插件激活、TUI 插件加载；安装包包含根目录 `index.js` / `tui.js`、编译产物及类型声明。
+- 空会话隐藏零值的 Cache Write 与 Cost；基础统计行、宿主标题、Context 与费用区继续保留。
+- 首条 assistant 完成后无需重新进入会话即可刷新：Input 100、Output 50、Reasoning 20、Cache Read 1,000、Cache Write 100，Total 1,270。
+- 父会话三条 assistant 消息和一个真实子代理的一条消息共同累计为 Total 5,080，显示为 `5,080`。
+- 父视图与子代理视图都显示 Input 400、Output 200、Reasoning 80、Cache Read 4,000、Cache Write 400、Cache Rate 83.3%。
+- 切换根会话活动模型后，重新读取 `usage-test/large` 的价格并重算费用；模型切换费用重算另有数值单元断言。
+
+### 接口适配与验证边界
+
+- 2.0.10 的本地目录加载器通过根部 `index` / `tui` 文件发现入口，仅有 package exports 不足以加载本地目录，因此包包含转发入口；2.0.9 兼容性也已验证。
+- 2.0.10 在子代理视图中不挂载侧边栏；通过官方 `session.composer.top` 插槽显示同一完整面板；2.0.9 兼容性也已验证。
+- 完整历史使用 `message.list`，不使用会在压缩后截断历史的 `session.context`。
+- 分叉副本识别依赖 2.0.9 的消息 ID 后缀约定；更高 OpenCode 版本尚未验证。
+- 多层分页、压缩与分叉去重、故障恢复由自动化逻辑测试覆盖；真实 TUI 验证覆盖加载、正常消息、一级真实子代理和模型切换。
+
+重现时运行 README 中的检查命令。烟雾测试会输出临时产物目录，包含 `result.json`、`plugins.json`、各阶段终端捕获和已隐藏服务器密码的日志。

package/index.js

@@ -0,0 +1,2 @@
+// OpenCode 2.0.9 resolves local directory plugins by their root index/tui files.
+export { default } from "./dist/index.js";

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "@chenlongapps/opencode-token-usage",
+  "version": "0.2.1",
+  "description": "Session-tree token usage, live performance, context window and estimated cost for OpenCode 2",
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "token-usage",
+    "context-window",
+    "tps",
+    "ttft",
+    "cost"
+  ],
+  "homepage": "https://github.com/chenlongapps/opencode-token-usage#readme",
+  "bugs": {
+    "url": "https://github.com/chenlongapps/opencode-token-usage/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chenlongapps/opencode-token-usage.git"
+  },
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "index.js",
+    "tui.js",
+    "dist",
+    "README.md",
+    "ROADMAP.md",
+    "docs/verification.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./tui": {
+      "types": "./dist/tui.d.ts",
+      "import": "./dist/tui.js"
+    }
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "typecheck": "tsc --noEmit",
+    "test": "tsx --test test/*.test.ts",
+    "test:smoke": "node scripts/smoke.mjs",
+    "prepublishOnly": "npm run typecheck && npm test",
+    "prepack": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@opencode/plugin": "2.0.9"
+  },
+  "peerDependencies": {
+    "@opentui/core": "0.5.10",
+    "@opentui/solid": "0.5.10",
+    "solid-js": ">=1.9.0"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.28.0",
+    "@opencode/client": "2.0.9",
+    "@opencode/schema": "2.0.9",
+    "@opencode/theme": "2.0.9",
+    "@opentui/core": "0.5.10",
+    "@opentui/solid": "0.5.10",
+    "@types/node": "^22.0.0",
+    "@xterm/headless": "6.0.0",
+    "babel-preset-solid": "1.9.12",
+    "solid-js": "1.9.12",
+    "tsx": "^4.20.0",
+    "typescript": "^5.9.0"
+  },
+  "packageManager": "npm@10.9.8"
+}

package/tui.js

@@ -0,0 +1 @@
+export { default } from "./dist/tui.js";