pi-show-token-rate 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,9 @@
+The MIT License
+
+Copyright 2026-present Luo Huidong
+
+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,118 @@
-# Temporary Holding Version
+# Show Token Rate For Pi Coding Agent
 
-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.
+A [pi](https://github.com/earendil-works/pi) extension that shows how fast the
+active model is streaming output tokens, in the bottom status bar of the TUI.
+
+```plaintext
+⚡ 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
+```
+
+The line is provider-agnostic: it measures whatever model is active, so there is
+no activation condition and nothing to configure per provider.
+
+## Install
+
+Install from npm:
+
+```bash
+pi install npm:pi-show-token-rate
+```
+
+For a one-off test run without installing:
+
+```bash
+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.
+
+## 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".
+- **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.
+
+## 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.
+
+## 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
+```
+
+## Development
+
+Requires the workspace's Node version (`>=26`): the suite is plain
+`node --test`, which relies on Node running `.ts` files through its built-in
+type stripping.
+
+```bash
+pnpm install
+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.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "pi-show-token-rate",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Shows the live output token rate (tok/s) of the current model in the pi TUI status bar.",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "tokens",
+    "token-rate",
+    "tps",
+    "tui"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "files": [
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "test": "node --test",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "pnpm typecheck && pnpm test"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.85.1"
+  }
+}

package/src/format.ts

@@ -0,0 +1,105 @@
+/**
+ * TUI formatting — pure functions, no side effects, no I/O.
+ *
+ * The status line is intentionally terse so it fits next to pi's own footer
+ * 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
+ */
+
+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;
+
+/** 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;
+}
+
+/**
+ * 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.
+ */
+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));
+}
+
+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);
+}
+
+export function formatStatusLine(theme: Theme, view: RateView): string {
+  const label = theme.fg("dim", LABEL);
+  if (
+    view.rate === undefined ||
+    !Number.isFinite(view.rate) ||
+    view.rate <= 0
+  ) {
+    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("");
+}
+
+/** 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(" · ");
+}

package/src/index.ts

@@ -0,0 +1,74 @@
+/**
+ * Token rate for the pi TUI footer.
+ *
+ * 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
+ *
+ * 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`.
+ */
+
+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]";
+
+export default function (pi: ExtensionAPI) {
+  const line = new TokenRateLine();
+
+  pi.on("session_start", (_event, ctx) => {
+    line.start(ctx);
+  });
+
+  pi.on("message_start", (event, ctx) => {
+    line.onMessageStart(ctx, event.message);
+  });
+
+  pi.on("message_update", (event, ctx) => {
+    line.onUpdate(ctx, event);
+  });
+
+  pi.on("message_end", (event, ctx) => {
+    line.onMessageEnd(ctx, event.message);
+  });
+
+  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 !== "") {
+        ctx.ui.notify(USAGE, "warning");
+        return;
+      }
+
+      ctx.ui.notify(
+        line.toggle(ctx)
+          ? "token-rate: status line on"
+          : "token-rate: status line off",
+        "info",
+      );
+    },
+  });
+}

package/src/line.ts

@@ -0,0 +1,233 @@
+/**
+ * Token-rate status line controller.
+ *
+ * Owns the footer entry: it observes assistant stream events, turns them
+ * into a rate, throttles the writes so a 100 tok/s stream does not ask the
+ * TUI to re-render 100 times a second, and keeps the session statistics the
+ * line and `/token-rate stats` read from.
+ *
+ * The controller holds no timers and no handles — pi delivers stream events
+ * for the lifetime of a response, and `message_end` is the last one. That
+ * keeps `session_shutdown` a no-op and avoids the "start resources in
+ * `session_start`" trap the extension API warns about.
+ */
+
+import type {
+  ExtensionContext,
+  MessageEndEvent,
+  MessageUpdateEvent,
+} from "@earendil-works/pi-coding-agent";
+
+import { formatStatusLine } from "./format.ts";
+import {
+  countContentChars,
+  estimateTokensFromChars,
+  type RateSample,
+  type RateSummary,
+  RateTracker,
+  summarize,
+} from "./rate.ts";
+
+/** Footer row identifier. Locked: other extensions may look the row up. */
+const STATUS_KEY = "token-rate";
+
+/**
+ * Minimum gap between footer writes while streaming. 150ms is ~6 updates per
+ * second — fast enough to look live, slow enough to stay off the render path
+ * of every token delta.
+ */
+const WRITE_INTERVAL_MS = 150;
+
+/** Cap on retained samples, so a very long session cannot grow unbounded. */
+const MAX_SAMPLES = 200;
+
+type StreamEvent = MessageUpdateEvent["assistantMessageEvent"];
+type AssistantMessage = Extract<
+  MessageEndEvent["message"],
+  { role: "assistant" }
+>;
+
+/** Characters carried by a token-bearing stream event; 0 for lifecycle events. */
+function deltaChars(event: StreamEvent): number {
+  switch (event.type) {
+    case "text_delta":
+    case "thinking_delta":
+    case "toolcall_delta":
+      return event.delta.length;
+    default:
+      return 0;
+  }
+}
+
+/**
+ * Stop reasons that end a response without finishing it. pi still emits
+ * `message_end` for these, and the window they produce is a truncated sample
+ * of a model that was cut off — folding it into `avg` / `peak` would bias both.
+ */
+function isDroppedResponse(message: AssistantMessage): boolean {
+  return message.stopReason === "aborted" || message.stopReason === "error";
+}
+
+export class TokenRateLine {
+  #tracker = new RateTracker();
+  #samples: RateSample[] = [];
+  #chars = 0;
+  #visible = true;
+  #lastWriteAt = Number.NEGATIVE_INFINITY;
+  #rendered: string | undefined;
+  readonly #now: () => number;
+
+  /** `now` is injectable so tests can drive the throttle deterministically. */
+  constructor(now: () => number = Date.now) {
+    this.#now = now;
+  }
+
+  /** Session start: forget everything, including any line a reload left behind. */
+  start(ctx: ExtensionContext): void {
+    this.#tracker.abort();
+    this.#samples = [];
+    this.#chars = 0;
+    this.#visible = true;
+    this.#lastWriteAt = Number.NEGATIVE_INFINITY;
+    this.#rendered = undefined;
+    this.#write(ctx, undefined);
+  }
+
+  /** A new assistant message begins; the generation window reopens here. */
+  onMessageStart(
+    ctx: ExtensionContext,
+    message: MessageEndEvent["message"],
+  ): void {
+    if (!ctx.hasUI || message.role !== "assistant") return;
+    this.#tracker.arm();
+    this.#chars = 0;
+    // The next delta writes immediately instead of waiting out an old throttle.
+    this.#lastWriteAt = Number.NEGATIVE_INFINITY;
+  }
+
+  /** Stream progress. Throttled: the tracker always sees every observation. */
+  onUpdate(ctx: ExtensionContext, event: MessageUpdateEvent): void {
+    if (!ctx.hasUI) return;
+    const message = event.message;
+    if (message.role !== "assistant") return;
+
+    const chars = deltaChars(event.assistantMessageEvent);
+    if (chars === 0) return;
+
+    const now = this.#now();
+    this.#chars += chars;
+    const usage = message.usage.output;
+    const reported = Number.isFinite(usage) && usage > 0;
+    this.#tracker.observe(
+      now,
+      reported ? usage : estimateTokensFromChars(this.#chars),
+      reported ? "usage" : "estimate",
+    );
+
+    if (now - this.#lastWriteAt < WRITE_INTERVAL_MS) return;
+    this.#lastWriteAt = now;
+    this.#render(ctx, true);
+  }
+
+  /** The response is done: record the sample and repaint the settled rate. */
+  onMessageEnd(
+    ctx: ExtensionContext,
+    message: MessageEndEvent["message"],
+  ): void {
+    if (!ctx.hasUI || message.role !== "assistant") return;
+
+    if (isDroppedResponse(message)) {
+      // Interrupted or failed: keep the previous settled line instead of
+      // showing a rate that was never really measured.
+      this.#tracker.abort();
+      this.#lastWriteAt = Number.NEGATIVE_INFINITY;
+      this.#render(ctx, false);
+      return;
+    }
+
+    const usage = message.usage.output;
+    const reported = Number.isFinite(usage) && usage > 0;
+    // Without provider usage, prefer the richest estimate available: chars
+    // accumulated from deltas, or the finished content if it holds more.
+    // Counting the content is the expensive half (it stringifies tool-call
+    // arguments), so it stays behind the `reported` check.
+    const tokens = reported
+      ? usage
+      : Math.max(
+          estimateTokensFromChars(this.#chars),
+          estimateTokensFromChars(countContentChars(message.content)),
+        );
+
+    const sample = this.#tracker.finish(
+      this.#now(),
+      tokens,
+      reported ? "usage" : "estimate",
+    );
+    if (sample) {
+      this.#samples.push(sample);
+      if (this.#samples.length > MAX_SAMPLES) this.#samples.shift();
+    }
+
+    this.#lastWriteAt = Number.NEGATIVE_INFINITY;
+    this.#render(ctx, false);
+  }
+
+  /** Flip the line on or off. Returns the new visibility. */
+  toggle(ctx: ExtensionContext): boolean {
+    this.#visible = !this.#visible;
+    this.#render(ctx, this.#tracker.streaming);
+    return this.#visible;
+  }
+
+  /** Forget collected samples, keep the current visibility. */
+  reset(ctx: ExtensionContext): void {
+    this.#samples = [];
+    this.#render(ctx, this.#tracker.streaming);
+  }
+
+  summary(): RateSummary {
+    return summarize(this.#samples);
+  }
+
+  /** Live rate while streaming, last response's rate once settled. */
+  #render(ctx: ExtensionContext, streaming: boolean): void {
+    if (!this.#visible) {
+      // Forget the cached line so showing it again always repaints — but
+      // don't re-clear a row that is already blank on every stream tick.
+      if (this.#rendered === undefined) return;
+      this.#rendered = undefined;
+      this.#write(ctx, undefined);
+      return;
+    }
+
+    const live = streaming ? this.#tracker.liveRate() : null;
+    // Nothing measurable yet for this response (no token inside the window) —
+    // keep the previous line instead of blanking it out mid-stream.
+    if (streaming && live === null) return;
+
+    const summary = this.summary();
+    const rate = live ?? summary.last?.tokPerSec;
+    // The live rate is a difference of the window's checkpoints, so it counts
+    // as estimated exactly when the window opened on estimates — a provider
+    // that starts reporting usage mid-stream keeps the `~` until the response
+    // settles on the reported count.
+    const source =
+      live !== null ? this.#tracker.windowSource : summary.last?.source;
+
+    const text = formatStatusLine(ctx.ui.theme, {
+      rate,
+      estimated: source === "estimate",
+      // One response has no "average" — it would just repeat the last value.
+      average: summary.count >= 2 ? summary.average : undefined,
+    });
+
+    if (text === this.#rendered) return;
+    this.#rendered = text;
+    this.#write(ctx, text);
+  }
+
+  #write(ctx: ExtensionContext, text: string | undefined): void {
+    if (!ctx.hasUI) return;
+    ctx.ui.setStatus(STATUS_KEY, text);
+  }
+}

package/src/rate.ts

@@ -0,0 +1,322 @@
+/**
+ * Token-rate math.
+ *
+ * Pure functions plus one small per-response tracker. Nothing here knows
+ * about pi, the terminal, or the network: the caller feeds it `(timestamp,
+ * output tokens)` observations and gets rates back, which keeps every rule
+ * below unit-testable in isolation.
+ *
+ * Two rules drive the whole module:
+ *
+ *   1. **Rate is measured over the generation window** — from the first
+ *      observed token to the last one. Prompt prefill / time-to-first-token
+ *      is deliberately excluded, because "how fast does this model stream"
+ *      means generation speed, not request latency.
+ *   2. **The live number is a trailing-window rate**, not an instantaneous
+ *      one. Providers emit token deltas in bursts (and stall while writing a
+ *      tool call or a thinking block), so a per-event rate flickers between
+ *      0 and several hundred tok/s. Averaging over the last few seconds
+ *      smooths that out without lagging far behind reality.
+ */
+
+/**
+ * Chars per token for the fallback estimator. Matches pi's own
+ * `estimateTokens` heuristic (content length ÷ 4), which is what the TUI
+ * uses when a provider has not reported usage yet.
+ */
+const CHARS_PER_TOKEN = 4;
+
+/**
+ * Trailing window for the live rate. Long enough to smooth bursty deltas,
+ * short enough that a real slowdown (thinking, tool-call JSON) still shows up
+ * within a couple of seconds.
+ */
+export const LIVE_WINDOW_MS = 3_000;
+
+/**
+ * Where a token count came from:
+ *
+ *   - `usage` — the provider reported real output tokens (authoritative)
+ *   - `estimate` — derived from streamed characters ÷ 4 (providers such as
+ *     OpenAI-compatible endpoints only send usage on the final chunk)
+ */
+export type TokenSource = "usage" | "estimate";
+
+export interface RateSample {
+  /** Output tokens produced inside the measured window. */
+  tokens: number;
+  /** Generation window in milliseconds (first token → last token). */
+  elapsedMs: number;
+  /** Tokens per second over that window. */
+  tokPerSec: number;
+  /** Whether `tokens` is a real count or a chars ÷ 4 estimate. */
+  source: TokenSource;
+}
+
+export interface Checkpoint {
+  /** Wall-clock stamp in milliseconds. */
+  at: number;
+  /** Output tokens produced so far (monotonic). */
+  tokens: number;
+}
+
+/**
+ * The first checkpoint of a generation window, plus the scale its counter is
+ * in. A chars ÷ 4 estimate and a provider usage count are not interchangeable,
+ * so `finish()` has to know which one the window opened with.
+ */
+interface WindowStart extends Checkpoint {
+  source: TokenSource;
+}
+
+/**
+ * Structural subset of an assistant content block. Only the fields the
+ * estimator reads are declared, so a real `AssistantMessage["content"]` is
+ * assignable without an index signature.
+ */
+export interface ContentBlock {
+  type: string;
+  text?: string;
+  thinking?: string;
+  arguments?: unknown;
+}
+
+/**
+ * Chars ÷ 4 → tokens, rounded up. Non-finite or negative input → 0, so a
+ * malformed event can never poison the rate with NaN.
+ */
+export function estimateTokensFromChars(chars: number): number {
+  if (!Number.isFinite(chars) || chars <= 0) return 0;
+  return Math.ceil(chars / CHARS_PER_TOKEN);
+}
+
+/**
+ * Total characters of an assistant message's content: answer text, thinking
+ * text, and tool-call argument JSON. Mirrors what a tokenizer would see,
+ * which is all the fallback estimator needs.
+ */
+export function countContentChars(content: readonly ContentBlock[]): number {
+  let chars = 0;
+  for (const block of content) {
+    if (block.type === "toolCall") {
+      chars += argumentsChars(block.arguments);
+      continue;
+    }
+    chars += block.text?.length ?? block.thinking?.length ?? 0;
+  }
+  return chars;
+}
+
+function argumentsChars(args: unknown): number {
+  if (args === undefined) return 0;
+  try {
+    return JSON.stringify(args)?.length ?? 0;
+  } catch {
+    // Cyclic or otherwise unserializable arguments — count as zero rather
+    // than tearing down the stream handler.
+    return 0;
+  }
+}
+
+/**
+ * Per-response rate tracker.
+ *
+ * Lifecycle: `arm()` on `message_start`, `observe()` on every token-bearing
+ * stream event, then exactly one `finish()` on `message_end` (or `abort()`
+ * when the response is dropped). The first `observe()` opens the generation
+ * window, so prefill never counts against the rate.
+ *
+ * Two checkpoint sets are kept: `#first` pins the start of the generation
+ * window so `finish()` can still average the whole response after pruning,
+ * and `#checkpoints` holds only the trailing window that `liveRate()`
+ * reads.
+ */
+export class RateTracker {
+  #checkpoints: Checkpoint[] = [];
+  #first: WindowStart | undefined;
+  #armed = false;
+
+  /** True between `arm()` and `finish()` / `abort()`. */
+  get armed(): boolean {
+    return this.#armed;
+  }
+
+  /** True once at least one token has been observed for this response. */
+  get streaming(): boolean {
+    return this.#checkpoints.length > 0;
+  }
+
+  /**
+   * Scale the current window's checkpoints are counted in — the scale the
+   * window *opened* with, not the scale of the newest observation. `undefined`
+   * while nothing has been observed.
+   *
+   * Callers label the live rate from this: a provider that starts reporting
+   * usage mid-stream does not upgrade the in-flight number to exact, it just
+   * stops being believed for the rest of the window.
+   */
+  get windowSource(): TokenSource | undefined {
+    return this.#first?.source;
+  }
+
+  /** Mark a response as in flight. Drops any state from the previous one. */
+  arm(): void {
+    this.#checkpoints = [];
+    this.#first = undefined;
+    this.#armed = true;
+  }
+
+  /**
+   * Record progress. The first call opens the generation window; later calls
+   * append. Non-monotonic stamps, token counts that go backwards, and
+   * observations on a different scale than the window opened with are ignored,
+   * so a provider that resets (or reorders, or starts reporting usage halfway
+   * through) its usage counter cannot produce a spike.
+   *
+   * `source` is the scale `tokens` is counted in. Checkpoints inside one
+   * window must share it — the counters are cumulative, so mixing them would
+   * compare two different units.
+   */
+  observe(at: number, tokens: number, source: TokenSource): void {
+    if (!this.#armed) this.arm();
+
+    const last = this.#checkpoints.at(-1);
+    if (last) {
+      if (at <= last.at || tokens < last.tokens) return;
+      // Stay on the scale the window opened with. `finish()` is where a
+      // reported count is allowed to replace an estimated one.
+      if (this.#first?.source !== source) return;
+    } else {
+      this.#first = { at, tokens, source };
+    }
+
+    this.#checkpoints.push({ at, tokens });
+    this.#prune(at);
+  }
+
+  /**
+   * Rate over the trailing {@link LIVE_WINDOW_MS}, in tokens per second.
+   * `null` when nothing was observed yet, when the window holds a single
+   * point, or when no new token arrived inside it.
+   *
+   * The window length is not a parameter: `#prune` already discards anything
+   * older than `LIVE_WINDOW_MS`, so a wider window could only ever read from
+   * checkpoints that no longer exist.
+   */
+  liveRate(): number | null {
+    const current = this.#checkpoints.at(-1);
+    if (!current) return null;
+
+    const baseline = this.#baselineAt(current.at);
+    const elapsedMs = current.at - baseline.at;
+    const tokens = current.tokens - baseline.tokens;
+    if (elapsedMs <= 0 || tokens <= 0) return null;
+
+    return (tokens * 1000) / elapsedMs;
+  }
+
+  /**
+   * Close the window and return the response's overall rate, or `null` when
+   * the response produced no measurable tokens (empty reply, instant abort).
+   * The rate covers the whole generation window, which is what pruning the
+   * live checkpoints would otherwise throw away.
+   */
+  finish(at: number, tokens: number, source: TokenSource): RateSample | null {
+    const first = this.#first;
+    this.#checkpoints = [];
+    this.#first = undefined;
+    this.#armed = false;
+
+    if (!first) return null;
+    const elapsedMs = at - first.at;
+    // Tokens that were already on the counter when the window opened are
+    // excluded — they were produced during prefill. That subtraction is only
+    // meaningful when both numbers use the same scale: a provider that only
+    // reports usage on its final chunk opened the window on chars ÷ 4
+    // estimates, so there the full count is the closer approximation.
+    const produced = first.source === source ? tokens - first.tokens : tokens;
+    if (elapsedMs <= 0 || produced <= 0) return null;
+
+    return {
+      tokens: produced,
+      elapsedMs,
+      tokPerSec: (produced * 1000) / elapsedMs,
+      source,
+    };
+  }
+
+  /** Drop the in-flight response without producing a sample. */
+  abort(): void {
+    this.#checkpoints = [];
+    this.#first = undefined;
+    this.#armed = false;
+  }
+
+  /** Newest checkpoint at/before the window start; falls back to the oldest. */
+  #baselineAt(now: number): Checkpoint {
+    const cutoff = now - LIVE_WINDOW_MS;
+    let baseline = this.#checkpoints[0];
+    for (const checkpoint of this.#checkpoints) {
+      if (checkpoint.at <= cutoff) baseline = checkpoint;
+      else break;
+    }
+    return baseline;
+  }
+
+  /** Keep the window's tail plus the single baseline in front of it. */
+  #prune(now: number): void {
+    const cutoff = now - LIVE_WINDOW_MS;
+    let baseline: Checkpoint | undefined;
+    const kept: Checkpoint[] = [];
+    for (const checkpoint of this.#checkpoints) {
+      if (checkpoint.at <= cutoff) baseline = checkpoint;
+      else kept.push(checkpoint);
+    }
+    this.#checkpoints = baseline ? [baseline, ...kept] : kept;
+  }
+}
+
+export interface RateSummary {
+  /** Number of completed responses. */
+  count: number;
+  /** Most recent completed response. */
+  last: RateSample | undefined;
+  /** Duration-weighted mean rate across completed responses. */
+  average: number | undefined;
+  /** Fastest completed response. */
+  peak: number | undefined;
+  /** How many of the samples came from the chars ÷ 4 fallback. */
+  estimated: number;
+}
+
+/** Aggregate completed samples into the numbers the status line and `/token-rate stats` show. */
+export function summarize(samples: readonly RateSample[]): RateSummary {
+  if (samples.length === 0) {
+    return {
+      count: 0,
+      last: undefined,
+      average: undefined,
+      peak: undefined,
+      estimated: 0,
+    };
+  }
+
+  let tokens = 0;
+  let elapsedMs = 0;
+  let peak = Number.NEGATIVE_INFINITY;
+  let estimated = 0;
+  for (const sample of samples) {
+    tokens += sample.tokens;
+    elapsedMs += sample.elapsedMs;
+    if (sample.tokPerSec > peak) peak = sample.tokPerSec;
+    if (sample.source === "estimate") estimated += 1;
+  }
+
+  return {
+    count: samples.length,
+    last: samples[samples.length - 1],
+    average: elapsedMs > 0 ? (tokens * 1000) / elapsedMs : undefined,
+    peak: Number.isFinite(peak) ? peak : undefined,
+    estimated,
+  };
+}