pi-ptc-meter 1.0.12 → 1.0.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.en.md +18 -65
  2. package/README.md +57 -54
  3. package/package.json +1 -1
package/README.en.md CHANGED
@@ -1,86 +1,39 @@
1
- # pi-ptc-meter — per-turn tool-call metering and feedback (pi extension)
1
+ # pi-ptc-meter
2
2
 
3
- > Requires pi >= 0.74 · Node >= 20 · MIT · no runtime dependencies
4
-
5
- ## What it solves
6
-
7
- "One tool call = one round trip" is the biggest systematic waste in agent execution, and it is invisible. This extension turns call counts, duration and deviation into a number that appears every turn, and flags turns above the threshold for a merge review.
8
-
9
- ## Features
10
-
11
- - Tracks calls per turn, actual duration, and declared estimates.
12
- - Feeds back counts, duration, baseline median and deviation; flags over-threshold turns (default 39 calls/turn).
13
- - Numbers travel as trailing messages; the system section keeps a byte-stable skeleton.
14
- - Log `~/.pi/ptc-meter.jsonl`; command `/ptc [n]`.
3
+ Per-turn tool-call metering: counts calls and duration, then feeds the numbers back to the model.
15
4
 
16
5
  ## Install
17
6
 
18
7
  ```bash
19
8
  pi install npm:pi-ptc-meter
20
- pi install ./pi-ptc-meter
21
9
  ```
22
10
 
23
11
  ## Configuration
24
12
 
25
- ### 1 · Config file `~/.pi/ptc-meter.json`
26
-
27
- | Key | Type | Default | Description |
28
- | --- | --- | --- | --- |
29
- | `threshold` | number | `39` | Per-turn threshold, **39 calls/turn** (p75 calibration; 12 would fire on 62% of turns) |
30
- | `inject` | boolean | `true` | Enable feedback message |
31
- | `notify` | boolean | `false` | Use UI notifications instead of silent injection |
13
+ Config file `~/.pi/ptc-meter.json` (optional; invalid JSON falls back):
32
14
 
33
- ```json
34
- { "threshold": 39, "inject": true, "notify": false }
35
- ```
36
-
37
- ### 2 · Environment
15
+ | Key | Default | Description |
16
+ | --- | --- | --- |
17
+ | `threshold` | `39` | Per-turn call threshold (> 0) |
18
+ | `inject` | `true` | Enable the feedback message |
19
+ | `notify` | `false` | Use UI notifications instead |
38
20
 
39
- None.
21
+ Also: log `~/.pi/ptc-meter.jsonl` (1 MiB truncation, tail-preserving); no environment variables.
40
22
 
41
- ### 3 · Commands
23
+ ## Commands
42
24
 
43
25
  | Command | Purpose |
44
26
  | --- | --- |
45
- | `/ptc` / `/ptc <n>` | Last n turns: counts, duration, estimates, median, over-threshold |
46
-
47
- ### 4 · Log
48
-
49
- | Path | Content |
50
- | --- | --- |
51
- | `~/.pi/ptc-meter.jsonl` | turn, calls, duration, estimated calls/duration, session id; tail-preserving at 1 MiB |
52
-
53
- ## Where it acts (execution path, not thinking)
54
-
55
- | Stage | Does |
56
- | --- | --- |
57
- | `tool_call` | Increments the counter (counts only; never intercepts) |
58
- | `turn_end` | Records counts and duration (no disk write) |
59
- | `agent_end` | Writes one log line per run |
60
- | `session_start` | Resets module-level counters so a new session does not report the previous one |
61
-
62
- ## Feedback path
63
-
64
- | Item | Path | Why |
65
- | --- | --- | --- |
66
- | Previous calls / duration / deviation | Trailing message, `nextTurn`, `display:false` | Changing numbers in the system prompt invalidate the conversation's prefix cache |
67
- | `ptc_meter` section | Byte-identical skeleton only | Stable bytes keep the cache intact |
68
- | Baseline median / systematic bias | "recent N turns median +x% -> report ~k times" | An executable multiplier, not "be more precise" |
69
- | No estimate declared | Actual value + peer median | The mechanism must not depend on declarations |
70
-
71
- **Boundary**: it reports how many calls were used, not whether they could be merged.
72
-
73
- ## How it works
74
-
75
- - `tool_call` increments; `turn_end` records; the next `before_agent_start` settles and injects.
76
- - Estimates parse from reply text (`预计 Ns` / `预计 Nm` / `预计 N 次`), last match in a trailing window.
77
- - Counters reset on session change; history for the same sid is merged across restarts.
27
+ | `/ptc [n]` | Last n turns: counts, duration, estimates, median, over-threshold |
78
28
 
79
- ## Limitations
29
+ ## What it does (source facts)
80
30
 
81
- - Counts only; no mergeability judgement.
82
- - Never intercepts, rewrites input, or reads content.
83
- - Estimate parsing is heuristic; duration is wall-clock (includes waiting and network).
31
+ - `tool_call`: increments a counter (never intercepts or rewrites).
32
+ - `turn_end`: records calls and duration (no disk write).
33
+ - `agent_end`: writes one log line per run.
34
+ - `before_agent_start`: settles the previous turn and feeds back counts, duration, deviation and the baseline median as a `nextTurn` trailing message.
35
+ - `session_start`: resets module-level counters.
36
+ - The `ptc_meter` system section holds only a byte-stable skeleton.
84
37
 
85
38
  ## License
86
39
 
package/README.md CHANGED
@@ -1,87 +1,90 @@
1
- # pi-ptc-meter —— 每轮工具调用计量与回灌（pi 扩展）
1
+ # pi-ptc-meter
2
2
 
3
- > 适用 pi ≥ 0.74 · Node ≥ 20 · MIT · 无运行时依赖
3
+ > 中文 · [English](#english)（页面内折叠）
4
4
 
5
- ## 它解决什么问题
6
-
7
- 「一次工具调用 = 一次往返」是代理执行里最大的系统性浪费，却不可见。本扩展把每轮调用次数、耗时与偏差变成每轮都会出现的数字，并在超阈值时点明「这一轮有没有可合并的调用」。
8
-
9
- ## 功能
10
-
11
- - 统计每轮调用次数、实际耗时、开工前声明的预计次数 / 时长。
12
- - 回灌计数、耗时、基线中位与偏差；超阈值（默认 39 次/轮）时标注需复核。
13
- - 数字走对话尾部消息，system 只留逐字稳定的骨架（保护前缀缓存）。
14
- - 日志 `~/.pi/ptc-meter.jsonl`；命令 `/ptc [n]`。
5
+ 每轮工具调用计量：统计调用次数与耗时，并把数字回灌给模型。
15
6
 
16
7
  ## 安装
17
8
 
18
9
  ```bash
19
10
  pi install npm:pi-ptc-meter
20
- pi install ./pi-ptc-meter
21
11
  ```
22
12
 
23
13
  ## 配置
24
14
 
25
- ### 1 · 配置文件 `~/.pi/ptc-meter.json`
26
-
27
- | 键 | 类型 | 默认 | 说明 |
28
- | --- | --- | --- | --- |
29
- | `threshold` | number | `39` | 每轮调用数阈值 **39 次/轮**（> 0；p75 口径，12 会触发 62% 的轮次） |
30
- | `inject` | boolean | `true` | 是否注入回灌消息 |
31
- | `notify` | boolean | `false` | 改用弹窗提示（默认静默注入） |
32
-
33
- ```json
34
- { "threshold": 39, "inject": true, "notify": false }
35
- ```
15
+ 配置文件 `~/.pi/ptc-meter.json`（可省略；非法 JSON 回退默认）：
36
16
 
37
- ### 2 · 环境变量
17
+ | 键 | 默认 | 说明 |
18
+ | --- | --- | --- |
19
+ | `threshold` | `39` | 每轮调用数阈值 **39 次/轮**（> 0） |
20
+ | `inject` | `true` | 是否注入回灌消息 |
21
+ | `notify` | `false` | 改用弹窗提示 |
38
22
 
39
- 无（不读环境变量）。
23
+ 其他：日志 `~/.pi/ptc-meter.jsonl`（1 MiB 截断，保留尾部整行）；无环境变量。
40
24
 
41
- ### 3 · 命令
25
+ ## 命令
42
26
 
43
27
  | 命令 | 作用 |
44
28
  | --- | --- |
45
- | `/ptc` / `/ptc <n>` | 最近 n 轮：次数、时长、预计、中位、超标 |
29
+ | `/ptc [n]` | 最近 n 轮：次数、时长、预计、中位、超标 |
46
30
 
47
- ### 4 · 日志
31
+ ## 作用（源码事实）
48
32
 
49
- | 路径 | 内容 |
50
- | --- | --- |
51
- | `~/.pi/ptc-meter.jsonl` | 轮次、调用数、时长、预计次数、预计耗时、会话 id；超 1 MiB 保留尾部整行 |
33
+ - `tool_call`：计数 +1（不拦截、不改调用）。
34
+ - `turn_end`：记录本轮次数与耗时（不落盘）。
35
+ - `agent_end`：每 run 落盘一行日志。
36
+ - `before_agent_start`：结算上一轮并以 `nextTurn` 尾部消息回灌计数、耗时、偏差、基线中位。
37
+ - `session_start`：模块级计量归零。
38
+ - system 内 section `ptc_meter` 只含逐字不变的骨架。
39
+
40
+ ## License
52
41
 
53
- ## 作用点（执行通路，不碰 thinking）
42
+ MIT
54
43
 
55
- | 阶段 | 做什么 |
56
- | --- | --- |
57
- | `tool_call` | 计数 +1（只数，不拦截、不改调用） |
58
- | `turn_end` | 记录本轮次数与耗时（不落盘） |
59
- | `agent_end` | 每 run 落盘一行日志 |
60
- | `session_start` | 模块级计量归零（新会话不把上会话当作上一轮） |
44
+ ---
61
45
 
62
- ## 回灌（反馈回到模型的通路）
46
+ <a id="english"></a>
63
47
 
64
- | 项 | 通路 | 设计理由 |
48
+ <details>
49
+ <summary><b>English</b></summary>
50
+
51
+ Per-turn tool-call metering: counts calls and duration, then feeds the numbers back to the model.
52
+
53
+ ## Install
54
+
55
+ ```bash
56
+ pi install npm:pi-ptc-meter
57
+ ```
58
+
59
+ ## Configuration
60
+
61
+ Config file `~/.pi/ptc-meter.json` (optional; invalid JSON falls back):
62
+
63
+ | Key | Default | Description |
65
64
  | --- | --- | --- |
66
- | 上轮调用数 / 耗时 / 偏差 | 尾部消息，`nextTurn`，`display:false` | 变化数字进 system → 整段对话前缀缓存失效 |
67
- | `ptc_meter` section | 只放逐字不变的骨架（阈值口径 + 工程自问索引） | 字节稳定才不毁缓存 |
68
- | 基线中位 / 系统性偏差 | 附「近 N 轮中位 +x% → 本轮按约 k 倍报」 | 给可执行的倍数，而非抽象的「注意精度」 |
69
- | 未声明预计 | 只报实际 + 同类中位 | 机制不依赖模型是否声明 |
65
+ | `threshold` | `39` | Per-turn call threshold (> 0) |
66
+ | `inject` | `true` | Enable the feedback message |
67
+ | `notify` | `false` | Use UI notifications instead |
70
68
 
71
- **边界**：只报「上一轮用了多少次」，不判断调用是否真能合并——可并性需人工复核。
69
+ Also: log `~/.pi/ptc-meter.jsonl` (1 MiB truncation, tail-preserving); no environment variables.
72
70
 
73
- ## 机制
71
+ ## Commands
74
72
 
75
- - `tool_call` 计数 → `turn_end` 记录 → 下次 `before_agent_start` 结算注入。
76
- - 预计值从回复文本解析（`预计 Ns` / `预计 Nm` / `预计 N 次`），取尾部窗口最后一次匹配。
77
- - 会话切换后计数归零；同 sid 跨重启合并历史。
73
+ | Command | Purpose |
74
+ | --- | --- |
75
+ | `/ptc [n]` | Last n turns: counts, duration, estimates, median, over-threshold |
78
76
 
79
- ## 限制
77
+ ## What it does (source facts)
80
78
 
81
- - 只数次数，不判断可并性。
82
- - 不拦截、不改输入、不读对话内容。
83
- - 预计解析是文本启发式；耗时是墙钟时间（含等待与网络）。
79
+ - `tool_call`: increments a counter (never intercepts or rewrites).
80
+ - `turn_end`: records calls and duration (no disk write).
81
+ - `agent_end`: writes one log line per run.
82
+ - `before_agent_start`: settles the previous turn and feeds back counts, duration, deviation and the baseline median as a `nextTurn` trailing message.
83
+ - `session_start`: resets module-level counters.
84
+ - The `ptc_meter` system section holds only a byte-stable skeleton.
84
85
 
85
86
  ## License
86
87
 
87
88
  MIT
89
+
90
+ </details>
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pi-ptc-meter",
3
- "version": "1.0.12",
3
+ "version": "1.0.14",
4
4
  "description": "Measures tool-call batching per turn and feeds the numbers back to the model.",
5
5
  "type": "module",
6
6
  "license": "MIT",