pi-metrics 0.2.0

package/README.md

@@ -0,0 +1,26 @@
+# pi-hud
+
+Heads-up session timing for the [Pi coding agent](https://github.com/earendil-works/pi): a live elapsed timer in the working spinner plus per-turn and total run summaries in the chat flow.
+
+[中文文档](./README.zh-CN.md)
+
+## Features
+
+- While the agent is working, the spinner shows the **total elapsed time since you sent the message** (for example `⏱ 47s`). It keeps counting across turns instead of resetting per turn.
+- When each turn ends, a dim line shows that turn's precise duration (`⏱ Turn elapsed 8.2s`).
+- When the agent fully settles (`agent_settled` — including auto-retries, compaction continuations, or Esc interruption), a final line shows the **total elapsed time from message send to stop** (`⏱ Total elapsed 18.9s`).
+
+## Install
+
+```bash
+pi install npm:pi-hud
+```
+
+## How it works
+
+- The total timer starts on the `input` event (the moment you submit a message) and ends on `agent_settled`, so multi-turn tool calls, automatic retries, and queued continuations are all covered. Steer/follow-up messages sent mid-run do not reset the start point.
+- In non-TUI mode (rpc/print) the timer and notifications are disabled.
+
+## Localization
+
+All user-facing text is provided in `zh-CN` and `en-US` through `pi-extensions-i18n`.

package/README.zh-CN.md

@@ -0,0 +1,26 @@
+# pi-hud
+
+面向 [Pi coding agent](https://github.com/earendil-works/pi) 的会话耗时抬头显示：working spinner 实时计时，并在对话流中给出每轮耗时与全程总耗时。
+
+[English](./README.md)
+
+## 功能
+
+- 工作期间 spinner 显示**从发出消息起的全程耗时**（如 `⏱ 47s`），跨轮次持续累加，不再每轮回零。
+- 每个轮次结束时插入一条灰色文本，显示该轮精确耗时（`⏱ 本轮耗时 8.2s`）。
+- AI 完全停止时（`agent_settled`，覆盖自动重试、compaction 续跑以及 Esc 中断）追加一行**从发出消息到停止的总耗时**（`⏱ 总耗时 18.9s`）。
+
+## 安装
+
+```bash
+pi install npm:pi-hud
+```
+
+## 实现说明
+
+- 总耗时以 `input` 事件（用户提交消息的时刻）为起点、`agent_settled` 为终点，因此多轮工具调用、自动重试和队列续跑都计入同一次总耗时；运行中发送的 steer/followUp 消息不会重置起点。
+- 非 TUI 模式（rpc/print）下不启动定时器、不发送通知。
+
+## 国际化
+
+所有面向用户的文案均通过 `pi-extensions-i18n` 提供 `zh-CN` 和 `en-US` 双语。

package/index.ts

@@ -0,0 +1 @@
+export { default } from "./src/index.ts";

package/locales/index.json

@@ -0,0 +1,14 @@
+{
+  "elapsedWorking": {
+    "zh-CN": "⏱ {value}",
+    "en-US": "⏱ {value}"
+  },
+  "elapsedDone": {
+    "zh-CN": "⏱ 本轮耗时 {value}",
+    "en-US": "⏱ Turn elapsed {value}"
+  },
+  "elapsedTotal": {
+    "zh-CN": "⏱ 总耗时 {value}",
+    "en-US": "⏱ Total elapsed {value}"
+  }
+}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "pi-metrics",
+  "version": "0.2.0",
+  "description": "Pi metrics extension: live session elapsed timer with per-turn and total run summaries",
+  "type": "module",
+  "main": "./index.ts",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "files": [
+    "index.ts",
+    "src",
+    "locales",
+    "README.md",
+    "README.zh-CN.md"
+  ],
+  "scripts": {
+    "test": "tsx --test tests/pi-metrics.test.ts",
+    "typecheck": "tsc --noEmit --pretty false",
+    "build": "npm run typecheck",
+    "check": "npm run typecheck && npm test && npm pack --dry-run --json > /dev/null"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "MIT",
+  "author": "maplezzk",
+  "homepage": "https://github.com/maplezzk/pi-extensions/tree/main/packages/pi-metrics",
+  "bugs": "https://github.com/maplezzk/pi-extensions/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/maplezzk/pi-extensions.git",
+    "directory": "packages/pi-metrics"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "coding-agent",
+    "hud",
+    "elapsed-time"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-ai": ">=0.80.0 <0.81.0",
+    "@earendil-works/pi-coding-agent": ">=0.80.0 <0.81.0",
+    "@earendil-works/pi-tui": ">=0.80.0 <0.81.0",
+    "pi-extensions-i18n": "^0.3.0"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "0.80.10",
+    "@earendil-works/pi-coding-agent": "0.80.10",
+    "@earendil-works/pi-tui": "0.80.10",
+    "@types/node": "24.12.4",
+    "tsx": "4.23.1",
+    "typescript": "5.9.3"
+  }
+}

package/src/format-utils.ts

@@ -0,0 +1,23 @@
+/**
+ * 耗时格式化纯函数
+ *
+ * 抽离为独立模块便于单元测试（仓库门禁要求测试确定性、不依赖 Pi 运行时）。
+ */
+
+/** working 期间：紧凑格式（秒级 / 分秒） */
+export function formatTick(ms: number): string {
+  const totalSec = Math.floor(ms / 1000);
+  if (totalSec < 60) return `${totalSec}s`;
+  const m = Math.floor(totalSec / 60);
+  const s = totalSec % 60;
+  return s === 0 ? `${m}m` : `${m}m ${s}s`;
+}
+
+/** turn_end / agent_settled：精确格式（1 位小数） */
+export function formatDone(ms: number): string {
+  const sec = ms / 1000;
+  if (sec < 60) return `${sec.toFixed(1)}s`;
+  const m = Math.floor(sec / 60);
+  const s = sec - m * 60;
+  return `${m}m ${s.toFixed(1)}s`;
+}

package/src/i18n.ts

@@ -0,0 +1,3 @@
+import { createTranslator, loadCatalog } from "pi-extensions-i18n";
+
+export const i18n = createTranslator(loadCatalog(new URL("../locales/index.json", import.meta.url)));

package/src/index.ts

@@ -0,0 +1,10 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import turnElapsed from "./turn-elapsed.ts";
+
+export default function piHud(pi: ExtensionAPI): void {
+  // 后续 HUD 类功能（如 token 用量、上下文水位等）在此注册
+  turnElapsed(pi);
+}
+
+export { default as turnElapsed } from "./turn-elapsed.ts";
+export * from "./format-utils.ts";

package/src/turn-elapsed.ts

@@ -0,0 +1,99 @@
+/**
+ * Pi turn 耗时显示插件
+ *
+ * - working 期间：实时更新 spinner 文字，显示从用户发出消息起的全程耗时（如 "⏱ 47s"），
+ *   跨轮不归零 —— 用户等待时最关心的是"一共等了多久"
+ * - turn 结束时：在 chat 流插入一条 dim 灰文本，提示本轮耗时（如 "✓ 本轮耗时 12.3s"）
+ * - agent 完全停止时（agent_settled）：再插入一条总耗时，覆盖从用户发出消息到 AI 停止
+ *   的整段过程（跨越多轮工具调用、自动重试和 compaction 续跑）
+ *
+ * 设计取舍：
+ * - 用 setWorkingMessage 改 spinner 文字会覆盖 pi 默认的 "Working... (Esc to interrupt)"。
+ *   为了让耗时最显眼，接受这个 trade-off —— 用户更关心"等了多久"而非"怎么中断"。
+ * - 总耗时起点用 input 事件（用户真正发出消息的时刻），而不是 agent_start（略晚）。
+ *   运行中收到的 steer/followUp 消息不重置起点：整段连续工作计入同一次总耗时。
+ * - 总耗时终点用 agent_settled 而不是 agent_end：agent_end 之后还可能发生自动重试、
+ *   compaction 和队列续跑，agent_settled 才表示 AI 真正停下（Esc 中断也会在 finally 中触发）。
+ * - 非 TUI 模式（rpc / print）下 hasUI 为 false，不启动定时器、不发 notify。
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { formatDone, formatTick } from "./format-utils.ts";
+import { i18n } from "./i18n.ts";
+
+const TICK_MS = 1000;
+
+export default function (pi: ExtensionAPI) {
+  let turnStartTime = 0;
+  let runStartTime = 0;
+  let tickHandle: ReturnType<typeof setInterval> | null = null;
+
+  const stopTick = () => {
+    if (tickHandle !== null) {
+      clearInterval(tickHandle);
+      tickHandle = null;
+    }
+  };
+
+  pi.on("input", async (event) => {
+    // 只在空闲时收到用户消息才记总耗时起点；运行中的 steer/followUp 保留原起点
+    if (runStartTime === 0 && (event.source === "interactive" || event.source === "rpc")) {
+      runStartTime = Date.now();
+    }
+  });
+
+  pi.on("agent_start", async () => {
+    // 兜底：extension 注入消息触发的运行没有用户 input 事件
+    if (runStartTime === 0) runStartTime = Date.now();
+  });
+
+  pi.on("turn_start", async (event, ctx) => {
+    stopTick();
+    // 优先用事件自带的时间戳，避免 handler 调度延迟
+    turnStartTime = event.timestamp || Date.now();
+    if (!ctx.hasUI) return;
+
+    const tick = () => {
+      // spinner 显示全程总耗时（从用户发出消息起），跨轮不归零；
+      // runStartTime 尚未记录时（理论上不会）退化为本轮起点
+      const base = runStartTime || turnStartTime;
+      if (!base) return;
+      ctx.ui.setWorkingMessage(i18n.t("elapsedWorking", { value: formatTick(Date.now() - base) }));
+    };
+    tick();
+    tickHandle = setInterval(tick, TICK_MS);
+  });
+
+  pi.on("turn_end", async (_event, ctx) => {
+    stopTick();
+    if (!turnStartTime) return;
+    const elapsed = Date.now() - turnStartTime;
+    turnStartTime = 0;
+    if (!ctx.hasUI) return;
+
+    // 恢复 pi 默认 working 文字（下次 streaming 由 pi 内部重置）
+    ctx.ui.setWorkingMessage(undefined);
+    // 在 chat 流末尾插入一条 dim 灰文本
+    ctx.ui.notify(i18n.t("elapsedDone", { value: formatDone(elapsed) }), "info");
+  });
+
+  pi.on("agent_end", async (_event, ctx) => {
+    stopTick();
+    turnStartTime = 0;
+    if (!ctx.hasUI) return;
+    ctx.ui.setWorkingMessage(undefined);
+  });
+
+  pi.on("agent_settled", async (_event, ctx) => {
+    stopTick();
+    const runElapsed = runStartTime ? Date.now() - runStartTime : 0;
+    runStartTime = 0;
+    turnStartTime = 0;
+    if (!ctx.hasUI) return;
+
+    ctx.ui.setWorkingMessage(undefined);
+    if (runElapsed > 0) {
+      ctx.ui.notify(i18n.t("elapsedTotal", { value: formatDone(runElapsed) }), "info");
+    }
+  });
+}