pi-metrics-footer 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mingjian Shao
+
+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,55 @@
+# pi-metrics-footer
+
+Live model speed and usage metrics in the pi TUI footer: tokens/sec while streaming, per-turn average speed, token/cost/context stats, and model name — with configurable model labels.
+
+## Features
+
+- **Live tokens/sec** while the model streams (`⚡ 45t/s`), computed from a 2s rolling window of `text_delta` / `thinking_delta` events.
+- **Per-turn average** as a fallback: after a reply finishes, the average speed shows for 8 seconds — so it works even when the provider doesn't stream deltas.
+- **Token / cost / context line**: input, output, cache read/write, cost, and context usage, plus the current model (emoji label + thinking level).
+- **Configurable model labels**: map `provider/model` IDs to your own display names.
+
+## Install
+
+```bash
+pi install npm:pi-metrics-footer
+```
+
+Then restart pi. The footer is replaced on session start.
+
+## Update
+
+```bash
+pi update npm:pi-metrics-footer
+```
+
+Updates are manual; the package does not auto-update.
+
+## Uninstall
+
+Remove `pi-metrics-footer` from the `packages` list in `~/.pi/agent/settings.json`, then restart pi.
+
+## Configuration
+
+Create `<pi-agent-dir>/pi-metrics-footer.json` (default: `~/.pi/agent/pi-metrics-footer.json`):
+
+```json
+{
+  "modelLabels": {
+    "anthropic/claude-sonnet-5": "🎭 Sonnet 5",
+    "openai/gpt-5.5": "🧠 GPT-5.5"
+  }
+}
+```
+
+Keys are `provider/model` exactly as shown by pi (e.g. from `/model`). User labels override the built-in defaults for the same key and add new ones. Restart pi (or `/reload`) after editing.
+
+## How It Works
+
+- **Live TPS** uses a 2s rolling window of streaming token events; it needs at least 2 samples within the window, so very short replies may not show it.
+- **Average TPS** = output tokens ÷ wall time of the last finished assistant message, shown for 8s.
+- When idle, nothing shows — the indicator hides on its own.
+
+## License
+
+MIT

package/extensions/index.ts

@@ -0,0 +1,182 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { AssistantMessage } from "@earendil-works/pi-ai";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+
+/**
+ * pi-metrics-footer
+ *
+ * Replaces the pi TUI footer with a metrics line:
+ *   - live tokens/sec while streaming (2s rolling window),
+ *   - average tokens/sec for the last finished turn (8s fallback, works even when
+ *     the provider does not stream deltas),
+ *   - input/output/cache/cost tokens, context usage, and the current model.
+ *
+ * Model display names come from a default map and can be overridden per user via
+ * `<agent-dir>/pi-metrics-footer.json`:
+ *   { "modelLabels": { "anthropic/claude-sonnet-5": "🎭 Sonnet 5" } }
+ */
+
+const CONFIG_FILE = "pi-metrics-footer.json";
+
+/** Default labels for well-known public model IDs. Override via config. */
+const DEFAULT_MODEL_LABELS: Record<string, string> = {
+  // Anthropic
+  "anthropic/claude-opus-4": "🦑 Opus 4",
+  "anthropic/claude-opus-4-1": "🦑 Opus 4.1",
+  "anthropic/claude-sonnet-4": "🎭 Sonnet 4",
+  "anthropic/claude-sonnet-4-5": "🎭 Sonnet 4.5",
+  "anthropic/claude-haiku-4-5": "🎋 Haiku 4.5",
+  // OpenAI
+  "openai/gpt-5": "🧠 GPT-5",
+  "openai/gpt-5-mini": "⚡ GPT-5 Mini",
+  "openai/gpt-5-nano": "⚡ GPT-5 Nano",
+  // Google
+  "google/gemini-2.5-pro": "💎 Gemini Pro",
+  "google/gemini-2.5-flash": "💎 Gemini Flash",
+  // Others
+  "deepseek/deepseek-chat": "🐋 DeepSeek",
+  "deepseek/deepseek-reasoner": "🐋 DeepSeek R",
+  "qwen/qwen3-coder": "👾 Qwen Coder",
+};
+
+function loadUserLabels(): Record<string, string> {
+  try {
+    const raw = readFileSync(join(getAgentDir(), CONFIG_FILE), "utf8");
+    const parsed: unknown = JSON.parse(raw);
+    if (parsed && typeof parsed === "object" && "modelLabels" in parsed) {
+      const labels = (parsed as { modelLabels: unknown }).modelLabels;
+      if (labels && typeof labels === "object") return labels as Record<string, string>;
+    }
+  } catch {
+    // missing or unreadable config is fine; defaults apply
+  }
+  return {};
+}
+
+const MODEL_LABELS: Record<string, string> = { ...DEFAULT_MODEL_LABELS, ...loadUserLabels() };
+
+const ROLLING_WINDOW_MS = 2000;
+const AVG_DISPLAY_MS = 8000;
+const tokenTimestamps: number[] = [];
+let messageStartTime = 0;
+let lastAvgTps: number | null = null;
+let lastAvgExpires = 0;
+
+function recordStreamToken(): void {
+  const now = Date.now();
+  tokenTimestamps.push(now);
+  const cutoff = now - ROLLING_WINDOW_MS;
+  while (tokenTimestamps.length > 0 && tokenTimestamps[0]! < cutoff) {
+    tokenTimestamps.shift();
+  }
+}
+
+function computeStreamTps(): number | null {
+  const cutoff = Date.now() - ROLLING_WINDOW_MS;
+  while (tokenTimestamps.length > 0 && tokenTimestamps[0]! < cutoff) {
+    tokenTimestamps.shift();
+  }
+  if (tokenTimestamps.length < 2) return null;
+  const elapsed = tokenTimestamps[tokenTimestamps.length - 1]! - tokenTimestamps[0]!;
+  if (elapsed <= 0) return null;
+  return tokenTimestamps.length / (elapsed / 1000);
+}
+
+function formatTokens(tokens: number): string {
+  if (tokens < 1_000) return String(tokens);
+  if (tokens < 10_000) return `${(tokens / 1_000).toFixed(1)}k`;
+  if (tokens < 1_000_000) return `${Math.round(tokens / 1_000)}k`;
+  return `${(tokens / 1_000_000).toFixed(1)}M`;
+}
+
+export default function (pi: ExtensionAPI) {
+  pi.on("session_start", (_event, ctx) => {
+    if (ctx.mode !== "tui") return;
+
+    pi.on("message_start", (event) => {
+      if (event.message?.role === "assistant") {
+        tokenTimestamps.length = 0;
+        messageStartTime = Date.now();
+        lastAvgTps = null;
+      }
+    });
+
+    pi.on("message_update", (event) => {
+      const ev = event.assistantMessageEvent;
+      if (ev?.type === "text_delta" || ev?.type === "thinking_delta") {
+        recordStreamToken();
+      }
+    });
+
+    pi.on("message_end", (event) => {
+      if (event.message?.role !== "assistant") return;
+      const usage = (event.message as AssistantMessage).usage;
+      const output = usage?.output ?? 0;
+      const elapsed = Date.now() - messageStartTime;
+      if (output > 0 && elapsed > 400) {
+        lastAvgTps = output / (elapsed / 1000);
+        lastAvgExpires = Date.now() + AVG_DISPLAY_MS;
+      }
+    });
+
+    ctx.ui.setFooter((_tui, theme, footerData) => {
+      const unsubscribe = footerData.onBranchChange(() => _tui.requestRender());
+
+      return {
+        dispose: unsubscribe,
+        invalidate() {},
+        render(width: number): string[] {
+          let input = 0;
+          let output = 0;
+          let cacheRead = 0;
+          let cacheWrite = 0;
+          let cost = 0;
+
+          for (const entry of ctx.sessionManager.getEntries()) {
+            if (entry.type !== "message" || entry.message.role !== "assistant") continue;
+            const message = entry.message as AssistantMessage;
+            input += message.usage.input;
+            output += message.usage.output;
+            cacheRead += message.usage.cacheRead;
+            cacheWrite += message.usage.cacheWrite;
+            cost += message.usage.cost.total;
+          }
+
+          const usage = ctx.getContextUsage();
+          const context = usage?.percent == null
+            ? `?/${formatTokens(usage?.contextWindow ?? ctx.model?.contextWindow ?? 0)}`
+            : `${usage.percent.toFixed(1)}%/${formatTokens(usage.contextWindow)}`;
+          const leftParts = [`↑${formatTokens(input)}`, `↓${formatTokens(output)}`];
+          const live = computeStreamTps();
+          const avg = Date.now() < lastAvgExpires ? lastAvgTps : null;
+          const tps = live ?? avg;
+          if (tps !== null) {
+            leftParts.unshift(`⚡ ${tps.toFixed(0)}t/s`);
+          }
+          if (cacheRead) leftParts.push(`R${formatTokens(cacheRead)}`);
+          if (cacheWrite) leftParts.push(`W${formatTokens(cacheWrite)}`);
+          if (cost) leftParts.push(`$${cost.toFixed(3)}`);
+          leftParts.push(context);
+          const left = theme.fg("dim", leftParts.join(" "));
+
+          const model = ctx.model;
+          const modelKey = model ? `${model.provider}/${model.id}` : "";
+          const label = MODEL_LABELS[modelKey] ?? model?.name ?? model?.id ?? "no model";
+          const thinking = model?.reasoning ? ` · ${ctx.thinkingLevel ?? "off"}` : "";
+          const right = theme.fg("accent", `${label}${thinking}`);
+          const padding = " ".repeat(Math.max(2, width - visibleWidth(left) - visibleWidth(right)));
+
+          const branch = footerData.getGitBranch();
+          const pwd = branch ? `${ctx.cwd} (${branch})` : ctx.cwd;
+          return [
+            truncateToWidth(theme.fg("dim", pwd), width, theme.fg("dim", "...")),
+            truncateToWidth(left + padding + right, width, ""),
+          ];
+        },
+      };
+    });
+  });
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "pi-metrics-footer",
+  "version": "0.1.0",
+  "description": "Live model speed (tokens/s), token/cost/context stats, and configurable model labels in the pi TUI footer",
+  "keywords": [
+    "pi",
+    "pi-package",
+    "extension",
+    "footer",
+    "metrics",
+    "tokens",
+    "tps",
+    "tokens-per-second"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "pi": {
+    "extensions": ["./extensions"]
+  },
+  "files": [
+    "extensions"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run typecheck"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "@types/node": "^22",
+    "typescript": "^5"
+  }
+}