dsh-boost 0.1.0 → 0.1.2
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 +184 -70
- package/README.md +148 -59
- package/dist/gate/decide.js +33 -2
- package/dist/gate/decide.js.map +1 -1
- package/dist/hooks/llm-stream.js +242 -89
- package/dist/hooks/llm-stream.js.map +1 -1
- package/dist/hooks/post-execute.js +282 -25
- package/dist/hooks/post-execute.js.map +1 -1
- package/dist/hooks/session-state.js +18 -8
- package/dist/hooks/session-state.js.map +1 -1
- package/dist/host/root.js +22 -1
- package/dist/host/root.js.map +1 -1
- package/dist/index.js +494 -72
- package/dist/index.js.map +1 -1
- package/dist/scope/doc.js.map +1 -1
- package/dist/scope/store.js +24 -9
- package/dist/scope/store.js.map +1 -1
- package/dist/tools/boost.js +37 -4
- package/dist/tools/boost.js.map +1 -1
- package/dist/types.d.ts +18 -1
- package/dist/types.js.map +1 -1
- package/package.json +10 -6
- package/dist/admission/fixed-cost.d.ts +0 -23
- package/dist/admission/ledger.d.ts +0 -113
- package/dist/admission/retrieval.d.ts +0 -65
- package/dist/admission/usage.d.ts +0 -75
- package/dist/config.d.ts +0 -43
- package/dist/gate/binding.d.ts +0 -113
- package/dist/gate/decide.d.ts +0 -82
- package/dist/gate/guard.d.ts +0 -69
- package/dist/gate/invalidate.d.ts +0 -112
- package/dist/gate/plan.d.ts +0 -86
- package/dist/hooks/clock.d.ts +0 -68
- package/dist/hooks/execute.d.ts +0 -79
- package/dist/hooks/llm-stream.d.ts +0 -276
- package/dist/hooks/pending.d.ts +0 -89
- package/dist/hooks/post-execute.d.ts +0 -247
- package/dist/hooks/session-state.d.ts +0 -158
- package/dist/hooks/synthesize.d.ts +0 -74
- package/dist/host/loader.d.ts +0 -23
- package/dist/host/platform.d.ts +0 -18
- package/dist/host/root.d.ts +0 -18
- package/dist/projection/apply.d.ts +0 -174
- package/dist/projection/canonicalise.d.ts +0 -43
- package/dist/projection/counters.d.ts +0 -65
- package/dist/projection/truncate.d.ts +0 -47
- package/dist/prompt/protocol.d.ts +0 -45
- package/dist/receipts/store.d.ts +0 -198
- package/dist/scope/doc.d.ts +0 -117
- package/dist/scope/resolve.d.ts +0 -91
- package/dist/scope/store.d.ts +0 -135
- package/dist/selector/jev.d.ts +0 -93
- package/dist/tools/boost.d.ts +0 -367
- package/dist/tools/family.d.ts +0 -26
package/README.en.md
CHANGED
|
@@ -4,12 +4,14 @@ Cut DeepSeek Harness (DSH) token usage with **tool-receipt projection** and **de
|
|
|
4
4
|
read-only substitution**.
|
|
5
5
|
|
|
6
6
|
> **Status: v1 is implemented.** Projection, substitution, and the control surface are all in
|
|
7
|
-
> place; `npm run build` is clean and the full test suite passes.
|
|
7
|
+
> place; `npm run build` is clean and the full test suite passes. The benefit range is an
|
|
8
|
+
> **ex-ante design estimate** (3.5% lower bound / 10.0% ideal upper bound; ~0.4% honest net
|
|
9
|
+
> floor); nothing in the deliverable can recompute it — see below.
|
|
8
10
|
|
|
9
11
|
## What it does
|
|
10
12
|
|
|
11
13
|
DSH replays the whole history on every model request. Across the 300 longest sessions measured
|
|
12
|
-
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.1 stats`
|
|
13
15
|
banner to stdout, so use `--silent` or `node scripts/session-stats.mjs` for machine-readable
|
|
14
16
|
output; snapshot at `2026-11-19T03:13:21Z`): 54,141 steps and 54,088 requests,
|
|
15
17
|
10,575,904,022 raw tokens in total. The mean is 195,340 tokens per step and 195,531 per request
|
|
@@ -22,28 +24,44 @@ The plugin does two things:
|
|
|
22
24
|
1. **Projection** — before a tool receipt enters the context, keep its head and tail per tool
|
|
23
25
|
family and replace the middle with a retrievable on-disk handle. The original stays readable;
|
|
24
26
|
the footer names the path. Projection is deterministic and makes no per-call decision.
|
|
25
|
-
2. **Substitution** — when a repeated read-only call (`read` / `grep` / `glob`) already
|
|
26
|
-
deterministic evidence satisfying its guard, commit it without asking the model for another
|
|
27
|
+
2. **Substitution** — when a repeated read-only call (`read` / `grep` / `glob`) in a plan already
|
|
28
|
+
has deterministic evidence satisfying its guard, commit it without asking the model for another
|
|
27
29
|
decision. With several candidates, a single-label selector — one auxiliary request
|
|
28
|
-
(`maxTokens` 512 plus its input) — picks one.
|
|
30
|
+
(`maxTokens` 512 plus its input) — picks one. This is a **narrowing** of original requirement
|
|
31
|
+
2.2: the request asked Jev to score each tool result and decide whether it could feed the next
|
|
32
|
+
tool; v1 only picks one of several candidates on the same receipt, with no per-result scoring
|
|
33
|
+
(see the 2.2 row and decision 9 in the
|
|
34
|
+
[clarification record](docs/superpowers/clarifications/2026-11-18-dsh-token-efficiency.md)).
|
|
35
|
+
For the three substituted tools, the plan's
|
|
29
36
|
`$public` argument binding (copying a value from an earlier receipt into a later call's
|
|
30
37
|
arguments) is effective in practice only for `glob`'s single-token output; `read` and `grep`
|
|
31
38
|
emit line-numbered or bare-path output that the identifier projection cannot match, so those
|
|
32
39
|
calls fall back to the model.
|
|
33
40
|
|
|
34
|
-
The
|
|
35
|
-
**
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
41
|
+
The multi-candidate selector **does not read a separate model configuration**: it reuses the
|
|
42
|
+
**boundary request's** `provider` / `model` / `reasoningEffort` (`rememberRoute` in
|
|
43
|
+
`src/index.ts`, fed mainly by `agent/pre-step`'s `modelSelection`, with the `agent/request`
|
|
44
|
+
resolution only as a fallback), so it is not necessarily a cheap model. To move it, either
|
|
45
|
+
change the model on the boundary session (the host routes per agent) or leave the plan with a
|
|
46
|
+
single candidate (one candidate never calls the selector).
|
|
47
|
+
|
|
48
|
+
The **ex-ante estimate** for v1 is **3.5% (lower bound) to 10.0% (ideal upper bound)** of raw
|
|
49
|
+
`totalTokens`; **3.5% is not a floor** — it is the lower bound of an offline estimate against a
|
|
50
|
+
300-session corpus, and its substitution component (2.70%) is a **ceiling** that must not be
|
|
51
|
+
counted as a floor. The honest net floor is about **0.4%** (projection gross ~0.8% minus ~0.4%
|
|
52
|
+
fixed per-request overhead). It is not a guarantee, and not a figure the shipped
|
|
53
|
+
`session-snapshot.json` can recompute (the snapshot stores aggregate counts only, not the
|
|
54
|
+
components of the estimate) — **nothing in the deliverable can recompute it**. Nor can the shadow
|
|
55
|
+
week turn the range into a measured percentage: the shadow report outputs four ratios only (see
|
|
56
|
+
"Shadow week"), with no total-token denominator, and `boost status` carries absolute values only;
|
|
57
|
+
replacing the range with measurements needs a denominator statistic that a later version must add.
|
|
42
58
|
|
|
43
59
|
## Requirements
|
|
44
60
|
|
|
45
|
-
- Node.js `>=24.9.0` and DSH
|
|
46
|
-
`
|
|
61
|
+
- Node.js `>=24.9.0` and DSH `>=0.2.2-rc.4 <0.2.3-0` (a **range**, not an exact pin: the host
|
|
62
|
+
evaluates it with `includePrerelease` semantics and disables the plugin on a miss, while
|
|
63
|
+
`0.2.2-rc.5` is byte-identical to rc.4 in every host package this plugin touches). Both live in
|
|
64
|
+
`package.json` `engines`; the Node floor matches the host `@deepseek-ai/dsh@0.2.2-rc.4`.
|
|
47
65
|
- **The package declares no peerDependencies**: installing it pulls in no `@deepseek-ai/*`
|
|
48
66
|
package, and the module loads without any of them; the runtime capabilities (`tokenMeter`,
|
|
49
67
|
`spillStore`, the estimator, the footer formatter) are provided by the DSH host process, and a
|
|
@@ -59,16 +77,28 @@ statistic that a later version must add.
|
|
|
59
77
|
directory:
|
|
60
78
|
|
|
61
79
|
```bash
|
|
62
|
-
# install from the registry
|
|
63
|
-
|
|
80
|
+
# install from the registry: npmjs has latest = 0.1.1 (this repository's
|
|
81
|
+
# .npmrc and lockfile are pinned to npmjs too — see below)
|
|
82
|
+
dsh plugin --profile <name> add dsh-boost@^0.1.1 --registry=https://registry.npmjs.org/
|
|
64
83
|
|
|
65
84
|
# or from a local checkout (build first; dist/ is not committed)
|
|
66
85
|
npm run build
|
|
67
86
|
dsh plugin --profile <name> add /absolute/path/to/dsh-boost
|
|
68
87
|
```
|
|
69
88
|
|
|
70
|
-
For the web profile: `dsh plugin --profile web add dsh-boost@^0.1.
|
|
71
|
-
to pnpm, so pnpm must be on `PATH`.
|
|
89
|
+
For the web profile: `dsh plugin --profile web add dsh-boost@^0.1.1 --registry=https://registry.npmjs.org/`.
|
|
90
|
+
`dsh plugin` forwards the operation to pnpm, so pnpm must be on `PATH`.
|
|
91
|
+
|
|
92
|
+
> **The two registries carry different versions, so `^0.1.0` is not a safe pin.**
|
|
93
|
+
> `registry.npmjs.org` has three version records: `0.1.1` (current `latest`), `0.1.0`, and
|
|
94
|
+
> `0.0.0-stage`, a placeholder npm creates on a package's first publish. The
|
|
95
|
+
> `registry.npmmirror.com` currently has only `0.1.0` (its `latest` is 0.1.0 too) — this
|
|
96
|
+
> repository's `.npmrc` and lockfile are pinned to npmjs, but your global npm config may not be.
|
|
97
|
+
> The same `^0.1.0` therefore resolves to 0.1.1 on npmjs and to 0.1.0 on
|
|
98
|
+
> the mirror — and a mirror user installs a build missing ten of 0.1.1's fixes, several of which
|
|
99
|
+
> repair silent failures. Use `dsh-boost@^0.1.1` (or `@latest`), and pass
|
|
100
|
+
> `--registry=https://registry.npmjs.org/` explicitly when the registry matters; while the mirror
|
|
101
|
+
> has not synced 0.1.1, `@^0.1.1` without that flag fails to resolve.
|
|
72
102
|
|
|
73
103
|
The package is ESM (`"type": "module"`) and the `.` entry of `exports` also maps `require` /
|
|
74
104
|
`default`: on Node >= 24.9, `require('dsh-boost')` loads the very same code as `import`. Nothing
|
|
@@ -102,9 +132,13 @@ equivalent. In the conversation, ask the agent to call it, for example:
|
|
|
102
132
|
|
|
103
133
|
The first `status` should answer `ok: true`, with `data.scope.workspaceIds` empty, `revision` `0`,
|
|
104
134
|
`shadow` `true`, `projection` `"shadow"`, and `counts` empty (in a fresh session — any earlier tool
|
|
105
|
-
call from an out-of-scope session has already recorded `skip:no-scope`). `
|
|
106
|
-
`ERR_SCOPE_READ_FAILED`
|
|
107
|
-
|
|
135
|
+
call from an out-of-scope session has already recorded `skip:no-scope`). The first `status` does
|
|
136
|
+
**not** report `ERR_SCOPE_READ_FAILED` merely because `scope.json` is missing: a missing file is
|
|
137
|
+
the clean default (`ENOENT` carries no degradation code, `src/scope/store.ts`); on a fresh root
|
|
138
|
+
with the host capabilities in place, `degraded` is simply an empty array. On the `status` read
|
|
139
|
+
path,
|
|
140
|
+
`ERR_SCOPE_READ_FAILED` means the file **exists but cannot be read** (permissions, I/O, a
|
|
141
|
+
directory in its place, …) — not a normal first run; fix it first. The first successful `scope-set` creates the file.
|
|
108
142
|
|
|
109
143
|
Then list the workspace to expose:
|
|
110
144
|
|
|
@@ -123,10 +157,14 @@ Then list the workspace to expose:
|
|
|
123
157
|
|
|
124
158
|
- `workspaceIds` are the host's workspace UUIDs, not paths; the host maps the agent's cwd to this
|
|
125
159
|
id through its workspace registry. **Finding the UUID is itself friction**: either ask the
|
|
126
|
-
host / dig through session records, or read `tables.workspaces` (the id ↔ path table) in
|
|
127
|
-
|
|
128
|
-
you
|
|
129
|
-
|
|
160
|
+
host / dig through session records, or read `tables.workspaces` (the id ↔ path table) in the
|
|
161
|
+
host's `<hostDshHome>/storages/workspace.json` yourself — v1 ships no command that does this
|
|
162
|
+
for you. The host resolves its home as "a non-empty `$DSH_HOME` (`~` expands) → `~/.dsh`", so
|
|
163
|
+
on a default install the file is `~/.dsh/storages/workspace.json`, **not**
|
|
164
|
+
`$DSH_HOME/storages/workspace.json` (unless `$DSH_HOME` is actually set). Note that
|
|
165
|
+
`config.dshHome` moves only the plugin's `<dshHome>/boost`, never this host file. If you cannot
|
|
166
|
+
find the UUID and this is a single-user machine, `"mode": "global"` widens the scope to every
|
|
167
|
+
*defined* workspace; sessions with no workspace stay invisible.
|
|
130
168
|
- `baseRevision` is `data.scope.revision` from the status you just read (`0` for the first write).
|
|
131
169
|
This is compare-and-swap: a stale revision returns `ERR_SCOPE_REVISION_CONFLICT`; read `status`
|
|
132
170
|
again and retry. When the caller's cancellation signal interrupts the write, the tool returns
|
|
@@ -188,7 +226,20 @@ projection priced but never applied — then decide whether to project and subst
|
|
|
188
226
|
**"Changes nothing the model sees" would be false**: whenever a workspace is visible the protocol
|
|
189
227
|
section (379 tokens) is injected into the system prompt, and a multi-candidate plan still makes a
|
|
190
228
|
**real selector call** (a separate auxiliary model request). By design the shadow week saves
|
|
191
|
-
nothing; it produces only the four ratios below.
|
|
229
|
+
nothing; it produces only the four ratios below.
|
|
230
|
+
|
|
231
|
+
Of those ratios, `saveableRatio`, `byFamily`, and `candidateRecall` can decide **whether the
|
|
232
|
+
substitution side is worth turning on**: how many substitution decisions the whitelist could
|
|
233
|
+
actually deliver, which tool families the hits land in, and how high candidate recall is — that
|
|
234
|
+
is, whether substitution would fire at all and where. They **cannot decide release**: v1 ships as
|
|
235
|
+
a normal release and does not gate on shadow-week savings — and that call was the
|
|
236
|
+
**implementer's** decision during design, not a user ruling. The user accepted a one-week shadow
|
|
237
|
+
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
|
+
`retrievalUpperBound` is structurally `0` during the shadow week (it only counts applied
|
|
239
|
+
`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) and
|
|
241
|
+
post-hoc detection, not on shadow labels.
|
|
242
|
+
`scope.json` has two independent switches:
|
|
192
243
|
|
|
193
244
|
| Switch | Value | Behaviour |
|
|
194
245
|
|---|---|---|
|
|
@@ -203,16 +254,19 @@ The recommended sequence:
|
|
|
203
254
|
1. **Week one**: use `shadow: true` and `projection: 'shadow'` with the `scope-set` above, and work
|
|
204
255
|
normally.
|
|
205
256
|
2. **Read the report**: from a repository checkout, run
|
|
206
|
-
`node scripts/shadow-report.mjs --dir "
|
|
207
|
-
|
|
257
|
+
`node scripts/shadow-report.mjs --dir "<root>/receipts"`, where `<root>` is the `root=` printed
|
|
258
|
+
by the assembly log (that is, `<dshHome>/boost`; `dshHome` config wins over `$DSH_HOME`, and
|
|
259
|
+
with neither set it falls back to `~/.dsh`). The script is dev-only and is not in the npm
|
|
260
|
+
tarball. It prints four labels:
|
|
208
261
|
`saveableRatio` (the share of substitution the v1 whitelist could actually deliver: whitelisted
|
|
209
262
|
shadow commits over **all** substitution decisions — the denominator is every substitution
|
|
210
263
|
decision, not just the whitelisted calls; shadow mode records every family, so bash/ssh
|
|
211
264
|
potential shows up in `byFamily`), `byFamily` (hit rate per candidate family), `candidateRecall`
|
|
212
265
|
(recall of the candidate set), and `retrievalUpperBound` (retrieval upper bound; structurally
|
|
213
266
|
`0` during the shadow week because nothing is projected for real).
|
|
214
|
-
3. **Turn on projection**:
|
|
215
|
-
|
|
267
|
+
3. **Turn on projection**: projection is not released on shadow labels (its basis is the
|
|
268
|
+
visibility contract and post-hoc detection); once the host spill backend is available, keep
|
|
269
|
+
`shadow: true` and set `projection` to `'on'`:
|
|
216
270
|
|
|
217
271
|
```json
|
|
218
272
|
{ "cmd": "scope-set", "body": { "projection": "on" }, "baseRevision": 1 }
|
|
@@ -220,8 +274,9 @@ The recommended sequence:
|
|
|
220
274
|
|
|
221
275
|
`scope-set` patches only the fields you pass; everything else stays as it was. Receipts now get
|
|
222
276
|
replaced, while substitution decisions are still recorded only.
|
|
223
|
-
4. **Turn on substitution**:
|
|
224
|
-
|
|
277
|
+
4. **Turn on substitution**: when the shadow report shows acceptable whitelist hits and candidate
|
|
278
|
+
recall, just switch the shadow off — **checking before the switch is a no-op**: the shadow
|
|
279
|
+
week never synthesizes a turn, so a `content[].thinking` 400 is
|
|
225
280
|
structurally impossible and a check made before switching it off can only ever read "not
|
|
226
281
|
seen". After `shadow` becomes `false`, check for that 400 in the **first genuinely
|
|
227
282
|
substituted round** as described in [`docs/RELEASE.md`](docs/RELEASE.md) §4, and keep
|
|
@@ -265,11 +320,11 @@ cap is 256 KiB, so `300000` prevents the family from triggering at all (there is
|
|
|
265
320
|
Characters are Unicode code points. Error receipts and receipts above 256 KiB are never projected.
|
|
266
321
|
|
|
267
322
|
The invariant is **not** `triggerChars >= headChars + tailChars + 1`. The real replacement is head
|
|
268
|
-
line + head + footer + tail + 3 newlines; the footer is produced by the host's `formatSpillNotice
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
`400 + 100 + 50 (head line) +
|
|
272
|
-
about
|
|
323
|
+
line + head + footer + tail + 3 newlines; the footer is produced by the host's `formatSpillNotice`.
|
|
324
|
+
With a 68-character locator and the host's fixed 66-character retrieval hint, a 3-digit
|
|
325
|
+
omitted-byte count gives 190 characters and a 5-digit count gives 192. With the grep/glob defaults
|
|
326
|
+
of 400+100: `400 + 100 + 50 (head line) + 190 (footer) + 3 = 743 > 700` (745 with a 5-digit count).
|
|
327
|
+
So a receipt just over 700 — up to about 743 — is judged cuttable by `truncate`, but `projectApply` assembles a replacement that is
|
|
273
328
|
not shorter than the original and returns the original. That is a dead band, not a net loss. The
|
|
274
329
|
runtime `assembled.length >= text.length` check guarantees projection never makes a receipt
|
|
275
330
|
longer; to remove the dead band, raise `triggerChars` to at least that sum (for example 800 for
|
|
@@ -323,24 +378,66 @@ silently.
|
|
|
323
378
|
|
|
324
379
|
## State, rollback, and removal
|
|
325
380
|
|
|
326
|
-
State lives in
|
|
381
|
+
State lives in `<dshHome>/boost/`: `dshHome` config **wins over** `$DSH_HOME`, and with neither
|
|
382
|
+
set it falls back to `~/.dsh`; the assembly log prints the resolved `root=` (that is,
|
|
383
|
+
`<dshHome>/boost`).
|
|
327
384
|
|
|
328
385
|
- `scope.json` — the single source of truth for the exposure surface (version 2, with revision).
|
|
329
386
|
- `scope.lock` — the short-lived write lock, removed after a normal write.
|
|
330
|
-
- `receipts/<encoded-session>.jsonl` — append-only receipts.
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
`
|
|
336
|
-
|
|
337
|
-
|
|
387
|
+
- `receipts/<encoded-session>.jsonl` — append-only receipts. **A receipt is written per
|
|
388
|
+
decision, not per call**: a line appears only for a projection, a substitution decision
|
|
389
|
+
(including skips), or an out-of-scope `skip:no-scope`. A `write` / `edit` with no plan produces
|
|
390
|
+
**no receipt at all**, so its arguments are never recorded. Every line carries metadata, a
|
|
391
|
+
preview of the first 256 code points of the receipt (never the full stdout), and that call's
|
|
392
|
+
bound `args` (model-written: above 2048 code points they are stored as visibly truncated JSON
|
|
393
|
+
with an `args_truncated` flag; nesting deeper than 64 levels sets `args_depth_truncated` and
|
|
394
|
+
replaces the deeper subtree with `{ "truncated_depth": 64 }`). **Only substitution receipts**
|
|
395
|
+
also carry the plan goal (≤256 code points) and guards (≤8, each ≤300 code points):
|
|
396
|
+
`kind:'substitute'`, `kind:'substitute-settled'`, and `kind:'shadow'` with `code:'ok'`.
|
|
397
|
+
`kind:'shadow'` is not substitution-only — projection shadowing also writes `kind:'shadow'`,
|
|
398
|
+
but with `code:'projection-shadow'`, and that is a projection receipt with no plan evidence.
|
|
399
|
+
**Projection receipts** (`kind:'projection'`, `code:'projected'`, and the projection shadow)
|
|
400
|
+
carry `before` / `after` / `saved_projection_tokens` / `unit` / `estimate` / `horizon_steps`;
|
|
401
|
+
without a token meter only `estimate:'unknown'` is written and the three numeric fields are
|
|
402
|
+
omitted entirely. **Retrieval receipts** (`kind:'projection'`, `code:'projection-retrieval'`)
|
|
403
|
+
carry `locator` plus `retrieval_call_tokens` / `retrieval_content_tokens` / `retrieval_tokens`;
|
|
404
|
+
those three are written only when the retrieval was priced, and an unpriced one has
|
|
405
|
+
`estimate:'unknown'` with the fields omitted. `skip` receipts carry only `preview` and `args`
|
|
406
|
+
(`skip:no-scope` carries neither — just the tool name).
|
|
407
|
+
|
|
408
|
+
When the current shard exceeds 8 MiB or 20,000 lines, the next write first rotates it to
|
|
409
|
+
`<encoded-session>.1.jsonl`; only the current shard and its predecessor are kept (an older `.1`
|
|
410
|
+
is overwritten). `boost status` reads `.1` before the current shard. The 256-shard cap counts
|
|
411
|
+
**encoded session names**: a rotated `.1.jsonl` belongs to the same name and takes no extra
|
|
412
|
+
slot, though the scan reads both files under that name.
|
|
338
413
|
|
|
339
414
|
`boost status` replays the projection ledger at each receipt's own `horizon_steps`; a receipt
|
|
340
415
|
written before that field existed is replayed at the current horizon and counted in
|
|
341
416
|
`projection_horizon_reestimated`, while `projection_horizon_steps` reports the horizon currently
|
|
342
417
|
in effect (the minimum over live sessions, falling back to `horizonSteps` when no history exists).
|
|
343
418
|
|
|
419
|
+
`status.data` also carries several status and ledger fields that never appear in `degraded`:
|
|
420
|
+
|
|
421
|
+
- `receipts_stopped`: `true` once receipt writes have failed 3 times in a row. Substitution is then
|
|
422
|
+
refused **entirely** (fail closed — no further selector call or step budget is spent), projection
|
|
423
|
+
continues, and every ledger figure is the snapshot from before the writes stopped. The count
|
|
424
|
+
clears and the field returns to `false` after a write succeeds. This is the only place that says
|
|
425
|
+
"receipts have stopped" — there is no `degraded` code for it.
|
|
426
|
+
- `protocol_suppressed`: how many times the protocol section was dropped at assembly (invisible
|
|
427
|
+
workspace, a diagnostic assembly with no agent, and a `complete: true` override). Assembly runs
|
|
428
|
+
per request, so this only counts — it writes no receipt.
|
|
429
|
+
- `projection_locator_evictions`: locators dropped because of the per-session cap (512, oldest
|
|
430
|
+
first); above 0 means the retrieval ledger has losses.
|
|
431
|
+
- `projection_unknown_families`: calls carrying an `mcp__` prefix that reached projection but
|
|
432
|
+
matched no tool family; `projection_unknown_tools` is the retained unmapped tool names with
|
|
433
|
+
counts (at most 32), for spotting mapper gaps.
|
|
434
|
+
- `hasWorkspaceRegistry`: whether the host currently offers `workspaceRegistry`. The key is
|
|
435
|
+
**omitted** when nothing was probed — it is not `false`.
|
|
436
|
+
- `saved`: a camelCase ledger object for older consumers (`substitution` / `projectionGross` /
|
|
437
|
+
`projectionNet` / `retrievals`), derived from the same aggregation as the top-level snake_case
|
|
438
|
+
fields. A projection receipt written before T23b has no `saved_projection_tokens` and is priced
|
|
439
|
+
from its legacy `saved` field instead.
|
|
440
|
+
|
|
344
441
|
With `projection: 'on'`, the complete original is written to the host spill backend **before** the
|
|
345
442
|
replacement happens, and the footer locator can be read with `read` / `grep`. Projection never
|
|
346
443
|
discards the only copy; if the spill write fails, nothing is replaced (the receipt records
|
|
@@ -348,9 +445,10 @@ discards the only copy; if the spill write fails, nothing is replaced (the recei
|
|
|
348
445
|
`projection-skipped:footer-failed`; a missing footer renderer records
|
|
349
446
|
`projection-skipped:no-footer`, see "Host dependencies").
|
|
350
447
|
|
|
351
|
-
Rollback and disablement (the `baseRevision` values below are `3` after the
|
|
352
|
-
|
|
353
|
-
`
|
|
448
|
+
Rollback and disablement (the `baseRevision` values below are `3` after the recommended
|
|
449
|
+
"Enable it" + "Shadow week" sequence — enablement ends at `1`, and the two shadow-week steps add
|
|
450
|
+
one each — and `4` after the first rollback; in practice always use the `data.scope.revision` you
|
|
451
|
+
just read from `status`, never copy these):
|
|
354
452
|
|
|
355
453
|
- **Turn both behaviours off** (no projection, no substitution; the protocol section is still
|
|
356
454
|
injected for every still-visible workspace — the selected ones under `selected`, every defined
|
|
@@ -362,10 +460,11 @@ Rollback and disablement (the `baseRevision` values below are `3` after the enab
|
|
|
362
460
|
```
|
|
363
461
|
|
|
364
462
|
- **Go back to fully inert**: set `mode` back to `selected` and empty the list. **Note that
|
|
365
|
-
`workspaceIds` matters only in `selected` mode**: `isVisible` is
|
|
366
|
-
|
|
367
|
-
`
|
|
368
|
-
|
|
463
|
+
`workspaceIds` matters only in `selected` mode**: `isVisible` is true under `mode:"global"` for
|
|
464
|
+
every **defined** workspace (`src/scope/doc.ts` — the `global` branch never reads the list; a
|
|
465
|
+
session whose `workspaceId` is undefined stays invisible), so **while in `global`, writing only
|
|
466
|
+
`workspaceIds: []` stops nothing** — projection and substitution keep running while you believe
|
|
467
|
+
you have rolled back. Under `selected`, removing one workspace is
|
|
369
468
|
enough; under `global` you must switch the mode at the same time:
|
|
370
469
|
|
|
371
470
|
```json
|
|
@@ -376,7 +475,7 @@ Rollback and disablement (the `baseRevision` values below are `3` after the enab
|
|
|
376
475
|
(only the `boost` tool schema's standing cost remains).
|
|
377
476
|
|
|
378
477
|
- **Uninstall the plugin**: `dsh plugin --profile <name> remove dsh-boost`, then restart DSH.
|
|
379
|
-
- Deleting
|
|
478
|
+
- Deleting `<dshHome>/boost` clears the scope and receipts (back to defaults), but does not delete
|
|
380
479
|
the original files already written to the host spill backend.
|
|
381
480
|
|
|
382
481
|
## Host dependencies
|
|
@@ -390,11 +489,12 @@ to load. `llm` is soft (only the selector uses it); when absent the selector fal
|
|
|
390
489
|
| `workspaceRegistry` | soft (`ctx.get('workspaceRegistry')`) | **The workspace is invisible**: a cwd can never map to a workspace id, so everything fails closed as invisible — no protocol section, projection and substitution all skipped, only `skip:no-scope` receipts accumulating; `status.degraded` reports `ERR_HOST_NO_WORKSPACE_REGISTRY`. This is the host-capability explanation **when a workspace should be visible**, not the only explanation for "installed but nothing happens": the shipped default `selected + []` is inert by design and reports no error; a missing token meter also refuses real substitution; a `complete: true` section also suppresses the protocol |
|
|
391
490
|
| `tokenMeter` | soft (`ctx.get('tokenMeter')`) | Substitution is refused; projection keeps working and its accounting records `unknown` (never a fabricated number); `status.degraded` reports `ERR_HOST_NO_TOKENMETER` |
|
|
392
491
|
| `spillStore` | soft (`ctx.get('spillStore')`) | With `projection: 'on'`, an over-limit receipt is not projected (evidence preserved) and the receipt records `projection-skipped:no-spill`; `status.degraded` reports `ERR_HOST_NO_SPILL` (the live probe only in on mode; a historical receipt reports it in any mode) |
|
|
393
|
-
| `@deepseek-ai/dsh-spill-policy/notice` | soft (dynamic import) | The spill backend exists but the footer renderer `formatSpillNotice` cannot be loaded/is absent: apply-mode projection cannot build its footer and skips every receipt (`projection-skipped:no-footer`); `status.degraded` reports `ERR_HOST_NO_SPILL_NOTICE`. This is a different absence from `ERR_HOST_NO_SPILL` (no spill backend at all) |
|
|
492
|
+
| `@deepseek-ai/dsh-spill-policy/notice` | soft (dynamic import) | The spill backend exists but the footer renderer `formatSpillNotice` cannot be loaded/is absent: apply-mode projection cannot build its footer and skips every receipt (`projection-skipped:no-footer`; a throw while rendering records `projection-skipped:footer-failed`); `status.degraded` reports `ERR_HOST_NO_SPILL_NOTICE`. This is a different absence from `ERR_HOST_NO_SPILL` (no spill backend at all) |
|
|
493
|
+
| (spill backend present but failing) | — | Every `saveText` is rejected: the receipt records `projection-skipped:spill-failed` and `status.degraded` reports **`ERR_HOST_SPILL_FAILING`**. This is a **third** state — neither "no backend" nor "no footer renderer" — and telling an operator to restore the spill package would send them after a package that is installed and failing |
|
|
394
494
|
| `@deepseek-ai/dsh-token-meter/estimate` | soft (dynamic import) | Fixed overhead cannot be measured, so `fixedOverheadTokens` is `'unknown'`; `status.degraded` reports `ERR_HOST_NO_ESTIMATOR` |
|
|
395
495
|
| `win32` platform | runtime `isPosixOnly()` check | Substitution is refused, projection still works; `status.degraded` reports `ERR_HOST_PLATFORM_UNSUPPORTED` |
|
|
396
496
|
| Host version line | startup check of the `@deepseek-ai/dsh-app-boot` version | A version other than `0.2.2-rc.4` logs `ERR_HOST_VERSION_MISMATCH` and loads anyway — advisory only, not a `status.degraded` code. An undeterminable version logs an info line, no code |
|
|
397
|
-
| Receipt shard readability | `boost status` full scan (not a dependency) | When at least one receipt shard cannot be read (EACCES, a directory named `x.jsonl`, …), `status.degraded` carries `ERR_RECEIPTS_UNREADABLE`; `status` stays a **total over the healthy shards** — they are still counted — so the figures may be incomplete. Check permissions and stray entries in
|
|
497
|
+
| Receipt shard readability | `boost status` full scan (not a dependency) | When at least one receipt shard cannot be read (EACCES, a directory named `x.jsonl`, …), `status.degraded` carries `ERR_RECEIPTS_UNREADABLE`; `status` stays a **total over the healthy shards** — they are still counted — so the figures may be incomplete. Check permissions and stray entries in `<dshHome>/boost/receipts/`, fix, and re-run `status`, comparing counts |
|
|
398
498
|
| Receipt shard count | `boost status` full scan (not a dependency) | When more than 256 shards exist, `status` counts only the first 256 by encoded name and `status.degraded` carries `ERR_RECEIPTS_TRUNCATED`; every count is therefore a **lower bound**. Shards are never pruned automatically; archive or move old session shards and re-run `status` |
|
|
399
499
|
| Prompt assembly waterfall | outgoing-request probe (not a dependency) | When the host's `complete: true` prompt section replaces the assembled system prompt after the waterfall and the protocol section never reaches the request, `status.degraded` carries `ERR_HOST_COMPLETE_SECTION`; substitution and projection fail closed for the affected requests (the plugin stays inert although the workspace is visible). Find the complete section overriding the waterfall (usually another plugin's) and remove it, or accept the inaction on those requests |
|
|
400
500
|
|
|
@@ -402,13 +502,13 @@ to load. `llm` is soft (only the selector uses it); when absent the selector fal
|
|
|
402
502
|
`ToolRegistrationOptions` since the oldest host line this package declares, so the plugin no
|
|
403
503
|
longer probes it and registers unconditionally.
|
|
404
504
|
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
this mount; a failure to
|
|
411
|
-
`ERR_BOOST_TOOL_REGISTER_FAILED
|
|
505
|
+
Registration codes come in two kinds. A non-duplicate throw while registering the protocol
|
|
506
|
+
section logs `ERR_BOOST_SECTION_REGISTER_FAILED` (log only). The three event hooks
|
|
507
|
+
(`tools/post-execute`, `llm/stream`, `tools/execute`) are then mounted **independently**: a
|
|
508
|
+
failure in any of them is named and reported through **`ERR_BOOST_PARTIAL_MOUNT`** in
|
|
509
|
+
`status.degraded`, so a partially assembled plugin no longer looks healthy. The host's genuine
|
|
510
|
+
duplicate-section error logs `ERR_BOOST_ALREADY_MOUNTED` and skips this mount; a failure to
|
|
511
|
+
register the `boost` tool itself logs `ERR_BOOST_TOOL_REGISTER_FAILED` (log only).
|
|
412
512
|
|
|
413
513
|
`ERR_HOST_NO_TOKENMETER` and `ERR_HOST_NO_ESTIMATOR` are **two different things**; do not merge
|
|
414
514
|
them. The first is the host service (`ctx.get('tokenMeter')`) being absent, which refuses
|
|
@@ -432,15 +532,26 @@ evidence" degraded path would be unreachable.
|
|
|
432
532
|
|
|
433
533
|
- Only two things: **replace tool receipts in place** and **substitute read-only calls** (`read` /
|
|
434
534
|
`grep` / `glob`).
|
|
435
|
-
- **No batched tool execution** (no PTC / `run_code
|
|
535
|
+
- **No batched tool execution** (no PTC / `run_code`): this is not a boundary v1 chose for
|
|
536
|
+
itself but the **narrowed** form of original requirement 2.1 — the request asked for several
|
|
537
|
+
tool calls at once, and the adjudication excluded it explicitly for a later phase (see the
|
|
538
|
+
2.1 row and decision 9 in the
|
|
539
|
+
[clarification record](docs/superpowers/clarifications/2026-11-18-dsh-token-efficiency.md);
|
|
540
|
+
design N1).
|
|
436
541
|
- **No deduplication or merging of tool calls** (design N5) — this was not started at all, and
|
|
437
542
|
v1 ships **no tool that measures duplicate-call rate**: the "shadow-week duplication
|
|
438
543
|
statistic" the design reserved as its restart trigger was never delivered; `shadow-report.mjs`
|
|
439
544
|
does not produce it.
|
|
440
545
|
- **The shadow week saves nothing by design**: it only records (the protocol section is still
|
|
441
546
|
injected and the selector is still called); its output is four ratios, not saved tokens.
|
|
442
|
-
- **v1 does not judge "better results"**: there is a token ledger and a 20-task
|
|
547
|
+
- **v1 does not judge "better results"**: there is a token ledger and a **manual** 20-task
|
|
548
|
+
regression procedure (the task set does not ship with the package; see `docs/RELEASE.md` §3),
|
|
443
549
|
no quality metric; whether substituted outcomes are better is unjudgeable in v1.
|
|
550
|
+
- **Projection is truncation, not refinement**: it keeps the head and tail and drops the middle;
|
|
551
|
+
the before/after token difference in the ledger measures *shorter*, not *more relevant*. The
|
|
552
|
+
dropped middle may be exactly what the next decision needs — with `projection: 'on'` the
|
|
553
|
+
original can be retrieved through the footer locator, but that costs a tool call, and v1 has
|
|
554
|
+
no metric that separates "refined" from "wrongly cut".
|
|
444
555
|
- **Installed but not enabled is a small net loss**: the `boost` tool registers as soon as the
|
|
445
556
|
plugin is assembled, and its schema costs a measured 399 tokens on every request (see the
|
|
446
557
|
breakdown in "Enable it") while yielding nothing.
|
|
@@ -448,9 +559,12 @@ evidence" degraded path would be unreachable.
|
|
|
448
559
|
- Does not replace or take over DSH's compaction, pruning, or spill decisions (design N3);
|
|
449
560
|
projection changes only the model-visible content and keeps the original in the host spill.
|
|
450
561
|
- No model training or weight changes (N2); no attempt at the paper's 87.93% (N4).
|
|
451
|
-
- No 10% promise: 3.5% is the
|
|
452
|
-
|
|
453
|
-
|
|
562
|
+
- No 10% promise: 3.5% is the **lower bound** of the ex-ante estimate, not a floor; 10% is the
|
|
563
|
+
ideal upper bound. The honest net floor is about 0.4% (projection gross ~0.8% minus ~0.4%
|
|
564
|
+
fixed per-request overhead). The shadow week only answers whether the substitution side is
|
|
565
|
+
worth turning on (candidate coverage and hit rate); it does not decide release, and it cannot
|
|
566
|
+
replace the range with a measurement (`shadow-report.mjs` emits four ratios and no total-token
|
|
567
|
+
denominator).
|
|
454
568
|
|
|
455
569
|
## Documentation
|
|
456
570
|
|
|
@@ -468,7 +582,7 @@ The source and docs live in the repository at
|
|
|
468
582
|
| [Design](docs/superpowers/specs/2026-11-18-dsh-token-efficiency-design.md) | Goals, evidence, architecture, contracts, measurement, risks, release shape |
|
|
469
583
|
| [Host contracts appendix](docs/superpowers/plans/2026-11-18-host-contracts.md) | Interface reference copied line by line from the host sources |
|
|
470
584
|
| [Three-tier delegation research](docs/research/2026-11-18-three-tier-delegation.md) | 25 primary sources on caching, routing thresholds, compression, and verification |
|
|
471
|
-
| [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
|
|
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 does not ship), and the shadow week and stats recompute |
|
|
472
586
|
|
|
473
587
|
## License
|
|
474
588
|
|