pi-ptc-meter 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The Authors
+
+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.en.md

@@ -0,0 +1,44 @@
+# pi-ptc-meter — per-turn tool-call metering (pi extension)
+
+Turns "one tool call = one round trip" into visible numbers, and feeds them back to the model when a turn runs long.
+
+## Features
+
+- Counts tool calls, wall time and the predicted count declared before the turn.
+- Flags turns above the threshold (default 39) for a merge review.
+- Numbers travel in a tail message; the system section stays byte-identical (prefix cache safe).
+- Log: `~/.pi/ptc-meter.jsonl`, one JSON line per turn.
+- `/ptc [n]` shows the last n turns: calls, time, prediction, median, over-threshold.
+
+## Defaults
+
+| Item | Default | Note |
+| --- | --- | --- |
+| Threshold | 39 calls/turn | `threshold` in `~/.pi/ptc-meter.json` |
+| Injection | on | `inject: false` disables |
+| Popup | off | `notify: true` enables (silent by default) |
+| Log | `~/.pi/ptc-meter.jsonl` | keeps whole trailing lines over 1 MiB |
+| Language | Chinese | injected text and command output |
+
+## Install
+
+```bash
+pi install npm:pi-ptc-meter@1.0.0
+pi install ./pi-ptc-meter
+```
+
+## Config
+
+```json
+{ "threshold": 39, "inject": true, "notify": false }
+```
+
+## How it works
+
+- `tool_call` counts → `turn_end` records → next `before_agent_start` settles and feeds back.
+- Only the tail message changes; the section is stable.
+
+## Limits
+
+- Counts calls only; whether they could be merged still needs a human check.
+- Does not intercept input or read conversation content.

package/README.md

@@ -1,3 +1,44 @@
-# Temporary Holding Version
+# pi-ptc-meter — 每轮工具调用计量与回灌（pi 扩展）
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+把「一次工具调用 = 一次往返」的浪费变成可见数字：统计每轮调用次数与时长，超阈值时把数字回灌给模型。
+
+## 功能
+
+- 统计每轮工具调用次数、实际耗时、开工前声明的预计值。
+- 超阈值（默认 39 次/轮）时提示复核「是否有可合并的调用」。
+- 数字走对话尾部消息回灌，system 内只留逐字稳定的骨架（保护前缀缓存）。
+- 日志 `~/.pi/ptc-meter.jsonl`，每行含轮次、次数、时长、预计、会话 id。
+- 命令 `/ptc [n]`：最近 n 轮的次数、时长、预计、中位、超标。
+
+## 默认配置
+
+| 项 | 默认 | 说明 |
+| --- | --- | --- |
+| 阈值 | 39 次/轮 | `~/.pi/ptc-meter.json` 的 `threshold` |
+| 注入回灌 | 开 | `inject: false` 关闭 |
+| 弹窗提示 | 关 | `notify: true` 开启（默认走静默注入） |
+| 日志 | `~/.pi/ptc-meter.jsonl` | 超过 1 MiB 保留尾部整行 |
+| 语言 | 中文 | 注入文本与命令输出 |
+
+## 安装
+
+```bash
+pi install npm:pi-ptc-meter@1.0.0
+pi install ./pi-ptc-meter
+```
+
+## 配置
+
+```json
+{ "threshold": 39, "inject": true, "notify": false }
+```
+
+## 机制
+
+- `tool_call` 计数 → `turn_end` 记录 → 下轮 `before_agent_start` 结算并回灌。
+- 只在尾部消息里变化，system section 每轮字节相同。
+
+## 限制
+
+- 计数只反映调用次数，不判断调用是否真的可合并；可并性需要自行复核。
+- 不拦截、不改输入、不读取对话内容。

package/index.ts

@@ -0,0 +1,386 @@
+/**
+ * ptc-meter —— PTC（执行合并）的计量与**反馈回路**（pi 扩展，自建）
+ *
+ * ## 为什么存在
+ * 手册 §2 把 PTC 列为「第一纪律」，但它此前是唯一零反馈的纪律：每轮用了多少工具调用、
+ * 有多少轮明显超标，全靠自省 —— 而手册自己写着「不以自省为准，以计数为准」。
+ *
+ * ## 闭环（同 caveman-think-zh 的「剥离 → 计数 → 注入 → 改正」）
+ *   tool_call 计数 → before_agent_start 结算上轮 → 静态骨架进 section、数字进**对话尾部消息** → 我读到数字 → 改正
+ * 数字**回灌到我自己的上下文**才叫闭环：只落盘给用户看是仪表盘，不是回路。
+ *
+ * ## 与 caveman-think-zh 的两处有意差异（源对照，避免误读为背离）
+ *   ① **双通道**：section 只放逐字稳定的**静态骨架**（含常量 SELF_QUESTIONS 索引），**回灌数据**（计数 / 计时 / 判定）走**对话尾部消息**（回灌四律②）——**不复述规则**：规则的权威定义只在手册（§2 PTC / §3 本条目），代码里只有数字与自问。
+ *   ② section key `ptc_meter` 是本扩展新造的（caveman 的 `caveman_reasoning` 亦然）；pi 的 sections 是
+ *      `Record<string,string>`，扩展写自己的 key 即可（与内置 MCP 的 `sections[MCP_SERVERS_SECTION]` 同法）。
+ *
+ * ## 为什么写 section 而不是 return systemPrompt
+ * pi 对 section 做 diff 增量下发（内容不变时零额外 token），且返回 systemPrompt 是 forceSystemPrompt
+ * **覆盖式替换**——会静默丢弃其后所有 section 的修改。本扩展永远只改自己那一节、永不返回 systemPrompt。
+ *
+ * ## 计时（预计 vs 实际）
+ * 我在每轮开工前于回复里声明 `预计 ~Ns`（或 `预计 2m`）；turn_end 解析该声明并入日志，
+ * before_agent_start 回灌「实际 Xs（预计 Ys，偏差 ±Z%）」——偏差可见，下次估得更准。
+ * 未声明则只报实际 + 同类中位（机制不依赖我是否声明）。回灌尾句放**工程自问索引**（常量 `SELF_QUESTIONS`，关键词指向手册元规则 14 全文——不复述规则，见回灌四律④）。
+ * 仍然**不弹窗**：反馈走对话尾部消息（section 只放静态骨架；notify 由配置显式开启）。
+ *
+ * ## 纪律
+ * - 任何失败只跳过 —— **绝不抛错**（tool_call 层无 try/catch，抛错即调用失败）。
+ * - 绝不拦截、绝不改输入、不读 event 字段以外的任何东西。
+ *
+ * ## 配置
+ * `~/.pi/ptc-meter.json`：{ "threshold": 39, "notify": false, "inject": true }
+ *   threshold 超标线 · **notify 超标时弹窗（默认关**——反馈走 section 注入，弹窗只在你想被打扰时才开）· inject 是否写 section（关掉就退回纯计量）
+ */
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { appendFileSync, closeSync, existsSync, openSync, readFileSync, readSync, statSync, writeFileSync } from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+const HOME = os.homedir();
+const LOG = path.join(HOME, ".pi", "ptc-meter.jsonl");
+const CONF = path.join(HOME, ".pi", "ptc-meter.json");
+const DEFAULT_THRESHOLD = 39; // p75 口径：3661 轮实测中位 18 / p75 39；12 会 62% 触发（提示失真，2026-10-17）
+const SECTION_KEY = "ptc_meter";
+const SELF_QUESTIONS = "工程自问（元规则 14：空间换时间 / 复杂度 / 公式 / 算法 / 库 / 框架）";
+// system 里只留这句**静态**骨架（每轮字节相同 → 零缓存成本）；动态数字走对话尾部消息。
+const SECTION_STATIC = `PTC 计量（F = 合并可并调用、删冗余；域 = 一轮内工具调用，读/查/验/算可并、写不并；不动点 = 本轮计数不超阈值，且复核无同类调用可并（机制只数调用，可并性须人工复核）；观察者 = agent_end 落盘日志；回路 = 上轮计数与计时偏差回灌）· ${SELF_QUESTIONS}`;
+const TAIL = 40; // 基线窗口：中位数只取最近这么多轮
+
+type Conf = { threshold?: number; notify?: boolean; inject?: boolean };
+
+function loadConf(): Conf {
+  try {
+    if (!existsSync(CONF)) return {};
+    const j = JSON.parse(readFileSync(CONF, "utf8")) as Conf;
+    return j && typeof j === "object" ? j : {};
+  } catch { return {}; }
+}
+
+/** 生效阈值（配置无值或非法时回退默认）。 */
+function threshold(): number {
+  const c = loadConf();
+  return typeof c.threshold === "number" && c.threshold > 0 ? c.threshold : DEFAULT_THRESHOLD;
+}
+
+// 轮内计数（反馈回路：随注入回到上下文，见 before_agent_start）
+let callsThisTurn = 0;
+let lastCompletedCalls = -1; // 已完成轮的调用数（agent_end 落盘后置位；before_agent_start 缺席时仍可回灌）
+let injectedThisTurn = false; // 本轮是否已由 before_agent_start 注入（缺席时由 agent_end 补发）
+let lastTurnCalls = -1;
+let lastTurnMs = -1;
+let lastTurnEst: number | null = null;
+let turnStartedAt = Date.now();
+let turns = 0;
+
+function percentile(xs: number[], p: number): number {
+  if (!xs.length) return 0;
+  const s = [...xs].sort((a, b) => a - b);
+  const idx = Math.min(s.length - 1, Math.max(0, Math.ceil((p / 100) * s.length) - 1));
+  return s[idx];
+}
+
+
+export function median(xs: number[]): number {
+  if (!xs.length) return 0;
+  const s = [...xs].sort((a, b) => a - b);
+  const m = Math.floor(s.length / 2);
+  return s.length % 2 ? s[m] : Math.round((s[m - 1] + s[m]) / 2);
+}
+
+/** 会话短标识（工作区目录 + 会话文件名，统一小写、去 .jsonl）。日志全局、多会话共写，靠它切分统计；Windows 重启后路径大小写/后缀会变，故规范化。 */
+function sidOf(ctx: ExtensionContext): string {
+  try {
+    const f = ctx.sessionManager.getSessionFile();
+    if (!f) return "";
+    const parts = f.split(/[\\/]+/);
+    const lower = parts.map((p) => p.toLowerCase());
+    const i = lower.indexOf("sessions");
+    // 工作区目录 + 会话 id：子代理 run-* 共享父会话 id，不同会话不再共用 "session"。
+    const pick = i >= 0 && parts.length > i + 2 ? parts.slice(i + 1, i + 3) : parts.slice(-2);
+    return pick.join("/").toLowerCase().replace(/\.jsonl$/, "");
+  } catch { return ""; }
+}
+
+
+type Row = { calls: number; ms: number; est: number | null; estCalls?: number | null };
+
+/** 只读文件尾部至多 maxBytes 字节并按行切分；起点不在文件头时丢弃首行残片。 */
+function tailText(file: string, maxBytes: number): string {
+  let fd: number | null = null;
+  try {
+    fd = openSync(file, "r");
+    const size = statSync(file).size;
+    const start = Math.max(0, size - maxBytes);
+    const buf = Buffer.alloc(size - start);
+    readSync(fd, buf, 0, buf.length, start);
+    const text = buf.toString("utf8");
+    return start > 0 ? text.slice(text.indexOf("\n") + 1) : text;
+  } catch { return ""; } finally {
+    if (fd !== null) { try { closeSync(fd); } catch { /* 静默 */ } }
+  }
+}
+
+/** 读最近 n 轮的 calls/ms/est（缺文件、坏行、旧格式都当 0，绝不抛错）。只统计本会话。 */
+function recentRows(n: number, sid: string): Row[] {
+  try {
+    if (!existsSync(LOG)) return [];
+    // 只读尾部 1 MiB：日志全局累积、无轮转，全量读会让每轮成本随历史线性增长。
+    return tailText(LOG, 1 << 20).trim().split("\n").slice(-2000).filter(Boolean)
+      .map((r) => {
+        try {
+          const j = JSON.parse(r) as { calls?: number; ms?: number; est?: number | null; estCalls?: number | null; sid?: string };
+          const jsid = (j.sid ?? "").toLowerCase().replace(/\.jsonl$/, "");
+          if (jsid !== sid) return null; // 会话不符或无 sid 旧记录：不进统计（sid 已规范化，跨重启/带后缀的历史行可合并）
+          return { calls: j.calls ?? 0, ms: typeof j.ms === "number" ? j.ms : 0, est: typeof j.est === "number" ? j.est : null, estCalls: typeof j.estCalls === "number" ? j.estCalls : null };
+        } catch { return null; }
+      })
+      .filter((r): r is Row => r !== null)
+      .slice(-n);
+  } catch { return []; }
+}
+
+const MAX_LOG = 1 << 20;
+
+/** 落盘并保持日志不超过 1 MiB（与 think-anchor 同口径）：超限保留尾部整行，末行始终是完整 JSON。 */
+export function appendRow(row: Record<string, unknown>): void {
+  try {
+    appendFileSync(LOG, JSON.stringify(row) + "\n");
+    if (statSync(LOG).size > MAX_LOG) {
+      const keep = readFileSync(LOG, "utf8").slice(-MAX_LOG);
+      const cut = keep.indexOf("\n");
+      writeFileSync(LOG, cut >= 0 ? keep.slice(cut + 1) : keep);
+    }
+  } catch { /* 静默：计量不该影响会话 */ }
+}
+
+export { sidOf, recentRows };
+
+// 预计声明：`预计 ~Ns` / `预计 2m` / `ETA 90s`。单位 m 带 (?!s) 以免把 ms 读成分钟。
+const EST_RE = /(?:预计|预估|eta)[^0-9\n]{0,8}(\d+(?:\.\d+)?)\s*(秒|s(?!\w)|分钟|min|m(?!s))/i;
+
+/** 从我的回复文本里解析预计耗时（秒）；无声明或非法值返回 null。 */
+function parseEstimate(text: string): number | null {
+  try {
+    // 扫**尾部窗口**：声明写在回复末尾；前 6000 字符从未覆盖到它（实测 est 填充率仅 1.5%）
+    // 取最后一个匹配 = 末尾的声明（同时谈格式时，正文中部的不算，因窗口在尾部）
+    const m = [...text.slice(-15000).matchAll(new RegExp(EST_RE.source, "gi"))].pop();
+    if (!m) return null;
+    const n = parseFloat(m[1]);
+    if (!isFinite(n) || n <= 0) return null;
+    const u = m[2].toLowerCase();
+    const secs = u === "秒" || u.startsWith("s") ? n : n * 60;
+    return Math.round(Math.min(secs, 7200));
+  } catch { return null; }
+}
+
+/** 取消息里的纯文本（content 可为字符串或分片数组；其它形态返回空串）。 */
+function textOf(msg: unknown): string {
+  try {
+    const c = (msg as { content?: unknown } | null | undefined)?.content;
+    if (typeof c === "string") return c;
+    if (Array.isArray(c)) return c.map((p) => (p && typeof (p as { text?: unknown }).text === "string" ? String((p as { text: string }).text) : "")).join("\n");
+    return "";
+  } catch { return ""; }
+}
+// 上一轮缓存命中率（%）：数字走对话尾部（同其它动态值），不写 system。
+let lastTurnHit: number | null = null;
+let lastTurnEstCalls: number | null = null;
+
+/** 回灌给模型的统计行：计数 + 计时（预计 vs 实际）+ 基线 + 判定；校正指引直给倍数。 */
+function statsLine(th: number, med: number, rows: Row[]): string {
+  const last = lastTurnCalls;
+  if (last < 0) return `PTC 计量：尚无完成轮次。阈值 ${th} 次/轮；本轮开工前先报「预计 N 次」；判据 = 本轮计数不超阈值，且无同类调用可并（机制只数调用，可并性须人工复核）。`;
+  const secs = lastTurnMs >= 0 ? Math.round(lastTurnMs / 1000) : null;
+  const parts: string[] = [`上一轮 ${last} 次工具调用`];
+  if (secs !== null) {
+    parts.push(`实际 ${secs}s`);
+    if (lastTurnHit !== null) parts.push(`命中 ${lastTurnHit}%${lastTurnHit < 90 ? "（低）" : ""}`);
+    if (lastTurnEstCalls !== null && lastTurnEstCalls > 0) {
+      const dc = Math.round(((last - lastTurnEstCalls) / lastTurnEstCalls) * 100);
+      parts.push(`预计 ${lastTurnEstCalls} 次 / 实际 ${last} 次（偏差 ${dc >= 0 ? "+" : ""}${dc}%）`);
+    }
+    if (lastTurnEst !== null) {
+      const dev = Math.round(((lastTurnMs / 1000 - lastTurnEst) / lastTurnEst) * 100);
+      parts.push(`预计 ${lastTurnEst}s / 实际 ${secs}s（偏差 ${dev >= 0 ? "+" : ""}${dev}%）`);
+    } else {
+      const base = Math.round(median(rows.map((r) => r.ms)) / 1000);
+      parts.push(base > 0 ? `预计未声明（同类中位 ${base}s）→ 本轮开工前先报「预计 N 次」` : "预计未声明 → 本轮开工前先报「预计 N 次」");
+    }
+  }
+  // 校正指引（回路自动纠偏）：近若干轮系统性偏离时，直接给出本轮该报的倍数——不靠自觉。
+  // 调用数校正：次数由任务类型决定，方差远小于时长——优先用它给指引。
+  try {
+    const ecRows = rows.filter((r) => typeof r.estCalls === "number" && (r.estCalls as number) > 0);
+    if (ecRows.length >= 3) {
+      const dcs = ecRows.map((r) => ((r.calls - (r.estCalls as number)) / (r.estCalls as number)) * 100);
+      const mdc = median(dcs);
+      if (mdc <= -20 || mdc >= 20) {
+        const f = Math.min(3, Math.max(0.2, Math.round((1 + mdc / 100) * 100) / 100)); // 夹在 0.2–3：极端中位（声明失真）不放大成荒谬倍数
+        parts.push(`近 ${ecRows.length} 轮调用数系统性${mdc < 0 ? "高估" : "低估"}（中位 ${mdc > 0 ? "+" : ""}${Math.round(mdc)}%）→ 本轮按约 ${f} 倍报`);
+      }
+    }
+  } catch { /* 静默 */ }
+  try {
+    const estRows = rows.filter((r) => typeof r.est === "number" && (r.est as number) > 0);
+    if (estRows.length >= 3) {
+      const devs = estRows.map((r) => ((r.ms / 1000) - (r.est as number)) / (r.est as number) * 100);
+      const md = median(devs);
+      if (md <= -20 || md >= 20) {
+        const factor = Math.min(3, Math.max(0.2, Math.round((1 + md / 100) * 100) / 100));
+        parts.push(`近 ${estRows.length} 轮耗时系统性${md < 0 ? "高估" : "低估"}（中位 ${md > 0 ? "+" : ""}${Math.round(md)}%）→ 本轮按约 ${factor} 倍报`);
+      }
+    }
+  } catch { /* 指引失败不影响统计行 */ }
+  const verdict = last >= th
+    ? `超阈值 ${th} · 判据 = 本轮计数不超阈值且无同类调用可并（可并性人工复核）`
+    : `阈值 ${th} · 判据 = 本轮计数不超阈值且无同类调用可并`;
+  return `PTC 计量：${parts.join(" · ")} · 会话中位 ${med} · ${verdict}`;
+}
+
+/** 在给定文本后追加统计段（rows 由调用方读好，避免同一命令重复读文件）。 */
+function withStats(text: string, rows: Row[], th: number): string {
+  if (!rows.length) return text + "\nPTC: 暂无已完成轮次。";
+  const cs = rows.map((r) => r.calls);
+  const over = cs.filter((x) => x >= th).length;
+  const medS = Math.round(median(rows.map((r) => r.ms)) / 1000);
+  const withEst = rows.filter((r) => typeof r.est === "number" && r.est > 0);
+  const dev = withEst.map((r) => Math.round((((r.ms / 1000) - (r.est as number)) / (r.est as number)) * 100));
+  const devLine = dev.length ? ` · 估算偏差(实际-预计) ${dev.slice(-5).join("/")}%` : "";
+  return text + `\nPTC 最近 ${rows.length} 轮: 中位 ${median(cs)} 次 · p90 ${percentile(cs, 90)} · 最高 ${Math.max(...cs)} · 超标(>=${th}) ${over} 轮 · 耗时中位 ${medS}s${devLine}`;
+}
+
+export default function ptcMeter(pi: ExtensionAPI) {
+  pi.on("session_start", () => {
+    // 进程内新会话：模块级计量归零，避免把上一会话的 turns/calls 当作「上轮」
+    callsThisTurn = 0;
+    lastCompletedCalls = -1;
+    injectedThisTurn = false;
+    lastTurnCalls = -1;
+    lastTurnMs = -1;
+    lastTurnEst = null;
+    lastTurnEstCalls = null;
+    lastTurnHit = null;
+    turns = 0;
+    turnStartedAt = Date.now();
+  });
+  // 计数：不读 event 字段、不返回任何值 —— 这是最安全的形态（该层无 try/catch）。
+  pi.on("tool_call", async () => {
+    try { callsThisTurn++; } catch { /* 静默：计量不该影响调用 */ }
+    return undefined;
+  });
+
+  // 捕获：turn_end 只更新时序/用量（**不重置** calls —— 重置在 before_agent_start，避免双重置丢计数）
+  // 捕获：turn_end 每条 assistant 消息触发一次（pi agent-loop）：只更新时序/用量证据，不落盘、不计轮。
+  pi.on("turn_end", async (_event) => {
+    try {
+      lastTurnMs = Date.now() - turnStartedAt;
+      // 量纲一致：est 取本轮**首次**声明（开工前），ms 是整轮；中途覆盖会让偏差失真
+      { const e = parseEstimate(textOf((_event as unknown as { message?: unknown })?.message)); if (e !== null && lastTurnEst === null) lastTurnEst = e; }
+      try {
+        const u = (_event as unknown as { message?: { usage?: Record<string, unknown> } })?.message?.usage;
+        if (u) {
+          const i = Number(u.input) || 0, cr = Number(u.cacheRead) || 0, cw = Number(u.cacheWrite) || 0;
+          const den = i + cr + cw;
+          lastTurnHit = den > 0 ? Math.round((cr / den) * 1000) / 10 : null;
+        }
+      } catch { lastTurnHit = null; }
+      try {
+        const t2 = textOf((_event as unknown as { message?: unknown })?.message);
+        const em = [...t2.slice(-15000).matchAll(/预计[^0-9\n]{0,8}(\d+)\s*次/g)].pop();
+        const ec = em ? parseInt(em[1], 10) : 0;
+        if (ec > 0 && lastTurnEstCalls === null) lastTurnEstCalls = ec; // 同上：首个声明
+      } catch { lastTurnEstCalls = null; }
+    } catch { /* 静默 */ }
+  });
+
+  // 落盘：每用户请求（run）一次；用 turn_end 计轮会把一轮记成多次。
+  pi.on("agent_end", async (event, ctx: ExtensionContext) => {
+    try {
+      // 扩展事件没有 willRetry 字段；error 轮不落盘且其 calls 不计入下一轮；aborted 与正常轮同路径（整 run 计时，无半轮逻辑）
+      const msgs = (event as unknown as { messages?: Array<{ role?: string; stopReason?: string }> }).messages ?? [];
+      const lastA = [...msgs].reverse().find((m) => m.role === "assistant");
+      if (lastA?.stopReason === "error") { callsThisTurn = 0; return; }
+      const th = threshold();
+      const calls = callsThisTurn;
+      const ms = Date.now() - turnStartedAt;
+      turns++;
+      appendRow({ ts: new Date().toISOString(), turn: turns, calls, ms, est: lastTurnEst, estCalls: lastTurnEstCalls, sid: sidOf(ctx) });
+      // 落盘即封存本轮计数并重置：GOAL / 自动续轮场景下 before_agent_start 可能缺席，避免跨轮累计（2026-10-17 实证：317 次 = 多轮累计）。
+      lastCompletedCalls = calls;
+      callsThisTurn = 0;
+      turnStartedAt = Date.now();
+      // D16：自动续轮下 before_agent_start 可能缺席——本轮未注入过则补发一次尾部回灌，保证反馈不断链（2026-10-17 实证：本轮无任何回灌行）。
+      if (!injectedThisTurn && loadConf().inject !== false) {
+        lastTurnCalls = calls;
+        lastTurnMs = ms;
+        try {
+          const rows = recentRows(TAIL, sidOf(ctx));
+          const line = statsLine(threshold(), median(rows.map((r) => r.calls)), rows);
+          (pi as unknown as { sendMessage?: (m: unknown, o?: unknown) => void }).sendMessage?.(
+            { customType: SECTION_KEY, content: line, display: false },
+            { deliverAs: "nextTurn" },
+          );
+        } catch { /* 静默 */ }
+        lastTurnEst = null;
+        lastTurnEstCalls = null;
+        lastTurnHit = null;
+      }
+      injectedThisTurn = false;
+      // 弹窗默认关（用户指令：弹窗太频繁）。反馈走 section 注入那条路——我读得到，用户不被打扰。
+      if (calls >= th && loadConf().notify === true) {
+        ctx.ui.notify(`PTC: 本轮 ${calls} 次工具调用（中位 ${median(recentRows(TAIL, sidOf(ctx)).map((r) => r.calls))}，阈值 ${th}）—— 是否本可合并？`, "warning");
+      }
+    } catch { /* 静默 */ }
+  });
+
+  // 回路：结算上一轮 → **静态骨架**写 system section、**动态数字**投对话尾部消息。
+  // 为什么这么拆（本机实测）：system 在对话之前，system 里任一个字节变化都会让其后整段
+  // 前缀缓存失效 —— 数字留在 system 时每轮首请求只命中 ~1.3 万 token、丢 12 万，
+  // 87 次低命中吃掉 47% 会话成本（$3.48/$7.38；低命中请求总价约为命中态的 12 倍，miss 单价 = 命中 ×50）；
+  // 数字移到对话尾部后 system 永久字节稳定，前缀命中恢复。
+  pi.on("before_agent_start", async (event, ctx: ExtensionContext) => {
+    try {
+      lastTurnCalls = lastCompletedCalls >= 0 ? lastCompletedCalls : turns > 0 ? callsThisTurn : -1; // 首轮尚无完成记录：保持「无历史」，不误报 0
+      callsThisTurn = 0;
+      turnStartedAt = Date.now();
+      const c = loadConf();
+      if (c.inject === false) { lastTurnEst = null; lastTurnEstCalls = null; lastTurnHit = null; return undefined; }
+      const rows = recentRows(TAIL, sidOf(ctx));
+      const line = statsLine(threshold(), median(rows.map((r) => r.calls)), rows);
+      const sections = (event as unknown as { systemPromptOptions?: { sections?: Record<string, string> } })
+        .systemPromptOptions?.sections;
+      if (sections) sections[SECTION_KEY] = SECTION_STATIC; // 静态：每轮字节相同，零缓存成本
+      // 动态：对话尾部消息。deliverAs "nextTurn" = pi 在本轮构造 messages 时消费，
+      // 位置紧跟 user 消息之后（agent-session: Inject pending nextTurn messages）。
+      (pi as unknown as { sendMessage?: (m: unknown, o?: unknown) => void }).sendMessage?.(
+        { customType: SECTION_KEY, content: line, display: false },
+        { deliverAs: "nextTurn" },
+      );
+      injectedThisTurn = true;
+      lastTurnEst = null;
+      lastTurnEstCalls = null;
+      lastTurnHit = null;
+    } catch { /* 静默 */ }
+    return undefined; // 永不返回 systemPrompt（覆盖式替换会丢弃其它 section 的修改）
+  });
+
+  pi.registerCommand("ptc", {
+    description: "PTC 计量：最近若干轮的工具调用数、中位数与超标轮次",
+    handler: async (args: string, ctx: ExtensionContext) => {
+      try {
+        const n = Math.max(1, Math.min(200, parseInt((args || "20").trim(), 10) || 20));
+        const rows = recentRows(n, sidOf(ctx));
+        const c = loadConf();
+        const th = threshold();
+        const cs = rows.map((r) => r.calls);
+        const over = cs.filter((x) => x >= th).length;
+        const mostlyOver = cs.length > 0 && over > cs.length / 2;
+        const start = Math.max(0, rows.length - 8);
+        const head = rows.slice(-8).map((r, i) => `  #${start + i + 1} ${r.calls} 次 · ${Math.round(r.ms / 1000)}s${r.est !== null ? ` / 预计 ${r.est}s` : ""}`).join("\n");
+        const status = `PTC 状态\n  阈值 ${th} · inject ${c.inject !== false ? "on" : "off"} · notify ${c.notify === true ? "on" : "off"}\n  本会话完成 ${turns} 轮\n最近几轮:\n${head}`;
+        ctx.ui.notify(withStats(status, rows, th), mostlyOver ? "warning" : "info");
+      } catch (e) { ctx.ui.notify("PTC: " + (e as Error).message, "error"); }
+    },
+  });
+}

package/package.json

@@ -1,6 +1,26 @@
 {
   "name": "pi-ptc-meter",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Measures tool-call batching per turn and feeds the numbers back to the model.",
+  "type": "module",
+  "license": "MIT",
+  "keywords": [
+    "pi",
+    "pi-extension",
+    "pi-coding-agent"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "files": [
+    "index.ts",
+    "README.md",
+    "README.en.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  }
+}