pi-metrics 0.2.2 → 0.3.0

package/README.md

@@ -11,7 +11,7 @@ Session metrics for the [Pi coding agent](https://github.com/earendil-works/pi):
 - 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`).
 - After each LLM turn, a notification reports TPS, TTFT, token counts, generation time, stalls, and blended cost when available.
 - Telemetry is persisted as `tps` custom session entries and restored after session resume or `/tree` navigation.
-- `/tps-export` exports telemetry JSONL; `/session-export` exports the session JSONL.
+- Metrics are exposed through session entries and notifications; this package does not register export slash commands.
 
 ## Migration from pi-tps
 

package/README.zh-CN.md

@@ -11,7 +11,7 @@
 - AI 完全停止时（`agent_settled`，覆盖自动重试、compaction 续跑以及 Esc 中断）追加一行**从发出消息到停止的总耗时**（`⏱ 总耗时 18.9s`）。
 - 每轮 LLM 调用结束后显示 TPS、TTFT、token 数、生成耗时、stall 和可用的综合成本。
 - Telemetry 以 `tps` custom session entry 持久化，并在恢复 session 或 `/tree` 后恢复显示。
-- `/tps-export` 导出 TPS JSONL，`/session-export` 导出 session JSONL。
+- Metrics 通过 session entry 和通知提供；本包不再注册导出类斜杠命令。
 
 ## 从 pi-tps 迁移
 

package/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: configure-pi-metrics
+description: "启用与排查 pi-metrics 的耗时、TPS、TTFT、token 和成本遥测。Use when configuring or diagnosing Pi session metrics."
+---
+
+# 配置 pi-metrics
+
+`pi-metrics` 当前没有配置文件或配置命令；不要编造开关、阈值或导出命令。配置动作仅限安装、启用或禁用该 package，以及共享语言设置。
+
+## 诊断与修改
+
+1. 确认 `npm:pi-metrics` 已安装且扩展资源已启用。
+2. 若同时启用了 `npm:@monotykamary/pi-tps`，先让用户选择保留一个；两者会重复写入 `tps` session entry 和通知。
+3. 文案语言由 `pi-extensions-i18n` 控制。
+
+## 验证
+
+在 TUI 中完成一次真实模型回合，观察 working spinner、轮次耗时、总耗时和可用的 TPS/TTFT/token/cost。RPC/print 模式不会启动 UI 定时器或通知；provider 未返回 usage 时部分指标不可用。真实模型回合属于 E2E，执行前遵守当前任务授权边界；未运行时明确报告 `NOT_RUN`。

package/locales/index.json

@@ -38,33 +38,5 @@
   "tpsRate": {
     "zh-CN": "${value}/M",
     "en-US": "${value}/M"
-  },
-  "tpsExportDescription": {
-    "zh-CN": "导出 TPS telemetry JSONL（--full 导出整个 session）",
-    "en-US": "Export TPS telemetry as JSONL (--full for the full session)"
-  },
-  "sessionExportDescription": {
-    "zh-CN": "导出 session JSONL（--full 导出所有分支）",
-    "en-US": "Export session JSONL (--full for all branches)"
-  },
-  "tpsFullFlag": {
-    "zh-CN": "--full（导出所有分支）",
-    "en-US": "--full (all branches)"
-  },
-  "tpsNoEntries": {
-    "zh-CN": "在 {scope} 中没有匹配的条目",
-    "en-US": "No matching entries found in {scope}"
-  },
-  "tpsAllEntries": {
-    "zh-CN": "全部条目",
-    "en-US": "all entries"
-  },
-  "tpsCurrentBranch": {
-    "zh-CN": "当前分支",
-    "en-US": "current branch"
-  },
-  "tpsExported": {
-    "zh-CN": "已导出 {count} 个条目 → {filepath}",
-    "en-US": "Exported {count} entries → {filepath}"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-metrics",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Pi metrics extension: elapsed-time HUD and resilient TPS telemetry",
   "type": "module",
   "main": "./index.ts",
@@ -12,7 +12,8 @@
     "src",
     "locales",
     "README.md",
-    "README.zh-CN.md"
+    "README.zh-CN.md",
+    "SKILL.md"
   ],
   "scripts": {
     "test": "tsx --test tests/*.test.ts",
@@ -22,7 +23,11 @@
   },
   "pi": {
     "extensions": [
-      "./index.ts"
+      "./index.ts",
+      "../pi-extensions-i18n/index.ts"
+    ],
+    "skills": [
+      "./SKILL.md"
     ]
   },
   "engines": {
@@ -54,8 +59,10 @@
   "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"
+    "@earendil-works/pi-tui": ">=0.80.0 <0.81.0"
+  },
+  "dependencies": {
+    "pi-extensions-i18n": "^0.4.0"
   },
   "devDependencies": {
     "@earendil-works/pi-ai": "0.80.10",

package/src/tps.ts

@@ -5,15 +5,10 @@
  * elapsed-time HUD and generation telemetry share one lifecycle.
  */
 
-import { execFileSync } from "node:child_process";
-import { mkdirSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { join } from "node:path";
 import { performance } from "node:perf_hooks";
 import type { AssistantMessage } from "@earendil-works/pi-ai";
 import type {
   ExtensionAPI,
-  ExtensionCommandContext,
   ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
 import { i18n } from "./i18n.ts";
@@ -345,54 +340,6 @@ function restoreTPSNotification(
   }
 }
 
-function openDirectory(directory: string): void {
-  try {
-    execFileSync(process.platform === "darwin" ? "open" : "xdg-open", [directory], {
-      stdio: "ignore",
-    });
-  } catch {
-    // Opening an export directory is optional; the path is still reported.
-  }
-}
-
-function exportEntries(
-  entries: SessionEntryLike[],
-  full: boolean,
-  filterType: string | null,
-  directoryName: "pi-telemetry" | "pi-sessions",
-  prefix: "pi-telemetry" | "pi-session",
-  sessionId: string,
-): { filepath: string; count: number } {
-  const isStructural = (entry: SessionEntryLike) =>
-    entry.type === "model_change" || entry.type === "branch_summary";
-  const exported = entries.filter(
-    (entry) => isStructural(entry) ||
-      (entry.type === "custom" && (!filterType || entry.customType === filterType)),
-  );
-  const byId = new Map(entries.map((entry) => [entry.id, entry]));
-  const exportedIds = new Set(exported.map((entry) => entry.id));
-  const rechainParentId = (entry: SessionEntryLike): string | null => {
-    let parentId = entry.parentId ?? null;
-    while (parentId) {
-      if (exportedIds.has(parentId)) return parentId;
-      parentId = byId.get(parentId)?.parentId ?? null;
-    }
-    return null;
-  };
-  const rechained = exported.map((entry) => ({ ...entry, parentId: rechainParentId(entry) }));
-  const cacheBase = process.env.XDG_CACHE_HOME || join(homedir(), ".cache");
-  const directory = join(cacheBase, directoryName);
-  mkdirSync(directory, { recursive: true });
-  const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
-  const scope = [full ? "full" : "branch", filterType?.replace(/[^a-zA-Z0-9_-]/g, "-")]
-    .filter(Boolean)
-    .join("-");
-  const filepath = join(directory, `${prefix}-${scope}-${sessionId.slice(0, 8)}-${timestamp}.jsonl`);
-  writeFileSync(filepath, `${rechained.map((entry) => JSON.stringify(entry)).join("\n")}\n`);
-  openDirectory(directory);
-  return { filepath, count: exported.length };
-}
-
 export default function tpsExtension(pi: ExtensionAPI): void {
   let currentTiming: TurnTiming | null = null;
   let pendingNeuralwattBilledCost: { turnIndex: number; costUsd: number } | null = null;
@@ -402,7 +349,6 @@ export default function tpsExtension(pi: ExtensionAPI): void {
     billedApplied: boolean;
     ctx: ExtensionContext;
   } | null = null;
-  let cachedEntries: Array<{ type?: string; customType?: string }> = [];
   const tpsCaps = new Map<string, number>();
   const restoreTimers = new Set<ReturnType<typeof setTimeout>>();
   let unsubscribeNeuralwatt: (() => void) | undefined;
@@ -411,7 +357,6 @@ export default function tpsExtension(pi: ExtensionAPI): void {
     currentTiming = null;
     pendingNeuralwattBilledCost = null;
     lastCommittedTurn = null;
-    cachedEntries = [];
     for (const timer of restoreTimers) clearTimeout(timer);
     restoreTimers.clear();
   };
@@ -447,7 +392,6 @@ export default function tpsExtension(pi: ExtensionAPI): void {
     committed.telemetry = corrected;
     pi.appendEntry("tps", corrected);
     pi.events?.emit("tps:telemetry", corrected);
-    cachedEntries.push({ type: "custom", customType: "tps" });
     if (committed.ctx.hasUI) committed.ctx.ui.notify(composeDisplayString(corrected), "info");
   });
 
@@ -459,14 +403,12 @@ export default function tpsExtension(pi: ExtensionAPI): void {
 
   pi.on("session_start", (_event, ctx) => {
     clearState();
-    cachedEntries = ctx.sessionManager.getEntries();
     restoreTPSNotification(ctx, scheduleRestore);
   });
 
   pi.on("session_tree", (_event: SessionTreeEvent, ctx) => {
     pendingNeuralwattBilledCost = null;
     lastCommittedTurn = null;
-    cachedEntries = ctx.sessionManager.getEntries();
     restoreTPSNotification(ctx, scheduleRestore);
   });
 
@@ -572,53 +514,6 @@ export default function tpsExtension(pi: ExtensionAPI): void {
     pi.appendEntry("tps", telemetry);
     pi.events?.emit("tps:telemetry", telemetry);
     if (ctx.hasUI) ctx.ui.notify(composeDisplayString(telemetry), "info");
-    cachedEntries.push({ type: "custom", customType: "tps" });
-  });
-
-  pi.registerCommand("tps-export", {
-    description: i18n.t("tpsExportDescription"),
-    getArgumentCompletions: (argumentPrefix: string) => {
-      if ("--full".startsWith(argumentPrefix)) return [{ value: "--full", label: i18n.t("tpsFullFlag") }];
-      const types = new Set<string>();
-      for (const entry of cachedEntries) {
-        if (entry.type === "custom" && entry.customType) types.add(entry.customType);
-      }
-      return [...types]
-        .filter((customType) => customType.startsWith(argumentPrefix))
-        .map((customType) => ({ value: customType, label: customType }));
-    },
-    handler: async (args: string, ctx: ExtensionCommandContext) => {
-      const tokens = args.trim().split(/\s+/).filter(Boolean);
-      const full = tokens.includes("--full");
-      const filterType = tokens.filter((token) => token !== "--full").join(" ") || null;
-      const entries = (full ? ctx.sessionManager.getEntries() : ctx.sessionManager.getBranch()) as SessionEntryLike[];
-      const isStructural = (entry: SessionEntryLike) => entry.type === "model_change" || entry.type === "branch_summary";
-      const matching = entries.filter((entry) => isStructural(entry) ||
-        (entry.type === "custom" && (!filterType || entry.customType === filterType)));
-      if (matching.length === 0) {
-        ctx.ui.notify(i18n.t("tpsNoEntries", { scope: full ? i18n.t("tpsAllEntries") : i18n.t("tpsCurrentBranch") }), "warning");
-        return;
-      }
-      const sessionId = ctx.sessionManager.getSessionId?.() ?? "unknown";
-      const result = exportEntries(entries, full, filterType, "pi-telemetry", "pi-telemetry", sessionId);
-      ctx.ui.notify(i18n.t("tpsExported", { count: result.count, filepath: result.filepath }), "info");
-    },
   });
 
-  pi.registerCommand("session-export", {
-    description: i18n.t("sessionExportDescription"),
-    getArgumentCompletions: (argumentPrefix: string) =>
-      "--full".startsWith(argumentPrefix) ? [{ value: "--full", label: i18n.t("tpsFullFlag") }] : [],
-    handler: async (args: string, ctx: ExtensionCommandContext) => {
-      const full = args.trim().split(/\s+/).includes("--full");
-      const entries = (full ? ctx.sessionManager.getEntries() : ctx.sessionManager.getBranch()) as SessionEntryLike[];
-      if (entries.length === 0) {
-        ctx.ui.notify(i18n.t("tpsNoEntries", { scope: full ? i18n.t("tpsAllEntries") : i18n.t("tpsCurrentBranch") }), "warning");
-        return;
-      }
-      const sessionId = ctx.sessionManager.getSessionId?.() ?? "unknown";
-      const result = exportEntries(entries, full, null, "pi-sessions", "pi-session", sessionId);
-      ctx.ui.notify(i18n.t("tpsExported", { count: result.count, filepath: result.filepath }), "info");
-    },
-  });
 }