@smoose/pi-tps 0.0.1

package/LICENSE

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

@@ -0,0 +1,101 @@
+# pi-tps
+
+Decode throughput for pi: how fast the model is actually generating, in the footer.
+
+`20 tok/s` appears once an assistant message settles, and keeps running for the
+session.
+
+## What it measures
+
+```
+tps = Σ provider output tokens / (Σ decode wall time / 1000)
+decode wall time = first output token → settled message
+```
+
+The sums run over the most recent 200 settled messages, so a normal session is
+cumulative and a long one becomes a rolling readout.
+
+- **Decode only.** TTFT, queueing, tool execution and retry waits stay out of the
+  denominator, so this reads lower than an end-to-end tokens/second figure.
+- **Provider tokens.** The numerator is the provider's reported `usage.output`,
+  never a count of stream deltas. A message with no reported usage is skipped, not
+  estimated.
+- **Time-weighted.** Windows are summed before dividing; this is not an average of
+  per-message rates, so a slow answer weighs more than a fast one.
+- **First token means real output.** `text_delta`, `thinking_delta` or
+  `toolcall_delta` carrying a non-empty fragment, or the start of a tool call —
+  the last one counts so a tool call with no argument deltas still gets a
+  first-token time instead of being dropped.
+- **Cancelled and failed calls are excluded.** They settle as messages but
+  assembled no response, so they contribute nothing to the window.
+- **Settled only.** The figure never moves mid-stream; a displayed number is
+  always a complete window.
+- **One attempt per turn.** pi restarts a turn when it auto-retries, so only the
+  attempt that produced the message is measured.
+
+## Install
+
+```bash
+pi install npm:@smoose/pi-tps
+```
+
+Or from a local checkout — point settings at the directory:
+
+```json
+{ "extensions": ["/path/to/pi-tps"] }
+```
+
+or symlink it into the auto-discovered directory (`/reload` picks it up):
+
+```bash
+ln -s /path/to/pi-tps ~/.pi/agent/extensions/pi-tps
+```
+
+Or run a package once without installing it:
+
+```bash
+pi -e npm:@smoose/pi-tps
+```
+
+## Footer wiring
+
+The extension publishes the `tps` status key. With `@smoose/pi-footer`, add a
+custom item and a segment to `~/.pi/agent/settings.json`:
+
+```json
+{
+  "footer": {
+    "segments": ["model", "thinking", "path", "git", "context_pct", "custom:tps", "cost"],
+    "customItems": [
+      { "id": "tps", "statusKey": "tps", "prefix": "TPS", "color": "accent", "hideWhenMissing": true }
+    ]
+  }
+}
+```
+
+`hideWhenMissing: true` keeps the slot empty until the first message settles.
+Without a footer extension the key is simply unused; nothing breaks.
+
+## State
+
+In memory only. Nothing is written to the session: no custom entries, nothing in
+the transcript, nothing in `/tree`. The window is cleared when:
+
+- the process restarts, or `/reload`, `/new`, `/resume`, `/fork` recreates the
+  session or the extension;
+- the model changes — decode speed is a property of the model, and blending two
+  models' samples would make the figure meaningless. Selecting the same model
+  again does not clear it.
+
+`/tree` navigation deliberately does not clear it: rewinding is not a model
+change and those tokens were still generated. Auto-compaction does not clear it
+either.
+
+The window holds the 200 most recent samples, and the oldest drop out beyond that.
+
+## Development
+
+```bash
+bun install
+bun run typecheck
+```

package/index.ts

@@ -0,0 +1,84 @@
+/**
+ * pi-tps — decode throughput in the footer.
+ *
+ * The measurement is deepseek-harness's: provider-reported output tokens over the
+ * decode wall time only (first output token → settled message), blended over the
+ * most recent WINDOW_SIZE settled messages. It is settled-only by design — the
+ * figure updates when an assistant message lands and never moves mid-stream, so a
+ * displayed value is always a complete window rather than a running guess.
+ *
+ * State is in-memory: nothing is written to the session, so /tree stays clean and
+ * a restarted process starts over.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+  formatTokensPerSecond,
+  isTokenDelta,
+  outputTokens,
+  pushSample,
+  tokensPerSecond,
+  type DecodeSample,
+} from "./metrics.ts";
+
+/** Footer status key. Point a footer custom item's `statusKey` at it. */
+const STATUS_KEY = "tps";
+
+export default function (pi: ExtensionAPI) {
+  let samples: DecodeSample[] = [];
+  let firstTokenAt: number | null = null;
+
+  function publish(ctx: ExtensionContext): void {
+    const value = tokensPerSecond(samples);
+    ctx.ui.setStatus(STATUS_KEY, value === undefined ? undefined : formatTokensPerSecond(value));
+  }
+
+  /** Drop the window and blank the footer slot: the old figure describes work that no longer applies. */
+  function reset(ctx: ExtensionContext): void {
+    samples = [];
+    firstTokenAt = null;
+    ctx.ui.setStatus(STATUS_KEY, undefined);
+  }
+
+  // A restarted, resumed, forked or newly created session is a different
+  // conversation than whatever this process was counting.
+  pi.on("session_start", (_event, ctx) => {
+    reset(ctx);
+  });
+
+  // Decode speed is a property of the model; mixing two models' samples makes the
+  // figure meaningless. /tree navigation is not a model change and keeps the window.
+  pi.on("model_select", (_event, ctx) => {
+    reset(ctx);
+  });
+
+  pi.on("turn_start", () => {
+    firstTokenAt = null;
+  });
+
+  pi.on("message_update", (event) => {
+    if (firstTokenAt !== null) return;
+    if (event.message.role !== "assistant") return;
+    if (!isTokenDelta(event.assistantMessageEvent)) return;
+    firstTokenAt = Date.now();
+  });
+
+  pi.on("message_end", (event, ctx) => {
+    if (event.message.role !== "assistant") return;
+    const started = firstTokenAt;
+    firstTokenAt = null;
+    const { stopReason, usage } = event.message;
+    // A cancelled or failed call settles a message here, but it assembled no
+    // response; the harness excludes those windows and so does this window.
+    if (stopReason === "error" || stopReason === "aborted") return;
+    if (started === null) return;
+    const tokens = outputTokens(usage);
+    if (tokens === undefined) return;
+    samples = pushSample(samples, { decodeMs: Math.max(0, Date.now() - started), outputTokens: tokens });
+    publish(ctx);
+  });
+
+  pi.on("session_shutdown", (_event, ctx) => {
+    reset(ctx);
+  });
+}

package/metrics.ts

@@ -0,0 +1,104 @@
+/**
+ * Decode-throughput window, ported from deepseek-harness's `turn-metrics` /
+ * `sessionStats` projection.
+ *
+ * Throughput is provider-reported output tokens over the decode wall time alone:
+ * first output token → settled message. TTFT, queueing, tool execution and
+ * retry waits stay outside the denominator on purpose. The figure is a
+ * time-weighted blend over the retained samples, never an average of per-message
+ * rates.
+ */
+
+import type { AssistantMessageEvent } from "@earendil-works/pi-ai";
+
+/** Samples retained for the figure: the most recent N settled messages. */
+export const WINDOW_SIZE = 200;
+
+/** One settled message's decode window and provider-reported output tokens. */
+export interface DecodeSample {
+  /** First output token → settled message, ms. */
+  decodeMs: number
+  /** Provider-reported output tokens over that window. */
+  outputTokens: number
+}
+
+function isCount(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+
+/**
+ * Add one sample, dropping the oldest once the window is full.
+ * @param samples - the samples retained so far, oldest first.
+ * @param sample - one message's decode window and output tokens.
+ * @param capacity - samples to retain.
+ * @returns a new window; the input is never mutated.
+ */
+export function pushSample(
+  samples: readonly DecodeSample[],
+  sample: DecodeSample,
+  capacity: number = WINDOW_SIZE,
+): DecodeSample[] {
+  const next = [...samples, sample];
+  return next.length > capacity ? next.slice(next.length - capacity) : next;
+}
+
+/**
+ * Throughput over the retained samples.
+ * @param samples - the window, oldest first.
+ * @returns tokens per second, or undefined while the window holds no decode time.
+ */
+export function tokensPerSecond(samples: readonly DecodeSample[]): number | undefined {
+  let decodeMs = 0;
+  let outputTokens = 0;
+  for (const sample of samples) {
+    decodeMs += sample.decodeMs;
+    outputTokens += sample.outputTokens;
+  }
+  if (decodeMs <= 0) return undefined;
+  return outputTokens / (decodeMs / 1000);
+}
+
+/**
+ * Display figure: whole tokens from ten up, one decimal below.
+ * @param tps - tokens per second.
+ * @returns the number with its unit, e.g. `20 tok/s`.
+ */
+export function formatTokensPerSecond(tps: number): string {
+  const clamped = Math.max(0, tps);
+  const value = clamped >= 10 ? String(Math.round(clamped)) : String(Math.round(clamped * 10) / 10);
+  return `${value} tok/s`;
+}
+
+/**
+ * Whether one stream event carries model-emitted output, i.e. the model has
+ * started decoding. Block/usage/finish boundaries do not qualify, and an empty
+ * fragment is whitespace-only noise rather than a token. `toolcall_start`
+ * counts because a tool call with no argument deltas would otherwise leave a
+ * response with no first-token time at all.
+ * @param event - one assistant stream event.
+ * @returns whether it marks the first output token's arrival.
+ */
+export function isTokenDelta(event: AssistantMessageEvent): boolean {
+  switch (event.type) {
+    case "text_delta":
+    case "thinking_delta":
+    case "toolcall_delta":
+      return event.delta !== "";
+    case "toolcall_start":
+      return true;
+    default:
+      return false;
+  }
+}
+
+/**
+ * Provider-reported output tokens, guarded so a malformed usage record cannot
+ * poison the window with NaN.
+ * @param usage - an assistant message's usage record.
+ * @returns the output-token count, or undefined when unreported or invalid.
+ */
+export function outputTokens(usage: unknown): number | undefined {
+  if (typeof usage !== "object" || usage === null) return undefined;
+  const value = (usage as Record<string, unknown>).output;
+  return isCount(value) ? value : undefined;
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@smoose/pi-tps",
+  "version": "0.0.1",
+  "description": "Decode throughput (tok/s) in the footer of the pi coding agent",
+  "type": "module",
+  "files": [
+    "*.ts",
+    "README.md",
+    "package.json"
+  ],
+  "keywords": [
+    "pi-package",
+    "pi",
+    "coding-agent",
+    "extension",
+    "tps",
+    "tokens-per-second",
+    "throughput",
+    "footer"
+  ],
+  "author": "smoose",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/smoosex/pi-tps.git"
+  },
+  "homepage": "https://github.com/smoosex/pi-tps#readme",
+  "bugs": {
+    "url": "https://github.com/smoosex/pi-tps/issues"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "^0.85.1",
+    "@earendil-works/pi-coding-agent": "^0.85.1",
+    "typescript": "^7.0.2"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  }
+}