@jack-yang/pi-tps-meter 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## [0.1.1] - 2026-11-03
+
+- Published from GitHub Actions through npm Trusted Publishing, so this and later versions
+  carry a signed provenance attestation linking the package to its source commit.
+- No functional changes.
+
+## [0.1.0] - 2026-11-03
+
+- Initial release: port of opencode-tps-meter to pi 1.5.0.
+- Live TPS (5s sliding window, ~10Hz), session AVG and TTFT, colour-coded by tier.
+- Calibration of the UTF-8 byte estimate against `usage.output` (median of the last 10 ratios).
+- `/tps` cycles status → widget → off; `/tps status|widget|off` sets the mode. The mode is
+  persisted in `~/.pi/agent/pi-tps-meter/config.json`, which also takes tier overrides.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jack Yang
+
+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

@@ -1,3 +1,163 @@
-# Temporary Holding Version
+# pi-tps-meter
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm version](https://img.shields.io/npm/v/@jack-yang/pi-tps-meter)](https://www.npmjs.com/package/@jack-yang/pi-tps-meter) [![license](https://img.shields.io/npm/l/@jack-yang/pi-tps-meter)](./LICENSE) [![CI](https://github.com/yangwudong/pi-tps-meter/actions/workflows/ci.yml/badge.svg)](https://github.com/yangwudong/pi-tps-meter/actions/workflows/ci.yml) ![pi](https://img.shields.io/badge/pi-%E2%89%A5%201.5.0-blue)
+
+为 [pi coding agent](https://pi.dev) 实时显示 token 生成速度的扩展：**TPS**（当前速度）、**AVG**（会话均值）、**TTFT**（首 token 延迟），并用模型返回的权威 token 数自动校准，中文内容下读数也可信。
+
+移植自 [opencode-tps-meter](https://github.com/yangwudong/opencode-tps-meter)：测量核心（5 秒滑动窗口、权威 token 校准、AVG 口径）与分档配色和原版一致，只替换了宿主事件层和渲染层。
+
+## 显示效果
+
+```
+TPS 42.5 | AVG 38.2 | TTFT 0.8s
+```
+
+底部状态条（`/tps status`，默认），流式输出中：
+
+![底部状态条模式：流式输出中，TPS 40.8 / AVG 39.8 / TTFT 2.0s](https://raw.githubusercontent.com/yangwudong/pi-tps-meter/main/docs/screenshot-status.png)
+
+编辑器上方组件（`/tps widget`）：
+
+![编辑器上方组件模式：TPS 40.2 / AVG 38.1 / TTFT 3.2s](https://raw.githubusercontent.com/yangwudong/pi-tps-meter/main/docs/screenshot-widget.png)
+
+- **TPS**：流式输出时的实时速度，基于 5 秒滑动窗口，约 10Hz 刷新；超过 1.5 秒没有新 token 时显示 `--`。
+- **AVG**：会话级累计平均。所有已完成消息的权威 token 数之和，除以各消息生成时长之和。
+- **TTFT**：从本轮请求开始到第一个文本或思考 token 的时间。首个 token 到达立即显示，一直保留到下一次生成开始。
+
+流结束后 AVG / TTFT 摘要不会清空：工具执行期间、等待下一轮响应期间都保持可见，下一条助手消息开始时才更新。
+
+## 颜色
+
+**TPS / AVG**（越高越好）
+
+| 档位 | 范围（tok/s） | 颜色 |
+|---|---|---|
+| slow | < 20 | 红 |
+| normal | 20–50 | 黄 |
+| fast | 50–100 | 绿 |
+| faster | ≥ 100 | 青 |
+
+**TTFT**（越低越好）
+
+| 档位 | 范围 | 颜色 |
+|---|---|---|
+| fast | < 10s | 绿 |
+| ok | 10–20s | 黄 |
+| slow | ≥ 20s | 红 |
+
+档位下界包含在内：恰好 20 TPS 算 normal，恰好 10s 算 ok。阈值可以在配置文件里改。标签和 `--` 用暗色显示。
+
+## 安装
+
+```bash
+pi install npm:@jack-yang/pi-tps-meter     # 从 npm 安装（推荐）
+pi install /path/to/pi-tps-meter           # 本地目录：不复制，直接从该路径加载
+pi -e npm:@jack-yang/pi-tps-meter          # 只在本次启动试用，不写入 settings
+```
+
+安装后重启 pi，或在已打开的会话里执行 `/reload`。以后升级用 `pi update --extensions`。npm 版和本地目录版只装一个，两个都装会出现两条读数，命令也会变成 `/tps:1` 和 `/tps:2`。
+
+本地目录请用不带 `npm:` 前缀的路径形式。`pi install npm:./pi-tps-meter` 在 pi 1.5.0 下能装上，但加载不了：pi 按 `npm:` 后面的字符串推算安装目录，路径形式的 spec 永远对不上 `node_modules/@jack-yang/pi-tps-meter`；而且这个相对路径会原样写进 settings，下次启动时 pi 会在新的工作目录下重装并失败。
+
+环境要求：pi ≥ 1.5.0（已在 1.5.0 实测）。没有运行时依赖，也不发起任何网络请求。
+
+## 命令
+
+| 命令 | 作用 |
+|---|---|
+| `/tps` | 循环切换 status → widget → off |
+| `/tps status` | 显示在底部状态条（footer），和其他扩展的状态共用一行 |
+| `/tps widget` | 显示为编辑器上方的单行组件 |
+| `/tps off` | 完全隐藏。计量仍在后台进行，切回来立即显示当前读数 |
+
+模式写入配置文件，下次启动沿用。
+
+## 配置
+
+配置文件位于 `~/.pi/agent/pi-tps-meter/config.json`；设置了 `PI_CODING_AGENT_DIR` 时，位于该目录下的 `pi-tps-meter/config.json`。
+
+```json
+{
+  "mode": "status",
+  "tiers": {
+    "tps":  { "slow": 20, "normal": 50, "fast": 100 },
+    "ttft": { "fast": 10000, "ok": 20000 }
+  }
+}
+```
+
+| 键 | 默认值 | 说明 |
+|---|---|---|
+| `mode` | `"status"` | `status` / `widget` / `off`。`/tps` 只改写这个键，其他内容原样保留 |
+| `tiers.tps` | `{ slow: 20, normal: 50, fast: 100 }` | TPS 与 AVG 的分档阈值（tok/s） |
+| `tiers.ttft` | `{ fast: 10000, ok: 20000 }` | TTFT 分档阈值（毫秒） |
+
+- 所有键都可省略，按字段覆盖默认值，例如只写 `{ "tiers": { "tps": { "fast": 80 } } }`。不是数字的值会被忽略。
+- 文件在会话启动时读取，手动修改后执行 `/reload` 生效。
+- 文件无法解析时，使用默认值并给出提示；这种情况下 `/tps` 也不会覆盖它。
+
+## 工作原理
+
+### TPS
+
+每个流式 delta（text、thinking、toolcall 三种都算）按 UTF-8 字节数 ÷ 4 估算 token 数，记入 5 秒滑动窗口：
+
+```
+TPS = 窗口内估算 token 之和 × 校准因子 ÷ (当前时间 − 窗口内最早样本)
+```
+
+时长下限是 1 秒，避免刚开始的一两个 chunk 显示成尖峰；最后一个样本已经超过 1.5 秒时不显示。跨度用墙钟时间计算，不累加 delta 之间的间隔，因为网络会把多个 token 打包到达，间隔之和会让速率虚高。
+
+### 校准
+
+字节 ÷ 4 对中文偏差很大（一个汉字占 3 字节）。每条消息结束时，用 pi 给出的权威输出 token 数（`usage.output`）除以这条消息的累计估算值，得到一个比率（限制在 0.3–3.0 之间）。扩展保留最近 10 个比率，取**中位数**作为校准因子，用于之后消息的实时速率；第一条消息结束之前，因子是 1.0。
+
+实测（GLM-5.3-Flash，400–500 字中文短文）：未校准时实时 TPS 偏高 17%–30%；校准一轮之后，按校准因子换算的整条消息 token 数与权威值相差 +1%～+12%。
+
+### AVG
+
+```
+AVG = Σ 权威 token 数 ÷ Σ (最后一个 delta − 第一个 delta)
+```
+
+只统计已完成的消息，单条消息的时长下限为 1 秒，所以 TTFT 等待和工具执行时间都不计入。出错或被中断的消息（`usage` 不完整）不计入 AVG，也不参与校准。
+
+### TTFT
+
+TTFT 从 `turn_start` 开始计时（在 pi 里，一个 turn 就是一次模型请求），到这条消息的第一个 text 或 thinking delta 为止。toolcall delta 不会结束 TTFT 等待，但会计入 TPS。只调用工具、没有任何文本或思考输出的消息，TTFT 显示 `--`。
+
+为什么不从 `message_start` 开始算：pi 收到 HTTP 响应头之后才发出 `message_start`，而多数服务端要排完队、做完 prefill 才返回响应头。实测中，响应头在请求发出约 2 秒后才到，`message_start` 和第一个 delta 落在同一毫秒；从 `message_start` 算，TTFT 几乎永远是 0。
+
+### 工具调用
+
+工具在两条助手消息之间执行。每条消息结束时清空滑动窗口，所以工具耗时不会摊进下一条消息的速率。
+
+## 与 opencode-tps-meter 的差异
+
+- TTFT 起点用 `turn_start`，对应原版的 `session.step.started`（模型调用开始）。
+- 下一条助手消息开始时清空 TTFT，原版要等到下一个首 token 才覆盖。
+- toolcall delta 计入 TPS 和校准，因为 pi 的 `usage.output` 包含工具调用参数的 token；原版只统计文本和推理。TTFT 仍然只认文本和思考。
+- 权威 token 数直接用 `usage.output`：pi 的 output 已经包含推理 token，原版需要把 output 和 reasoning 相加。
+- 没有移植思考粒子动画，pi 自带工作指示器。
+- 颜色用 ANSI 基本色：红 31、黄 33、绿 32、青 36，标签用暗色；原版用的是 opencode 主题槽位。
+
+## 已知限制
+
+- **不流式输出的推理**：有些模型按推理 token 计费，但不把推理内容流式发出来。这时校准比率会顶到 3.0 上限，AVG 也会偏高（原版同样如此）。
+- **一次性返回工具参数的 provider**（如 Gemini）：消息末尾会出现一个短暂的 TPS 尖峰，消息结束后立即清除。
+- **底部状态条依赖 pi 的默认 footer**：如果另一个扩展换掉了 footer，并且不渲染扩展状态（比如 awesome-pi-themes 的 look-pack），请改用 `/tps widget`。
+- **AVG 和校准只在当前会话内累计**：`/new`、`/resume`、`/fork`、`/reload` 会重新开始；不会从历史记录里重建。
+- **TTFT 包含客户端准备时间**：包括请求前的上下文处理（实测约 7ms）和 provider 层的自动重试等待，也就是用户实际等待的时间。
+- **时间戳取自 pi 把事件派发给扩展的时刻**：其他扩展的慢 handler 会推迟派发，从而影响读数。
+
+## 开发
+
+```bash
+npm test                            # node --test，不需要安装依赖（Node ≥ 22.19）
+npm install && npm run typecheck    # 可选：tsc 严格检查，会装上 pi 作为 peer 依赖以获得类型
+pi -e .                             # 在真实会话中试用
+```
+
+## 许可证
+
+MIT

package/extensions/index.ts

@@ -0,0 +1,160 @@
+// pi-tps-meter — live TPS / AVG / TTFT for the pi coding agent.
+//
+// Port of opencode-tps-meter: the measurement core (src/core.ts) and the formatting
+// (src/format.ts) are the original's. This file is the replaced host layer: pi events in,
+// a footer status line or a widget above the editor out.
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent"
+import { DISPLAY_MODES, isDisplayMode, loadConfig, nextMode, resolveConfig, saveMode, type DisplayMode, type MeterConfig } from "../src/config.ts"
+import { abandonMessage, completeMessage, createMeterState, readMeter, recordDelta, startMessage, startTurn, type DeltaKind, type MeterState } from "../src/core.ts"
+import { renderLine } from "../src/format.ts"
+
+// One key for both surfaces: the footer status entry and the widget.
+const KEY = "tps-meter"
+
+// ~10Hz: smooth enough for a rolling number without re-rendering on every delta.
+const REFRESH_MS = 100
+
+type UI = ExtensionContext["ui"]
+
+export default function tpsMeter(pi: ExtensionAPI): void {
+  let state: MeterState = createMeterState()
+  // Defaults until session_start reads the file: the factory may run in invocations that never
+  // start a session, so it does no IO and starts no timers.
+  let config: MeterConfig = resolveConfig(undefined)
+  let ui: UI | undefined
+  let color = false
+  let ticker: ReturnType<typeof setInterval> | undefined
+  // What is on screen right now, so unchanged readings cost no re-render.
+  let shownMode: DisplayMode | undefined
+  let shownLine: string | undefined
+
+  // Handlers re-bind from their own ctx; the ticker only ever uses the latest binding.
+  const bind = (ctx: ExtensionContext): void => {
+    ui = ctx.hasUI ? ctx.ui : undefined
+    // The TUI renders ANSI in status text and widget lines; RPC clients get plain text.
+    color = ctx.mode === "tui"
+  }
+
+  const render = (): void => {
+    if (!ui) return
+    const mode = config.mode
+    if (mode !== shownMode) {
+      // Exactly one surface (or none) shows the meter: clear the one being left.
+      if (shownMode === "status") ui.setStatus(KEY, undefined)
+      if (shownMode === "widget") ui.setWidget(KEY, undefined)
+      shownMode = mode
+      shownLine = undefined
+    }
+    if (mode === "off") return
+    const line = renderLine(readMeter(state, Date.now()), config.tiers, color)
+    if (line === shownLine) return
+    shownLine = line
+    if (mode === "status") ui.setStatus(KEY, line)
+    else ui.setWidget(KEY, [line])
+  }
+
+  const stopTicker = (): void => {
+    if (ticker === undefined) return
+    clearInterval(ticker)
+    ticker = undefined
+  }
+
+  // Ticks only while a message streams: that is the only time the reading changes by itself
+  // (the window slides, STALE_MS expires). Between messages the line is static.
+  const startTicker = (): void => {
+    if (ticker !== undefined || !ui || config.mode === "off" || !state.streaming) return
+    ticker = setInterval(() => {
+      render()
+      if (!state.streaming || config.mode === "off") stopTicker()
+    }, REFRESH_MS)
+    // Never the reason the process stays alive.
+    ticker.unref?.()
+  }
+
+  pi.on("session_start", (_event, ctx) => {
+    stopTicker()
+    state = createMeterState()
+    const loaded = loadConfig()
+    config = loaded.config
+    shownMode = undefined
+    shownLine = undefined
+    bind(ctx)
+    if (loaded.warning) ui?.notify(`tps-meter: config ignored, using defaults (${loaded.warning})`, "warning")
+    render()
+  })
+
+  pi.on("turn_start", (event) => {
+    startTurn(state, Number.isFinite(event.timestamp) ? event.timestamp : Date.now())
+  })
+
+  pi.on("message_start", (event, ctx) => {
+    if (event.message.role !== "assistant") return
+    bind(ctx)
+    startMessage(state, Date.now())
+    startTicker()
+  })
+
+  pi.on("message_update", (event) => {
+    const ev = event.assistantMessageEvent
+    let kind: DeltaKind
+    switch (ev.type) {
+      case "text_delta": kind = "text"; break
+      case "thinking_delta": kind = "thinking"; break
+      case "toolcall_delta": kind = "toolcall"; break
+      default: return
+    }
+    // The first text/thinking token shows TTFT at once instead of on the next tick.
+    if (recordDelta(state, Date.now(), ev.delta, kind)) render()
+  })
+
+  pi.on("message_end", (event, ctx) => {
+    const message = event.message
+    if (message.role !== "assistant") return
+    bind(ctx)
+    if (message.stopReason === "error" || message.stopReason === "aborted") abandonMessage(state)
+    else completeMessage(state, message.usage?.output ?? 0)
+    stopTicker()
+    render()
+  })
+
+  // The summary (AVG, TTFT) outlives the stream and stays as it is through tool runs and the
+  // wait for the next response. turn_end only re-asserts it; it never clears it.
+  pi.on("turn_end", (_event, ctx) => {
+    bind(ctx)
+    render()
+  })
+
+  pi.on("session_shutdown", () => {
+    // pi resets extension UI itself when it reloads or replaces the runtime; the timer and the
+    // reference to this session's UI are the only things left for us to drop.
+    stopTicker()
+    ui = undefined
+  })
+
+  pi.registerCommand("tps", {
+    description: "TPS meter display: /tps cycles status → widget → off, /tps status|widget|off sets it",
+    getArgumentCompletions: (prefix) => {
+      // Only strict prefixes: pi's editor makes Enter apply an open argument completion instead
+      // of submitting, so a fully typed mode must close the popup or `/tps off` needs two Enters.
+      const typed = prefix.trim().toLowerCase()
+      const items = DISPLAY_MODES.filter((m) => m.startsWith(typed) && m !== typed).map((m) => ({ value: m, label: m }))
+      return items.length > 0 ? items : null
+    },
+    handler: async (args, ctx) => {
+      bind(ctx)
+      const arg = args.trim().toLowerCase()
+      if (arg && !isDisplayMode(arg)) {
+        ctx.ui.notify(`tps-meter: unknown mode "${arg}" (use status | widget | off)`, "error")
+        return
+      }
+      const mode = isDisplayMode(arg) ? arg : nextMode(config.mode)
+      config = { ...config, mode }
+      const saved = saveMode(mode)
+      render()
+      startTicker()
+      if (saved.ok) ctx.ui.notify(`tps-meter: ${mode}`, "info")
+      else ctx.ui.notify(`tps-meter: ${mode} (not saved: ${saved.error})`, "warning")
+    },
+  })
+}

package/package.json

@@ -1,6 +1,55 @@
 {
+  "$schema": "https://json.schemastore.org/package.json",
   "name": "@jack-yang/pi-tps-meter",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Live TPS / AVG / TTFT meter for the pi coding agent, calibrated against authoritative token counts (port of opencode-tps-meter)",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi-coding-agent",
+    "tps",
+    "tokens-per-second",
+    "ttft",
+    "llm"
+  ],
+  "author": "Jack Yang",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yangwudong/pi-tps-meter.git"
+  },
+  "homepage": "https://github.com/yangwudong/pi-tps-meter#readme",
+  "bugs": {
+    "url": "https://github.com/yangwudong/pi-tps-meter/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "extensions",
+    "src",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions/index.ts"
+    ],
+    "image": "https://raw.githubusercontent.com/yangwudong/pi-tps-meter/main/docs/screenshot-status.png"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.0"
+  },
+  "scripts": {
+    "test": "node --test",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/config.ts

@@ -0,0 +1,107 @@
+// Display mode persistence and tier overrides — the only module that touches the filesystem.
+//
+// File: <agent dir>/pi-tps-meter/config.json, where <agent dir> is $PI_CODING_AGENT_DIR or
+// ~/.pi/agent, resolved the same way pi resolves its own config directory.
+//
+//   { "mode": "status", "tiers": { "tps": { "slow": 20, "normal": 50, "fast": 100 },
+//                                  "ttft": { "fast": 10000, "ok": 20000 } } }
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
+import { homedir } from "node:os"
+import { dirname, join } from "node:path"
+import type { Tiers } from "./format.ts"
+
+export type DisplayMode = "status" | "widget" | "off"
+
+// Also the cycle order of a bare `/tps`.
+export const DISPLAY_MODES: readonly DisplayMode[] = ["status", "widget", "off"]
+
+export type MeterConfig = { mode: DisplayMode; tiers: Tiers }
+
+export type LoadedConfig = { config: MeterConfig; warning?: string }
+
+export type SaveResult = { ok: true } | { ok: false; error: string }
+
+export function isDisplayMode(value: unknown): value is DisplayMode {
+  return typeof value === "string" && (DISPLAY_MODES as readonly string[]).includes(value)
+}
+
+export function nextMode(mode: DisplayMode): DisplayMode {
+  return DISPLAY_MODES[(DISPLAY_MODES.indexOf(mode) + 1) % DISPLAY_MODES.length]
+}
+
+// The original's resolveConfig override shape: `tiers.tps` / `tiers.ttft`, field by field over
+// the defaults. Values that are not finite numbers fall back to the default instead of reaching
+// the tier comparisons, where a string or null would silently mis-tier every reading.
+export function resolveConfig(raw: unknown): MeterConfig {
+  const o = isObject(raw) ? raw : {}
+  const tiers = isObject(o.tiers) ? o.tiers : {}
+  const tp = isObject(tiers.tps) ? tiers.tps : {}
+  const tt = isObject(tiers.ttft) ? tiers.ttft : {}
+  return {
+    mode: isDisplayMode(o.mode) ? o.mode : "status",
+    tiers: {
+      tps: { slow: num(tp.slow, 20), normal: num(tp.normal, 50), fast: num(tp.fast, 100) },
+      ttft: { fast: num(tt.fast, 10_000), ok: num(tt.ok, 20_000) },
+    },
+  }
+}
+
+export function agentDir(env: NodeJS.ProcessEnv = process.env): string {
+  const dir = env.PI_CODING_AGENT_DIR
+  if (!dir) return join(homedir(), ".pi", "agent")
+  if (dir === "~") return homedir()
+  return dir.startsWith("~/") ? join(homedir(), dir.slice(2)) : dir
+}
+
+export function configPath(env: NodeJS.ProcessEnv = process.env): string {
+  return join(agentDir(env), "pi-tps-meter", "config.json")
+}
+
+// A missing file is the normal first run. A file that does not parse falls back to the defaults
+// with a warning, so a typo in hand-edited tiers is not ignored silently.
+export function loadConfig(file: string = configPath()): LoadedConfig {
+  const read = readJson(file)
+  if (!read.ok) return { config: resolveConfig(undefined), warning: read.error }
+  return { config: resolveConfig(read.value) }
+}
+
+// Rewrites only `mode` and keeps every other key (hand-edited tiers). A file that does not parse
+// as a JSON object is left untouched and reported, rather than replaced by a bare { mode }.
+// Never throws: a failed save must not stop the mode switch for the running session.
+export function saveMode(mode: DisplayMode, file: string = configPath()): SaveResult {
+  const read = readJson(file)
+  if (!read.ok) return read
+  const current = read.value === undefined ? {} : read.value
+  if (!isObject(current)) return { ok: false, error: `${file}: not a JSON object, left unchanged` }
+  try {
+    mkdirSync(dirname(file), { recursive: true })
+    writeFileSync(file, `${JSON.stringify({ ...current, mode }, null, 2)}\n`, "utf8")
+    return { ok: true }
+  } catch (err) {
+    return { ok: false, error: `${file}: ${errorMessage(err)}` }
+  }
+}
+
+type ReadResult = { ok: true; value: unknown } | { ok: false; error: string }
+
+// The single place file text becomes data. A missing file reads as `undefined`.
+function readJson(file: string): ReadResult {
+  try {
+    return { ok: true, value: existsSync(file) ? JSON.parse(readFileSync(file, "utf8")) : undefined }
+  } catch (err) {
+    return { ok: false, error: `${file}: ${errorMessage(err)}` }
+  }
+}
+
+function errorMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err)
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+function num(value: unknown, fallback: number): number {
+  return typeof value === "number" && Number.isFinite(value) ? value : fallback
+}

package/src/core.ts

@@ -0,0 +1,191 @@
+// Measurement core, ported from opencode-tps-meter/tui.tsx (the porting source of truth).
+//
+// Pure state machine: every function takes the clock as a parameter (`at` / `now`). Nothing
+// here reads Date.now(), performs IO, or knows about pi — extensions/index.ts maps pi events
+// onto these calls. The constants and the window / calibration / AVG arithmetic are the
+// original's, unchanged; deviations are limited to the host mapping and are commented inline.
+
+export const WINDOW_MS = 5_000
+export const STALE_MS = 1_500
+export const MIN_DURATION_MS = 1_000
+export const MAX_CALIBRATION_RATIOS = 10
+
+export type DeltaSample = { at: number; rawTokens: number }
+
+export type SessionStats = {
+  totalOutputTokens: number
+  totalDurationMs: number
+  calibrationRatios: number[]
+}
+
+// Which stream a delta came from. All three are generated output and all are inside
+// usage.output, but only text/thinking may end the TTFT wait.
+export type DeltaKind = "text" | "thinking" | "toolcall"
+
+// The original kept one map per field, keyed by sessionID / messageID, because one opencode
+// TUI watches many sessions. A pi extension instance belongs to exactly one session and pi
+// streams one assistant message at a time, so each map collapses to a single field (the
+// original field is named on the right).
+export type MeterState = {
+  samples: DeltaSample[] // samplesBySession
+  stats: SessionStats // statsBySession
+  turnStartedAt: number | undefined // when the current turn (one LLM request) began
+  streaming: boolean // between an assistant message_start and its message_end
+  ttftOrigin: number | undefined // messageCreatedAt (v1) / step.started (v2)
+  firstDeltaAt: number | undefined // firstDeltaByMessage
+  lastDeltaAt: number | undefined // lastDeltaByMessage
+  estimatedTokens: number // estimatedTokensByMessage
+  ttftMs: number | undefined // liveTtftBySession
+}
+
+export type MeterReading = {
+  tps: number | undefined
+  avg: number | undefined
+  ttftMs: number | undefined
+}
+
+// UTF-8 bytes / 4. Deliberately crude: CJK text (3 bytes per character) and code tokenize very
+// differently, and the calibration factor below corrects whatever bias the content mix has.
+export function estimateTokens(delta: string): number {
+  return Math.max(1, Math.ceil(Buffer.byteLength(delta, "utf8") / 4))
+}
+
+// Median, not mean: one odd message (reasoning the provider bills but never streams, a huge
+// tool payload) must not drag the factor used for the next ten messages.
+export function median(values: number[]): number {
+  if (values.length === 0) return 1.0
+  const sorted = [...values].sort((a, b) => a - b)
+  const mid = Math.floor(sorted.length / 2)
+  if (sorted.length % 2 !== 0) return sorted[mid]
+  return Math.round(((sorted[mid - 1] + sorted[mid]) / 2) * 1e10) / 1e10
+}
+
+// 1.0 until the first message completes: the raw byte estimate is the best guess there is.
+export function calibrationFactor(ratios: number[]): number {
+  return ratios.length === 0 ? 1.0 : median(ratios)
+}
+
+// The span is wall clock (now - oldest sample), never a sum of inter-arrival gaps: providers
+// batch several tokens into one network chunk, and summing the near-zero gaps between batched
+// deltas inflates the rate. MIN_DURATION_MS keeps the first chunk of a stream from reading as
+// a spike; STALE_MS blanks the reading once the stream pauses instead of letting it decay.
+export function calculateLiveTps(samples: DeltaSample[], now: number, calibration: number): number | undefined {
+  if (samples.length === 0) return undefined
+  const cutoff = now - WINDOW_MS
+  const relevant = samples.filter((s) => s.at >= cutoff)
+  if (relevant.length === 0) return undefined
+  const last = relevant[relevant.length - 1]
+  if (now - last.at > STALE_MS) return undefined
+  const oldest = relevant[0]
+  const durationMs = Math.max(now - oldest.at, MIN_DURATION_MS)
+  const totalRaw = relevant.reduce((sum, s) => sum + s.rawTokens, 0)
+  return (totalRaw * calibration) / (durationMs / 1000)
+}
+
+export function createMeterState(): MeterState {
+  return {
+    samples: [],
+    stats: { totalOutputTokens: 0, totalDurationMs: 0, calibrationRatios: [] },
+    turnStartedAt: undefined,
+    streaming: false,
+    ttftOrigin: undefined,
+    firstDeltaAt: undefined,
+    lastDeltaAt: undefined,
+    estimatedTokens: 0,
+    ttftMs: undefined,
+  }
+}
+
+// turn_start: one pi turn is one LLM request — the counterpart of the original's
+// session.step.started, i.e. "when the LLM call begins". pi's message_start cannot be the
+// origin: pi emits it when the provider stream opens, after the HTTP response headers, and most
+// backends only send those once queueing and prefill are done. Measured from message_start,
+// TTFT reads ~0ms (observed: headers after 2.2s, message_start and the first delta in the same
+// millisecond).
+export function startTurn(state: MeterState, at: number): void {
+  state.turnStartedAt = at
+}
+
+// message_start of an assistant message: a new generation begins. The previous TTFT is cleared
+// here rather than at turn_end, so the old reading stays on screen through tool runs and the
+// wait for the next response. Falls back to `at` when no turn_start was seen.
+export function startMessage(state: MeterState, at: number): void {
+  state.streaming = true
+  state.ttftOrigin = state.turnStartedAt ?? at
+  state.turnStartedAt = undefined
+  state.ttftMs = undefined
+  state.firstDeltaAt = undefined
+  state.lastDeltaAt = undefined
+  state.estimatedTokens = 0
+  state.samples = []
+}
+
+// One streamed chunk (the original's recordDelta). Every kind feeds the window, the span and the
+// calibration estimate, because usage.output counts all of them and tool-call arguments (edit /
+// write payloads) are a large share of a coding agent's output: leaving them out would inflate
+// the calibration ratio (up to its 3.0 clamp) and AVG, and blank TPS while a long tool call
+// streams. Only text/thinking end the TTFT wait.
+// Returns true when this delta produced the message's TTFT, so the caller can show it at once.
+export function recordDelta(state: MeterState, at: number, delta: string, kind: DeltaKind): boolean {
+  const rawTokens = estimateTokens(delta)
+  const cutoff = at - WINDOW_MS
+  state.samples = [...state.samples.filter((s) => s.at >= cutoff), { at, rawTokens }]
+  if (state.firstDeltaAt === undefined) state.firstDeltaAt = at
+  state.lastDeltaAt = at
+  state.estimatedTokens += rawTokens
+  if (kind === "toolcall" || state.ttftMs !== undefined || state.ttftOrigin === undefined) return false
+  state.ttftMs = Math.max(0, at - state.ttftOrigin)
+  return true
+}
+
+// message_end with the provider's authoritative output count (the original's
+// recordMessageCompleted). pi's usage.output already includes reasoning tokens; the original
+// summed tokens.output + tokens.reasoning only because opencode reports them separately.
+export function completeMessage(state: MeterState, outputTokens: number): void {
+  const stats = state.stats
+  const actualTokens = outputTokens
+  const generationMs = state.firstDeltaAt !== undefined && state.lastDeltaAt !== undefined
+    ? Math.max(state.lastDeltaAt - state.firstDeltaAt, MIN_DURATION_MS) : 0
+
+  if (actualTokens > 0 && generationMs > 0) {
+    stats.totalOutputTokens += actualTokens
+    stats.totalDurationMs += generationMs
+
+    const estimated = state.estimatedTokens
+    if (estimated > 0) {
+      // Clamped so a single pathological message cannot swing the factor arbitrarily.
+      const ratio = Math.min(Math.max(actualTokens / estimated, 0.3), 3.0)
+      stats.calibrationRatios = [...stats.calibrationRatios, ratio].slice(-MAX_CALIBRATION_RATIOS)
+    }
+  }
+  endMessage(state)
+}
+
+// message_end of an errored or aborted message — the counterpart of the original's
+// session.step.failed: its usage is partial, so it touches neither AVG nor calibration.
+// A TTFT it already produced stays on screen.
+export function abandonMessage(state: MeterState): void {
+  endMessage(state)
+}
+
+// Samples are dropped at the end of every message, as the original did on completion. In pi the
+// tools run between messages; samples left in the 5s window would otherwise stretch the next
+// message's window across the tool run and dilute its rate.
+function endMessage(state: MeterState): void {
+  state.streaming = false
+  state.ttftOrigin = undefined
+  state.firstDeltaAt = undefined
+  state.lastDeltaAt = undefined
+  state.estimatedTokens = 0
+  state.samples = []
+}
+
+// What the meter shows at `now` (the original's MeterDisplay sync).
+export function readMeter(state: MeterState, now: number): MeterReading {
+  const stats = state.stats
+  return {
+    tps: calculateLiveTps(state.samples, now, calibrationFactor(stats.calibrationRatios)),
+    avg: stats.totalDurationMs > 0 ? stats.totalOutputTokens / (stats.totalDurationMs / 1000) : undefined,
+    ttftMs: state.ttftMs,
+  }
+}

package/src/format.ts

@@ -0,0 +1,104 @@
+// Display formatting and tier colouring, ported from opencode-tps-meter/tui.tsx.
+// Pure: no pi imports. The caller decides whether the host renders ANSI.
+
+import type { MeterReading } from "./core.ts"
+
+export type TpsTiers = { slow: number; normal: number; fast: number }
+export type TtftTiers = { fast: number; ok: number }
+export type Tiers = { tps: TpsTiers; ttft: TtftTiers }
+
+export type SpeedTier = "slow" | "normal" | "fast" | "faster"
+export type TtftTier = "fast" | "ok" | "slow"
+
+// The original painted with opencode theme slots (error / warning / success / accent, labels in
+// textMuted). A pi status line is a plain string, so each slot maps to its basic ANSI colour.
+export type Hue = "red" | "yellow" | "green" | "cyan" | "muted"
+
+// Precision follows magnitude: two decimals while the number is small, an integer once three
+// digits would make the decimal noise.
+export function formatTps(value: number): string | undefined {
+  if (!Number.isFinite(value) || value <= 0) return undefined
+  if (value >= 100) return Math.round(value).toString()
+  if (value >= 10) return value.toFixed(1)
+  return value.toFixed(2)
+}
+
+export function formatTtft(valueMs: number): string | undefined {
+  if (!Number.isFinite(valueMs) || valueMs < 0) return undefined
+  return `${(valueMs / 1000).toFixed(1)}s`
+}
+
+// Lower bounds are inclusive: exactly 20 TPS is "normal", exactly 10s of TTFT is "ok".
+export function speedTier(tps: number, c: TpsTiers): SpeedTier {
+  if (tps < c.slow) return "slow"
+  if (tps < c.normal) return "normal"
+  if (tps < c.fast) return "fast"
+  return "faster"
+}
+
+export function ttftTier(ms: number, c: TtftTiers): TtftTier {
+  if (ms < c.fast) return "fast"
+  if (ms < c.ok) return "ok"
+  return "slow"
+}
+
+export function speedHue(tier: SpeedTier): Hue {
+  switch (tier) {
+    case "slow": return "red" // theme.error
+    case "normal": return "yellow" // theme.warning
+    case "fast": return "green" // theme.success
+    case "faster": return "cyan" // theme.accent
+  }
+}
+
+// TTFT is lower-is-better, so its scale runs the other way.
+export function ttftHue(tier: TtftTier): Hue {
+  switch (tier) {
+    case "fast": return "green"
+    case "ok": return "yellow"
+    case "slow": return "red"
+  }
+}
+
+// Each code is closed by its own reset (39 = default foreground, 22 = normal intensity) rather
+// than a blanket \x1b[0m, so the line never cancels styling the host wraps around it.
+const SGR: Record<Hue, [open: string, close: string]> = {
+  red: ["\x1b[31m", "\x1b[39m"],
+  yellow: ["\x1b[33m", "\x1b[39m"],
+  green: ["\x1b[32m", "\x1b[39m"],
+  cyan: ["\x1b[36m", "\x1b[39m"],
+  muted: ["\x1b[2m", "\x1b[22m"],
+}
+
+export function paint(text: string, hue: Hue): string {
+  const [open, close] = SGR[hue]
+  return `${open}${text}${close}`
+}
+
+type Cell = { text: string; hue: Hue }
+
+// A missing reading is "--" in the muted colour, like the original's idle state.
+const DASH: Cell = { text: "--", hue: "muted" }
+
+function tpsCell(value: number | undefined, tiers: TpsTiers): Cell {
+  const text = value === undefined ? undefined : formatTps(value)
+  return value === undefined || text === undefined ? DASH : { text, hue: speedHue(speedTier(value, tiers)) }
+}
+
+function ttftCell(valueMs: number | undefined, tiers: TtftTiers): Cell {
+  const text = valueMs === undefined ? undefined : formatTtft(valueMs)
+  return valueMs === undefined || text === undefined ? DASH : { text, hue: ttftHue(ttftTier(valueMs, tiers)) }
+}
+
+// TPS 42.5 | AVG 38.2 | TTFT 0.8s — labels muted; TPS and AVG share the speed tiers.
+export function renderLine(reading: MeterReading, tiers: Tiers, color: boolean): string {
+  const cells: Cell[] = [
+    { text: "TPS ", hue: "muted" },
+    tpsCell(reading.tps, tiers.tps),
+    { text: " | AVG ", hue: "muted" },
+    tpsCell(reading.avg, tiers.tps),
+    { text: " | TTFT ", hue: "muted" },
+    ttftCell(reading.ttftMs, tiers.ttft),
+  ]
+  return cells.map((c) => (color ? paint(c.text, c.hue) : c.text)).join("")
+}