opencode-tokenwatch 0.5.0 → 0.6.0

package/dist/kernel/perf-aggregate.d.ts

@@ -0,0 +1,62 @@
+/**
+ * 性能聚合核心 —— perf 追踪器（内存）、持久化统计（store）、报告聚合（report）
+ * 三处共用的 Welford 增量聚合 + Reservoir 分位数采样。
+ *
+ * 口径约定（与宿主官方对齐，详见 AGENTS.md）：
+ * - tokenTotal 五分量：input + output + reasoning + cache.read + cache.write
+ * - TPS：可见输出 tokens / (流式终点 − 流式窗口起点)，单位 tok/s
+ * - TTFT：首个"首 token"锚点（可见输出 part / delta）− 请求起点
+ * - latency：端到端 completed − created（含收尾 settlement）
+ */
+import type { LogEntry, ModelPerfStats } from "./format.js";
+/** 线性插值百分位数，输入须为升序数组 */
+export declare function computePercentile(sortedArr: number[], p: number): number | null;
+/** 每 marker 最多保留的原始样本数（Reservoir Sampling，内存有界） */
+export declare const RESERVOIR_SIZE = 500;
+/**
+ * Reservoir Sampling：保证每个观测值以相同概率进入样本（算法 R 变体），
+ * 使分位数估算在统计意义上无偏。
+ */
+export declare function reservoirAdd(reservoir: number[], value: number, totalCount: number): number[];
+/** 单模型聚合累加器（内存态；持久化层可直接序列化本结构） */
+export interface ModelAccumulator {
+    model: string;
+    providerID: string;
+    requestCount: number;
+    ttftCount: number;
+    tpsCount: number;
+    latencyCount: number;
+    totalInput: number;
+    totalOutput: number;
+    totalCacheRead: number;
+    totalCacheWrite: number;
+    totalCost: number;
+    avgTTFT: number | null;
+    maxTTFT: number | null;
+    minTTFT: number | null;
+    avgTPS: number | null;
+    maxTPS: number | null;
+    minTPS: number | null;
+    avgLatency: number | null;
+    maxLatency: number | null;
+    minLatency: number | null;
+    /** TTFT / 端到端延迟原始样本（Reservoir，用于分位数） */
+    ttftReservoir: number[];
+    latencyReservoir: number[];
+    /** 最近一次请求值（侧边栏与宿主 footer 单次口径对照） */
+    lastTTFT: number | null;
+    lastTPS: number | null;
+    lastLatency: number | null;
+}
+export declare function createAccumulator(model: string, providerID: string): ModelAccumulator;
+/**
+ * 把一条日志条目增量并入累加器。
+ *
+ * 均值用 Welford 在线算法；分母是各自的**有效样本数**
+ * （ttftCount/tpsCount/latencyCount），缺失指标的请求不会拉低均值。
+ * 全零 token（五分量均为 0）的失败请求被跳过 —— 与宿主官方
+ * `tokenTotal(msg) <= 0 continue` 的过滤口径一致（含 reasoning）。
+ */
+export declare function accumulateEntry(acc: ModelAccumulator, entry: LogEntry): void;
+/** 聚合累加器 → 对外输出的 ModelPerfStats（分位数在此计算） */
+export declare function finalizeAccumulator(acc: ModelAccumulator): ModelPerfStats;

package/dist/{perf-tracker.d.ts → kernel/perf.d.ts}

@@ -1,4 +1,4 @@
-import type { LogEntry, SessionPerfStats } from "./formatter.js";
+import type { LogEntry, SessionPerfStats } from "./format.js";
 interface PartEvent {
     message_id?: string;
     type?: string;
@@ -39,22 +39,28 @@ interface MessageRemoveEvent {
     };
 }
 declare class PerfTracker {
+    /** 最早的任意 part（含 step 起点）—— 用作 TPS 的流式窗口起点（对齐宿主官方口径） */
     private firstPartTimes;
+    /** 最早的输出 part（text/reasoning）—— 用作 TTFT（用户等待首个可见 token 的时间） */
+    private firstOutputTimes;
     private statsMap;
-    /** 原始样本串，用于分位数计算，不持久化 */
-    private ttftSamples;
-    private latencySamples;
+    /** 会话加载令牌：异步重放期间再次切会话时，旧加载结果按令牌过期丢弃 */
+    private loadToken;
     handlePartUpdated(event: PartEvent): void;
     handleMessageUpdated(event: MessageUpdateEvent): void;
     private appendLog;
     handleMessageRemoved(event: MessageRemoveEvent): void;
     private updateStats;
-    /** 计算有序数组的指定百分位数（线性插值法） */
-    private percentile;
     getSessionStats(): SessionPerfStats;
     readLogs(last?: number): LogEntry[];
     reset(): void;
-    loadSession(sessionID: string): void;
+    /**
+     * 切换会话：清空内存态后异步重放该会话的 JSONL 历史。
+     *
+     * 异步化是为了不阻塞 TUI 渲染线程（5MB 日志的同步读可达数十毫秒）；
+     * 重放完成前若又切换了会话，由 loadToken 令牌丢弃过期结果。
+     */
+    loadSession(sessionID: string): Promise<void>;
 }
 export declare function createPerfTracker(): PerfTracker;
 export type { PartEvent, PerfTracker };

package/dist/{generate-usage-html.d.ts → kernel/report-html.d.ts}

@@ -1,2 +1,2 @@
-import type { CombinedReportData } from "./formatter.js";
+import type { CombinedReportData } from "./format.js";
 export declare function generateUsageHtml(data: CombinedReportData): string;

package/dist/kernel/report.d.ts

@@ -0,0 +1,19 @@
+import type { CombinedReportData, UsageFilters, UsageReport } from "./format.js";
+/** 本地时区 YYYY-MM-DD（toISOString 按 UTC，跨时区会偏一天）—— 全项目统一日期出口 */
+export declare function localDateStr(d: Date): string;
+/** 报告输出目录（~/.opencode/reports） */
+export declare function ensureReportDir(): string;
+/** 用系统默认程序打开文件（多平台，失败静默；spawn detached 不阻塞 TUI） */
+export declare function openInBrowser(filePath: string): void;
+export declare function getRangeSlug(filters: UsageFilters, presetTag?: string): string;
+/** 生成不覆盖已有文件的报告路径（同名追加时间戳，仍冲突则递增后缀） */
+export declare function generateUniqueReportPath(dir: string, rangeSlug: string): string;
+/**
+ * 装配完整报告数据。
+ *
+ * `usage` 由宿主数据源提供（v1 走 SQL、v2 走客户端遍历），
+ * 其余全部来自内核，因此两代宿主产出的报告结构完全一致。
+ */
+export declare function buildCombinedData(usage: Omit<UsageReport, "filters">): CombinedReportData;
+/** 生成 HTML 报告并写入磁盘，返回文件路径 */
+export declare function writeHtmlReport(data: CombinedReportData, rangeSlug: string): string;

package/dist/{stats-store.d.ts → kernel/store.d.ts}

@@ -7,17 +7,17 @@
  * - 百分位数采用 Reservoir Sampling 保持有界内存占用
  * - 首次启动时自动从现有 JSONL 日志迁移，不丢失历史数据
  */
-import type { LogEntry, ModelPerfStats } from "./formatter.js";
+import type { LogEntry, ModelPerfStats } from "./format.js";
 /**
  * 将一条新的日志条目增量更新到持久化统计文件。
- * 在 perf-tracker.ts 的 appendLog() 之后调用。
+ * 在 perf-tracker 的 appendLog() 之后调用。
  *
- * 设计原则：本函数只做增量更新，迁移逻辑由 readPersistedStats() 负责。
- * 这样可以避免迁移与增量更新之间的竞态问题。
+ * 增量先累积在内存副本上（至多每 WRITE_COALESCE_MS 落盘一次），
+ * 进程正常退出时由 exit 钩子强制刷盘。
  */
 export declare function updatePersistedStats(entry: LogEntry): void;
 /**
  * 读取所有持久化统计，返回 ModelPerfStats 数组（含分位数）。
- * 用于 HTML 报告生成，替代 aggregatePerfStats(readLogs(N)) 的有限窗口方案。
+ * 用于 HTML 报告生成，替代有限窗口的日志聚合方案。
  */
 export declare function readPersistedStats(): ModelPerfStats[];

package/dist/server.d.ts

@@ -1,5 +1,15 @@
 import type { PluginModule } from "@opencode-ai/plugin";
+/**
+ * Server 插件入口。
+ *
+ * v1 契约禁止 server 与 tui 同时出现，因此 TUI 入口在 ./tui（dist/tui.js）。
+ * 这里额外携带 setup，使 opencode2 在以包主入口解析时也能找到 v2 入口：
+ * - v1 加载器忽略多余字段，不受影响
+ * - setup 内部用动态 import 惰性加载 TUI 装配代码，
+ *   避免 server 进程在加载阶段就解析 @opentui 依赖
+ */
 declare const plugin: PluginModule & {
     id: string;
+    setup?: (ctx: any) => Promise<(() => void) | void>;
 };
 export default plugin;

package/dist/server.js

@@ -3,6 +3,10 @@ var plugin = {
   id: "opencode-tokenwatch",
   server: async () => {
     return {};
+  },
+  setup: async (ctx) => {
+    const mod = await import("./tui.js");
+    return mod.default.setup?.(ctx);
   }
 };
 var server_default = plugin;

package/dist/tui.d.ts

@@ -1,17 +1,16 @@
+/** @jsxImportSource @opentui/solid */
+/**
+ * 分发入口 —— 单一包体同时服务两代宿主。
+ *
+ * default export 同时携带 `tui` 与 `setup`：
+ * - opencode 1.x 加载后调用 `tui(api)`（v1 加载器只认 tui，忽略 setup）
+ * - opencode2 加载后调用 `setup(ctx)`（v2 校验只查 id + setup，忽略 tui）
+ *
+ * 宿主调用哪个入口，本身就是 100% 可靠的代际判断，无需任何启发式探测。
+ */
 import type { TuiPluginModule } from "@opencode-ai/plugin/tui";
-export interface TokenMessage {
-    id: string;
-    sessionID: string;
-    providerID: string;
-    modelID: string;
-    inputTokens: number;
-    outputTokens: number;
-    reasoningTokens: number;
-    cacheRead: number;
-    cacheWrite: number;
-    cost: number;
-}
 declare const plugin: TuiPluginModule & {
     id: string;
+    setup?: (ctx: any) => (() => void) | void;
 };
 export default plugin;