dsh-boost 0.1.2 → 0.1.3
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.
- package/README.en.md +65 -39
- package/README.md +50 -35
- package/dist/admission/usage.js +41 -7
- package/dist/admission/usage.js.map +1 -1
- package/dist/hooks/llm-stream.js +103 -4
- package/dist/hooks/llm-stream.js.map +1 -1
- package/dist/hooks/post-execute.js +102 -18
- package/dist/hooks/post-execute.js.map +1 -1
- package/dist/index.js +230 -5
- package/dist/index.js.map +1 -1
- package/dist/tools/boost.js +82 -2
- package/dist/tools/boost.js.map +1 -1
- package/package.json +2 -2
package/README.en.md
CHANGED
|
@@ -11,7 +11,7 @@ read-only substitution**.
|
|
|
11
11
|
## What it does
|
|
12
12
|
|
|
13
13
|
DSH replays the whole history on every model request. Across the 300 longest sessions measured
|
|
14
|
-
locally (`npm run --silent stats` — without `--silent`, npm prints its `> dsh-boost@0.1.
|
|
14
|
+
locally (`npm run --silent stats` — without `--silent`, npm prints its `> dsh-boost@0.1.2 stats`
|
|
15
15
|
banner to stdout, so use `--silent` or `node scripts/session-stats.mjs` for machine-readable
|
|
16
16
|
output; snapshot at `2026-11-19T03:13:21Z`): 54,141 steps and 54,088 requests,
|
|
17
17
|
10,575,904,022 raw tokens in total. The mean is 195,340 tokens per step and 195,531 per request
|
|
@@ -50,11 +50,14 @@ The **ex-ante estimate** for v1 is **3.5% (lower bound) to 10.0% (ideal upper bo
|
|
|
50
50
|
300-session corpus, and its substitution component (2.70%) is a **ceiling** that must not be
|
|
51
51
|
counted as a floor. The honest net floor is about **0.4%** (projection gross ~0.8% minus ~0.4%
|
|
52
52
|
fixed per-request overhead). It is not a guarantee, and not a figure the shipped
|
|
53
|
-
`session-snapshot.json` can recompute
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
53
|
+
`session-snapshot.json` can recompute: the snapshot stores per-session aggregates plus each
|
|
54
|
+
session's `requestTokens` / `receiptChars` arrays, `valueTransfer` / `whitelist` counts, and
|
|
55
|
+
its per-family `toolChars` totals, but it has **no per-receipt family bytes** — the projection
|
|
56
|
+
components the estimate needs cannot be assembled from it, so **nothing in the deliverable can
|
|
57
|
+
recompute it**. Nor can the shadow week turn the range into a measured percentage: the shadow
|
|
58
|
+
report outputs four ratios only (see "Shadow week"), with no total-token denominator, and
|
|
59
|
+
`boost status` carries absolute values only; replacing the range with measurements needs a
|
|
60
|
+
denominator statistic that a later version must add.
|
|
58
61
|
|
|
59
62
|
## Requirements
|
|
60
63
|
|
|
@@ -77,28 +80,29 @@ replacing the range with measurements needs a denominator statistic that a later
|
|
|
77
80
|
directory:
|
|
78
81
|
|
|
79
82
|
```bash
|
|
80
|
-
# install from the registry: npmjs has latest = 0.1.
|
|
83
|
+
# install from the registry: npmjs has latest = 0.1.2 (this repository's
|
|
81
84
|
# .npmrc and lockfile are pinned to npmjs too — see below)
|
|
82
|
-
dsh plugin --profile <name> add dsh-boost@^0.1.
|
|
85
|
+
dsh plugin --profile <name> add dsh-boost@^0.1.2 --registry=https://registry.npmjs.org/
|
|
83
86
|
|
|
84
87
|
# or from a local checkout (build first; dist/ is not committed)
|
|
85
88
|
npm run build
|
|
86
89
|
dsh plugin --profile <name> add /absolute/path/to/dsh-boost
|
|
87
90
|
```
|
|
88
91
|
|
|
89
|
-
For the web profile: `dsh plugin --profile web add dsh-boost@^0.1.
|
|
92
|
+
For the web profile: `dsh plugin --profile web add dsh-boost@^0.1.2 --registry=https://registry.npmjs.org/`.
|
|
90
93
|
`dsh plugin` forwards the operation to pnpm, so pnpm must be on `PATH`.
|
|
91
94
|
|
|
92
|
-
> **
|
|
93
|
-
> `registry.npmjs.org`
|
|
94
|
-
> `0.0.0-stage`,
|
|
95
|
-
>
|
|
96
|
-
>
|
|
97
|
-
>
|
|
98
|
-
>
|
|
99
|
-
>
|
|
100
|
-
>
|
|
101
|
-
>
|
|
95
|
+
> **Both registries now carry 0.1.2, so `^0.1.2` is a safe pin.**
|
|
96
|
+
> `registry.npmjs.org` and `registry.npmmirror.com` each have four version records: `0.1.2` (the
|
|
97
|
+
> current `latest` on both), `0.1.1`, `0.1.0`, and `0.0.0-stage`, the placeholder npm creates on a
|
|
98
|
+
> package's first publish — **do not install `0.0.0-stage`**; it is not a usable build. 0.1.2
|
|
99
|
+
> carries the scope-overwrite fix: corrupt JSON (including a non-object or an array) and an
|
|
100
|
+
> unrecognizable version are no longer silently overwritten with the default document. Use
|
|
101
|
+
> `dsh-boost@^0.1.2` (or `@latest`). This repository's `.npmrc` and lockfile are pinned to npmjs,
|
|
102
|
+
> but **your machine's global npm config** may still point at a mirror that has not synced 0.1.2:
|
|
103
|
+
> that is local configuration, not this repository's state. Pass
|
|
104
|
+
> `--registry=https://registry.npmjs.org/` explicitly when the registry matters; against a lagging
|
|
105
|
+
> mirror, `@^0.1.2` fails to resolve until the sync lands.
|
|
102
106
|
|
|
103
107
|
The package is ESM (`"type": "module"`) and the `.` entry of `exports` also maps `require` /
|
|
104
108
|
`default`: on Node >= 24.9, `require('dsh-boost')` loads the very same code as `import`. Nothing
|
|
@@ -131,8 +135,8 @@ equivalent. In the conversation, ask the agent to call it, for example:
|
|
|
131
135
|
> Call the boost tool with `{"cmd":"status"}` and show me the JSON.
|
|
132
136
|
|
|
133
137
|
The first `status` should answer `ok: true`, with `data.scope.workspaceIds` empty, `revision` `0`,
|
|
134
|
-
`shadow` `true`, `projection` `"shadow"`, and `counts` empty (
|
|
135
|
-
|
|
138
|
+
`shadow` `true`, `projection` `"shadow"`, and `counts` empty (only on a fresh receipt root — `scan()` reads every shard, so earlier out-of-scope
|
|
139
|
+
calls from other sessions in the same DSH home have already recorded `skip:no-scope`). The first `status` does
|
|
136
140
|
**not** report `ERR_SCOPE_READ_FAILED` merely because `scope.json` is missing: a missing file is
|
|
137
141
|
the clean default (`ENOENT` carries no degradation code, `src/scope/store.ts`); on a fresh root
|
|
138
142
|
with the host capabilities in place, `degraded` is simply an empty array. On the `status` read
|
|
@@ -184,7 +188,7 @@ After the write, call `status` again. A healthy result looks like this:
|
|
|
184
188
|
`"host"` because the token-meter service is present — the two are different things.
|
|
185
189
|
- `data.counts` usually starts empty — but **control calls count too**: while no workspace is
|
|
186
190
|
visible, `boost`'s own calls pass the same post-execute scope gate (there is no boost exemption
|
|
187
|
-
there; the exemption lives at tool registration), each recording one `skip:no-scope
|
|
191
|
+
there; the exemption lives at tool registration), each recording one `skip:no-scope` — except PTC inner calls (`exec.parent` set) and cancelled calls, which return before the scope gate and record nothing. It grows
|
|
188
192
|
after normal tool calls, for example with `projection-shadow` entries.
|
|
189
193
|
|
|
190
194
|
Excerpt (illustrative values; ledger fields omitted):
|
|
@@ -223,10 +227,12 @@ above a workspace is selected, so 778 is the true per-request cost there.
|
|
|
223
227
|
|
|
224
228
|
The design chose **shadow first**: record for a week — no synthesized turns, no skipped calls,
|
|
225
229
|
projection priced but never applied — then decide whether to project and substitute for real.
|
|
226
|
-
**"Changes nothing the model sees" would be false**:
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
+
**"Changes nothing the model sees" would be false**: the `boost` tool schema (399 tokens) is
|
|
231
|
+
registered whenever the plugin is assembled, and whenever a workspace is visible the protocol
|
|
232
|
+
section (379 tokens) is also injected into the system prompt — **778 per request** in the
|
|
233
|
+
recommended setup; a multi-candidate plan still makes a **real selector call** (a separate
|
|
234
|
+
auxiliary model request). The shadow week saves no tokens; it produces only the four ratios below.
|
|
235
|
+
Under `selected + []` the protocol section is empty and the fixed cost is still **399**.
|
|
230
236
|
|
|
231
237
|
Of those ratios, `saveableRatio`, `byFamily`, and `candidateRecall` can decide **whether the
|
|
232
238
|
substitution side is worth turning on**: how many substitution decisions the whitelist could
|
|
@@ -237,8 +243,12 @@ a normal release and does not gate on shadow-week savings — and that call was
|
|
|
237
243
|
period; they did not rule on whether shadow results should gate a release. They also **cannot measure savings**: the report has no total-token denominator, and
|
|
238
244
|
`retrievalUpperBound` is structurally `0` during the shadow week (it only counts applied
|
|
239
245
|
`projection:'on'` retrievals), so it cannot even bound projection's retrieval damage. Projection
|
|
240
|
-
is released on the visibility contract (the original stays retrievable through the footer)
|
|
241
|
-
post-hoc detection
|
|
246
|
+
is released on the visibility contract alone (the original stays retrievable through the footer),
|
|
247
|
+
not on shadow labels — and **not on post-hoc detection**: v1 has no mis-truncation detector.
|
|
248
|
+
`src/admission/retrieval.ts` only counts exact-locator retrievals, and design §6.1 itself records
|
|
249
|
+
that the damage metric was never delivered and that retrieval counts are not a damage bound. The
|
|
250
|
+
only guard is that the model can retrieve the original; a retrieval being attempted is a signal,
|
|
251
|
+
not proof that nothing was wrongly cut.
|
|
242
252
|
`scope.json` has two independent switches:
|
|
243
253
|
|
|
244
254
|
| Switch | Value | Behaviour |
|
|
@@ -265,7 +275,8 @@ The recommended sequence:
|
|
|
265
275
|
(recall of the candidate set), and `retrievalUpperBound` (retrieval upper bound; structurally
|
|
266
276
|
`0` during the shadow week because nothing is projected for real).
|
|
267
277
|
3. **Turn on projection**: projection is not released on shadow labels (its basis is the
|
|
268
|
-
visibility contract
|
|
278
|
+
visibility contract — the original stays retrievable through the footer; v1 has no
|
|
279
|
+
mis-truncation detector); once the host spill backend is available, keep
|
|
269
280
|
`shadow: true` and set `projection` to `'on'`:
|
|
270
281
|
|
|
271
282
|
```json
|
|
@@ -431,12 +442,23 @@ in effect (the minimum over live sessions, falling back to `horizonSteps` when n
|
|
|
431
442
|
- `projection_unknown_families`: calls carrying an `mcp__` prefix that reached projection but
|
|
432
443
|
matched no tool family; `projection_unknown_tools` is the retained unmapped tool names with
|
|
433
444
|
counts (at most 32), for spotting mapper gaps.
|
|
434
|
-
- `hasWorkspaceRegistry`: whether the host
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
`
|
|
438
|
-
|
|
439
|
-
|
|
445
|
+
- `hasWorkspaceRegistry`: whether the host **provides** `workspaceRegistry` (also presence). The
|
|
446
|
+
production assembly always supplies the key, so it is **always boolean**: no service is `false` +
|
|
447
|
+
`ERR_HOST_NO_WORKSPACE_REGISTRY`; a service whose `list()` throws is `true` +
|
|
448
|
+
`ERR_HOST_WORKSPACE_REGISTRY_BROKEN`. Both leave every session invisible, but they are fixed
|
|
449
|
+
differently. The key is omitted only when `boost` is constructed directly with no host facts.
|
|
450
|
+
- `hasSpill`: whether the host **provides** a spill backend (presence, not usability). A missing
|
|
451
|
+
service is `false` + `ERR_HOST_NO_SPILL`; a service without `saveText` keeps it **`true`** and puts
|
|
452
|
+
`ERR_HOST_SPILL_UNUSABLE` in `degraded` — the capability fact lives in `degraded`, not in this boolean.
|
|
453
|
+
- `saved`: the camelCase ledger object kept for older consumers (`substitution` /
|
|
454
|
+
`substitutionAvoided` / `projectionGross` / `projectionNet` / `retrievals`), derived from the same
|
|
455
|
+
aggregation as the top-level snake_case fields. Legacy projection receipts (pre-T23b) without
|
|
456
|
+
`saved_projection_tokens` fall back to the receipt's own `saved` field.
|
|
457
|
+
**The two substitution numbers are a range, not the same quantity.** `substitution` takes the
|
|
458
|
+
input of the *next* real request after the skipped one — it includes the substituted call's own
|
|
459
|
+
result, so it is an **upper bound**. `substitutionAvoided` takes the planning request's
|
|
460
|
+
`input + cacheRead + output` — it excludes that result, so it is a **lower bound**. The true
|
|
461
|
+
saving lies between them.
|
|
440
462
|
|
|
441
463
|
With `projection: 'on'`, the complete original is written to the host spill backend **before** the
|
|
442
464
|
replacement happens, and the footer locator can be read with `read` / `grep`. Projection never
|
|
@@ -542,11 +564,15 @@ evidence" degraded path would be unreachable.
|
|
|
542
564
|
v1 ships **no tool that measures duplicate-call rate**: the "shadow-week duplication
|
|
543
565
|
statistic" the design reserved as its restart trigger was never delivered; `shadow-report.mjs`
|
|
544
566
|
does not produce it.
|
|
545
|
-
- **The shadow week saves
|
|
546
|
-
|
|
567
|
+
- **The shadow week saves no tokens**: it only records (the protocol section is still injected
|
|
568
|
+
and the selector is still called), and the recommended setup still costs 778 per request
|
|
569
|
+
(`selected + []` costs 399); its output is four ratios, not saved tokens.
|
|
547
570
|
- **v1 does not judge "better results"**: there is a token ledger and a **manual** 20-task
|
|
548
571
|
regression procedure (the task set does not ship with the package; see `docs/RELEASE.md` §3),
|
|
549
|
-
no quality metric; whether substituted outcomes are better is unjudgeable in v1.
|
|
572
|
+
no quality metric; whether substituted outcomes are better is unjudgeable in v1. The procedure
|
|
573
|
+
itself is not fully delivered either: neither the smoke runner (`test/regression/run.mjs`) nor
|
|
574
|
+
the same section's locator-retrieval integrity check exists, and `test/regression/` holds only
|
|
575
|
+
`.gitkeep` — so the "no data loss" invariant in its pass predicate is **unverified** in v1.
|
|
550
576
|
- **Projection is truncation, not refinement**: it keeps the head and tail and drops the middle;
|
|
551
577
|
the before/after token difference in the ledger measures *shorter*, not *more relevant*. The
|
|
552
578
|
dropped middle may be exactly what the next decision needs — with `projection: 'on'` the
|
|
@@ -582,7 +608,7 @@ The source and docs live in the repository at
|
|
|
582
608
|
| [Design](docs/superpowers/specs/2026-11-18-dsh-token-efficiency-design.md) | Goals, evidence, architecture, contracts, measurement, risks, release shape |
|
|
583
609
|
| [Host contracts appendix](docs/superpowers/plans/2026-11-18-host-contracts.md) | Interface reference copied line by line from the host sources |
|
|
584
610
|
| [Three-tier delegation research](docs/research/2026-11-18-three-tier-delegation.md) | 25 primary sources on caching, routing thresholds, compression, and verification |
|
|
585
|
-
| [Release acceptance](docs/RELEASE.md) | The one-command `npm run verify:package` acceptance, the zero-peerDependencies state and install spec, the degradation-code matrix, the 20-task regression procedure (manual; the task set
|
|
611
|
+
| [Release acceptance](docs/RELEASE.md) | The one-command `npm run verify:package` acceptance, the zero-peerDependencies state and install spec, the degradation-code matrix, the 20-task regression procedure (manual; the task set, runner, and locator-retrieval integrity check all remain undelivered), and the shadow week and stats recompute |
|
|
586
612
|
|
|
587
613
|
## License
|
|
588
614
|
|
package/README.md
CHANGED
|
@@ -8,7 +8,7 @@
|
|
|
8
8
|
## 它解决什么
|
|
9
9
|
|
|
10
10
|
DSH 每次模型请求都会回放全部历史。本机 300 个最长会话的实测聚合(`npm run --silent stats`——不带
|
|
11
|
-
`--silent` 时 npm 会把 `> dsh-boost@0.1.
|
|
11
|
+
`--silent` 时 npm 会把 `> dsh-boost@0.1.2 stats` 横幅打进 stdout,机器解析请用 `--silent` 或直接
|
|
12
12
|
`node scripts/session-stats.mjs`;快照时刻 `2026-11-19T03:13:21Z`):54,141 步、54,088 个请求,合计 10,575,904,022 raw token。按步均值
|
|
13
13
|
195,340 token,按请求均值 195,531、中位 187,681;97.01% 的输入是缓存读。工具回执是体积主体
|
|
14
14
|
(bash 61.75%、read 22.13%、ssh 10.01%),而下一步真正会用到的部分通常远小于回执本身。
|
|
@@ -36,7 +36,9 @@ v1 的**事前估算**区间是 **3.5%(下界)– 10.0%(理想上界)**
|
|
|
36
36
|
**3.5% 不是保底**——它是设计阶段对一个 300 会话语料做离线估算得到的下界,其中替换账的
|
|
37
37
|
2.70% 是**上限**,不能算进保底;诚实的净保底只有约 **0.4%**(投影侧毛额约 0.8% 减去每请求
|
|
38
38
|
固定开销约 0.4%)。这个区间不是保证,也不是从交付的 `session-snapshot.json` 能复算出来的
|
|
39
|
-
|
|
39
|
+
数字:快照按会话存了聚合计数,也存了每个会话的 `requestTokens` / `receiptChars` 数组、
|
|
40
|
+
`valueTransfer` / `whitelist` 计数,以及该会话按工具族归因的 `toolChars` 字符总量,但
|
|
41
|
+
**没有逐回执的族别字节**,估算所需的投影分项仍然凑不出来——交付物里**没有任何工具能复算它**。影子周也
|
|
40
42
|
**不能**把这个区间变成实测百分比:影子报告只输出四个比例(见「影子周」一节),没有总 token
|
|
41
43
|
分母,`boost status` 也只有绝对值;区间要被实测取代,得等后续版本补上分母统计。
|
|
42
44
|
|
|
@@ -58,26 +60,26 @@ v1 的**事前估算**区间是 **3.5%(下界)– 10.0%(理想上界)**
|
|
|
58
60
|
`dsh plugin` 要求指定 profile,剩下的参数原样转发给该 profile 目录里的 pnpm:
|
|
59
61
|
|
|
60
62
|
```bash
|
|
61
|
-
# 从 registry 安装:npmjs 上的 latest 是 0.1.
|
|
63
|
+
# 从 registry 安装:npmjs 上的 latest 是 0.1.2(本仓库 .npmrc 与 lockfile
|
|
62
64
|
# 也已钉在 npmjs,见下)
|
|
63
|
-
dsh plugin --profile <name> add dsh-boost@^0.1.
|
|
65
|
+
dsh plugin --profile <name> add dsh-boost@^0.1.2 --registry=https://registry.npmjs.org/
|
|
64
66
|
|
|
65
67
|
# 或从本地 checkout 安装(先构建;dist/ 不入库)
|
|
66
68
|
npm run build
|
|
67
69
|
dsh plugin --profile <name> add /absolute/path/to/dsh-boost
|
|
68
70
|
```
|
|
69
71
|
|
|
70
|
-
例如 web profile:`dsh plugin --profile web add dsh-boost@^0.1.
|
|
72
|
+
例如 web profile:`dsh plugin --profile web add dsh-boost@^0.1.2 --registry=https://registry.npmjs.org/`。
|
|
71
73
|
`dsh plugin` 把操作转发给 pnpm,所以 pnpm 必须在 PATH 上。
|
|
72
74
|
|
|
73
|
-
> **两个 registry
|
|
74
|
-
> `0.1.
|
|
75
|
-
> `
|
|
76
|
-
>
|
|
77
|
-
>
|
|
78
|
-
>
|
|
79
|
-
>
|
|
80
|
-
>
|
|
75
|
+
> **两个 registry 现在都到 0.1.2,`^0.1.2` 是安全的钉法。** `registry.npmjs.org` 与
|
|
76
|
+
> `registry.npmmirror.com` 各有四条版本记录:`0.1.2`(两边都是当前 `latest`)、`0.1.1`、
|
|
77
|
+
> `0.1.0`,以及首次发布时 npm 自动创建的占位版本 `0.0.0-stage`——**不要安装 `0.0.0-stage`**,
|
|
78
|
+
> 它不是可用构建。0.1.2 修掉了 scope 文件被静默覆盖的问题:坏 JSON(含非对象或数组)与
|
|
79
|
+
> 无法识别的版本不再被默认文档覆盖。请用 `dsh-boost@^0.1.2`(或 `@latest`)。本仓库已把 `.npmrc`
|
|
80
|
+
> 与 lockfile 钉在 npmjs,但**你机器上的全局 npm 配置**可能仍指向一个尚未同步 0.1.2 的镜像:
|
|
81
|
+
> 那是本机配置,不是本仓库的状态。在意 registry 时显式传
|
|
82
|
+
> `--registry=https://registry.npmjs.org/`;镜像滞后时,`@^0.1.2` 会在同步前解析失败。
|
|
81
83
|
|
|
82
84
|
包是 ESM(`"type": "module"`),`exports` 的 `.` 条目同时映射 `require` / `default`:Node ≥ 24.9
|
|
83
85
|
下 `require('dsh-boost')` 与 `import` 加载同一份代码,装好的包里**不做任何构建**(`files` 只带
|
|
@@ -97,7 +99,7 @@ bundle,patch 的 `insert` 行落在 profile root 上。**装完必须重启 DS
|
|
|
97
99
|
```
|
|
98
100
|
|
|
99
101
|
`workspaceIds` 为空时没有可见工作区:协议段不注入,投影与替换都原样放行,但每个工具调用
|
|
100
|
-
仍会记一条 `skip:no-scope`
|
|
102
|
+
仍会记一条 `skip:no-scope` 收据——但 PTC 内层调用(`exec.parent` 存在)与被取消的调用在 scope 门之前就返回,两条都不记。`boost` 工具本身是唯一的 scope 豁免,因此没有工作区时仍然
|
|
101
103
|
可以调用它来启用。
|
|
102
104
|
|
|
103
105
|
`boost` 是**模型工具,不是 shell 命令**——这个包没有 `bin`,启用全程都要在对话里让模型调用
|
|
@@ -106,8 +108,8 @@ bundle,patch 的 `insert` 行落在 profile root 上。**装完必须重启 DS
|
|
|
106
108
|
> 调用 boost 工具,参数 `{"cmd":"status"}`,把 JSON 结果给我。
|
|
107
109
|
|
|
108
110
|
首次 `status` 应看到 `ok: true`;`data.scope.workspaceIds` 为空、`revision` 为 `0`,`shadow` 为
|
|
109
|
-
`true`、`projection` 为 `"shadow"`,`counts`
|
|
110
|
-
|
|
111
|
+
`true`、`projection` 为 `"shadow"`,`counts` 为空(**仅限全新回执根**——`scan()` 读全部分片,同一 DSH home 里别的会话早先的
|
|
112
|
+
越界调用已经各记过一条 `skip:no-scope`)。首次 `status` 的 `degraded` 里**不会**因为 `scope.json`
|
|
111
113
|
缺失而出现 `ERR_SCOPE_READ_FAILED`:缺失是干净的默认值(`ENOENT` 不带降级码,
|
|
112
114
|
`src/scope/store.ts`);全新根目录且宿主能力齐全时,`degraded` 就是空数组。在 `status` 的
|
|
113
115
|
读取路径上,`ERR_SCOPE_READ_FAILED` 只表示文件**存在但读不出来**(权限、I/O、路径是目录
|
|
@@ -187,9 +189,10 @@ scope**:`boost` 工具 schema(399)只要插件装配就常驻——`boost`
|
|
|
187
189
|
## 影子周
|
|
188
190
|
|
|
189
191
|
设计选择**影子优先**:先用一周只记账(不合成回合、不跳过调用,投影只记账不改内容),再决定
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
192
|
+
是否真的投影与替换。**「什么都不改」并不成立**:`boost` 工具 schema(399 token)只要插件装配
|
|
193
|
+
就常驻;只要有可见工作区,协议段(379 token)还会注入系统提示——推荐配置下每请求固定成本
|
|
194
|
+
**778**;多候选计划仍会**真实调用一次选择器**(一次独立的辅助模型请求)。影子周不省任何
|
|
195
|
+
token,它只产出下一节的四个比例;`selected + []` 下协议段为空,固定成本仍有 **399**。
|
|
193
196
|
|
|
194
197
|
其中 `saveableRatio`、`byFamily`、`candidateRecall` 能决定的是**替换侧是否值得打开**:
|
|
195
198
|
白名单能兑现多少替换决策、命中落在哪些工具族、候选集召回多高——也就是替换打开后会不会
|
|
@@ -197,8 +200,10 @@ scope**:`boost` 工具 schema(399)只要插件装配就常驻——`boost`
|
|
|
197
200
|
门;这个决定是**实现者在设计阶段做的,不是用户裁决**——用户只接受了为期一周的影子期,没有
|
|
198
201
|
裁定影子结果是否该当发布门。它们也**不能测出节省**:报告没有总 token 分母,
|
|
199
202
|
`retrievalUpperBound` 在影子期结构性为 `0`(它只统计 `projection:'on'` 的已应用投影取回),
|
|
200
|
-
|
|
201
|
-
|
|
203
|
+
连投影的取回损害都约束不了。投影的放行依据只有可见性契约(原文可经页脚取回),不是影子
|
|
204
|
+
标签,也**不是事后检测**:v1 没有误截检测器——`src/admission/retrieval.ts` 只按精确 locator
|
|
205
|
+
统计取回次数,设计稿 §6.1 也写明损害度量未交付、取回计数不是损害上界。唯一的护栏是模型
|
|
206
|
+
能取回原文;而「发生过取回」只是信号,不是「没有误截」的证明。
|
|
202
207
|
`scope.json` 里有两个独立开关:
|
|
203
208
|
|
|
204
209
|
| 开关 | 取值 | 行为 |
|
|
@@ -220,8 +225,8 @@ scope**:`boost` 工具 schema(399)只要插件装配就常驻——`boost`
|
|
|
220
225
|
是每一次替换决策,不只是白名单调用;影子期全族记账,bash/ssh 的潜力看 `byFamily`)、`byFamily`(按候选工具族的命中率)、
|
|
221
226
|
`candidateRecall`(候选集召回)、`retrievalUpperBound`(取回率上界;影子期没有真正投影,
|
|
222
227
|
结构上恒为 `0`)。
|
|
223
|
-
3.
|
|
224
|
-
后端可用后,保持 `shadow: true`,把 `projection` 改成 `'on'`:
|
|
228
|
+
3. **打开投影**:投影的放行不靠影子标签(依据是可见性契约:原文可经页脚取回;v1 没有
|
|
229
|
+
误截检测器),确认宿主 spill 后端可用后,保持 `shadow: true`,把 `projection` 改成 `'on'`:
|
|
225
230
|
|
|
226
231
|
```json
|
|
227
232
|
{ "cmd": "scope-set", "body": { "projection": "on" }, "baseRevision": 1 }
|
|
@@ -272,7 +277,7 @@ scope**:`boost` 工具 schema(399)只要插件装配就常驻——`boost`
|
|
|
272
277
|
不变量不是 `triggerChars ≥ headChars + tailChars + 1`。真实替换串是 head line + head + 页脚 +
|
|
273
278
|
tail + 3 个换行;页脚由宿主 `formatSpillNotice` 生成:68 字符 locator 加宿主固定的 66 字符
|
|
274
279
|
retrieval hint 下,3 位省略字节数是 190 字符,5 位是 192 字符。grep/glob 默认 400+100 时:
|
|
275
|
-
`400 + 100 + 50(head line) + 190(页脚) + 3 = 743 > 700`(5
|
|
280
|
+
`400 + 100 + 50(head line) + 190(页脚) + 3 = 743 > 700`(5 位计数时页脚 192、head line 里的数字也各长一位,实测 747–749)。于是刚过 700、
|
|
276
281
|
约 743 以下的回执会被 `truncate` 判定“可裁”,但 `projectApply` 组装后并不短于原文,直接返回
|
|
277
282
|
原文——这是死区,不是净亏。运行时的 `assembled.length >= text.length` 检查保证投影绝不会让
|
|
278
283
|
回执变长;要消除死区,把 `triggerChars` 提到至少这个和(例如 grep/glob 用 800),或缩小窗口。
|
|
@@ -366,11 +371,19 @@ horizon 重放,并计入 `projection_horizon_reestimated`;`projection_horizo
|
|
|
366
371
|
- `projection_unknown_families`:带 `mcp__` 前缀、进入投影阶段但没有匹配到工具族的调用数;
|
|
367
372
|
`projection_unknown_tools` 是其中保留的未映射工具名及次数(最多 32 个),用来发现 mapper
|
|
368
373
|
缺口。
|
|
369
|
-
- `hasWorkspaceRegistry
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
`
|
|
373
|
-
|
|
374
|
+
- `hasWorkspaceRegistry`:宿主是否**提供** `workspaceRegistry`(同样是存在性)。生产装配总是传入
|
|
375
|
+
这个键,所以它**总是布尔**:宿主没有该服务是 `false` + `ERR_HOST_NO_WORKSPACE_REGISTRY`;服务在但
|
|
376
|
+
`list()` 抛错是 `true` + `ERR_HOST_WORKSPACE_REGISTRY_BROKEN`——两种都让每个会话被判不可见,但
|
|
377
|
+
修法不同。只有直接构造 `boost` 依赖、完全不给宿主事实时该键才省略(测试场景)。
|
|
378
|
+
- `hasSpill`:宿主是否**提供** spill 后端(存在性,不是可用性)。服务缺失是 `false` +
|
|
379
|
+
`ERR_HOST_NO_SPILL`;服务在但不提供 `saveText` 时它**仍是 `true`**,同时 `degraded` 带
|
|
380
|
+
`ERR_HOST_SPILL_UNUSABLE`——能力事实在 `degraded` 里,不在这个布尔里。
|
|
381
|
+
- `saved`:兼容旧消费者的 camelCase 账目对象(`substitution` / `substitutionAvoided` /
|
|
382
|
+
`projectionGross` / `projectionNet` / `retrievals`),与顶层 snake_case 字段由同一次聚合派生。
|
|
383
|
+
旧投影收据(pre-T23b)没有 `saved_projection_tokens` 时,按收据里的 legacy `saved` 字段回退计价。
|
|
384
|
+
**两个替换数是一对区间,不是同一个量**:`substitution` 取被跳过请求的**下一**个真实请求的输入
|
|
385
|
+
(含被替换调用自己的结果,所以是**上界**);`substitutionAvoided` 取计划那一次请求的
|
|
386
|
+
`input + cacheRead + output`(不含被替换调用的结果,所以是**下界**)。真实节省落在两者之间。
|
|
374
387
|
|
|
375
388
|
`projection: 'on'` 时,完整原文在替换发生**之前**写入宿主的 spill 后端,页脚 locator 可以用
|
|
376
389
|
`read` / `grep` 取回。投影不会丢掉唯一副本;spill 写入失败就不替换(收据记
|
|
@@ -407,7 +420,7 @@ horizon 重放,并计入 `projection_horizon_reestimated`;`projection_horizo
|
|
|
407
420
|
|
|
408
421
|
## 宿主依赖
|
|
409
422
|
|
|
410
|
-
`inject` 是硬依赖:`tools`、`systemPrompt
|
|
423
|
+
`inject` 是硬依赖:`tools`、`systemPrompt`——缺任一,cordis 让插件停在 pending、不 apply(不是抛错,但对使用者而言效果相同:插件不工作)。`llm` 是软依赖(只有
|
|
411
424
|
选择器用),缺失时选择器以 `selector-unavailable` 退回,投影与替换的其余部分照常。
|
|
412
425
|
|
|
413
426
|
| 依赖 | 形态 | 缺失时 |
|
|
@@ -457,10 +470,12 @@ spill,报它只会制造噪音);但**收据通道**不看当前模式—
|
|
|
457
470
|
- **不去重、不合并工具调用**(设计 N5)——这条完全没开工,且 v1 **没有任何工具能测出重复
|
|
458
471
|
调用率**:设计稿里用来触发重启判定的「影子周重复率统计」没有交付,`shadow-report.mjs`
|
|
459
472
|
不产出它。
|
|
460
|
-
-
|
|
461
|
-
|
|
462
|
-
- **v1 不评判「结果更好」**:只有 token 账目和一套**人工**的 20
|
|
463
|
-
|
|
473
|
+
- **影子周不省 token**:只记账(协议段照注入、选择器照调用),推荐配置下每请求仍固定花
|
|
474
|
+
778(`selected + []` 为 399);它的产出是四个比例,不是省下的 token。
|
|
475
|
+
- **v1 不评判「结果更好」**:只有 token 账目和一套**人工**的 20 任务回退流程(任务集不随包发布,
|
|
476
|
+
见 `docs/RELEASE.md` §3),没有任何质量指标;「替换后结果质量」在 v1 是不可判的。这套流程
|
|
477
|
+
本身也没交付完整:冒烟 runner(`test/regression/run.mjs`)与同一节的取回完整性检查都未实现,
|
|
478
|
+
`test/regression/` 只有 `.gitkeep`,因此 pass 谓词里的「无数据丢失」不变量在 v1 **未经核实**。
|
|
464
479
|
- **投影是截断,不是精炼**:它保留头尾、丢掉中段;账本里的 before/after token 差量的是
|
|
465
480
|
「变短」,不是「变相关」。被丢掉的中段可能正是下一步决策要用的内容——`projection: 'on'`
|
|
466
481
|
下原文可经页脚 locator 取回,但取回要花一次工具调用,且 v1 没有指标区分「精炼」与
|
|
@@ -490,7 +505,7 @@ spill,报它只会制造噪音);但**收据通道**不看当前模式—
|
|
|
490
505
|
| [设计稿](docs/superpowers/specs/2026-11-18-dsh-token-efficiency-design.md) | 目标、证据、架构、契约、度量、风险、发布形态 |
|
|
491
506
|
| [宿主契约附录](docs/superpowers/plans/2026-11-18-host-contracts.md) | 逐条抄自宿主源码的接口准绳 |
|
|
492
507
|
| [三层委派研究](docs/research/2026-11-18-three-tier-delegation.md) | 缓存、路由阈值、压缩、校验的 25 条一手来源 |
|
|
493
|
-
| [发布验收](docs/RELEASE.md) | `npm run verify:package` 一条命令验收、零 peerDependencies 现状与安装规格、降级码矩阵、20
|
|
508
|
+
| [发布验收](docs/RELEASE.md) | `npm run verify:package` 一条命令验收、零 peerDependencies 现状与安装规格、降级码矩阵、20 任务回退流程(人工;任务集、runner 与取回完整性检查均未交付)、影子周与统计复算 |
|
|
494
509
|
|
|
495
510
|
## 许可证
|
|
496
511
|
|
package/dist/admission/usage.js
CHANGED
|
@@ -9,6 +9,14 @@
|
|
|
9
9
|
* next request is `'unknown'`; an interpolated number would be indistinguishable
|
|
10
10
|
* from a measurement once written to a receipt.
|
|
11
11
|
*
|
|
12
|
+
* That next request is not the avoided request: it also carries the executed
|
|
13
|
+
* call and its result, which the avoided request would not have seen. So
|
|
14
|
+
* `saved_input_tokens` is an **upper** estimate. `settle()` therefore also
|
|
15
|
+
* reports `avoided_total_tokens = before.input + before.cacheRead +
|
|
16
|
+
* before.output` — the whole request that produced the plan, which the avoided
|
|
17
|
+
* request would have carried (plus the plan) — as a **lower** estimate. Each
|
|
18
|
+
* side is `'unknown'` from its own sample, never a copy of the other's.
|
|
19
|
+
*
|
|
12
20
|
* The ledger keeps two request slots plus a mark: `latest`, the first request
|
|
13
21
|
* after the mark, and the mark itself — which holds the request that preceded
|
|
14
22
|
* it and the candidate id. No whole-history table (YAGNI). Pure arithmetic: no
|
|
@@ -91,12 +99,25 @@ export class UsageLedger {
|
|
|
91
99
|
/**
|
|
92
100
|
* Consume the mark and report the substitution's measured cost.
|
|
93
101
|
*
|
|
94
|
-
*
|
|
95
|
-
*
|
|
96
|
-
*
|
|
97
|
-
*
|
|
98
|
-
*
|
|
99
|
-
*
|
|
102
|
+
* Two estimates of the avoided request, from the same pair of samples:
|
|
103
|
+
*
|
|
104
|
+
* - `saved_input_tokens` is the first after-mark request's `input +
|
|
105
|
+
* cacheRead`. That request is the next real one, so its input also carries
|
|
106
|
+
* the executed call and its result — tokens the avoided request would never
|
|
107
|
+
* have seen. It is therefore the **upper** estimate of the avoided input,
|
|
108
|
+
* and the plugin's headline number.
|
|
109
|
+
* - `avoided_total_tokens` is the pre-mark request's `input + cacheRead +
|
|
110
|
+
* output`: the whole request that produced the plan. The avoided request
|
|
111
|
+
* would have carried that request's context plus the plan, so this is a
|
|
112
|
+
* **lower** estimate of the avoided total. It includes output, hence
|
|
113
|
+
* "total", never "input".
|
|
114
|
+
*
|
|
115
|
+
* Each side is `'unknown'` when its own sample is missing or unusable —
|
|
116
|
+
* never a copy of the other request's numbers. `output_tokens` is the
|
|
117
|
+
* after-mark request's `output`, a third count never folded into either
|
|
118
|
+
* estimate. `cache_hit_delta` is the after-mark hit rate minus the pre-mark
|
|
119
|
+
* hit rate, `null` when either side cannot be told (a `null` delta means
|
|
120
|
+
* "cannot tell", not zero).
|
|
100
121
|
*
|
|
101
122
|
* A second `settle()` has nothing left to consume and reports the same
|
|
102
123
|
* `'unknown'` / `null`.
|
|
@@ -108,14 +129,27 @@ export class UsageLedger {
|
|
|
108
129
|
this.beforeMark = undefined;
|
|
109
130
|
this.afterMark = undefined;
|
|
110
131
|
this.candidateId = undefined;
|
|
132
|
+
// The lower estimate depends only on the pre-mark sample: a settlement
|
|
133
|
+
// with no after-mark request still knows how much that request would have
|
|
134
|
+
// had to replay, and reporting it cannot overstate anything.
|
|
135
|
+
const avoided = before !== undefined && usable(before)
|
|
136
|
+
? before.input + before.cacheRead + before.output
|
|
137
|
+
: undefined;
|
|
138
|
+
const avoidedTotal = avoided !== undefined && Number.isFinite(avoided) ? avoided : 'unknown';
|
|
111
139
|
if (after === undefined || !usable(after)) {
|
|
112
|
-
return {
|
|
140
|
+
return {
|
|
141
|
+
saved_input_tokens: 'unknown',
|
|
142
|
+
avoided_total_tokens: avoidedTotal,
|
|
143
|
+
cache_hit_delta: null,
|
|
144
|
+
output_tokens: 'unknown',
|
|
145
|
+
};
|
|
113
146
|
}
|
|
114
147
|
const afterRate = hitRate(after);
|
|
115
148
|
const beforeRate = hitRate(before);
|
|
116
149
|
const delta = afterRate !== null && beforeRate !== null ? afterRate - beforeRate : null;
|
|
117
150
|
return {
|
|
118
151
|
saved_input_tokens: after.input + after.cacheRead,
|
|
152
|
+
avoided_total_tokens: avoidedTotal,
|
|
119
153
|
cache_hit_delta: delta !== null && Number.isFinite(delta) ? delta : null,
|
|
120
154
|
output_tokens: after.output,
|
|
121
155
|
};
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"usage.js","sourceRoot":"","sources":["../../src/admission/usage.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Usage pairing: turn two consecutive model requests into the measured saving\n * of one substitution (design §5.3).\n *\n * When the plugin substitutes a call, the model is not asked for that step, so\n * the next real request replays a shorter history. The saving is therefore\n * measured as the size of that next request — `input + cacheRead`, because the\n * host reports `inputTokens` excluding cache reads — never estimated. A missing\n * next request is `'unknown'`; an interpolated number would be indistinguishable\n * from a measurement once written to a receipt.\n *\n * The ledger keeps two request slots plus a mark: `latest`, the first request\n * after the mark, and the mark itself — which holds the request that preceded\n * it and the candidate id. No whole-history table (YAGNI). Pure arithmetic: no\n * timers, no I/O, no host calls.\n *\n * @module dsh-boost/admission/usage\n */\n\n/** One model request's raw counts, mapped from the `llm/stream` usage chunk. */\nexport interface Usage {\n input: number\n cacheRead: number\n output: number\n}\n\n/**\n * A sample is usable only when all three counts are finite and non-negative\n * and their input total does not overflow. A negative or non-finite count is a\n * protocol violation, and any arithmetic on it would invent `NaN` or\n * `Infinity` — a bogus number no receipt reader could tell from a measurement.\n * An unusable after-mark sample makes the whole settlement unusable; an\n * unusable pre-mark sample only loses the delta.\n */\nfunction usable(u: Usage): boolean {\n return (\n [u.input, u.cacheRead, u.output].every((n) => Number.isFinite(n) && n >= 0) &&\n Number.isFinite(u.input + u.cacheRead)\n )\n}\n\n/**\n * Cache hit rate of one request, `cacheRead / (input + cacheRead)`. `null`\n * when the rate cannot be told: no sample, an unusable sample, or a\n * non-positive denominator. Both sides of the delta go through this one\n * helper so they cannot drift.\n */\nfunction hitRate(u: Usage | undefined): number | null {\n if (u === undefined || !usable(u)) return null\n const denominator = u.input + u.cacheRead\n if (denominator <= 0) return null\n const rate = u.cacheRead / denominator\n return Number.isFinite(rate) ? rate : null\n}\n\n/**\n * Pairs two consecutive model requests around one substitution.\n *\n * The pairing target is the FIRST request after the mark, never the latest:\n * when a caller forgets to settle, a later unrelated request must not be\n * attributed to the substitution. `settle()` consumes the mark and clears the\n * pairing slots; `last()` is a pure reader and survives it.\n */\nexport class UsageLedger {\n private latest: Usage | undefined\n private hasMark = false\n private beforeMark: Usage | undefined\n private afterMark: Usage | undefined\n private candidateId: string | undefined\n\n /**\n * Record one real request. The first request after a mark claims the pairing\n * slot and keeps it; later requests only advance `last()`.\n */\n request(u: Usage): void {\n this.latest = u\n if (this.hasMark && this.afterMark === undefined) this.afterMark = u\n }\n\n /** Most recent request, or `undefined` before the first one. Never consumes. */\n last(): Usage | undefined {\n return this.latest\n }\n\n /**\n * Record that a substitution just happened.\n *\n * `candidateId` is kept only so the caller can pair `settle()` with the right\n * substitution receipt (`pendingCandidateId()`); it never changes the\n * arithmetic. A new mark discards any unconsumed pairing and starts over from\n * the current latest request.\n */\n markSubstituted(candidateId: string): void {\n this.hasMark = true\n this.beforeMark = this.latest\n this.afterMark = undefined\n this.candidateId = candidateId\n }\n\n /** Id of the pending mark, or `undefined` before a mark and after `settle()`. */\n pendingCandidateId(): string | undefined {\n return this.candidateId\n }\n\n /**\n * Consume the mark and report the substitution's measured cost.\n *\n * `saved_input_tokens` is the first after-mark request's `input + cacheRead`;\n * `output_tokens` is that request's `output`, a third count that is never\n * folded into input. Both are `'unknown'` when no usable request arrived after\n * the mark — never a copy of the previous request's numbers. `cache_hit_delta`\n * is the after-mark hit rate minus the pre-mark hit rate, `null` when either\n * side cannot be told (a `null` delta means \"cannot tell\", not zero).\n *\n * A second `settle()` has nothing left to consume and reports the same\n * `'unknown'` / `null`.\n */\n settle(): {\n saved_input_tokens: number | 'unknown'\n cache_hit_delta: number | null\n output_tokens: number | 'unknown'\n } {\n const after = this.hasMark ? this.afterMark : undefined\n const before = this.hasMark ? this.beforeMark : undefined\n this.hasMark = false\n this.beforeMark = undefined\n this.afterMark = undefined\n this.candidateId = undefined\n\n if (after === undefined || !usable(after)) {\n return { saved_input_tokens: 'unknown', cache_hit_delta: null, output_tokens: 'unknown' }\n }\n\n const afterRate = hitRate(after)\n const beforeRate = hitRate(before)\n const delta = afterRate !== null && beforeRate !== null ? afterRate - beforeRate : null\n\n return {\n saved_input_tokens: after.input + after.cacheRead,\n cache_hit_delta: delta !== null && Number.isFinite(delta) ? delta : null,\n output_tokens: after.output,\n }\n }\n}"]}
|
|
1
|
+
{"version":3,"file":"usage.js","sourceRoot":"","sources":["../../src/admission/usage.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Usage pairing: turn two consecutive model requests into the measured saving\n * of one substitution (design §5.3).\n *\n * When the plugin substitutes a call, the model is not asked for that step, so\n * the next real request replays a shorter history. The saving is therefore\n * measured as the size of that next request — `input + cacheRead`, because the\n * host reports `inputTokens` excluding cache reads — never estimated. A missing\n * next request is `'unknown'`; an interpolated number would be indistinguishable\n * from a measurement once written to a receipt.\n *\n * That next request is not the avoided request: it also carries the executed\n * call and its result, which the avoided request would not have seen. So\n * `saved_input_tokens` is an **upper** estimate. `settle()` therefore also\n * reports `avoided_total_tokens = before.input + before.cacheRead +\n * before.output` — the whole request that produced the plan, which the avoided\n * request would have carried (plus the plan) — as a **lower** estimate. Each\n * side is `'unknown'` from its own sample, never a copy of the other's.\n *\n * The ledger keeps two request slots plus a mark: `latest`, the first request\n * after the mark, and the mark itself — which holds the request that preceded\n * it and the candidate id. No whole-history table (YAGNI). Pure arithmetic: no\n * timers, no I/O, no host calls.\n *\n * @module dsh-boost/admission/usage\n */\n\n/** One model request's raw counts, mapped from the `llm/stream` usage chunk. */\nexport interface Usage {\n input: number\n cacheRead: number\n output: number\n}\n\n/**\n * A sample is usable only when all three counts are finite and non-negative\n * and their input total does not overflow. A negative or non-finite count is a\n * protocol violation, and any arithmetic on it would invent `NaN` or\n * `Infinity` — a bogus number no receipt reader could tell from a measurement.\n * An unusable after-mark sample makes the whole settlement unusable; an\n * unusable pre-mark sample only loses the delta.\n */\nfunction usable(u: Usage): boolean {\n return (\n [u.input, u.cacheRead, u.output].every((n) => Number.isFinite(n) && n >= 0) &&\n Number.isFinite(u.input + u.cacheRead)\n )\n}\n\n/**\n * Cache hit rate of one request, `cacheRead / (input + cacheRead)`. `null`\n * when the rate cannot be told: no sample, an unusable sample, or a\n * non-positive denominator. Both sides of the delta go through this one\n * helper so they cannot drift.\n */\nfunction hitRate(u: Usage | undefined): number | null {\n if (u === undefined || !usable(u)) return null\n const denominator = u.input + u.cacheRead\n if (denominator <= 0) return null\n const rate = u.cacheRead / denominator\n return Number.isFinite(rate) ? rate : null\n}\n\n/**\n * Pairs two consecutive model requests around one substitution.\n *\n * The pairing target is the FIRST request after the mark, never the latest:\n * when a caller forgets to settle, a later unrelated request must not be\n * attributed to the substitution. `settle()` consumes the mark and clears the\n * pairing slots; `last()` is a pure reader and survives it.\n */\nexport class UsageLedger {\n private latest: Usage | undefined\n private hasMark = false\n private beforeMark: Usage | undefined\n private afterMark: Usage | undefined\n private candidateId: string | undefined\n\n /**\n * Record one real request. The first request after a mark claims the pairing\n * slot and keeps it; later requests only advance `last()`.\n */\n request(u: Usage): void {\n this.latest = u\n if (this.hasMark && this.afterMark === undefined) this.afterMark = u\n }\n\n /** Most recent request, or `undefined` before the first one. Never consumes. */\n last(): Usage | undefined {\n return this.latest\n }\n\n /**\n * Record that a substitution just happened.\n *\n * `candidateId` is kept only so the caller can pair `settle()` with the right\n * substitution receipt (`pendingCandidateId()`); it never changes the\n * arithmetic. A new mark discards any unconsumed pairing and starts over from\n * the current latest request.\n */\n markSubstituted(candidateId: string): void {\n this.hasMark = true\n this.beforeMark = this.latest\n this.afterMark = undefined\n this.candidateId = candidateId\n }\n\n /** Id of the pending mark, or `undefined` before a mark and after `settle()`. */\n pendingCandidateId(): string | undefined {\n return this.candidateId\n }\n\n /**\n * Consume the mark and report the substitution's measured cost.\n *\n * Two estimates of the avoided request, from the same pair of samples:\n *\n * - `saved_input_tokens` is the first after-mark request's `input +\n * cacheRead`. That request is the next real one, so its input also carries\n * the executed call and its result — tokens the avoided request would never\n * have seen. It is therefore the **upper** estimate of the avoided input,\n * and the plugin's headline number.\n * - `avoided_total_tokens` is the pre-mark request's `input + cacheRead +\n * output`: the whole request that produced the plan. The avoided request\n * would have carried that request's context plus the plan, so this is a\n * **lower** estimate of the avoided total. It includes output, hence\n * \"total\", never \"input\".\n *\n * Each side is `'unknown'` when its own sample is missing or unusable —\n * never a copy of the other request's numbers. `output_tokens` is the\n * after-mark request's `output`, a third count never folded into either\n * estimate. `cache_hit_delta` is the after-mark hit rate minus the pre-mark\n * hit rate, `null` when either side cannot be told (a `null` delta means\n * \"cannot tell\", not zero).\n *\n * A second `settle()` has nothing left to consume and reports the same\n * `'unknown'` / `null`.\n */\n settle(): {\n saved_input_tokens: number | 'unknown'\n avoided_total_tokens: number | 'unknown'\n cache_hit_delta: number | null\n output_tokens: number | 'unknown'\n } {\n const after = this.hasMark ? this.afterMark : undefined\n const before = this.hasMark ? this.beforeMark : undefined\n this.hasMark = false\n this.beforeMark = undefined\n this.afterMark = undefined\n this.candidateId = undefined\n\n // The lower estimate depends only on the pre-mark sample: a settlement\n // with no after-mark request still knows how much that request would have\n // had to replay, and reporting it cannot overstate anything.\n const avoided =\n before !== undefined && usable(before)\n ? before.input + before.cacheRead + before.output\n : undefined\n const avoidedTotal =\n avoided !== undefined && Number.isFinite(avoided) ? avoided : ('unknown' as const)\n\n if (after === undefined || !usable(after)) {\n return {\n saved_input_tokens: 'unknown',\n avoided_total_tokens: avoidedTotal,\n cache_hit_delta: null,\n output_tokens: 'unknown',\n }\n }\n\n const afterRate = hitRate(after)\n const beforeRate = hitRate(before)\n const delta = afterRate !== null && beforeRate !== null ? afterRate - beforeRate : null\n\n return {\n saved_input_tokens: after.input + after.cacheRead,\n avoided_total_tokens: avoidedTotal,\n cache_hit_delta: delta !== null && Number.isFinite(delta) ? delta : null,\n output_tokens: after.output,\n }\n }\n}"]}
|