pi-metrics 0.6.0 → 0.7.1

package/README.md

@@ -1,17 +1,17 @@
 # pi-metrics
 
-Session metrics for the [Pi coding agent](https://github.com/earendil-works/pi): a live elapsed timer, per-turn summaries, and token-generation telemetry.
+Session metrics for the [Pi coding agent](https://github.com/earendil-works/pi): a live elapsed timer and token-generation telemetry, with two display timings.
 
 [中文文档](./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, one line reports TPS, TTFT, token counts, generation time, stalls, and blended cost (the line already carries the turn duration, so no separate elapsed notice is emitted).
-- When a run spans more than one turn and the agent fully settles (`agent_settled` — including auto-retries, compaction continuations, or Esc interruption), a final line adds the **total elapsed time from message send to stop** (`⏱ Total elapsed 18.9s`). Single-turn runs do not repeat it.
-- 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.
-- Metrics are exposed through session entries and notifications. Use `/config:metrics` to open the TUI settings menu, or use `/config:metrics enable|disable` to change the setting directly.
+- **Display timing** decides when metric lines appear:
+  - `on-stop` (default): the transcript stays quiet during the run. When the agent fully settles (`agent_settled` — including auto-retries, compaction continuations, or Esc interruption), one summary line reports the total elapsed time, blended TPS, TTFT, summed in/out tokens, stalls, and blended cost.
+  - `live`: one line per turn, right when the turn ends (the line already carries the turn duration, so no separate elapsed notice is emitted). A multi-turn run also gets a final `⏱ <duration>` line.
+- Telemetry for every turn is persisted as `tps` custom session entries in both modes, and restored after session resume or `/tree` navigation.
+- Metrics are exposed through session entries and notifications. Use `/config:metrics` to open the TUI settings menu, or `/config:metrics enable|disable|live|on-stop|reset` to change a setting directly.
 
 ## Configuration
 
@@ -19,13 +19,29 @@ The configuration file is `<pi-agent-dir>/extensions/pi-metrics/config.json`:
 
 ```json
 {
-  "enabled": true
+  "enabled": true,
+  "display": "on-stop"
 }
 ```
 
-Use `/config:metrics enable` or `/config:metrics disable` to update it, or open the normal TUI menu with `/config:metrics`. Run `/reload` after manually editing the file.
+| Field | Values | Default | Meaning |
+| --- | --- | --- | --- |
+| `enabled` | `true` / `false` | `true` | Master switch. `false` registers no metric handlers at all. |
+| `display` | `"on-stop"` / `"live"` | `"on-stop"` | When metric lines appear: one summary line after the run stops, or one line per turn. |
 
-The TPS implementation is maintained in this package. Remove the standalone `npm:@monotykamary/pi-tps` entry from Pi settings before enabling this package, otherwise both extensions will record duplicate `tps` entries and notifications.
+Use `/config:metrics` for the interactive menu (each selection is saved and the menu reopens until you pick **Done**), or the direct form to change one field. Run `/reload` after editing the file by hand.
+
+## How the summary line is computed
+
+```
+⏱ 2m 14.3s · TPS 62.4 tok/s · TTFT 1.2s · in 48.2K · out 12.7K · $0.42/M
+```
+
+- The leading **`⏱`** value measures from the moment you submit the message to `agent_settled` — the same clock the spinner has been showing, so the number matches what you watched.
+- **TPS** is weighted by output tokens (total output ÷ summed generation time), so a short turn cannot skew the run average.
+- **TTFT** is the first measurable value in the run: how long until the first token appeared.
+- **in/out** are summed over all turns; **stall** appears only when a stall was detected.
+- **Cost rate** is derived from what was actually billed (`billed` cost when a provider reports it, otherwise list price) per million tokens.
 
 ## Install
 
@@ -36,9 +52,12 @@ pi install npm:pi-metrics
 ## 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.
+- `on-stop` mode accumulates each finished turn into a run accumulator that keeps only the aggregated values (no per-turn records), then emits a single line at `agent_settled`. A late billed-cost event recomputes and re-emits that line instead of adding a per-turn line.
 - In non-TUI mode (rpc/print) the timer and notifications are disabled.
 - The shared Neuralwatt cost listener is unsubscribed during `session_shutdown`, and deferred rehydration notifications are cancelled during reload/session changes.
 
+The TPS implementation is maintained in this package. Remove the standalone `npm:@monotykamary/pi-tps` entry from Pi settings before enabling this package, otherwise both extensions will record duplicate `tps` entries and notifications.
+
 ## Localization
 
 All user-facing text is provided in `zh-CN` and `en-US` through `pi-extensions-i18n`.

package/README.zh-CN.md

@@ -1,17 +1,17 @@
 # pi-metrics
 
-面向 [Pi coding agent](https://github.com/earendil-works/pi) 的会话指标扩展：working spinner 实时计时，并提供每轮 TPS、TTFT 和 token 使用量。
+面向 [Pi coding agent](https://github.com/earendil-works/pi) 的会话指标扩展：实时耗时计时 + token 生成遥测，支持两种显示时机。
 
 [English](./README.md)
 
 ## 功能
 
 - 工作期间 spinner 显示**从发出消息起的全程耗时**（如 `⏱ 47s`），跨轮次持续累加，不再每轮回零。
-- 每个轮次结束时显示 TPS、TTFT、token 数、生成耗时、stall 和可用的综合成本（一行指标里已包含本轮耗时，不再单独发一条）。
-- 整段运行超过一轮时，AI 完全停止（`agent_settled`，覆盖自动重试、compaction 续跑以及 Esc 中断）再补一行**从发出消息到停止的总耗时**（`⏱ 总耗时 18.9s`）；单轮运行不重复报。
-- 每轮 LLM 调用结束后显示 TPS、TTFT、token 数、生成耗时、stall 和可用的综合成本。
-- Telemetry 以 `tps` custom session entry 持久化，并在恢复 session 或 `/tree` 后恢复显示。
-- Metrics 通过 session entry 和通知提供。使用 `/config:metrics` 打开 TUI 配置菜单，也可以使用 `/config:metrics enable|disable` 直接切换。
+- **显示时机**决定指标行什么时候出现：
+  - `on-stop`（默认）：运行过程中对话区保持干净；AI 完全停止（`agent_settled`，覆盖自动重试、compaction 续跑以及 Esc 中断）后只出一行汇总：总耗时、混合 TPS、TTFT、in/out 合计、stall 和综合费率。
+  - `live`：每轮结束时立刻出一行（该行已包含本轮耗时，不再单独发耗时提示）；整段超过一轮时再补一行 `⏱ <耗时>`。
+- 两种模式都会把每轮遥测写进 `tps` custom session entry，恢复 session 或 `/tree` 后照常恢复显示。
+- Metrics 通过 session entry 和通知提供。使用 `/config:metrics` 打开 TUI 配置菜单，或用 `/config:metrics enable|disable|live|on-stop|reset` 直接改一项。
 
 ## 配置
 
@@ -19,15 +19,29 @@
 
 ```json
 {
-  "enabled": true
+  "enabled": true,
+  "display": "on-stop"
 }
 ```
 
-使用 `/config:metrics enable` 或 `/config:metrics disable` 修改配置，也可以使用 `/config:metrics` 打开常规 TUI 菜单；手动修改文件后执行 `/reload`。可参考 [`config.example.json`](./config.example.json)。
+| 字段 | 取值 | 默认 | 含义 |
+| --- | --- | --- | --- |
+| `enabled` | `true` / `false` | `true` | 总开关；`false` 时完全不注册指标处理器。 |
+| `display` | `"on-stop"` / `"live"` | `"on-stop"` | 指标行何时出现：整段停下后汇总一行，还是每轮一行。 |
 
-## 从 pi-tps 迁移
+用 `/config:metrics` 打开交互菜单（每次选择都会保存并重新打开菜单，选「完成」退出），或用带参数的形式改单个字段；手动修改文件后执行 `/reload`。可参考 [`config.example.json`](./config.example.json)。
 
-TPS 实现现在由本包维护。启用本包前，请从 Pi 配置中移除独立的 `npm:@monotykamary/pi-tps`，否则两个扩展会重复写入 `tps` 条目并重复通知。
+## 汇总行是怎么算的
+
+```
+⏱ 2m 14.3s · TPS 62.4 tok/s · TTFT 1.2s · in 48.2K · out 12.7K · $0.42/M
+```
+
+- 开头的 **`⏱`** 数值从你发出消息算到 `agent_settled`，与 spinner 一直在显示的是同一个时钟，数字对得上。
+- **TPS** 按输出 token 加权（总输出量 ÷ 生成时间之和），单轮输出很少也不会把整段均值带偏。
+- **TTFT** 取本段第一个可测值，也就是「多久看到第一个字」。
+- **in/out** 是各轮求和；**stall** 只在检测到停顿且时长大于 0 时出现。
+- **费率**用真正计费的金额（provider 报账单时用实际账单，否则用列表价）折算每百万 token。
 
 ## 安装
 
@@ -38,9 +52,14 @@ pi install npm:pi-metrics
 ## 实现说明
 
 - 总耗时以 `input` 事件（用户提交消息的时刻）为起点、`agent_settled` 为终点，因此多轮工具调用、自动重试和队列续跑都计入同一次总耗时；运行中发送的 steer/followUp 消息不会重置起点。
+- `on-stop` 模式把每轮结束的指标累加进一个运行累加器（只保留聚合量，不囤各轮原始记录），在 `agent_settled` 时合成一行；账单迟到时重算并重发这一行，而不是补一条单轮行。
 - 非 TUI 模式（rpc/print）下不启动定时器、不发送通知。
 - Neuralwatt 成本监听器会在 `session_shutdown` 时取消订阅，恢复通知的延迟定时器也会在 reload/session 切换时清理。
 
+## 从 pi-tps 迁移
+
+TPS 实现现在由本包维护。启用本包前，请从 Pi 配置中移除独立的 `npm:@monotykamary/pi-tps`，否则两个扩展会重复写入 `tps` 条目并重复通知。
+
 ## 国际化
 
 所有面向用户的文案均通过 `pi-extensions-i18n` 提供 `zh-CN` 和 `en-US` 双语。

package/SKILL.md

@@ -5,14 +5,17 @@ description: "启用与排查 pi-metrics 的耗时、TPS、TTFT、token 和成
 
 # 配置 pi-metrics
 
-配置文件为 `<Pi agent 目录>/extensions/pi-metrics/config.json`，字段只有 `enabled`，默认是 `true`。可以使用 `/config:metrics` 打开 TUI 菜单，或使用 `/config:metrics enable|disable` 直接修改并持久化。手动修改配置文件后执行 `/reload`。
+配置文件为 `<Pi agent 目录>/extensions/pi-metrics/config.json`，字段有 `enabled`（默认 `true`）和 `display`（`"on-stop"` 默认 / `"live"`）。可以使用 `/config:metrics` 打开 TUI 菜单（每次选择都会保存并重新打开，选「完成」退出），或用 `/config:metrics enable|disable|live|on-stop|reset` 直接改一项。手动修改配置文件后执行 `/reload`。
+
+`display` 决定指标行何时出现：`on-stop` 只在整段运行停下后出一行汇总（总耗时 · 混合 TPS · TTFT · in/out · stall · 费率），`live` 每轮结束就出一行。spinner 上的实时耗时两种模式都有。
 
 ## 诊断与修改
 
 1. 确认 `npm:pi-metrics` 已安装且扩展资源已启用。
 2. 若同时启用了 `npm:@monotykamary/pi-tps`，先让用户选择保留一个；两者会重复写入 `tps` session entry 和通知。
-3. 文案语言由 `pi-extensions-i18n` 控制。
+3. 只有在 `live` 模式才应该看到每轮指标行；`on-stop` 模式下每轮都没有提示属于预期行为，不要当成 bug。
+4. 文案语言由 `pi-extensions-i18n` 控制。
 
 ## 验证
 
-在 TUI 中完成一次真实模型回合，观察 working spinner、每轮的 TPS/TTFT/token 指标行（含本轮耗时）和可用的 cost；如果一次运行跑了多轮，停下时还应看到一条 `⏱ 总耗时`。RPC/print 模式不会启动 UI 定时器或通知；provider 未返回 usage 时部分指标不可用。真实模型回合属于 E2E，执行前遵守当前任务授权边界；未运行时明确报告 `NOT_RUN`。
+在 TUI 中完成一次真实模型回合：两种模式都应看到 working spinner 计时；`on-stop` 模式在停下后只出现一行汇总，`live` 模式每轮一行、多轮时另有一条 `⏱ <耗时>`（只有图标和数值，不带「总耗时」字样）。RPC/print 模式不会启动 UI 定时器或通知；provider 未返回 usage 时部分指标不可用。真实模型回合属于 E2E，执行前遵守当前任务授权边界；未运行时明确报告 `NOT_RUN`。

package/locales/index.json

@@ -4,8 +4,8 @@
     "en-US": "⏱ {value}"
   },
   "elapsedTotal": {
-    "zh-CN": "⏱ 总耗时 {value}",
-    "en-US": "⏱ Total elapsed {value}"
+    "zh-CN": "⏱ {value}",
+    "en-US": "⏱ {value}"
   },
   "tpsValue": {
     "zh-CN": "TPS {value} tok/s",
@@ -40,8 +40,8 @@
     "en-US": "Configure metrics display"
   },
   "configCommandUsage": {
-    "zh-CN": "用法：/config:metrics（打开配置菜单）、enable、disable 或 reset",
-    "en-US": "Usage: /config:metrics (open settings), enable, disable, or reset"
+    "zh-CN": "用法：/config:metrics（打开配置菜单）、enable、disable、live、on-stop 或 reset",
+    "en-US": "Usage: /config:metrics (open settings), enable, disable, live, on-stop, or reset"
   },
   "configMenuTitle": {
     "zh-CN": "指标配置",
@@ -55,6 +55,18 @@
     "zh-CN": "禁用指标：{value}",
     "en-US": "Metrics disabled: {value}"
   },
+  "configDisplay": {
+    "zh-CN": "显示时机：{value}",
+    "en-US": "Display: {value}"
+  },
+  "configDisplayLive": {
+    "zh-CN": "每轮实时一行",
+    "en-US": "one line per turn"
+  },
+  "configDisplayOnStop": {
+    "zh-CN": "停下后汇总一行",
+    "en-US": "one summary line when stopped"
+  },
   "configOn": {
     "zh-CN": "开",
     "en-US": "on"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-metrics",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "Pi metrics extension: elapsed-time HUD and resilient TPS telemetry",
   "type": "module",
   "main": "./index.ts",
@@ -62,7 +62,7 @@
     "@earendil-works/pi-tui": ">=0.80.0"
   },
   "dependencies": {
-    "pi-extensions-i18n": "^0.6.0"
+    "pi-extensions-i18n": "^0.8.0"
   },
   "devDependencies": {
     "@earendil-works/pi-ai": "0.85.1",

package/src/config.ts

@@ -8,11 +8,17 @@ const CONFIG_FILE_NAME = "config.json";
 const UTF8_ENCODING = "utf8";
 const FILE_NOT_FOUND_CODE = "ENOENT";
 
+/** 指标显示时机：live 每轮一行；on-stop 只在整段运行停下后汇总一行。 */
+export type MetricsDisplay = "live" | "on-stop";
+
+const DISPLAY_VALUES: readonly MetricsDisplay[] = ["live", "on-stop"];
+
 export interface MetricsConfig {
   enabled: boolean;
+  display: MetricsDisplay;
 }
 
-export const DEFAULT_METRICS_CONFIG: MetricsConfig = { enabled: true };
+export const DEFAULT_METRICS_CONFIG: MetricsConfig = { enabled: true, display: "on-stop" };
 
 /** 返回 pi-metrics 配置文件路径。 */
 export function configPath(agentDir = getAgentDir()): string {
@@ -26,12 +32,18 @@ export function parseConfig(value: unknown): MetricsConfig {
   }
   const raw = value as Record<string, unknown>;
   for (const key of Object.keys(raw)) {
-    if (key !== "enabled") throw new Error(`unknown configuration field: ${key}`);
+    if (key !== "enabled" && key !== "display") throw new Error(`unknown configuration field: ${key}`);
   }
   if (raw.enabled !== undefined && typeof raw.enabled !== "boolean") {
     throw new Error("enabled must be a boolean");
   }
-  return { enabled: (raw.enabled as boolean | undefined) ?? DEFAULT_METRICS_CONFIG.enabled };
+  if (raw.display !== undefined && !DISPLAY_VALUES.includes(raw.display as MetricsDisplay)) {
+    throw new Error(`display must be one of: ${DISPLAY_VALUES.join(", ")}`);
+  }
+  return {
+    enabled: (raw.enabled as boolean | undefined) ?? DEFAULT_METRICS_CONFIG.enabled,
+    display: (raw.display as MetricsDisplay | undefined) ?? DEFAULT_METRICS_CONFIG.display,
+  };
 }
 
 /** 读取配置文件；缺少文件时使用默认启用状态。 */

package/src/format-utils.ts

@@ -1,23 +1,102 @@
 /**
- * 耗时格式化纯函数
+ * 指标格式化纯函数
  *
- * 抽离为独立模块便于单元测试（仓库门禁要求测试确定性、不依赖 Pi 运行时）。
+ * 抽离为独立模块便于单元测试（仓库门禁要求测试确定性、不依赖 Pi 运行时），
+ * 同时供 turn-elapsed、tps 和 run-summary 共用，避免循环依赖。
  */
 
+const MS_PER_SECOND = 1_000;
+const SECOND = 1;
+const MINUTE = 60 * SECOND;
+const HOUR = 60 * MINUTE;
+const DAY = 24 * HOUR;
+const WEEK = 7 * DAY;
+const MONTH = 30 * DAY;
+const YEAR = 365 * DAY;
+
+const THOUSAND = 1_000;
+const MILLION = 1_000_000;
+const BILLION = 1_000_000_000;
+
+const TOKEN_DECIMAL_PLACES = 1;
+/** 整数值的 1 位小数形式；命中时改回整数显示（2K 而不是 2.0K）。 */
+const ZERO_DECIMAL_SUFFIX = ".0";
+const DURATION_DECIMAL_PLACES = 1;
+const RATE_DECIMAL_PLACES = 2;
+
+/**
+ * 耗时单位表：label、该单位秒数、以及只显示一个单位时要补的次一级单位。
+ * 年和月跳过「周」，直接补「天」，因为「1y 0w」没有信息量。
+ */
+const DURATION_UNITS: ReadonlyArray<readonly [string, number, string | null]> = [
+  ["y", YEAR, "d"],
+  ["mo", MONTH, "d"],
+  ["w", WEEK, "d"],
+  ["d", DAY, "h"],
+  ["h", HOUR, "m"],
+  ["m", MINUTE, "s"],
+  ["s", SECOND, null],
+];
+
 /** 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;
+  const totalSec = Math.floor(ms / MS_PER_SECOND);
+  if (totalSec < MINUTE) return `${totalSec}s`;
+  const m = Math.floor(totalSec / MINUTE);
+  const s = totalSec % MINUTE;
   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`;
+  const sec = ms / MS_PER_SECOND;
+  if (sec < MINUTE) return `${sec.toFixed(DURATION_DECIMAL_PLACES)}s`;
+  const m = Math.floor(sec / MINUTE);
+  const s = sec - m * MINUTE;
+  return `${m}m ${s.toFixed(DURATION_DECIMAL_PLACES)}s`;
+}
+
+/** token 数的紧凑显示：1.2K / 2M / 1.5B。 */
+export function formatNumber(num: number): string {
+  if (num < THOUSAND) return String(num);
+
+  const [value, suffix] = num >= BILLION
+    ? [num / BILLION, "B"]
+    : num >= MILLION
+      ? [num / MILLION, "M"]
+      : [num / THOUSAND, "K"];
+  const formatted = value.toFixed(TOKEN_DECIMAL_PLACES);
+  return formatted.endsWith(ZERO_DECIMAL_SUFFIX) ? `${value.toFixed(0)}${suffix}` : `${formatted}${suffix}`;
+}
+
+/** 耗时的宽松显示：最多两个单位（如 1m 0s、1mo 0d）。 */
+export function formatDuration(totalSeconds: number): string {
+  if (totalSeconds < MINUTE) return `${totalSeconds.toFixed(DURATION_DECIMAL_PLACES)}s`;
+
+  const parts: Array<{ value: number; label: string }> = [];
+  let remaining = Math.round(totalSeconds);
+
+  for (const [label, seconds] of DURATION_UNITS) {
+    if (remaining >= seconds) {
+      parts.push({ value: Math.floor(remaining / seconds), label });
+      remaining %= seconds;
+    }
+  }
+
+  if (parts.length === 1) {
+    const companion = DURATION_UNITS.find(([label]) => label === parts[0].label)?.[2];
+    if (companion) parts.push({ value: 0, label: companion });
+  }
+
+  return parts.slice(0, 2).map(({ value, label }) => `${value}${label}`).join(" ");
+}
+
+/** 由成本（美元）和 token 数折算每百万 token 的费率；数据不可用时返回 null。 */
+export function computeRateUsdPerM(costUsd: number | null, totalTokens: number): number | null {
+  if (costUsd === null || !Number.isFinite(costUsd) || costUsd < 0) return null;
+  if (!Number.isFinite(totalTokens) || totalTokens <= 0) return null;
+  const rate = costUsd / (totalTokens / MILLION);
+  if (!Number.isFinite(rate) || rate < 0) return null;
+  const scale = 10 ** RATE_DECIMAL_PLACES;
+  return Math.round(rate * scale) / scale;
 }

package/src/index.ts

@@ -5,49 +5,143 @@ import type {
 } from "@earendil-works/pi-coding-agent";
 import { createTranslator, installNoticeRenderer, loadCatalog, notifyWithSource } from "pi-extensions-i18n";
 import { NOTICE_SOURCE } from "./notice.ts";
-import turnElapsed from "./turn-elapsed.ts";
+import turnElapsed, { createElapsedTracker } from "./turn-elapsed.ts";
 import tps from "./tps.ts";
-import { configPath, loadConfig, parseConfig, saveConfig, type MetricsConfig } from "./config.ts";
+import {
+  configPath,
+  DEFAULT_METRICS_CONFIG,
+  loadConfig,
+  saveConfig,
+  type MetricsConfig,
+  type MetricsDisplay,
+} from "./config.ts";
 
 const messages = loadCatalog(new URL("../locales/index.json", import.meta.url));
 const i18n = createTranslator(messages);
 const CONFIG_COMMAND_ALIASES = ["config:metrics", "metrics-config", "pi-metrics-config"] as const;
 const CONFIG_RESET_COMMAND = "reset";
-const CONFIG_CHOICE = { enabled: 0, disabled: 1 } as const;
 const ENABLE_COMMAND = "enable";
 const DISABLE_COMMAND = "disable";
+const DISPLAY_LIVE_COMMAND = "live";
+const DISPLAY_ON_STOP_COMMAND = "on-stop";
 const NOTICE_WARNING = "warning" as const;
 const NOTICE_INFO = "info" as const;
 const NOTICE_ERROR = "error" as const;
+const DISPLAY_FLIP: Record<MetricsDisplay, MetricsDisplay> = {
+  [DISPLAY_LIVE_COMMAND]: DISPLAY_ON_STOP_COMMAND,
+  [DISPLAY_ON_STOP_COMMAND]: DISPLAY_LIVE_COMMAND,
+};
 
-/** 注册配置命令，通过 TUI 选择是否启用指标。 */
+/** 命令参数到配置片段的映射：直接改配置时要覆盖的字段。 */
+const COMMAND_CONFIG_PATCH: ReadonlyMap<string, Partial<MetricsConfig>> = new Map([
+  [ENABLE_COMMAND, { enabled: true }],
+  [DISABLE_COMMAND, { enabled: false }],
+  [DISPLAY_LIVE_COMMAND, { display: "live" }],
+  [DISPLAY_ON_STOP_COMMAND, { display: "on-stop" }],
+]);
+
+/** 配置值对应的菜单文案。 */
+function displayLabel(display: MetricsDisplay): string {
+  return i18n.t(display === "on-stop" ? "configDisplayOnStop" : "configDisplayLive");
+}
+
+/** 保存配置并提示结果；写盘失败时只提示不抛出，返回是否成功。 */
+function persistConfig(ctx: ExtensionCommandContext, config: MetricsConfig): boolean {
+  try {
+    const path = saveConfig(config);
+    notifyWithSource({ ctx, source: NOTICE_SOURCE, level: NOTICE_INFO, message: i18n.t("configCommandSaved", { path }) });
+    return true;
+  } catch (error) {
+    notifyWithSource({
+      ctx,
+      source: NOTICE_SOURCE,
+      level: NOTICE_ERROR,
+      message: i18n.t("configCommandInvalid", {
+        error: error instanceof Error ? error.message : String(error),
+      }),
+    });
+    return false;
+  }
+}
+
+/** 提示无效配置并返回 false，供读取配置失败时复用。 */
+function reportConfigError(ctx: ExtensionCommandContext, error: unknown): false {
+  notifyWithSource({
+    ctx,
+    source: NOTICE_SOURCE,
+    level: NOTICE_ERROR,
+    message: i18n.t("configCommandInvalid", {
+      error: error instanceof Error ? error.message : String(error),
+    }),
+  });
+  return false;
+}
+
+/**
+ * 弹出配置菜单，返回用户改动后的配置。
+ * 只调用 TUI 选择，不写盘：选择「完成」或按 Esc 时返回 null，由调用方结束编辑；
+ * 返回的配置还需要调用方自己落盘。
+ */
+async function promptConfigChange(
+  ctx: ExtensionCommandContext,
+  current: MetricsConfig,
+): Promise<MetricsConfig | null> {
+  const enabledChoice = i18n.t("configEnabled", { value: i18n.t(current.enabled ? "configOn" : "configOff") });
+  const displayChoice = i18n.t("configDisplay", { value: displayLabel(current.display) });
+  const doneChoice = i18n.t("configDone");
+  const selected = await ctx.ui.select(i18n.t("configMenuTitle"), [enabledChoice, displayChoice, doneChoice]);
+  if (selected === undefined || selected === doneChoice) return null;
+  return selected === enabledChoice
+    ? { ...current, enabled: !current.enabled }
+    : { ...current, display: DISPLAY_FLIP[current.display] };
+}
+
+/** 取命令参数对应的配置补丁；`reset` 用整份默认配置覆盖当前值，未知参数返回 null。 */
+function configPatchFor(value: string): Partial<MetricsConfig> | null {
+  if (value === CONFIG_RESET_COMMAND) return { ...DEFAULT_METRICS_CONFIG };
+  return COMMAND_CONFIG_PATCH.get(value) ?? null;
+}
+
+/**
+ * 应用直接参数形式的配置命令：读当前配置、叠加一个补丁后写回。
+ * 未知参数只提示用法；写盘失败由 persistConfig 自己提示，本函数不抛出。
+ */
+function applyCommandSetting(value: string, ctx: ExtensionCommandContext): void {
+  const patch = configPatchFor(value);
+  if (patch === null) {
+    notifyWithSource({ ctx, source: NOTICE_SOURCE, level: NOTICE_WARNING, message: i18n.t("configCommandUsage") });
+    return;
+  }
+  let current: MetricsConfig;
+  try {
+    current = loadConfig();
+  } catch (error) {
+    reportConfigError(ctx, error);
+    return;
+  }
+  persistConfig(ctx, { ...current, ...patch });
+}
+
+/** 注册配置命令，通过 TUI 循环编辑，或直接用参数改一项。 */
 function registerConfigCommand(pi: ExtensionAPI): void {
   const command = {
     description: i18n.t("configCommandDescription"),
-    /** Completes the supported reset action. */
-    getArgumentCompletions: () => [{ value: CONFIG_RESET_COMMAND, label: CONFIG_RESET_COMMAND }],
-    /** Selects and persists the enabled state. */
+    /** Completes the supported direct settings. */
+    getArgumentCompletions: () => [
+      { value: CONFIG_RESET_COMMAND, label: CONFIG_RESET_COMMAND },
+      { value: ENABLE_COMMAND, label: ENABLE_COMMAND },
+      { value: DISABLE_COMMAND, label: DISABLE_COMMAND },
+      { value: DISPLAY_LIVE_COMMAND, label: DISPLAY_LIVE_COMMAND },
+      { value: DISPLAY_ON_STOP_COMMAND, label: DISPLAY_ON_STOP_COMMAND },
+    ],
+    /**
+     * 处理命令：带参数时直改一项，不带参数时进入 TUI 菜单循环；
+     * 写盘和提示都是副作用，配置改动需要 /reload 才生效。
+     */
     handler: async (args: string, ctx: ExtensionCommandContext): Promise<void> => {
       const value = args.trim();
-      if (value && value !== CONFIG_RESET_COMMAND && value !== ENABLE_COMMAND && value !== DISABLE_COMMAND) {
-        notifyWithSource({ ctx, source: NOTICE_SOURCE, level: NOTICE_WARNING, message: i18n.t("configCommandUsage") });
-        return;
-      }
-      if (value === CONFIG_RESET_COMMAND || value === ENABLE_COMMAND || value === DISABLE_COMMAND) {
-        try {
-          const config = parseConfig(value === CONFIG_RESET_COMMAND ? {} : { enabled: value === ENABLE_COMMAND });
-          const path = saveConfig(config);
-          notifyWithSource({ ctx, source: NOTICE_SOURCE, level: NOTICE_INFO, message: i18n.t("configCommandSaved", { path }) });
-        } catch (error) {
-          notifyWithSource({
-            ctx,
-            source: NOTICE_SOURCE,
-            level: NOTICE_ERROR,
-            message: i18n.t("configCommandInvalid", {
-              error: error instanceof Error ? error.message : String(error),
-            }),
-          });
-        }
+      if (value) {
+        applyCommandSetting(value, ctx);
         return;
       }
       if (!ctx.hasUI) {
@@ -58,38 +152,14 @@ function registerConfigCommand(pi: ExtensionAPI): void {
       try {
         current = loadConfig();
       } catch (error) {
-        notifyWithSource({
-          ctx,
-          source: NOTICE_SOURCE,
-          level: NOTICE_ERROR,
-          message: i18n.t("configCommandInvalid", {
-            error: error instanceof Error ? error.message : String(error),
-          }),
-        });
+        reportConfigError(ctx, error);
         return;
       }
-      const enabledChoice = i18n.t("configEnabled", { value: i18n.t(current.enabled ? "configOn" : "configOff") });
-      const disabledChoice = i18n.t("configDisabled", { value: i18n.t(current.enabled ? "configOff" : "configOn") });
-      const doneChoice = i18n.t("configDone");
-      const selected = await ctx.ui.select(i18n.t("configMenuTitle"), [
-        enabledChoice,
-        disabledChoice,
-        doneChoice,
-      ]);
-      if (selected === undefined || selected === doneChoice) return;
-      const choice = selected === enabledChoice ? CONFIG_CHOICE.enabled : CONFIG_CHOICE.disabled;
-      try {
-        const path = saveConfig({ enabled: choice === CONFIG_CHOICE.enabled });
-        notifyWithSource({ ctx, source: NOTICE_SOURCE, level: NOTICE_INFO, message: i18n.t("configCommandSaved", { path }) });
-      } catch (error) {
-        notifyWithSource({
-          ctx,
-          source: NOTICE_SOURCE,
-          level: NOTICE_ERROR,
-          message: i18n.t("configCommandInvalid", {
-            error: error instanceof Error ? error.message : String(error),
-          }),
-        });
+      // 每选一项就落盘并重新打开菜单，直到用户选「完成」或按 Esc。
+      for (;;) {
+        const next = await promptConfigChange(ctx, current);
+        if (next === null) return;
+        if (persistConfig(ctx, next)) current = next;
       }
     },
   };
@@ -106,7 +176,7 @@ export default function piHud(pi: ExtensionAPI): void {
   try {
     config = loadConfig();
   } catch (error) {
-    config = { enabled: true };
+    config = { ...DEFAULT_METRICS_CONFIG };
     configError = error;
   }
   if (configError !== undefined) {
@@ -123,8 +193,10 @@ export default function piHud(pi: ExtensionAPI): void {
     });
   }
   if (!config.enabled) return;
-  turnElapsed(pi);
-  tps(pi);
+  // 两个模块共用同一个运行时钟：on-stop 汇总行里的整段耗时和 spinner 显示的是同一段。
+  const tracker = createElapsedTracker();
+  turnElapsed(pi, { tracker, display: config.display });
+  tps(pi, { tracker, display: config.display });
 }
 
 export { configPath, loadConfig, parseConfig, saveConfig } from "./config.ts";
@@ -132,4 +204,5 @@ export type { MetricsConfig } from "./config.ts";
 export { default as turnElapsed } from "./turn-elapsed.ts";
 export { default as tps } from "./tps.ts";
 export * from "./format-utils.ts";
+export * from "./run-summary.ts";
 export * from "./tps.ts";

package/src/notice.ts

@@ -3,11 +3,11 @@
  * 所有 notifyWithSource 调用共用同一份标签与颜色，避免两个入口不一致。
  */
 
-import type { NoticeColor, NoticeSource } from "pi-extensions-i18n";
+import { NOTICE_TAG_COLOR, type NoticeColor, type NoticeSource } from "pi-extensions-i18n";
 
 /** 本扩展的提示标签；短且唯一，便于在会话里定位来源。 */
 export const NOTICE_TAG = "metrics";
-/** 提示标签颜色；与其它扩展错开，避免看起来像同一条消息。 */
-export const NOTICE_COLOR: NoticeColor = "dim";
+/** 提示标签颜色：所有扩展统一用弱化色，来源靠 tag 文本区分，不靠颜色。 */
+export const NOTICE_COLOR: NoticeColor = NOTICE_TAG_COLOR;
 /** 本扩展的提示来源。 */
 export const NOTICE_SOURCE: NoticeSource = { tag: NOTICE_TAG, color: NOTICE_COLOR };

package/src/run-summary.ts

@@ -0,0 +1,214 @@
+/**
+ * 整段运行的指标汇总
+ *
+ * 只在 `display: "on-stop"`（默认）下使用：一次运行里的每一轮指标边跑边累加，
+ * 等 AI 完全停下（agent_settled）再合成一行，避免多轮工具调用时对话区被刷屏。
+ * 累加器只保留聚合量（各字段求和 + 第一个 TTFT），不囤各轮原始记录；
+ * 聚合与格式化都是纯逻辑，便于不依赖 Pi 运行时做单元测试。
+ */
+
+import { computeRateUsdPerM, formatDone, formatDuration, formatNumber } from "./format-utils.ts";
+import { i18n } from "./i18n.ts";
+
+const TPS_DECIMAL_PLACES = 1;
+const RATE_DECIMAL_PLACES = 2;
+const MS_PER_SECOND = 1_000;
+
+/** 汇总需要的一轮指标；TurnTelemetry 结构上满足这个形状。 */
+export interface SummaryTurn {
+  tokens: {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    total: number;
+  };
+  timing: {
+    /** 该轮从开场到第一个 token 的耗时（毫秒）。 */
+    ttftMs: number | null;
+    stallMs: number;
+    stallCount: number;
+  };
+  /** 该轮 TPS；null 表示样本不足、无法测得。 */
+  tps: number | null;
+  /** 该轮列表价成本明细；null 表示 provider 没返回成本。 */
+  cost: {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    total: number;
+  } | null;
+}
+
+/** 一整段运行的汇总结果。 */
+export interface RunSummary {
+  /** 参与汇总的轮数。 */
+  turns: number;
+  tokens: {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    total: number;
+  };
+  /** 按输出 token 加权的混合 TPS；没有可用样本时为 null。 */
+  tps: number | null;
+  /** 本段第一个可测的 TTFT（毫秒），即用户等到第一个 token 的时间；没有样本时为 null。 */
+  ttftMs: number | null;
+  stallMs: number;
+  stallCount: number;
+  /** 各轮列表价成本之和；全部缺失时为 null。 */
+  cost: {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    total: number;
+  } | null;
+  /** 整段每百万 token 的费率；数据不足时为 null。 */
+  rateUsdPerMTokens: number | null;
+}
+
+/**
+ * 整段运行的增量累加器。
+ *
+ * - 内存只随聚合字段数量增长，不随轮数增长：轮数再多也只留下各字段的求和值。
+ * - TPS 按输出 token 加权：整段输出量 ÷ 各轮生成时间之和，不会因为某一轮输出很少就失真。
+ *   单轮生成时间由该轮的 `output / tps` 反推，省得再存一份中间量。
+ * - TTFT 取本段第一个可测值：用户感知的是「多久看到第一个字」。
+ * - 费率只用真正计费的金额折算，避免把列表价和实际账单混在一起。
+ */
+export interface RunAccumulator {
+  /** 累加一轮指标；effectiveCostUsd 是该轮实际计费金额（billed 优先，其次列表价）。 */
+  add(turn: SummaryTurn, effectiveCostUsd?: number | null): void;
+  /** 替换某一轮迟到到达的计费金额；返回是否真的改变了汇总数据。 */
+  replaceBilledCost(previous: number | null, next: number): boolean;
+  /** 汇总当前已累加的数据；一轮都没累加过时返回 null。 */
+  summarize(): RunSummary | null;
+}
+
+/** 是否是可用的计费金额（有限、非负）。 */
+function isUsableCost(value: number | null | undefined): value is number {
+  return value !== undefined && value !== null && Number.isFinite(value) && value >= 0;
+}
+
+/** 造一个空的整段运行累加器。 */
+export function createRunAccumulator(): RunAccumulator {
+  let turns = 0;
+  let input = 0;
+  let output = 0;
+  let cacheRead = 0;
+  let cacheWrite = 0;
+  let total = 0;
+  let stallMs = 0;
+  let stallCount = 0;
+  let ttftMs: number | null = null;
+  let costInput = 0;
+  let costOutput = 0;
+  let costCacheRead = 0;
+  let costCacheWrite = 0;
+  let costTotal = 0;
+  let hasCost = false;
+  let billedTotal = 0;
+  let hasBilled = false;
+  let measuredOutput = 0;
+  let generationMs = 0;
+
+  return {
+    /**
+     * 累加一轮指标：更新各字段求和、第一个可测 TTFT，以及按输出 token 加权的生成时间。
+     * 副作用：turns 递增；进第一个非空 TTFT 后不再被后续轮覆盖。
+     */
+    add(turn: SummaryTurn, effectiveCostUsd: number | null = null): void {
+      turns += 1;
+      input += turn.tokens.input;
+      output += turn.tokens.output;
+      cacheRead += turn.tokens.cacheRead;
+      cacheWrite += turn.tokens.cacheWrite;
+      total += turn.tokens.total;
+      stallMs += turn.timing.stallMs;
+      stallCount += turn.timing.stallCount;
+      if (ttftMs === null && turn.timing.ttftMs !== null) ttftMs = turn.timing.ttftMs;
+      if (turn.cost) {
+        costInput += turn.cost.input;
+        costOutput += turn.cost.output;
+        costCacheRead += turn.cost.cacheRead;
+        costCacheWrite += turn.cost.cacheWrite;
+        costTotal += turn.cost.total;
+        hasCost = true;
+      }
+      if (isUsableCost(effectiveCostUsd)) {
+        billedTotal += effectiveCostUsd;
+        hasBilled = true;
+      }
+      if (turn.tps !== null && turn.tps > 0 && turn.tokens.output > 0) {
+        measuredOutput += turn.tokens.output;
+        generationMs += (turn.tokens.output / turn.tps) * MS_PER_SECOND;
+      }
+    },
+    /**
+     * 用迟到的实际账单替换某一轮先前的计费金额。
+     * 副作用：billedTotal 先减旧值再加新值，并把 hasBilled 置为 true；
+     * 旧值等于新值时直接返回 false，让调用方跳过重新汇总和重发提示。
+     */
+    replaceBilledCost(previous: number | null, next: number): boolean {
+      const previousCounted = isUsableCost(previous);
+      if (previousCounted && previous === next) return false;
+      if (previousCounted) billedTotal -= previous;
+      billedTotal += next;
+      hasBilled = true;
+      return true;
+    },
+    /**
+     * 汇总已累加的数据：算出加权 TPS 与整段费率。
+     * 一轮都没累加过时返回 null，避免上层发出不带任何指标的空行。
+     */
+    summarize(): RunSummary | null {
+      if (turns === 0) return null;
+      const scale = 10 ** TPS_DECIMAL_PLACES;
+      const blendedTps = measuredOutput > 0 && generationMs > 0
+        ? Math.round((measuredOutput / (generationMs / MS_PER_SECOND)) * scale) / scale
+        : null;
+      const effectiveCost = hasBilled ? billedTotal : hasCost ? costTotal : null;
+      return {
+        turns,
+        tokens: { input, output, cacheRead, cacheWrite, total },
+        tps: blendedTps,
+        ttftMs,
+        stallMs,
+        stallCount,
+        cost: hasCost
+          ? { input: costInput, output: costOutput, cacheRead: costCacheRead, cacheWrite: costCacheWrite, total: costTotal }
+          : null,
+        rateUsdPerMTokens: computeRateUsdPerM(effectiveCost, total),
+      };
+    },
+  };
+}
+
+/** 合成一行整段汇总：总耗时 · TPS · TTFT · in · out · stall · 费率。 */
+export function composeRunSummary(summary: RunSummary, elapsedMs: number | null): string {
+  const parts: string[] = [];
+  if (elapsedMs !== null && elapsedMs > 0) {
+    parts.push(i18n.t("elapsedTotal", { value: formatDone(elapsedMs) }));
+  }
+  parts.push(summary.tps === null
+    ? i18n.t("tpsUnknown")
+    : i18n.t("tpsValue", { value: summary.tps.toFixed(TPS_DECIMAL_PLACES) }));
+  if (summary.ttftMs !== null) {
+    parts.push(i18n.t("tpsTtft", { value: formatDuration(summary.ttftMs / MS_PER_SECOND) }));
+  }
+  parts.push(i18n.t("tpsInput", { value: formatNumber(summary.tokens.input) }));
+  parts.push(i18n.t("tpsOutput", { value: formatNumber(summary.tokens.output) }));
+  if (summary.stallMs > 0) {
+    parts.push(i18n.t("tpsStall", {
+      value: formatDuration(summary.stallMs / MS_PER_SECOND),
+      count: summary.stallCount,
+    }));
+  }
+  if (summary.rateUsdPerMTokens !== null) {
+    parts.push(i18n.t("tpsRate", { value: summary.rateUsdPerMTokens.toFixed(RATE_DECIMAL_PLACES) }));
+  }
+  return parts.join(" · ");
+}

package/src/tps.ts

@@ -3,6 +3,11 @@
  *
  * This is the TPS portion of pi-tps, maintained inside pi-metrics so the
  * elapsed-time HUD and generation telemetry share one lifecycle.
+ *
+ * 两种显示时机：
+ * - `live`：每轮结束即出一行指标。
+ * - `on-stop`（默认）：每轮只记 `tps` session entry 和事件，不动对话区；等整段运行
+ *   `agent_settled` 后把各轮合成一行汇总（总耗时、混合 TPS、TTFT、in/out、成本）。
  */
 
 import { performance } from "node:perf_hooks";
@@ -12,8 +17,12 @@ import type {
   ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
 import { notifyWithSource } from "pi-extensions-i18n";
+import { DEFAULT_METRICS_CONFIG, type MetricsDisplay } from "./config.ts";
+import { computeRateUsdPerM, formatDuration, formatNumber } from "./format-utils.ts";
 import { i18n } from "./i18n.ts";
 import { NOTICE_SOURCE } from "./notice.ts";
+import { composeRunSummary, createRunAccumulator, type RunAccumulator } from "./run-summary.ts";
+import type { ElapsedTracker } from "./turn-elapsed.ts";
 
 interface TurnStartEvent {
   type: "turn_start";
@@ -108,58 +117,6 @@ interface SessionEntryLike {
 const STALL_THRESHOLD_MS = 500;
 const NEURALWATT_ENERGY_EVENT = "neuralwatt:turn-energy";
 
-export function formatNumber(num: number): string {
-  if (num < 1_000) return String(num);
-
-  const [value, suffix] = num >= 1_000_000_000
-    ? [num / 1_000_000_000, "B"]
-    : num >= 1_000_000
-      ? [num / 1_000_000, "M"]
-      : [num / 1_000, "K"];
-  const formatted = value.toFixed(1);
-  return formatted.endsWith(".0") ? `${value.toFixed(0)}${suffix}` : `${formatted}${suffix}`;
-}
-
-export function formatDuration(totalSeconds: number): string {
-  if (totalSeconds < 60) return `${totalSeconds.toFixed(1)}s`;
-
-  const units = [
-    ["y", 365 * 24 * 60 * 60],
-    ["mo", 30 * 24 * 60 * 60],
-    ["w", 7 * 24 * 60 * 60],
-    ["d", 24 * 60 * 60],
-    ["h", 60 * 60],
-    ["m", 60],
-    ["s", 1],
-  ] as const;
-  const parts: Array<{ value: number; label: string }> = [];
-  let remaining = Math.round(totalSeconds);
-
-  for (const [label, seconds] of units) {
-    if (remaining >= seconds) {
-      parts.push({ value: Math.floor(remaining / seconds), label });
-      remaining %= seconds;
-    }
-  }
-
-  if (parts.length === 1) {
-    const first = units.findIndex(([label]) => label === parts[0].label);
-    let next = first + 1;
-    if (parts[0].label === "mo") next++;
-    if (parts[0].label === "y") next += 2;
-    if (next < units.length) parts.push({ value: 0, label: units[next][0] });
-  }
-
-  return parts.slice(0, 2).map(({ value, label }) => `${value}${label}`).join(" ");
-}
-
-export function computeRateUsdPerM(costUsd: number | null, totalTokens: number): number | null {
-  if (costUsd === null || !Number.isFinite(costUsd) || costUsd < 0) return null;
-  if (!Number.isFinite(totalTokens) || totalTokens <= 0) return null;
-  const rate = costUsd / (totalTokens / 1_000_000);
-  return Number.isFinite(rate) && rate >= 0 ? Math.round(rate * 100) / 100 : null;
-}
-
 function isAssistantMessage(message: unknown): message is AssistantMessage {
   if (!message || typeof message !== "object") return false;
   const candidate = message as Record<string, unknown>;
@@ -342,7 +299,33 @@ function restoreTPSNotification(
   }
 }
 
-export default function tpsExtension(pi: ExtensionAPI): void {
+/** `on-stop` 模式下与汇总相关的运行状态。 */
+interface SummaryState {
+  /** 本段运行的增量累加器；只保留聚合量，不囤各轮原始记录。 */
+  accumulator: RunAccumulator;
+  /** 发提示用的上下文。 */
+  ctx: ExtensionContext;
+  /** 汇总行里的整段耗时（毫秒）；运行时钟没数据时为 null。 */
+  elapsedMs: number | null;
+  /** 最后累加的一轮下标；没有轮时为 null。 */
+  turnIndex: number | null;
+  /** 最后一轮已计入的计费金额，替换旧值时要用它扣减。 */
+  effectiveCostUsd: number | null;
+}
+
+/** tps 模块的可注入依赖：显示时机，以及 on-stop 模式下共用的运行时钟。 */
+export interface TpsOptions {
+  /** 显示时机；`live` 每轮一行，`on-stop` 只在整段停下后汇总一行。 */
+  display?: MetricsDisplay;
+  /** 共享的运行时钟；只在 `on-stop` 模式下用于汇总行的总耗时。 */
+  tracker?: ElapsedTracker;
+}
+
+/**
+ * 注册 TPS 指标事件：按 `display` 决定每轮实时出一行，还是整段停下后汇总出一行。
+ */
+export default function tpsExtension(pi: ExtensionAPI, options: TpsOptions = {}): void {
+  const display = options.display ?? DEFAULT_METRICS_CONFIG.display;
   let currentTiming: TurnTiming | null = null;
   let pendingNeuralwattBilledCost: { turnIndex: number; costUsd: number } | null = null;
   let lastCommittedTurn: {
@@ -351,6 +334,12 @@ export default function tpsExtension(pi: ExtensionAPI): void {
     billedApplied: boolean;
     ctx: ExtensionContext;
   } | null = null;
+  /** `on-stop` 模式下本段运行的累加器，agent_settled 时出一个汇总行。 */
+  let runAccumulator: RunAccumulator = createRunAccumulator();
+  /** 本段运行最后累加的那一轮；只有它能收到迟到的账单。 */
+  let lastRunTurn: { turnIndex: number; effectiveCostUsd: number | null } | null = null;
+  /** 最近一次已经发出的汇总；账单迟到时用它重算并重发。 */
+  let lastSummary: SummaryState | null = null;
   const tpsCaps = new Map<string, number>();
   const restoreTimers = new Set<ReturnType<typeof setTimeout>>();
   let unsubscribeNeuralwatt: (() => void) | undefined;
@@ -359,10 +348,34 @@ export default function tpsExtension(pi: ExtensionAPI): void {
     currentTiming = null;
     pendingNeuralwattBilledCost = null;
     lastCommittedTurn = null;
+    runAccumulator = createRunAccumulator();
+    lastRunTurn = null;
+    lastSummary = null;
     for (const timer of restoreTimers) clearTimeout(timer);
     restoreTimers.clear();
   };
 
+  /**
+   * 账单在汇总之后才到达时修正已发的那一行：
+   * 只可能落在本段运行的最后一轮，因此用累加器替换该轮的计费金额并重发一行更正，
+   * 不重发单轮指标；金额没变化时跳过重发。
+   */
+  const applyLateBilledCost = (turnIndex: number, costUsd: number): void => {
+    const summary = lastSummary;
+    // 只有已发出的那一行里的最后一轮可能收到迟到账单，其他轮一律忽略。
+    if (!summary || summary.turnIndex !== turnIndex) return;
+    if (!summary.accumulator.replaceBilledCost(summary.effectiveCostUsd, costUsd)) return;
+    summary.effectiveCostUsd = costUsd;
+    const aggregate = summary.accumulator.summarize();
+    if (aggregate === null || !summary.ctx.hasUI) return;
+    notifyWithSource({
+      ctx: summary.ctx,
+      source: NOTICE_SOURCE,
+      level: "info",
+      message: composeRunSummary(aggregate, summary.elapsedMs),
+    });
+  };
+
   const scheduleRestore = (callback: () => void) => {
     const timer = setTimeout(() => {
       restoreTimers.delete(timer);
@@ -394,6 +407,10 @@ export default function tpsExtension(pi: ExtensionAPI): void {
     committed.telemetry = corrected;
     pi.appendEntry("tps", corrected);
     pi.events?.emit("tps:telemetry", corrected);
+    if (display === "on-stop") {
+      applyLateBilledCost(committed.turnIndex, costUsd);
+      return;
+    }
     if (committed.ctx.hasUI) notifyWithSource({ ctx: committed.ctx, source: NOTICE_SOURCE, level: "info", message: composeDisplayString(corrected) });
   });
 
@@ -411,6 +428,9 @@ export default function tpsExtension(pi: ExtensionAPI): void {
   pi.on("session_tree", (_event: SessionTreeEvent, ctx) => {
     pendingNeuralwattBilledCost = null;
     lastCommittedTurn = null;
+    runAccumulator = createRunAccumulator();
+    lastRunTurn = null;
+    lastSummary = null;
     restoreTPSNotification(ctx, scheduleRestore);
   });
 
@@ -515,7 +535,42 @@ export default function tpsExtension(pi: ExtensionAPI): void {
     };
     pi.appendEntry("tps", telemetry);
     pi.events?.emit("tps:telemetry", telemetry);
+    if (display === "on-stop") {
+      // 先累加：整段停下后只出一行汇总，多轮工具调用不会把对话区刷满。
+      const effectiveCostUsd = billedCost ?? telemetry.cost?.total ?? null;
+      runAccumulator.add(telemetry, effectiveCostUsd);
+      lastRunTurn = { turnIndex: event.turnIndex, effectiveCostUsd };
+      return;
+    }
     if (ctx.hasUI) notifyWithSource({ ctx, source: NOTICE_SOURCE, level: "info", message: composeDisplayString(telemetry) });
   });
 
+  pi.on("agent_settled", (_event, ctx: ExtensionContext) => {
+    if (display !== "on-stop") return;
+    // 运行时钟由本模块结算（live 模式下由 turn-elapsed 结算）：先取数再复位，
+    // 汇总行里的总耗时就是 spinner 一直在显示的那一段。
+    const settlement = options.tracker?.currentRun();
+    options.tracker?.resetRun();
+    const aggregate = runAccumulator.summarize();
+    if (aggregate === null) return;
+    const elapsedMs = settlement && settlement.elapsedMs > 0 ? settlement.elapsedMs : null;
+    lastSummary = {
+      accumulator: runAccumulator,
+      ctx,
+      elapsedMs,
+      turnIndex: lastRunTurn?.turnIndex ?? null,
+      effectiveCostUsd: lastRunTurn?.effectiveCostUsd ?? null,
+    };
+    // 本段运行已经结算：换一个空累加器，下一段运行从零开始。
+    runAccumulator = createRunAccumulator();
+    lastRunTurn = null;
+    if (!ctx.hasUI) return;
+    notifyWithSource({
+      ctx,
+      source: NOTICE_SOURCE,
+      level: "info",
+      message: composeRunSummary(aggregate, elapsedMs),
+    });
+  });
+
 }

package/src/turn-elapsed.ts

@@ -3,8 +3,8 @@
  *
  * - working 期间：实时更新 spinner 文字，显示从用户发出消息起的全程耗时（如 "⏱ 47s"），
  *   跨轮不归零 —— 用户等待时最关心的是"一共等了多久"
- * - agent 完全停止时（agent_settled）：插入一条总耗时，覆盖从用户发出消息到 AI 停止
- *   的整段过程（跨越多轮工具调用、自动重试和 compaction 续跑）
+ * - agent 完全停止时（agent_settled）：`display: "live"` 下补一条总耗时；`display: "on-stop"`
+ *   下不再单独发，总耗时由 tps 的整段汇总行带上，避免同一段运行冒两条提示
  *
  * 关于「本轮耗时」：它已经包含在 tps 的那条指标提示里（TPS/TTFT/耗时/tokens 一行），
  * 所以这里不再单独发一条，避免同一轮冒两条指标提示。
@@ -22,6 +22,7 @@
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { notifyWithSource } from "pi-extensions-i18n";
+import { DEFAULT_METRICS_CONFIG, type MetricsDisplay } from "./config.ts";
 import { formatDone, formatTick } from "./format-utils.ts";
 import { i18n } from "./i18n.ts";
 import { NOTICE_SOURCE } from "./notice.ts";
@@ -31,6 +32,14 @@ const TICK_MS = 1000;
 /** 至少跑满两轮才值得单独报一次总耗时；单轮的总耗时是噪声。 */
 const MIN_TURNS_FOR_TOTAL = 2;
 
+/** 一次运行停下时结算出来的原始数据。 */
+export interface RunSettlement {
+  /** 从用户发出消息到 AI 停下的整段耗时（毫秒）。 */
+  elapsedMs: number;
+  /** 本段运行真正跑完的轮数。 */
+  turns: number;
+}
+
 /** 计时状态：与 Pi 事件解耦，便于直接测试判定规则。 */
 export interface ElapsedTracker {
   /** 用户发出消息（或没有 input 事件时的兜底）开始记一段运行；运行中重复调用不改起点。 */
@@ -41,8 +50,10 @@ export interface ElapsedTracker {
   startTurn(): void;
   /** 一轮结束：累计轮次并清掉本轮状态。 */
   endTurn(): void;
-  /** AI 停下：跑满两轮时返回本段总耗时（毫秒），否则返回 undefined。 */
-  settle(): number | undefined;
+  /** 本段运行的结算视图（只读，不复位）；没有进行中的运行返回 undefined。 */
+  currentRun(): RunSettlement | undefined;
+  /** 复位运行状态（一段运行结算完毕后由结算方调用）。 */
+  resetRun(): void;
   /** 清掉本轮起点（agent_end 用）。 */
   clearTurn(): void;
 }
@@ -78,15 +89,17 @@ export function createElapsedTracker(now: () => number = () => Date.now()): Elap
       if (inTurn) turnCount += 1;
       inTurn = false;
     },
-    /** AI 停下：跑满两轮时返回本段总耗时（毫秒），否则返回 undefined。 */
-    settle(): number | undefined {
-      const elapsed = running ? now() - runStartTime : 0;
-      const turns = turnCount;
+    /** 本段运行的结算视图（只读）；没有进行中的运行返回 undefined。 */
+    currentRun(): RunSettlement | undefined {
+      if (!running) return undefined;
+      return { elapsedMs: now() - runStartTime, turns: turnCount };
+    },
+    /** 复位运行状态（一段运行结算完毕后由结算方调用）。 */
+    resetRun(): void {
       running = false;
       inTurn = false;
       runStartTime = 0;
       turnCount = 0;
-      return elapsed > 0 && turns >= MIN_TURNS_FOR_TOTAL ? elapsed : undefined;
     },
     /** 清掉本轮状态（agent_end 用）。 */
     clearTurn(): void {
@@ -95,10 +108,37 @@ export function createElapsedTracker(now: () => number = () => Date.now()): Elap
   };
 }
 
-export default function (pi: ExtensionAPI) {
-  const tracker = createElapsedTracker();
+/** `live` 模式下是否值得单独报总耗时：跑满两轮且有实际耗时。 */
+export function shouldReportTotalRun(settlement: RunSettlement): boolean {
+  return settlement.elapsedMs > 0 && settlement.turns >= MIN_TURNS_FOR_TOTAL;
+}
+
+/** 耗时模块的可注入依赖：与 tps 共用同一个运行时钟，保证两处耗时一致。 */
+export interface TurnElapsedOptions {
+  /** 共享的计时状态；不传就自己造一个（便于单独使用和测试）。 */
+  tracker?: ElapsedTracker;
+  /** 显示时机；只有 `live` 才在这里补总耗时提示。 */
+  display?: MetricsDisplay;
+}
+
+/**
+ * 注册耗时事件：working 期间刷新 spinner，并（live 模式下）在停下时补总耗时提示。
+ *
+ * 运行时钟可以由外部注入：`on-stop` 模式下由 tps 结算同一个 tracker，保证汇总行的
+ * 总耗时与 spinner 显示的是同一段运行。
+ */
+export default function (pi: ExtensionAPI, options: TurnElapsedOptions = {}) {
+  const tracker = options.tracker ?? createElapsedTracker();
+  const display = options.display ?? DEFAULT_METRICS_CONFIG.display;
   let tickHandle: ReturnType<typeof setInterval> | null = null;
 
+  /** live 模式的结算入口：读运行数据后复位，只在本模块负责结算时调用。 */
+  const settleRun = (): RunSettlement | undefined => {
+    const settlement = tracker.currentRun();
+    tracker.resetRun();
+    return settlement;
+  };
+
   const stopTick = () => {
     if (tickHandle !== null) {
       clearInterval(tickHandle);
@@ -150,12 +190,18 @@ export default function (pi: ExtensionAPI) {
 
   pi.on("agent_settled", async (_event, ctx) => {
     stopTick();
-    const runElapsed = tracker.settle();
+    // 运行时钟只有一个结算者：live 模式在这里结算，on-stop 模式由 tps 结算（汇总行要同时带上耗时）。
+    const settlement = display === "live" ? settleRun() : undefined;
     if (!ctx.hasUI) return;
 
     ctx.ui.setWorkingMessage(undefined);
-    if (runElapsed !== undefined) {
-      notifyWithSource({ ctx, source: NOTICE_SOURCE, level: "info", message: i18n.t("elapsedTotal", { value: formatDone(runElapsed) }) });
+    if (settlement !== undefined && shouldReportTotalRun(settlement)) {
+      notifyWithSource({
+        ctx,
+        source: NOTICE_SOURCE,
+        level: "info",
+        message: i18n.t("elapsedTotal", { value: formatDone(settlement.elapsedMs) }),
+      });
     }
   });
 }