pi-show-token-rate 0.1.0 → 0.2.0

package/README.md

@@ -7,12 +7,10 @@ active model is streaming output tokens, in the bottom status bar of the TUI.
 ⚡ 62 tok/s
 ```
 
-While the model streams, the number is a **live** trailing-window rate. Once the
-response settles, the line keeps the last measured rate plus a session average:
-
-```plaintext
-⚡ 62 tok/s · avg 55
-```
+While the model streams, the number is a **live** trailing-window rate, coloured
+by speed. When the stream ends the last reading keeps its value but is dimmed.
+There is no session history and no settled average — the line only ever reports
+a rate.
 
 The line is provider-agnostic: it measures whatever model is active, so there is
 no activation condition and nothing to configure per provider.
@@ -33,67 +31,100 @@ pi -e npm:pi-show-token-rate
 
 ## What the bar shows
 
-| Segment    | Meaning                                                                                                       |
-| ---------- | ------------------------------------------------------------------------------------------------------------- |
-| `⚡`       | Label, always dim                                                                                             |
-| `~`        | Present only when the number is estimated rather than provider-reported (see **Accuracy** below)              |
-| `62`       | Output tokens per second: live while streaming, the last response's rate once settled, rounded to whole tok/s |
-| `tok/s`    | Unit, dim                                                                                                     |
-| `· avg 55` | Duration-weighted average across completed responses; hidden until a second response finishes                 |
-
-The rate is colored green at **50 tok/s** and above, yellow at **20 tok/s** and
-above, and dim below that — a slow model reads as quiet, not as an error.
-
-The row stays blank until a response produces a measurable rate: the first
-token of a stream cannot be timed on its own. A response that ends without a
-measurable rate — an empty reply, or `/token-rate reset` — shows
-`⚡ tok/s —` instead.
+| Segment | Meaning                                                                            |
+| ------- | ---------------------------------------------------------------------------------- |
+| `⚡`    | Marker: green while streaming, `dim` once the stream ends                          |
+| `62`    | Output tokens per second, rounded, live while streaming, kept once the stream ends |
+| `tok/s` | Unit, dim                                                                          |
+
+While the model streams, the rate is coloured by speed:
+
+| Rate           | Colour |
+| -------------- | ------ |
+| above 50 tok/s | green  |
+| 10–50 tok/s    | yellow |
+| below 10 tok/s | red    |
+
+The colour is chosen from the number actually displayed, so the label and its
+colour never disagree (e.g. `50` is yellow, `51` is green). The `⚡` marker is
+green for as long as the model is streaming — regardless of the rate's own
+colour — so the bar reads as live at a glance; once the stream ends the marker
+goes back to `dim`, and the last reading is dimmed too.
+
+The row starts blank and stays blank until a response produces a measurable
+rate: the first token of a stream cannot be timed on its own, and the character
+estimate waits for a full second of history before it is believed. The `⚡`
+marker still turns green as soon as a response starts streaming; until a rate is
+measurable the row carries the previous reading over, dimmed (or shows
+`⚡ tok/s —` when nothing has been measured yet). A response that ends without a
+measurable rate — an empty reply, or an aborted one — leaves the previous
+reading in place.
 
 ## How the rate is measured
 
-- **Generation window only.** The clock starts at the first streamed token, not
-  at the request. Prompt prefill and time-to-first-token are excluded, so the
-  number answers "how fast does this model generate", not "how long did the
-  request take".
+- **Streaming only.** The rate is measured while the model produces tokens, and
+  nothing is settled afterwards. A response that is aborted or errors out is not
+  frozen at all — the bar keeps the previous reading.
 - **Trailing window while streaming.** Live updates average the last 3 seconds
   of streaming. Providers emit deltas in bursts and stall while writing a
   thinking block or tool-call JSON, so a per-event rate would flicker between 0
   and several hundred tok/s.
-- **Whole-response average once settled.** When `message_end` arrives, the
-  response is scored over its full generation window and folded into the
-  session average.
+- **Two scales, two windows.** A provider's cumulative output-token count and
+  the character estimate are different units, so each gets its own trailing
+  window. Provider usage wins while its window is moving, fresh and plausible;
+  otherwise the estimate answers. A provider count that repeats a
+  constant, stops being reported, or resets cannot freeze the live number — its
+  window expires like any other.
+- **Freeze, don't average.** When `message_end` arrives the current window value
+  is captured and the trackers are dropped; the bar keeps showing that reading,
+  dimmed.
 
 ## Accuracy
 
 Not every provider reports token usage while a response is streaming:
 
-- When `usage.output` is available (Anthropic and other providers that stream
-  usage), the extension uses it — the number is exact.
-- When it is not (OpenAI-compatible endpoints typically send usage only on the
-  final chunk), the extension estimates tokens as **streamed characters ÷ 4**,
-  the same heuristic pi itself uses for context estimation. Estimated numbers
-  are marked with a leading `~` so they are never mistaken for reported ones.
-- If usage only starts arriving halfway through a stream, the live number keeps
-  its `~` and its scale until the response ends — mixing a reported count into
-  a chars ÷ 4 window would spike the rate. The settled number is the exact
-  one, and the `~` disappears with it.
-
-The same fallback is used to keep counting when a tool call is streamed as
-JSON, so tool-heavy turns still measure sensibly.
+- When the provider reports a cumulative count that keeps advancing mid-stream,
+  the extension uses it — the number is exact.
+- When it does not — OpenAI-compatible endpoints typically send usage only on
+  the final chunk, and Anthropic reports a small count at the start and only
+  updates it in a terminal event pi does not surface — the live number falls
+  back to a **character estimate**: CJK, kana, Hangul, and fullwidth punctuation
+  count as roughly one token each, text as one per four characters, and
+  tool-call argument JSON as one per two and a half — JSON keys and punctuation
+  tokenize denser than prose. The bar does not label which scale answered: the
+  estimate exists only to keep the number moving while the provider stays quiet.
+- The two scales are measured in parallel, and a window whose newest reading has
+  fallen outside the trailing 3 seconds counts as unmeasurable, so a provider
+  count that stops advancing — a repeated constant, a dropped field, or a reset
+  counter — hands the row back to the estimate until it moves again.
+
+### Buffered tool calls
+
+Characters say when text **arrived**, not when it was generated. Endpoints that
+do not stream tool-call arguments token by token deliver a whole command — or a
+whole file — in one delta, and crediting that at face value would print four
+digits of tok/s. An estimated window therefore credits each interval with at
+most **twice the pace it is already running at** (a floor of 100 tok/s covers
+the first second, before the window has a pace of its own) and stays silent
+until it has a full second of history; provider counts are never credited that
+way. The ceiling follows the window's own **raw** pace, so a genuinely fast
+stream still reaches its real rate within a second or two instead of being held
+near the floor.
+
+A reading above **5,000 tok/s** — faster than any production model streams today
+— is refused for the same reason: providers that buffer a whole tool call and
+flush it in one burst hand the extension thousands of tokens a few milliseconds
+apart, and printing that window would show tens of thousands of tok/s. The line
+keeps its previous value instead.
+
+The wide/narrow weighting is a heuristic, not a tokenizer, so mixed scripts can
+still read a few percent low or high.
 
 ## Slash command
 
-| Command             | Effect                                                                      |
-| ------------------- | --------------------------------------------------------------------------- |
-| `/token-rate`       | Toggle the status line on or off                                            |
-| `/token-rate stats` | Notify with the last / average / peak rate and how many responses were seen |
-| `/token-rate reset` | Drop collected statistics, keeping the current visibility                   |
-
-`stats` output looks like:
-
-```plaintext
-last 62 tok/s · avg 55 tok/s · peak 91 tok/s · 12 responses · 3 estimated
-```
+| Command       | Effect                           |
+| ------------- | -------------------------------- |
+| `/token-rate` | Toggle the status line on or off |
 
 ## Development
 
@@ -107,11 +138,14 @@ pnpm test          # node --test
 pnpm typecheck     # tsc --noEmit
 ```
 
-Tests cover the character estimator, the tracker (windowing, monotonicity,
-pruning), the summary math, the exact status-line strings, and the controller's
-throttling and toggle behavior. The suite drives an injected clock, so no test
-depends on wall-clock timing, and it uses a stub theme instead of the real ANSI
-palette.
+Tests cover the character estimator, the trailing window (monotonicity, pruning,
+credit guards), the two-scale tracker, the exact status-line strings, and the
+controller's throttling, freezing and toggle behavior. Two windowing tests are
+differential: they replay thousands of irregularly-spaced observations and check
+`rate(now)` against the trailing-window definition at every step, so the
+incremental pruning cannot drift from it. The suite drives an injected clock, so
+no test depends on wall-clock timing, and it uses a stub theme instead of the
+real ANSI palette.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-show-token-rate",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Shows the live output token rate (tok/s) of the current model in the pi TUI status bar.",
   "keywords": [
     "pi-package",
@@ -11,6 +11,15 @@
     "tui"
   ],
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/luohuidong/pi-extensions.git",
+    "directory": "packages/pi-show-token-rate"
+  },
+  "bugs": {
+    "url": "https://github.com/luohuidong/pi-extensions/issues"
+  },
+  "homepage": "https://github.com/luohuidong/pi-extensions/tree/main/packages/pi-show-token-rate#readme",
   "type": "module",
   "files": [
     "src/",

package/src/format.ts

@@ -5,60 +5,72 @@
  * stats without crowding them:
  *
  *   ⚡ 62 tok/s          while the model streams (trailing-window rate)
- *   ⚡ 62 tok/s · avg 55 once the response settles
- *   ⚡ ~62 tok/s         a `~` marks a chars ÷ 4 estimate instead of real usage
- *   ⚡ tok/s —           nothing measured yet
+ *   ⚡ 62 tok/s          the last measured rate, dimmed, once the stream ends
+ *   ⚡ tok/s —           nothing measured yet (marker still green while streaming)
+ *
+ * While streaming the rate is coloured by the spec's buckets — green above
+ * 50 tok/s, yellow from 10 through 50, red below 10 — and the `⚡` marker is
+ * green. Once the stream ends the number keeps its value but is dimmed, and
+ * the marker goes back to dim.
  */
 
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 
-import type { RateSummary } from "./rate.ts";
-
 export type Theme = ExtensionContext["ui"]["theme"];
 
 const LABEL = "⚡";
 export const RATE_UNIT = "tok/s";
 
-/** At or above this many tok/s the rate is green. */
-const FAST_MIN = 50;
-/** At or above this many tok/s the rate is yellow; below that it is dim. */
-const SLOW_MIN = 20;
+/** Strictly above this many displayed tok/s the rate is green. */
+const FAST_ABOVE = 50;
+/** At or above this many displayed tok/s the rate is yellow; below it, red. */
+const SLOW_MIN = 10;
 
 /** Everything the status line can render. */
 export interface RateView {
   /** Tokens per second to show; omitted when nothing has been measured. */
   rate?: number;
-  /** Mark the rate as estimated (`~` prefix) rather than provider-reported. */
-  estimated?: boolean;
-  /** Session average, appended as `· avg NN` when present. */
-  average?: number;
+  /** While true the `⚡` marker is green. */
+  streaming?: boolean;
+  /**
+   * Whether `rate` is a live measurement. While streaming, a response that
+   * cannot be measured yet carries the last reading over under a green marker;
+   * `measured: false` dims that carried-over number so it is not read as live.
+   * Defaults to true whenever `streaming` is set.
+   */
+  measured?: boolean;
 }
 
 /**
- * Rate → short display string. Sub-10 values keep one decimal (a slow model
- * is exactly where precision is interesting); everything above is rounded to
- * whole tokens so the footer does not jitter.
- *
- * The value is rounded to one decimal *first*, so 9.99 renders as `10`
- * instead of `10.0` — the same shape 10.0 gets.
+ * The numeric value the label shows: one decimal below 10 (a slow model is
+ * exactly where precision is interesting), whole tokens above it. Colour is
+ * picked from this same value, so the label and its bucket never disagree.
  */
+function displayedValue(value: number): number {
+  return value < 10 ? Math.round(value * 10) / 10 : Math.round(value);
+}
+
+/** Rate → short display string. */
 export function formatRate(value: number): string {
   if (!Number.isFinite(value) || value <= 0) return "—";
-  const rounded = Math.round(value * 10) / 10;
-  if (rounded < 10) return rounded.toFixed(1);
-  return String(Math.round(rounded));
+  const shown = displayedValue(value);
+  if (shown < 10) return shown.toFixed(1);
+  return String(shown);
 }
 
 function rateColor(theme: Theme, value: number): string {
   const text = formatRate(value);
-  if (value >= FAST_MIN) return theme.fg("success", text);
-  if (value >= SLOW_MIN) return theme.fg("warning", text);
-  // Slow is not an error — keep it readable but out of the way.
-  return theme.fg("dim", text);
+  const shown = displayedValue(value);
+  if (shown > FAST_ABOVE) return theme.fg("success", text);
+  if (shown >= SLOW_MIN) return theme.fg("warning", text);
+  // Below the spec's slow threshold the rate reads as a problem, not as quiet.
+  return theme.fg("error", text);
 }
 
 export function formatStatusLine(theme: Theme, view: RateView): string {
-  const label = theme.fg("dim", LABEL);
+  // The marker is green while the model streams — a live signal independent of
+  // the rate's own colour — and dim once the response is over.
+  const label = theme.fg(view.streaming ? "success" : "dim", LABEL);
   if (
     view.rate === undefined ||
     !Number.isFinite(view.rate) ||
@@ -67,39 +79,13 @@ export function formatStatusLine(theme: Theme, view: RateView): string {
     return [label, " ", theme.fg("dim", `${RATE_UNIT} —`)].join("");
   }
 
-  const parts = [
-    label,
-    " ",
-    view.estimated ? theme.fg("dim", "~") : "",
-    rateColor(theme, view.rate),
-    " ",
-    theme.fg("dim", RATE_UNIT),
-  ];
-  if (
-    view.average !== undefined &&
-    Number.isFinite(view.average) &&
-    view.average > 0
-  ) {
-    parts.push(
-      theme.fg("dim", " · avg "),
-      theme.fg("dim", formatRate(view.average)),
-    );
-  }
-  return parts.join("");
-}
+  // Streaming is the only state where the number means "right now"; a
+  // carried-over reading (streaming but not measurable yet) and the frozen
+  // idle value are both shown dim.
+  const measured = view.streaming && view.measured !== false;
+  const rate = measured
+    ? rateColor(theme, view.rate)
+    : theme.fg("dim", formatRate(view.rate));
 
-/** One-line summary for the `/token-rate stats` notification. */
-export function formatSummary(summary: RateSummary): string {
-  if (summary.count === 0 || !summary.last) return "no completed responses yet";
-
-  const parts = [
-    `last ${formatRate(summary.last.tokPerSec)} ${RATE_UNIT}`,
-    `avg ${formatRate(summary.average ?? 0)} ${RATE_UNIT}`,
-    `peak ${formatRate(summary.peak ?? 0)} ${RATE_UNIT}`,
-    `${summary.count} ${summary.count === 1 ? "response" : "responses"}`,
-  ];
-  if (summary.estimated > 0) {
-    parts.push(`${summary.estimated} estimated`);
-  }
-  return parts.join(" · ");
+  return [label, " ", rate, " ", theme.fg("dim", RATE_UNIT)].join("");
 }

package/src/index.ts

@@ -1,25 +1,21 @@
 /**
  * Token rate for the pi TUI footer.
  *
- * Watches the assistant message stream and shows how fast the active model
- * is producing output tokens:
+ * Watches the assistant message stream and shows how fast the active model is
+ * producing output tokens:
  *
- *   ⚡ 62 tok/s            live, while the model streams
- *   ⚡ 62 tok/s · avg 55   the last response plus the session average
+ *   ⚡ 62 tok/s   live while the model streams, dimmed once the stream ends
  *
- * The rate is measured over the generation window (first token → last token)
- * so prompt prefill does not drag it down, and the live number is a
- * trailing-window average so it stays readable between bursty deltas.
- *
- * This file only wires events to the controller in `./line.ts`.
+ * The rate is measured over a trailing window while tokens arrive, so it stays
+ * readable between bursty deltas; there is no session history and no settled
+ * average. This file only wires events to the controller in `./line.ts`.
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
-import { formatSummary } from "./format.ts";
 import { TokenRateLine } from "./line.ts";
 
-const USAGE = "token-rate: /token-rate [stats|reset]";
+const USAGE = "token-rate: /token-rate";
 
 export default function (pi: ExtensionAPI) {
   const line = new TokenRateLine();
@@ -43,22 +39,11 @@ export default function (pi: ExtensionAPI) {
   pi.registerCommand("token-rate", {
     description: "Show or hide the tok/s line in the status bar",
     handler: async (args, ctx) => {
-      const sub = args.trim().toLowerCase();
-
-      if (sub === "stats") {
-        ctx.ui.notify(`token-rate: ${formatSummary(line.summary())}`, "info");
-        return;
-      }
       if (!ctx.hasUI) {
         ctx.ui.notify("token-rate: no UI in this mode", "warning");
         return;
       }
-      if (sub === "reset") {
-        line.reset(ctx);
-        ctx.ui.notify("token-rate: statistics cleared", "info");
-        return;
-      }
-      if (sub !== "") {
+      if (args.trim() !== "") {
         ctx.ui.notify(USAGE, "warning");
         return;
       }