@jack-yang/pi-tps-meter 0.1.1 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## [0.3.0] - 2026-11-04
+
+- New default display `footer`: the meter sits at the right end of pi's footer line with the
+  working directory, in line with the model name below it, without taking an extra line. pi's
+  own `FooterComponent` still renders the whole footer (the stats and status lines are
+  byte-for-byte pi's); the meter is merged into its first line. On a narrow terminal the
+  directory is shortened first, so the reading stays whole.
+- If pi's footer cannot be wrapped (for example a future pi changes its internals), pi's own
+  footer is restored and the meter falls back to `right`, with a one-time notice.
+- `/tps` cycles footer → right → status → widget → off; a saved `mode` still wins.
+
+## [0.2.0] - 2026-11-03
+
+- New default display `right`: one line below the editor, right-aligned so it ends in the last
+  column, directly above the footer. Other extensions' footer statuses (such as pi-lens's
+  `LSP Inactive`) can no longer push it around. `/tps` now cycles right → status → widget → off;
+  a saved `mode` in config.json still wins.
+- The thinking particle stream from opencode-tps-meter is back: while the model streams its
+  reasoning, braille particles flow away from the reading, newest brightest, fading per cell.
+  Configurable via `spinner` (`theme` tech / red / none, `colors`, `intervalMs`, `cells`, `enabled`).
+
 ## [0.1.1] - 2026-11-03
 
 - Published from GitHub Actions through npm Trusted Publishing, so this and later versions

package/README.md

@@ -9,20 +9,17 @@
 ## 显示效果
 
 ```
-TPS 42.5 | AVG 38.2 | TTFT 0.8s
+⠔⠀⠈⠀⠤⠔ TPS 42.5 | AVG 38.2 | TTFT 0.8s
 ```
 
-底部状态条（`/tps status`，默认），流式输出中：
+默认显示在 footer 的目录那一行右端（`/tps footer`），和下一行的模型名右对齐，不额外占行；其他扩展的 footer 状态（比如 pi-lens 的 `LSP Inactive`）也挤不动它。下图是模型思考时的样子，读数左边是思考粒子流：
 
-![底部状态条模式：流式输出中，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)
+![footer 目录行右端：思考中，粒子流 + TPS 38.2 / AVG 62.2 / TTFT 1.9s](https://raw.githubusercontent.com/yangwudong/pi-tps-meter/main/docs/screenshot-footer.png)
 
 - **TPS**：流式输出时的实时速度，基于 5 秒滑动窗口，约 10Hz 刷新；超过 1.5 秒没有新 token 时显示 `--`。
 - **AVG**：会话级累计平均。所有已完成消息的权威 token 数之和，除以各消息生成时长之和。
 - **TTFT**：从本轮请求开始到第一个文本或思考 token 的时间。首个 token 到达立即显示，一直保留到下一次生成开始。
+- **思考粒子流**：模型流式输出思考内容时，一串盲文点从读数旁流出：最新的一格最亮，越旧越淡，亮色随时间沿渐变色漂移；开始输出正文就消失。只在思考时出现，平时不占位。
 
 流结束后 AVG / TTFT 摘要不会清空：工具执行期间、等待下一轮响应期间都保持可见，下一条助手消息开始时才更新。
 
@@ -65,32 +62,44 @@ pi -e npm:@jack-yang/pi-tps-meter          # 只在本次启动试用，不写
 
 | 命令 | 作用 |
 |---|---|
-| `/tps` | 循环切换 status → widget → off |
-| `/tps status` | 显示在底部状态条（footer），和其他扩展的状态共用一行 |
-| `/tps widget` | 显示为编辑器上方的单行组件 |
+| `/tps` | 循环切换 footer → right → status → widget → off |
+| `/tps footer` | footer 的目录那一行右端（默认），不额外占行 |
+| `/tps right` | 编辑器下方单独一行，右对齐，紧贴 footer |
+| `/tps status` | footer 的扩展状态行，和其他扩展共用一行，按扩展名排序 |
+| `/tps widget` | 编辑器上方的单行组件 |
 | `/tps off` | 完全隐藏。计量仍在后台进行，切回来立即显示当前读数 |
 
 模式写入配置文件，下次启动沿用。
 
+`footer` 模式是怎么做的：pi 的 footer 没有给扩展留定位的口子（扩展状态只能左对齐拼在最后一行），所以这里用 `setFooter` 挂了一个包装层：里面跑的就是 pi 自己导出的 `FooterComponent`，统计行、状态行都由 pi 自己渲染，实测和原装 footer 逐字符、连颜色都一致；只是在目录那一行右端补上读数。终端变窄时先截短目录（和 pi 一样用 `...`），读数保持完整；中文目录名按双宽字符计算。如果将来某个 pi 版本改了 footer 内部导致包装失败，会自动恢复 pi 原装 footer、退回 `right` 模式并提示一次，不会把 footer 弄坏。
+
+如果也嫌 pi-lens 的 `LSP Inactive` 占地方，pi-lens 自己有开关：在 `~/.pi-lens/config.json` 里设 `ui.compactLspStatus: true`（压成一个图标）或 `ui.hideLspStatus: true`（不显示）。
+
 ## 配置
 
 配置文件位于 `~/.pi/agent/pi-tps-meter/config.json`；设置了 `PI_CODING_AGENT_DIR` 时，位于该目录下的 `pi-tps-meter/config.json`。
 
 ```json
 {
-  "mode": "status",
+  "mode": "footer",
   "tiers": {
     "tps":  { "slow": 20, "normal": 50, "fast": 100 },
     "ttft": { "fast": 10000, "ok": 20000 }
-  }
+  },
+  "spinner": { "theme": "tech", "intervalMs": 100, "cells": 6 }
 }
 ```
 
 | 键 | 默认值 | 说明 |
 |---|---|---|
-| `mode` | `"status"` | `status` / `widget` / `off`。`/tps` 只改写这个键，其他内容原样保留 |
+| `mode` | `"footer"` | `footer` / `right` / `status` / `widget` / `off`。`/tps` 只改写这个键，其他内容原样保留 |
 | `tiers.tps` | `{ slow: 20, normal: 50, fast: 100 }` | TPS 与 AVG 的分档阈值（tok/s） |
 | `tiers.ttft` | `{ fast: 10000, ok: 20000 }` | TTFT 分档阈值（毫秒） |
+| `spinner.theme` | `"tech"` | 粒子流配色：`"tech"`（青 → 蓝 → 紫）、`"red"`（KITT 风格红）；`"none"` 关闭粒子流 |
+| `spinner.colors` | 随 theme | 自定义渐变色，`"#rrggbb"` / `"#rgb"` 数组，优先于 theme |
+| `spinner.intervalMs` | `100` | 粒子前进一格的间隔（毫秒） |
+| `spinner.cells` | `6` | 粒子流格数（宽度），至少 2 |
+| `spinner.enabled` | `true` | `false` 关闭粒子流 |
 
 - 所有键都可省略，按字段覆盖默认值，例如只写 `{ "tiers": { "tps": { "fast": 80 } } }`。不是数字的值会被忽略。
 - 文件在会话启动时读取，手动修改后执行 `/reload` 生效。
@@ -138,14 +147,14 @@ TTFT 从 `turn_start` 开始计时（在 pi 里，一个 turn 就是一次模型
 - 下一条助手消息开始时清空 TTFT，原版要等到下一个首 token 才覆盖。
 - toolcall delta 计入 TPS 和校准，因为 pi 的 `usage.output` 包含工具调用参数的 token；原版只统计文本和推理。TTFT 仍然只认文本和思考。
 - 权威 token 数直接用 `usage.output`：pi 的 output 已经包含推理 token，原版需要把 output 和 reasoning 相加。
-- 没有移植思考粒子动画，pi 自带工作指示器。
+- 思考粒子流已移植（配色预设、渐变、FIFO 流动、配置项都和原版一致），并做了原版想做但受限于 opencode 做不到的一点：每个粒子单独着色，真正从亮到暗渐隐（原版受 opentui 限制，整串只能用一种颜色）。右对齐时粒子流放在读数左边、方向镜像，读数本身不会移动。
 - 颜色用 ANSI 基本色：红 31、黄 33、绿 32、青 36，标签用暗色；原版用的是 opencode 主题槽位。
 
 ## 已知限制
 
 - **不流式输出的推理**：有些模型按推理 token 计费，但不把推理内容流式发出来。这时校准比率会顶到 3.0 上限，AVG 也会偏高（原版同样如此）。
 - **一次性返回工具参数的 provider**（如 Gemini）：消息末尾会出现一个短暂的 TPS 尖峰，消息结束后立即清除。
-- **底部状态条依赖 pi 的默认 footer**：如果另一个扩展换掉了 footer，并且不渲染扩展状态（比如 awesome-pi-themes 的 look-pack），请改用 `/tps widget`。
+- **`footer` 和其他替换 footer 的扩展互斥**：pi 同一时间只有一个 footer，后设置的生效。如果还开着 awesome-pi-themes 的 look-pack 这类扩展，改用 `/tps right`。`status` 模式也依赖 pi 的默认 footer（look-pack 不渲染扩展状态）。
 - **AVG 和校准只在当前会话内累计**：`/new`、`/resume`、`/fork`、`/reload` 会重新开始；不会从历史记录里重建。
 - **TTFT 包含客户端准备时间**：包括请求前的上下文处理（实测约 7ms）和 provider 层的自动重试等待，也就是用户实际等待的时间。
 - **时间戳取自 pi 把事件派发给扩展的时刻**：其他扩展的慢 handler 会推迟派发，从而影响读数。

package/extensions/index.ts

@@ -1,39 +1,211 @@
 // 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.
+// Port of opencode-tps-meter: the measurement core (src/core.ts), the formatting (src/format.ts)
+// and the thinking particle stream (src/spinner.ts) are the original's. This file is the replaced
+// host layer: pi events in; the meter out on pi's footer line (by wrapping pi's own footer), a
+// right-aligned line below the editor, a footer status, or a line above the editor.
 
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent"
+import type { ExtensionAPI, ExtensionContext, ReadonlyFooterDataProvider } 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"
+import { mergeFooterLine } from "../src/footer.ts"
+import { alignRight, renderLine, withSpinner } from "../src/format.ts"
+import { advanceSpinner, createSpinner, spinnerCells, type Rgb, type SpinnerState } from "../src/spinner.ts"
 
-// One key for both surfaces: the footer status entry and the widget.
+// One key for every surface: 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
 
+// Older particles fade toward this neutral grey (the original faded toward the theme's muted text).
+const SPINNER_MUTED: Rgb = { r: 128, g: 132, b: 142 }
+
 type UI = ExtensionContext["ui"]
+type Model = NonNullable<ExtensionContext["model"]>
+
+// The part of pi's AgentSession that pi's FooterComponent reads, rebuilt from what an extension
+// can see. pi does not hand extensions its session, but its footer only needs these members.
+export type SessionView = {
+  readonly sessionManager: ExtensionContext["sessionManager"]
+  readonly model: ExtensionContext["model"]
+  readonly state: { model: ExtensionContext["model"]; thinkingLevel: string }
+  readonly routedModel: { model: Model; thinkingLevel?: string } | undefined
+  readonly modelRuntime: { isUsingSubscription(provider: string): boolean }
+  getContextUsage(): ReturnType<ExtensionContext["getContextUsage"]>
+}
+
+export type FooterLike = { render(width: number): string[]; invalidate(): void; dispose?(): void; setAutoCompactEnabled(enabled: boolean): void }
+
+// pi runtime pieces the footer mode needs; loaded on demand (and injected in tests, which run on
+// plain Node without pi).
+export type FooterKit = {
+  createFooter(session: SessionView, footerData: ReadonlyFooterDataProvider): FooterLike
+  visibleWidth(text: string): number
+  truncateToWidth(text: string, width: number, ellipsis?: string): string
+}
+
+export type Deps = { loadFooterKit?: () => Promise<FooterKit> }
+
+async function loadPiFooterKit(): Promise<FooterKit> {
+  const [core, tuiLib] = await Promise.all([import("@earendil-works/pi-coding-agent"), import("@earendil-works/pi-tui")])
+  type Session = ConstructorParameters<typeof core.FooterComponent>[0]
+  return {
+    createFooter: (session, footerData) => {
+      // SAFETY: FooterComponent is typed to take pi's whole AgentSession, which extensions never
+      // get. In pi 1.5.0 (dist/modes/interactive/components/footer.js) it reads exactly the members
+      // SessionView provides: sessionManager.{getCwd, getEntries, getEntryCount, getLeafId,
+      // getSessionId, getSessionName}, model, state.{model, thinkingLevel}, routedModel,
+      // modelRuntime.isUsingSubscription and getContextUsage(). If a later pi reads anything else,
+      // render() throws, the wrapper catches it, and fallBack() restores pi's own footer.
+      const agentSession = session as unknown as Session
+      return new core.FooterComponent(agentSession, footerData)
+    },
+    visibleWidth: tuiLib.visibleWidth,
+    truncateToWidth: tuiLib.truncateToWidth,
+  }
+}
 
 export default function tpsMeter(pi: ExtensionAPI): void {
+  createTpsMeter(pi)
+}
+
+export function createTpsMeter(pi: ExtensionAPI, deps: Deps = {}): void {
+  const loadFooterKit = deps.loadFooterKit ?? loadPiFooterKit
   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 ctxRef: ExtensionContext | undefined
   let ui: UI | undefined
-  let color = false
+  let tui = false
   let ticker: ReturnType<typeof setInterval> | undefined
+  let spinner: SpinnerState | undefined
   // What is on screen right now, so unchanged readings cost no re-render.
   let shownMode: DisplayMode | undefined
   let shownLine: string | undefined
+  // The mounted component's host (widget or footer), told to redraw when the line changes.
+  let host: { requestRender(): void } | undefined
+  // Bumped on every mode change, so a footer mount still loading for an older mode is dropped.
+  let mountEpoch = 0
 
   // Handlers re-bind from their own ctx; the ticker only ever uses the latest binding.
   const bind = (ctx: ExtensionContext): void => {
+    ctxRef = ctx
     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"
+    // The TUI renders ANSI and components; RPC clients get plain text lines.
+    tui = ctx.mode === "tui"
+  }
+
+  // The particle stream exists only while reasoning streams, and only in the TUI (in RPC it would
+  // just be noise at 10Hz). A fresh stream starts each time thinking starts. Next to a
+  // right-aligned reading it goes on the left, so the reading itself never moves.
+  const decorate = (target: UI, line: string, now: number): string => {
+    if (!tui || !config.spinner.enabled || !state.thinking) {
+      spinner = undefined
+      return line
+    }
+    if (spinner === undefined) spinner = createSpinner(config.spinner.cells, now, Math.random)
+    else advanceSpinner(spinner, config.spinner, now, Math.random)
+    const paint = (text: string, c: Rgb) => target.theme.style(text, { fg: { kind: "rgb", r: c.r, g: c.g, b: c.b } })
+    const side = config.mode === "right" || config.mode === "footer" ? "before" : "after"
+    return withSpinner(line, spinnerCells(spinner, config.spinner, SPINNER_MUTED), paint, side)
+  }
+
+  // A component rather than a string widget: it right-aligns itself to the width of every render,
+  // so it stays in the corner across terminal resizes, and an update is only a redraw request.
+  const mountRight = (target: UI): void => {
+    target.setWidget(KEY, (h) => {
+      host = h
+      return { render: (width: number) => [alignRight(shownLine ?? "", width)], invalidate() {} }
+    }, { placement: "belowEditor" })
+  }
+
+  // pi's own footer, fed a SessionView, with the meter merged into its first (directory) line.
+  // Everything else on the footer stays pi's rendering.
+  const sessionView: SessionView = {
+    // Only read inside a mounted footer, which exists only after bind(); a throw here is caught
+    // by the footer's render() and ends in fallBack().
+    get sessionManager() {
+      if (!ctxRef) throw new Error("no session bound")
+      return ctxRef.sessionManager
+    },
+    get model() { return ctxRef?.model },
+    get state() { return { model: ctxRef?.model, thinkingLevel: pi.getThinkingLevel() } },
+    // As pi's AgentSession.routedModel: under a virtual model, the physical model of the latest
+    // successful response.
+    get routedModel() {
+      const model = ctxRef?.model
+      if (!ctxRef || !model || model.api !== "pi-virtual") return undefined
+      const branch = ctxRef.sessionManager.getBranch()
+      for (let i = branch.length - 1; i >= 0; i--) {
+        const entry = branch[i]
+        if (entry.type !== "message" || entry.message.role !== "assistant") continue
+        const m = entry.message
+        if (m.stopReason === "error" || m.stopReason === "aborted") continue
+        const physical = ctxRef.modelRegistry.find(m.provider, m.model)
+        return physical ? { model: physical, thinkingLevel: (m as { thinkingLevel?: string }).thinkingLevel } : undefined
+      }
+      return undefined
+    },
+    // As pi's ModelRuntime.isUsingSubscription: OAuth credentials for a subscription provider.
+    // The footer asks this about the current model's provider; ModelRegistry.isUsingOAuth takes
+    // the model and reads its provider.
+    modelRuntime: {
+      isUsingSubscription: (provider) => {
+        const registry = ctxRef?.modelRegistry
+        const model = ctxRef?.model
+        if (!registry || model?.provider !== provider || !registry.isUsingOAuth(model)) return false
+        const p = registry.getProvider(provider) as { auth?: { oauth?: { isSubscription?: boolean } } } | undefined
+        return p?.auth?.oauth?.isSubscription === true
+      },
+    },
+    getContextUsage: () => ctxRef?.getContextUsage(),
+  }
+
+  // If pi's footer cannot be wrapped (an older or newer pi changed it), never leave the user
+  // without a footer: restore pi's, fall back to the line below the editor, say so once.
+  // If pi's footer cannot be wrapped (an older or newer pi changed it), never leave the user
+  // without a footer: fall back to the line below the editor (leaving footer mode is what restores
+  // pi's own footer, in render()) and say so once. A mount that is no longer current (the mode
+  // changed, or the session was replaced, since it started) is ignored, so a stale UI is never used.
+  const fallBack = (target: UI, epoch: number, reason: unknown): void => {
+    if (epoch !== mountEpoch || ui !== target || config.mode !== "footer") return
+    config = { ...config, mode: "right" }
+    target.notify(`tps-meter: footer mode unavailable here (${reason instanceof Error ? reason.message : String(reason)}), using right`, "warning")
+    render()
+  }
+
+  const mountFooter = (target: UI, epoch: number): void => {
+    loadFooterKit().then((kit) => {
+      if (epoch !== mountEpoch || ui !== target) return
+      target.setFooter((h, theme, footerData) => {
+        host = h
+        const inner = kit.createFooter(sessionView, footerData)
+        const unsubscribe = footerData.onBranchChange(() => h.requestRender())
+        const fns = { visibleWidth: kit.visibleWidth, truncate: (text: string, width: number) => kit.truncateToWidth(text, width, theme.fg("dim", "...")) }
+        return {
+          render(width: number): string[] {
+            try {
+              // pi feeds this flag to its own footer instance; ours reads the same setting.
+              inner.setAutoCompactEnabled(pi.getSettings().compaction?.enabled ?? true)
+              const lines = inner.render(width)
+              if (lines.length > 0 && shownLine) lines[0] = mergeFooterLine(lines[0], shownLine, width, fns)
+              return lines
+            } catch (err) {
+              // Not from inside pi's render pass: swap the footer once this frame is done.
+              queueMicrotask(() => fallBack(target, epoch, err))
+              return []
+            }
+          },
+          invalidate() { inner.invalidate() },
+          dispose() {
+            unsubscribe()
+            inner.dispose?.()
+          },
+        }
+      })
+    }, (err: unknown) => fallBack(target, epoch, err))
   }
 
   const render = (): void => {
@@ -42,16 +214,26 @@ export default function tpsMeter(pi: ExtensionAPI): void {
     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)
+      if (shownMode === "widget" || shownMode === "right" || (shownMode === "footer" && !tui)) ui.setWidget(KEY, undefined)
+      if (shownMode === "footer" && tui) ui.setFooter(undefined)
+      host = undefined
+      mountEpoch++
       shownMode = mode
       shownLine = undefined
+      if (mode === "right" && tui) mountRight(ui)
+      if (mode === "footer" && tui) mountFooter(ui, mountEpoch)
     }
     if (mode === "off") return
-    const line = renderLine(readMeter(state, Date.now()), config.tiers, color)
+    const now = Date.now()
+    const line = decorate(ui, renderLine(readMeter(state, now), config.tiers, tui), now)
     if (line === shownLine) return
     shownLine = line
     if (mode === "status") ui.setStatus(KEY, line)
-    else ui.setWidget(KEY, [line])
+    else if (mode === "widget") ui.setWidget(KEY, [line])
+    // RPC has no custom footers or component widgets; there the line goes out as plain text
+    // below the editor.
+    else if (tui) host?.requestRender()
+    else ui.setWidget(KEY, [line], { placement: "belowEditor" })
   }
 
   const stopTicker = (): void => {
@@ -126,14 +308,18 @@ export default function tpsMeter(pi: ExtensionAPI): void {
   })
 
   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.
+    // pi resets extension UI itself when it reloads or replaces the runtime (including a custom
+    // footer); the timer and the references to this session are the only things left to drop.
     stopTicker()
+    mountEpoch++
     ui = undefined
+    ctxRef = undefined
+    host = undefined
+    spinner = undefined
   })
 
   pi.registerCommand("tps", {
-    description: "TPS meter display: /tps cycles status → widget → off, /tps status|widget|off sets it",
+    description: "TPS meter display: /tps cycles footer → right → status → widget → off, /tps footer|right|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.
@@ -145,7 +331,7 @@ export default function tpsMeter(pi: ExtensionAPI): void {
       bind(ctx)
       const arg = args.trim().toLowerCase()
       if (arg && !isDisplayMode(arg)) {
-        ctx.ui.notify(`tps-meter: unknown mode "${arg}" (use status | widget | off)`, "error")
+        ctx.ui.notify(`tps-meter: unknown mode "${arg}" (use footer | right | status | widget | off)`, "error")
         return
       }
       const mode = isDisplayMode(arg) ? arg : nextMode(config.mode)

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@jack-yang/pi-tps-meter",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Live TPS / AVG / TTFT meter for the pi coding agent, calibrated against authoritative token counts (port of opencode-tps-meter)",
   "type": "module",
   "keywords": [
@@ -36,7 +36,7 @@
     "extensions": [
       "./extensions/index.ts"
     ],
-    "image": "https://raw.githubusercontent.com/yangwudong/pi-tps-meter/main/docs/screenshot-status.png"
+    "image": "https://raw.githubusercontent.com/yangwudong/pi-tps-meter/main/docs/screenshot-footer.png"
   },
   "engines": {
     "node": ">=22.19.0"

package/src/config.ts

@@ -1,22 +1,27 @@
-// Display mode persistence and tier overrides — the only module that touches the filesystem.
+// Display mode persistence, tier and spinner 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 } } }
+//   { "mode": "right",
+//     "tiers": { "tps": { "slow": 20, "normal": 50, "fast": 100 }, "ttft": { "fast": 10000, "ok": 20000 } },
+//     "spinner": { "theme": "tech", "colors": ["#00e5ff", "#2979ff"], "intervalMs": 100, "cells": 6, "enabled": true } }
 
 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"
+import { parseHex, THEME_PRESETS, type Rgb, type SpinnerConfig } from "./spinner.ts"
 
-export type DisplayMode = "status" | "widget" | "off"
+// footer: the right end of pi's own footer line with the working directory (pi's footer is wrapped,
+// not replaced); right: one line below the editor, right-aligned; status: pi's footer status line;
+// widget: a line above the editor.
+export type DisplayMode = "footer" | "right" | "status" | "widget" | "off"
 
 // Also the cycle order of a bare `/tps`.
-export const DISPLAY_MODES: readonly DisplayMode[] = ["status", "widget", "off"]
+export const DISPLAY_MODES: readonly DisplayMode[] = ["footer", "right", "status", "widget", "off"]
 
-export type MeterConfig = { mode: DisplayMode; tiers: Tiers }
+export type MeterConfig = { mode: DisplayMode; tiers: Tiers; spinner: SpinnerConfig }
 
 export type LoadedConfig = { config: MeterConfig; warning?: string }
 
@@ -33,17 +38,29 @@ export function nextMode(mode: DisplayMode): DisplayMode {
 // 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.
+// `spinner` follows the original too: custom `colors` win over the `theme` preset, theme "none"
+// or `enabled: false` turns the stream off, `cells` is at least 2.
 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 : {}
+  const sp = isObject(o.spinner) ? o.spinner : {}
+  const theme = typeof sp.theme === "string" ? sp.theme : "tech"
+  const custom = hexColors(sp.colors)
+  const preset = hexColors(THEME_PRESETS[theme] ?? THEME_PRESETS.tech)
   return {
-    mode: isDisplayMode(o.mode) ? o.mode : "status",
+    mode: isDisplayMode(o.mode) ? o.mode : "footer",
     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) },
     },
+    spinner: {
+      enabled: sp.enabled !== false && theme !== "none",
+      colors: custom.length > 0 ? custom : preset,
+      intervalMs: positive(sp.intervalMs) ?? 100,
+      cells: (positive(sp.cells) ?? 0) >= 2 ? Math.floor(sp.cells as number) : 6,
+    },
   }
 }
 
@@ -105,3 +122,16 @@ function isObject(value: unknown): value is Record<string, unknown> {
 function num(value: unknown, fallback: number): number {
   return typeof value === "number" && Number.isFinite(value) ? value : fallback
 }
+
+function positive(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : undefined
+}
+
+// The valid "#rrggbb" / "#rgb" entries of a config value, in order; anything else is dropped.
+function hexColors(value: unknown): Rgb[] {
+  if (!Array.isArray(value)) return []
+  return value.flatMap((c) => {
+    const rgb = typeof c === "string" ? parseHex(c) : undefined
+    return rgb ? [rgb] : []
+  })
+}

package/src/core.ts

@@ -36,6 +36,7 @@ export type MeterState = {
   lastDeltaAt: number | undefined // lastDeltaByMessage
   estimatedTokens: number // estimatedTokensByMessage
   ttftMs: number | undefined // liveTtftBySession
+  thinking: boolean // thinkingBySession: the latest delta was reasoning (drives the particle stream)
 }
 
 export type MeterReading = {
@@ -93,6 +94,7 @@ export function createMeterState(): MeterState {
     lastDeltaAt: undefined,
     estimatedTokens: 0,
     ttftMs: undefined,
+    thinking: false,
   }
 }
 
@@ -118,6 +120,7 @@ export function startMessage(state: MeterState, at: number): void {
   state.lastDeltaAt = undefined
   state.estimatedTokens = 0
   state.samples = []
+  state.thinking = false
 }
 
 // One streamed chunk (the original's recordDelta). Every kind feeds the window, the span and the
@@ -133,6 +136,9 @@ export function recordDelta(state: MeterState, at: number, delta: string, kind:
   if (state.firstDeltaAt === undefined) state.firstDeltaAt = at
   state.lastDeltaAt = at
   state.estimatedTokens += rawTokens
+  // As the original's setThinking: reasoning turns it on; text and the tool-call stream (the
+  // original cleared it on tool input start) turn it off.
+  state.thinking = kind === "thinking"
   if (kind === "toolcall" || state.ttftMs !== undefined || state.ttftOrigin === undefined) return false
   state.ttftMs = Math.max(0, at - state.ttftOrigin)
   return true
@@ -178,6 +184,7 @@ function endMessage(state: MeterState): void {
   state.lastDeltaAt = undefined
   state.estimatedTokens = 0
   state.samples = []
+  state.thinking = false
 }
 
 // What the meter shows at `now` (the original's MeterDisplay sync).

package/src/footer.ts

@@ -0,0 +1,27 @@
+// Puts the meter on the right end of the first line of pi's own footer (the working directory
+// line), the way pi itself right-aligns the model name on the line below. Pure: the terminal
+// width functions are injected (pi-tui's in pi, simple ones in tests), so this runs on plain Node.
+
+export type WidthFns = {
+  // Terminal columns of a string: ANSI codes take none, CJK characters take two.
+  visibleWidth(text: string): number
+  // Cut a string to at most `width` columns; the caller decides the ellipsis (pi uses a dim "...").
+  truncate(text: string, width: number): string
+}
+
+// Columns kept free between the directory and the meter.
+export const FOOTER_GAP = 2
+
+// The meter is the point of this line, so on a narrow terminal the directory gives way first
+// (truncated with an ellipsis, as pi itself does); the meter is only dropped when even it alone
+// would not fit. Returns exactly `width` columns, padded between the two parts.
+export function mergeFooterLine(left: string, meter: string, width: number, fns: WidthFns): string {
+  const meterWidth = fns.visibleWidth(meter)
+  if (meter === "" || meterWidth > width) return left
+  const room = width - meterWidth - FOOTER_GAP
+  let head = left
+  if (room <= 0) head = ""
+  else if (fns.visibleWidth(left) > room) head = fns.truncate(left, room)
+  const pad = width - fns.visibleWidth(head) - meterWidth
+  return head + " ".repeat(Math.max(0, pad)) + meter
+}

package/src/format.ts

@@ -1,7 +1,9 @@
-// Display formatting and tier colouring, ported from opencode-tps-meter/tui.tsx.
+// Display formatting and tier colouring, ported from opencode-tps-meter/tui.tsx, plus the layout
+// of the thinking particle stream and right alignment.
 // Pure: no pi imports. The caller decides whether the host renders ANSI.
 
 import type { MeterReading } from "./core.ts"
+import type { Rgb, SpinnerCell } from "./spinner.ts"
 
 export type TpsTiers = { slow: number; normal: number; fast: number }
 export type TtftTiers = { fast: number; ok: number }
@@ -102,3 +104,36 @@ export function renderLine(reading: MeterReading, tiers: Tiers, color: boolean):
   ]
   return cells.map((c) => (color ? paint(c.text, c.hue) : c.text)).join("")
 }
+
+// Gaps in the stream are U+2800, the empty braille cell: one column, blank on screen, and not
+// whitespace. pi's footer sanitizer collapses runs of spaces and trims both ends of a status (JS
+// trim() also strips no-break spaces), either of which would make the stream jitter in width.
+const GAP = "\u2800"
+
+// The particle stream flows away from the meter. After the reading (status / widget) it runs
+// left to right, newest cell next to TTFT, as in the original. Before a right-aligned reading it
+// is mirrored, newest cell next to TPS, so the reading itself never moves.
+export function withSpinner(
+  line: string,
+  cells: SpinnerCell[],
+  paintRgb: (text: string, color: Rgb) => string,
+  side: "before" | "after",
+): string {
+  const ordered = side === "after" ? cells : [...cells].reverse()
+  const stream = ordered.map((c) => (c.glyph === " " ? GAP : paintRgb(c.glyph, c.color))).join("")
+  return side === "after" ? `${line} ${stream}` : `${stream} ${line}`
+}
+
+// Terminal columns of a string produced here: ANSI SGR codes take none, and every character used
+// (ASCII, braille) takes exactly one.
+export function visibleWidth(text: string): number {
+  return [...text.replace(/\x1b\[[0-9;]*m/g, "")].length
+}
+
+// Pads `line` so it ends in the last column. A line too wide for the terminal loses its colours and
+// is cut, because a TUI line must never exceed the width it is given.
+export function alignRight(line: string, width: number): string {
+  const w = visibleWidth(line)
+  if (w <= width) return " ".repeat(width - w) + line
+  return [...line.replace(/\x1b\[[0-9;]*m/g, "")].slice(w - width).join("")
+}

package/src/spinner.ts

@@ -0,0 +1,84 @@
+// The "thinking" particle stream, ported from opencode-tps-meter/tui.tsx: while reasoning streams,
+// a short FIFO of braille dots flows away from the meter, newest cell brightest, older cells fading
+// into the muted colour, the bright colour drifting along a gradient over time.
+//
+// Pure: randomness and the clock are parameters. Colours are plain sRGB; the extension paints them
+// through pi's theme, which converts to truecolor or 256 colours for the terminal.
+
+export type Rgb = { r: number; g: number; b: number }
+
+export type SpinnerConfig = { enabled: boolean; colors: Rgb[]; intervalMs: number; cells: number }
+
+export type SpinnerState = { stream: string[]; hueFrame: number; lastFrameAt: number }
+
+export type SpinnerCell = { glyph: string; color: Rgb }
+
+export type Random = () => number
+
+const DOT_GLYPHS = ["⠁", "⠂", "⠄", "⠈", "⠐", "⠠", "⠒", "⠑", "⠡", "⠢", "⠤", "⠨", "⠰", "⠸", "⠘", "⠔", "⠖", "⠦"]
+
+// One full sweep of the gradient takes this many frames (6s at the default 100ms).
+const HUE_FRAMES = 60
+
+export const THEME_PRESETS: Record<string, string[]> = {
+  tech: ["#00e5ff", "#2979ff", "#651fff"],
+  red: ["#ff1744", "#ff5252", "#ff8a80"],
+}
+
+// "#rrggbb" or "#rgb". The leading # is required: without it, words such as "bad" or "add" would
+// read as three-digit colours.
+export function parseHex(hex: string): Rgb | undefined {
+  const m = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(hex.trim())
+  if (!m) return undefined
+  const h = m[1].length === 3 ? [...m[1]].map((c) => c + c).join("") : m[1]
+  return { r: parseInt(h.slice(0, 2), 16), g: parseInt(h.slice(2, 4), 16), b: parseInt(h.slice(4, 6), 16) }
+}
+
+function lerp(a: number, b: number, t: number): number {
+  return a + (b - a) * t
+}
+
+export function lerpColor(a: Rgb, b: Rgb, t: number): Rgb {
+  return { r: Math.round(lerp(a.r, b.r, t)), g: Math.round(lerp(a.g, b.g, t)), b: Math.round(lerp(a.b, b.b, t)) }
+}
+
+// Position t in [0, 1] along a multi-stop gradient.
+export function gradientColor(colors: Rgb[], t: number): Rgb {
+  if (colors.length === 0) return { r: 136, g: 136, b: 136 }
+  if (colors.length === 1) return colors[0]
+  const c = Math.max(0, Math.min(1, t))
+  const seg = c * (colors.length - 1)
+  const i = Math.min(Math.floor(seg), colors.length - 2)
+  return lerpColor(colors[i], colors[i + 1], seg - i)
+}
+
+// Roughly one cell in five is a gap, so the stream reads as particles rather than a solid bar.
+function spawnGlyph(random: Random): string {
+  return random() < 0.18 ? " " : DOT_GLYPHS[Math.floor(random() * DOT_GLYPHS.length)]
+}
+
+// A fresh stream each time thinking starts, so consecutive thinking spans do not look identical.
+export function createSpinner(cells: number, now: number, random: Random): SpinnerState {
+  return { stream: Array.from({ length: cells }, () => spawnGlyph(random)), hueFrame: 0, lastFrameAt: now }
+}
+
+// Frames follow wall time (one per `intervalMs`), not render calls, so the stream keeps its speed
+// whatever the refresh rate. The frame count is capped so a long pause cannot loop for ages.
+export function advanceSpinner(state: SpinnerState, cfg: SpinnerConfig, now: number, random: Random): void {
+  const due = Math.floor((now - state.lastFrameAt) / cfg.intervalMs)
+  if (due <= 0) return
+  for (let i = 0; i < Math.min(due, cfg.cells); i++) {
+    state.stream.unshift(spawnGlyph(random))
+    if (state.stream.length > cfg.cells) state.stream.length = cfg.cells
+  }
+  state.hueFrame += due
+  state.lastFrameAt += due * cfg.intervalMs
+}
+
+// Cell 0 is the newest and carries the current gradient colour; each older cell fades a step
+// further toward `muted`. Gaps stay muted.
+export function spinnerCells(state: SpinnerState, cfg: SpinnerConfig, muted: Rgb): SpinnerCell[] {
+  const bright = gradientColor(cfg.colors, (state.hueFrame % HUE_FRAMES) / HUE_FRAMES)
+  const last = Math.max(1, state.stream.length - 1)
+  return state.stream.map((glyph, i) => ({ glyph, color: glyph === " " ? muted : lerpColor(bright, muted, i / last) }))
+}