dsh-boost 0.0.0-stage → 0.1.0

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 (110) hide show
  1. package/LICENSE +202 -0
  2. package/NOTICE +29 -0
  3. package/README.en.md +476 -0
  4. package/README.md +408 -2
  5. package/cordis.patch.yml +40 -0
  6. package/dist/admission/fixed-cost.d.ts +23 -0
  7. package/dist/admission/fixed-cost.js +61 -0
  8. package/dist/admission/fixed-cost.js.map +1 -0
  9. package/dist/admission/ledger.d.ts +113 -0
  10. package/dist/admission/ledger.js +176 -0
  11. package/dist/admission/ledger.js.map +1 -0
  12. package/dist/admission/retrieval.d.ts +65 -0
  13. package/dist/admission/retrieval.js +162 -0
  14. package/dist/admission/retrieval.js.map +1 -0
  15. package/dist/admission/usage.d.ts +75 -0
  16. package/dist/admission/usage.js +124 -0
  17. package/dist/admission/usage.js.map +1 -0
  18. package/dist/config.d.ts +43 -0
  19. package/dist/config.js +103 -0
  20. package/dist/config.js.map +1 -0
  21. package/dist/gate/binding.d.ts +113 -0
  22. package/dist/gate/binding.js +297 -0
  23. package/dist/gate/binding.js.map +1 -0
  24. package/dist/gate/decide.d.ts +82 -0
  25. package/dist/gate/decide.js +163 -0
  26. package/dist/gate/decide.js.map +1 -0
  27. package/dist/gate/guard.d.ts +69 -0
  28. package/dist/gate/guard.js +195 -0
  29. package/dist/gate/guard.js.map +1 -0
  30. package/dist/gate/invalidate.d.ts +112 -0
  31. package/dist/gate/invalidate.js +111 -0
  32. package/dist/gate/invalidate.js.map +1 -0
  33. package/dist/gate/plan.d.ts +86 -0
  34. package/dist/gate/plan.js +222 -0
  35. package/dist/gate/plan.js.map +1 -0
  36. package/dist/hooks/clock.d.ts +68 -0
  37. package/dist/hooks/clock.js +82 -0
  38. package/dist/hooks/clock.js.map +1 -0
  39. package/dist/hooks/execute.d.ts +79 -0
  40. package/dist/hooks/execute.js +128 -0
  41. package/dist/hooks/execute.js.map +1 -0
  42. package/dist/hooks/llm-stream.d.ts +276 -0
  43. package/dist/hooks/llm-stream.js +1008 -0
  44. package/dist/hooks/llm-stream.js.map +1 -0
  45. package/dist/hooks/pending.d.ts +89 -0
  46. package/dist/hooks/pending.js +115 -0
  47. package/dist/hooks/pending.js.map +1 -0
  48. package/dist/hooks/post-execute.d.ts +247 -0
  49. package/dist/hooks/post-execute.js +1776 -0
  50. package/dist/hooks/post-execute.js.map +1 -0
  51. package/dist/hooks/session-state.d.ts +158 -0
  52. package/dist/hooks/session-state.js +168 -0
  53. package/dist/hooks/session-state.js.map +1 -0
  54. package/dist/hooks/synthesize.d.ts +74 -0
  55. package/dist/hooks/synthesize.js +100 -0
  56. package/dist/hooks/synthesize.js.map +1 -0
  57. package/dist/host/loader.d.ts +23 -0
  58. package/dist/host/loader.js +31 -0
  59. package/dist/host/loader.js.map +1 -0
  60. package/dist/host/platform.d.ts +18 -0
  61. package/dist/host/platform.js +19 -0
  62. package/dist/host/platform.js.map +1 -0
  63. package/dist/host/root.d.ts +18 -0
  64. package/dist/host/root.js +43 -0
  65. package/dist/host/root.js.map +1 -0
  66. package/dist/index.d.ts +13 -0
  67. package/dist/index.js +866 -0
  68. package/dist/index.js.map +1 -0
  69. package/dist/projection/apply.d.ts +174 -0
  70. package/dist/projection/apply.js +137 -0
  71. package/dist/projection/apply.js.map +1 -0
  72. package/dist/projection/canonicalise.d.ts +43 -0
  73. package/dist/projection/canonicalise.js +43 -0
  74. package/dist/projection/canonicalise.js.map +1 -0
  75. package/dist/projection/counters.d.ts +65 -0
  76. package/dist/projection/counters.js +88 -0
  77. package/dist/projection/counters.js.map +1 -0
  78. package/dist/projection/truncate.d.ts +47 -0
  79. package/dist/projection/truncate.js +57 -0
  80. package/dist/projection/truncate.js.map +1 -0
  81. package/dist/prompt/protocol.d.ts +45 -0
  82. package/dist/prompt/protocol.js +56 -0
  83. package/dist/prompt/protocol.js.map +1 -0
  84. package/dist/receipts/store.d.ts +198 -0
  85. package/dist/receipts/store.js +734 -0
  86. package/dist/receipts/store.js.map +1 -0
  87. package/dist/scope/doc.d.ts +117 -0
  88. package/dist/scope/doc.js +158 -0
  89. package/dist/scope/doc.js.map +1 -0
  90. package/dist/scope/resolve.d.ts +91 -0
  91. package/dist/scope/resolve.js +146 -0
  92. package/dist/scope/resolve.js.map +1 -0
  93. package/dist/scope/store.d.ts +135 -0
  94. package/dist/scope/store.js +573 -0
  95. package/dist/scope/store.js.map +1 -0
  96. package/dist/selector/jev.d.ts +93 -0
  97. package/dist/selector/jev.js +171 -0
  98. package/dist/selector/jev.js.map +1 -0
  99. package/dist/tools/boost.d.ts +367 -0
  100. package/dist/tools/boost.js +768 -0
  101. package/dist/tools/boost.js.map +1 -0
  102. package/dist/tools/family.d.ts +26 -0
  103. package/dist/tools/family.js +26 -0
  104. package/dist/tools/family.js.map +1 -0
  105. package/dist/types.d.ts +113 -0
  106. package/dist/types.js +21 -0
  107. package/dist/types.js.map +1 -0
  108. package/locale/en.json +6 -0
  109. package/locale/zh.json +6 -0
  110. package/package.json +75 -4
package/README.en.md ADDED
@@ -0,0 +1,476 @@
1
+ # dsh-boost
2
+
3
+ Cut DeepSeek Harness (DSH) token usage with **tool-receipt projection** and **deterministic
4
+ read-only substitution**.
5
+
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.
8
+
9
+ ## What it does
10
+
11
+ 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.0 stats`
13
+ banner to stdout, so use `--silent` or `node scripts/session-stats.mjs` for machine-readable
14
+ output; snapshot at `2026-11-19T03:13:21Z`): 54,141 steps and 54,088 requests,
15
+ 10,575,904,022 raw tokens in total. The mean is 195,340 tokens per step and 195,531 per request
16
+ (median 187,681 per request); 97.01% of the input was cache reads. Tool receipts dominate the
17
+ volume (bash 61.75%, read 22.13%, ssh 10.01%), yet the part of a receipt the next step actually
18
+ uses is far smaller than the receipt itself.
19
+
20
+ The plugin does two things:
21
+
22
+ 1. **Projection** — before a tool receipt enters the context, keep its head and tail per tool
23
+ family and replace the middle with a retrievable on-disk handle. The original stays readable;
24
+ 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 has
26
+ deterministic evidence satisfying its guard, commit it without asking the model for another
27
+ decision. With several candidates, a single-label selector — one auxiliary request
28
+ (`maxTokens` 512 plus its input) — picks one. For the three substituted tools, the plan's
29
+ `$public` argument binding (copying a value from an earlier receipt into a later call's
30
+ arguments) is effective in practice only for `glob`'s single-token output; `read` and `grep`
31
+ emit line-numbered or bare-path output that the identifier projection cannot match, so those
32
+ calls fall back to the model.
33
+
34
+ The expected v1 range is **3.5% (floor) to 10.0% (ceiling)** of raw `totalTokens`. It was
35
+ **estimated offline, ex ante** against a 300-session corpus during design: not a guarantee, and
36
+ not a figure the shipped `session-snapshot.json` can recompute (the snapshot stores aggregate
37
+ counts only, not the components of the estimate) — **nothing in the deliverable can recompute
38
+ it**. Nor can the shadow week turn the range into a measured percentage: the shadow report
39
+ outputs four ratios only (see "Shadow week"), with no total-token denominator, and `boost
40
+ status` carries absolute values only; replacing the range with measurements needs a denominator
41
+ statistic that a later version must add.
42
+
43
+ ## Requirements
44
+
45
+ - Node.js `>=24.9.0` and DSH `0.2.2-rc.4` (an exact pin, not a range; both in `package.json`
46
+ `engines`; the Node floor matches the host `@deepseek-ai/dsh@0.2.2-rc.4`).
47
+ - **The package declares no peerDependencies**: installing it pulls in no `@deepseek-ai/*`
48
+ package, and the module loads without any of them; the runtime capabilities (`tokenMeter`,
49
+ `spillStore`, the estimator, the footer formatter) are provided by the DSH host process, and a
50
+ missing one degrades (see "Host dependencies").
51
+ - **Substitution is POSIX-only.** On Windows (`win32`) substitution is refused and
52
+ `boost status` reports `ERR_HOST_PLATFORM_UNSUPPORTED` in `degraded`; projection does not
53
+ depend on the platform and keeps working.
54
+ - v1 targets the web profile; the desktop profile is not supported.
55
+
56
+ ## Install
57
+
58
+ `dsh plugin` requires a profile and forwards the remaining arguments to pnpm in that profile
59
+ directory:
60
+
61
+ ```bash
62
+ # install from the registry (0.1.0 is the first release; latest will be 0.1.0)
63
+ dsh plugin --profile <name> add dsh-boost@^0.1.0
64
+
65
+ # or from a local checkout (build first; dist/ is not committed)
66
+ npm run build
67
+ dsh plugin --profile <name> add /absolute/path/to/dsh-boost
68
+ ```
69
+
70
+ For the web profile: `dsh plugin --profile web add dsh-boost@^0.1.0`. `dsh plugin` forwards the operation
71
+ to pnpm, so pnpm must be on `PATH`.
72
+
73
+ The package is ESM (`"type": "module"`) and the `.` entry of `exports` also maps `require` /
74
+ `default`: on Node >= 24.9, `require('dsh-boost')` loads the very same code as `import`. Nothing
75
+ is built inside the installed package (`files` ships only `dist`, `locale`, `cordis.patch.yml`,
76
+ both READMEs, `LICENSE`, and `NOTICE` — no `src/`; the `dist` source maps inline the sources).
77
+
78
+ The package's `dsh.bundle.patch` points at `cordis.patch.yml`, so after installation the host
79
+ registers it as a profile bundle and the patch's `insert` row lands over the profile root. **You
80
+ must restart DSH after installing**: plugins load at host startup, so a session that is already
81
+ running will not see the `boost` tool. For the web profile, restart `dsh web`.
82
+
83
+ ## Enable it
84
+
85
+ After installation the plugin is inert. While `scope.json` does not exist it uses
86
+ `DEFAULT_SCOPE`:
87
+
88
+ ```json
89
+ { "version": 2, "revision": 0, "mode": "selected", "workspaceIds": [], "shadow": true, "projection": "shadow" }
90
+ ```
91
+
92
+ With no `workspaceIds` no workspace is visible: the protocol section is not injected and
93
+ projection and substitution pass through unchanged — but each tool call still records one
94
+ `skip:no-scope` receipt. The `boost` tool itself is the one scope exemption, so it can always be
95
+ called to enable a workspace.
96
+
97
+ `boost` is a **model tool, not a shell command** — this package has no `bin`, and every step of
98
+ enabling it (status, scope-set, shadow) is a tool call inside the conversation; there is no CLI
99
+ equivalent. In the conversation, ask the agent to call it, for example:
100
+
101
+ > Call the boost tool with `{"cmd":"status"}` and show me the JSON.
102
+
103
+ The first `status` should answer `ok: true`, with `data.scope.workspaceIds` empty, `revision` `0`,
104
+ `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`). `degraded` containing
106
+ `ERR_SCOPE_READ_FAILED` is expected: `scope.json` does not exist yet, so the plugin is on its
107
+ fail-closed default. The first successful `scope-set` creates the file.
108
+
109
+ Then list the workspace to expose:
110
+
111
+ ```json
112
+ {
113
+ "cmd": "scope-set",
114
+ "body": {
115
+ "mode": "selected",
116
+ "workspaceIds": ["<workspace-id>"],
117
+ "shadow": true,
118
+ "projection": "shadow"
119
+ },
120
+ "baseRevision": 0
121
+ }
122
+ ```
123
+
124
+ - `workspaceIds` are the host's workspace UUIDs, not paths; the host maps the agent's cwd to this
125
+ 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
+ `$DSH_HOME/storages/workspace.json` yourself — v1 ships no command that does this for you. If
128
+ you cannot find the UUID and this is a single-user machine, `"mode": "global"` widens the
129
+ scope to every *defined* workspace; sessions with no workspace stay invisible.
130
+ - `baseRevision` is `data.scope.revision` from the status you just read (`0` for the first write).
131
+ This is compare-and-swap: a stale revision returns `ERR_SCOPE_REVISION_CONFLICT`; read `status`
132
+ again and retry. When the caller's cancellation signal interrupts the write, the tool returns
133
+ `ERR_SCOPE_ABORTED`: the lock is released, `scope.json` is untouched, and retrying with a
134
+ freshly read revision is safe — no residue is left behind.
135
+ - `version` and `revision` are store-owned; a `body` carrying either is rejected.
136
+
137
+ After the write, call `status` again. A healthy result looks like this:
138
+
139
+ - `ok: true`, `data.scope.workspaceIds` contains the id you wrote, and `data.scope.revision` is
140
+ `1` (each write increments it).
141
+ - `data.shadow` is `true` and `data.projection` is `"shadow"` — exactly the shadow-week state.
142
+ - `data.degraded` is empty on POSIX with a host token meter and spill backend; `estimate_kind` is
143
+ `"host"` and `fixedOverheadTokens` is a number, not `"unknown"`. If the estimate package
144
+ `@deepseek-ai/dsh-token-meter/estimate` is unreachable, `fixedOverheadTokens` is the string
145
+ `"unknown"` (not 0) and `degraded` carries `ERR_HOST_NO_ESTIMATOR`; `estimate_kind` may still be
146
+ `"host"` because the token-meter service is present — the two are different things.
147
+ - `data.counts` usually starts empty — but **control calls count too**: while no workspace is
148
+ visible, `boost`'s own calls pass the same post-execute scope gate (there is no boost exemption
149
+ there; the exemption lives at tool registration), each recording one `skip:no-scope`. It grows
150
+ after normal tool calls, for example with `projection-shadow` entries.
151
+
152
+ Excerpt (illustrative values; ledger fields omitted):
153
+
154
+ ```json
155
+ {
156
+ "ok": true,
157
+ "data": {
158
+ "scope": { "mode": "selected", "workspaceIds": ["<workspace-id>"], "revision": 1 },
159
+ "shadow": true,
160
+ "projection": "shadow",
161
+ "degraded": [],
162
+ "fixedOverheadTokens": 778,
163
+ "estimate_kind": "host",
164
+ "counts": { "skip:no-scope": 2 }
165
+ }
166
+ }
167
+ ```
168
+
169
+ The `counts` in the excerpt is not empty: the two earlier control calls (`status` and `scope-set`)
170
+ ran while no workspace was visible yet, and each recorded one `skip:no-scope` (the post-execute
171
+ scope gate does not exempt `boost` itself).
172
+
173
+ `fixedOverheadTokens` is measured once at startup and is the **sum** of both components: protocol
174
+ section 379 + `boost` tool schema 399 = 778 (in this checkout). It is never inferred from usage;
175
+ when the estimate package is unreachable it is the string `'unknown'`, not 778 and not 0, and
176
+ `status.degraded` also carries `ERR_HOST_NO_ESTIMATOR`. **Which number applies to a request
177
+ depends on scope**: the `boost` tool schema (399) is present whenever the plugin is assembled —
178
+ `boost` is the one scope exemption and always stays in the tool declaration — while the protocol
179
+ section (379) is injected only when a workspace is visible. Under `selected + []` the section's
180
+ text is empty, so the real per-request fixed cost is **399**. `status` reports the combined 778
181
+ (or `'unknown'` when the estimate package is unreachable) regardless of scope; in the excerpt
182
+ above a workspace is selected, so 778 is the true per-request cost there.
183
+
184
+ ## Shadow week
185
+
186
+ The design chose **shadow first**: record for a week — no synthesized turns, no skipped calls,
187
+ projection priced but never applied — then decide whether to project and substitute for real.
188
+ **"Changes nothing the model sees" would be false**: whenever a workspace is visible the protocol
189
+ section (379 tokens) is injected into the system prompt, and a multi-candidate plan still makes a
190
+ **real selector call** (a separate auxiliary model request). By design the shadow week saves
191
+ nothing; it produces only the four ratios below. `scope.json` has two independent switches:
192
+
193
+ | Switch | Value | Behaviour |
194
+ |---|---|---|
195
+ | `shadow` | `true` | Substitution decisions are recorded only (`kind:'shadow'` receipts); nothing is synthesized or skipped |
196
+ | | `false` | Qualifying `read` / `grep` / `glob` calls are actually substituted |
197
+ | `projection` | `off` | No projection at all |
198
+ | | `shadow` | Price what projection would save; model-visible content is unchanged, no spill write |
199
+ | | `on` | Spill the full original first, then replace the receipt with head + footer + tail |
200
+
201
+ The recommended sequence:
202
+
203
+ 1. **Week one**: use `shadow: true` and `projection: 'shadow'` with the `scope-set` above, and work
204
+ normally.
205
+ 2. **Read the report**: from a repository checkout, run
206
+ `node scripts/shadow-report.mjs --dir "${DSH_HOME:-$HOME/.dsh}/boost/receipts"`. The script is
207
+ dev-only and is not in the npm tarball. It prints four labels:
208
+ `saveableRatio` (the share of substitution the v1 whitelist could actually deliver: whitelisted
209
+ shadow commits over **all** substitution decisions — the denominator is every substitution
210
+ decision, not just the whitelisted calls; shadow mode records every family, so bash/ssh
211
+ potential shows up in `byFamily`), `byFamily` (hit rate per candidate family), `candidateRecall`
212
+ (recall of the candidate set), and `retrievalUpperBound` (retrieval upper bound; structurally
213
+ `0` during the shadow week because nothing is projected for real).
214
+ 3. **Turn on projection**: if the report supports it, keep `shadow: true` and set `projection` to
215
+ `'on'`:
216
+
217
+ ```json
218
+ { "cmd": "scope-set", "body": { "projection": "on" }, "baseRevision": 1 }
219
+ ```
220
+
221
+ `scope-set` patches only the fields you pass; everything else stays as it was. Receipts now get
222
+ replaced, while substitution decisions are still recorded only.
223
+ 4. **Turn on substitution**: just switch the shadow off — **checking before the switch is a
224
+ no-op**: the shadow week never synthesizes a turn, so a `content[].thinking` 400 is
225
+ structurally impossible and a check made before switching it off can only ever read "not
226
+ seen". After `shadow` becomes `false`, check for that 400 in the **first genuinely
227
+ substituted round** as described in [`docs/RELEASE.md`](docs/RELEASE.md) §4, and keep
228
+ recording it in every substitution window after that:
229
+
230
+ ```json
231
+ { "cmd": "shadow", "body": false, "baseRevision": 2 }
232
+ ```
233
+
234
+ `projection: 'on'` depends on the host spill backend. Without it, an over-limit receipt is **not**
235
+ projected and the original enters history intact (receipt `projection-skipped:no-spill`,
236
+ `status.degraded` with `ERR_HOST_NO_SPILL`). Shadow mode does not need spill.
237
+
238
+ ## Configuration
239
+
240
+ `config` in `cordis.patch.yml` is **replaced wholesale**, never deep-merged: a missing key falls
241
+ back to the plugin default. But note: `resolveConfig` fills **all five tool families** (`read` /
242
+ `grep` / `glob` / `bash` / `ssh`) from defaults, so **deleting a family does not disable it** —
243
+ deleting `projection.bash` just projects bash with the default 4000/2000/500 window. To truly
244
+ disable a family, raise its `triggerChars` above every receipt you will see; the projection byte
245
+ cap is 256 KiB, so `300000` prevents the family from triggering at all (there is no per-family
246
+ `off` key).
247
+
248
+ `projection.*` here is a **window**, not a switch. The switch lives in `scope.json`'s
249
+ `projection` field and is written by `boost scope-set`.
250
+
251
+ | Key | Default | Effect |
252
+ |---|---|---|
253
+ | `projection.read.triggerChars` / `headChars` / `tailChars` | 3000 / 2000 / 500 | Keep the first 2000 and last 500 characters of `read` receipts longer than 3000 characters |
254
+ | `projection.grep.*` | 700 / 400 / 100 | `grep` window |
255
+ | `projection.glob.*` | 700 / 400 / 100 | `glob` window |
256
+ | `projection.bash.*` | 4000 / 2000 / 500 | `bash` window |
257
+ | `projection.ssh.*` | 2000 / 1200 / 300 | `mcp__ssh__*` (such as `mcp__ssh__execute-command`) window |
258
+ | `admission.thresholdTokens` | 1024 | Minimum net saving per candidate before substitution; a single deterministic candidate is exempt |
259
+ | `selector.maxTokens` | 512 | Output budget for the multi-candidate selector (its input plus output bound is deducted from the saving) |
260
+ | `stepsPerTurn` | 8 | Maximum substituted steps per turn |
261
+ | `horizonSteps` | 20 | Remaining-step horizon used when the session average cannot be computed |
262
+ | `historyTurns` | 5 | Number of recent turns averaged for the step count |
263
+ | `dshHome` | `$DSH_HOME`, else `~/.dsh` | State-root prefix: the plugin uses `<dshHome>/boost`, and it wins over `$DSH_HOME`; a blank or non-string value counts as unset, and a relative path is resolved once against the cwd at assembly. The assembly log prints the resolved `root=` |
264
+
265
+ Characters are Unicode code points. Error receipts and receipts above 256 KiB are never projected.
266
+
267
+ 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
+ and is about 196 characters (68-character locator, 5-digit omitted-byte count, the host's fixed
270
+ retrieval hint). With the grep/glob defaults of 400+100:
271
+ `400 + 100 + 50 (head line) + 196 (footer) + 3 = 749 > 700`. So a receipt just over 700 — up to
272
+ about 749 — is judged cuttable by `truncate`, but `projectApply` assembles a replacement that is
273
+ not shorter than the original and returns the original. That is a dead band, not a net loss. The
274
+ runtime `assembled.length >= text.length` check guarantees projection never makes a receipt
275
+ longer; to remove the dead band, raise `triggerChars` to at least that sum (for example 800 for
276
+ grep/glob) or shrink the windows. The footer length varies with the locator and digit count.
277
+
278
+ (`projection: 'shadow'` prices only the `(Omitted N bytes.)` clause, not the locator or the full
279
+ footer, so the shadow account's `after` is a lower bound; the apply path re-checks after the write.)
280
+
281
+ ## Bundle patch
282
+
283
+ `cordis.patch.yml` is one `insert` over the profile root:
284
+
285
+ ```yaml
286
+ - insert:
287
+ - id: dsh-boost
288
+ name: 'dsh-boost'
289
+ config:
290
+ projection:
291
+ read: { triggerChars: 3000, headChars: 2000, tailChars: 500 }
292
+ grep: { triggerChars: 700, headChars: 400, tailChars: 100 }
293
+ glob: { triggerChars: 700, headChars: 400, tailChars: 100 }
294
+ bash: { triggerChars: 4000, headChars: 2000, tailChars: 500 }
295
+ ssh: { triggerChars: 2000, headChars: 1200, tailChars: 300 }
296
+ admission: { thresholdTokens: 1024 }
297
+ selector: { maxTokens: 512 }
298
+ stepsPerTurn: 8
299
+ horizonSteps: 20
300
+ historyTurns: 5
301
+ ```
302
+
303
+ The host performs **no id/name matching on top-level `insert` rows**: the loader
304
+ (cordis-plugin-include's `applyEntryPatches`) pushes them straight into the assembly plan —
305
+ there is no "mismatch means the row is silently skipped" path. The two equalities serve another
306
+ purpose: **the plugin manager uses them to attribute a running entry to this bundle's row** (the
307
+ in-use / addressable determination in `dsh-plugin-manager`, see `listPlugins` / `removeBundle`):
308
+
309
+ ```text
310
+ row.id === entry.options.id
311
+ row.name === entry.options.name
312
+ ```
313
+
314
+ `id` and `name` do **not** have to equal each other: the third-party plugin `dsh-mcp-btwy` (a
315
+ GitHub package installed into the user's profile, not a patch the host ships) uses
316
+ `id: dsh-mcp-server` and `name: dsh-mcp-btwy`. This package keeps all four names identical:
317
+ `dsh-boost` is the npm package name, the exported plugin `name`, and the patch row's `id` and
318
+ `name`, so the plugin manager can attribute the running entry to this bundle and address or
319
+ remove it through the profile patch. When an equality fails the row **still assembles** — it
320
+ only becomes unaddressable in the management plane (its read/write state and removal detection
321
+ break) — and a `name` pointing at a nonexistent package fails the load **loudly**, not
322
+ silently.
323
+
324
+ ## State, rollback, and removal
325
+
326
+ State lives in `$DSH_HOME/boost/` (`$DSH_HOME` falls back to `~/.dsh` when unset):
327
+
328
+ - `scope.json` — the single source of truth for the exposure surface (version 2, with revision).
329
+ - `scope.lock` — the short-lived write lock, removed after a normal write.
330
+ - `receipts/<encoded-session>.jsonl` — append-only receipts. Every line carries metadata, a
331
+ preview of the first 256 code points of the receipt (never the full stdout), and **the bound
332
+ arguments `args` (model-written, capped to 2048 code points, stored as visibly truncated JSON
333
+ with an `args_truncated` flag when oversized — `write` / `edit` arguments can carry whole file
334
+ contents and land here too)**. **Only substitution receipts** (`substitute` /
335
+ `substitute-settled` / `shadow`) also carry the plan goal (≤256 code points) and guards (≤8,
336
+ each ≤300 code points); projection and skip receipts carry `preview` and `args` but no plan
337
+ evidence.
338
+
339
+ `boost status` replays the projection ledger at each receipt's own `horizon_steps`; a receipt
340
+ written before that field existed is replayed at the current horizon and counted in
341
+ `projection_horizon_reestimated`, while `projection_horizon_steps` reports the horizon currently
342
+ in effect (the minimum over live sessions, falling back to `horizonSteps` when no history exists).
343
+
344
+ With `projection: 'on'`, the complete original is written to the host spill backend **before** the
345
+ replacement happens, and the footer locator can be read with `read` / `grep`. Projection never
346
+ discards the only copy; if the spill write fails, nothing is replaced (the receipt records
347
+ `projection-skipped:spill-failed`; a footer rendering failure records
348
+ `projection-skipped:footer-failed`; a missing footer renderer records
349
+ `projection-skipped:no-footer`, see "Host dependencies").
350
+
351
+ Rollback and disablement (the `baseRevision` values below are `3` after the enable path above and
352
+ `4` after the first rollback; in practice always use the `data.scope.revision` you just read from
353
+ `status`, never copy these):
354
+
355
+ - **Turn both behaviours off** (no projection, no substitution; the protocol section is still
356
+ injected for every still-visible workspace — the selected ones under `selected`, every defined
357
+ one under `global` — substitution decisions are still recorded in shadow, and the fixed
358
+ overhead remains):
359
+
360
+ ```json
361
+ { "cmd": "scope-set", "body": { "projection": "off", "shadow": true }, "baseRevision": 3 }
362
+ ```
363
+
364
+ - **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 unconditionally true under
366
+ `mode:"global"` (`src/scope/doc.ts` — the `global` branch never reads the list), so **while in
367
+ `global`, writing only `workspaceIds: []` stops nothing** — projection and substitution keep
368
+ running while you believe you have rolled back. Under `selected`, removing one workspace is
369
+ enough; under `global` you must switch the mode at the same time:
370
+
371
+ ```json
372
+ { "cmd": "scope-set", "body": { "mode": "selected", "workspaceIds": [] }, "baseRevision": 4 }
373
+ ```
374
+
375
+ With `selected` and an empty list the protocol section, projection, and substitution all stop
376
+ (only the `boost` tool schema's standing cost remains).
377
+
378
+ - **Uninstall the plugin**: `dsh plugin --profile <name> remove dsh-boost`, then restart DSH.
379
+ - Deleting `$DSH_HOME/boost` clears the scope and receipts (back to defaults), but does not delete
380
+ the original files already written to the host spill backend.
381
+
382
+ ## Host dependencies
383
+
384
+ `inject` lists hard dependencies: `tools`, `systemPrompt`. Missing either makes the plugin fail
385
+ to load. `llm` is soft (only the selector uses it); when absent the selector falls back with
386
+ `selector-unavailable` and the rest of projection and substitution keeps working.
387
+
388
+ | Dependency | Form | When missing |
389
+ |---|---|---|
390
+ | `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
+ | `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
+ | `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) |
394
+ | `@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
+ | `win32` platform | runtime `isPosixOnly()` check | Substitution is refused, projection still works; `status.degraded` reports `ERR_HOST_PLATFORM_UNSUPPORTED` |
396
+ | 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 `$DSH_HOME/boost/receipts/`, fix, and re-run `status`, comparing counts |
398
+ | 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
+ | 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
+
401
+ `ERR_HOST_NO_STEP_WHEN` no longer exists: step-level `when` has been part of
402
+ `ToolRegistrationOptions` since the oldest host line this package declares, so the plugin no
403
+ longer probes it and registers unconditionally.
404
+
405
+ Several registration codes are log-only and never enter `status.degraded`: a non-duplicate throw
406
+ while registering the protocol section logs `ERR_BOOST_SECTION_REGISTER_FAILED`; `registerHooks`
407
+ stops at the first mount, so the substitution, projection, and execute hooks are never registered
408
+ and the request path is effectively inert, while the `boost` tool and session events are still
409
+ attempted. The host's genuine duplicate-section error logs `ERR_BOOST_ALREADY_MOUNTED` and skips
410
+ this mount; a failure to register the `boost` tool itself logs
411
+ `ERR_BOOST_TOOL_REGISTER_FAILED`.
412
+
413
+ `ERR_HOST_NO_TOKENMETER` and `ERR_HOST_NO_ESTIMATOR` are **two different things**; do not merge
414
+ them. The first is the host service (`ctx.get('tokenMeter')`) being absent, which refuses
415
+ substitution. The second is the pure estimate package
416
+ `@deepseek-ai/dsh-token-meter/estimate` being unreachable, which only makes the fixed-overhead
417
+ figure unknown. One can exist without the other, and merging them sends the operator to the wrong
418
+ host. `ERR_HOST_NO_SPILL` (no spill backend) and `ERR_HOST_NO_SPILL_NOTICE` (backend present, no
419
+ footer renderer) are also two different things with different fixes.
420
+
421
+ `ERR_HOST_NO_SPILL` has two halves: the **live host probe** reports it only with
422
+ `projection: 'on'` (shadow mode never touches spill, so reporting it there would be noise); the
423
+ **receipt channel** does not look at the current mode — any historical receipt carrying
424
+ `projection-skipped:no-spill` maps to this code, so after you switch projection back to `off`, an
425
+ old receipt keeps it in `degraded`.
426
+
427
+ `tokenMeter` and `spillStore` must not be added to `inject`: with a host that lacks them the
428
+ plugin would fail to load outright, and the "refuse substitution, keep projecting, preserve
429
+ evidence" degraded path would be unreachable.
430
+
431
+ ## Scope of v1
432
+
433
+ - Only two things: **replace tool receipts in place** and **substitute read-only calls** (`read` /
434
+ `grep` / `glob`).
435
+ - **No batched tool execution** (no PTC / `run_code`; design N1).
436
+ - **No deduplication or merging of tool calls** (design N5) — this was not started at all, and
437
+ v1 ships **no tool that measures duplicate-call rate**: the "shadow-week duplication
438
+ statistic" the design reserved as its restart trigger was never delivered; `shadow-report.mjs`
439
+ does not produce it.
440
+ - **The shadow week saves nothing by design**: it only records (the protocol section is still
441
+ 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 regression gate,
443
+ no quality metric; whether substituted outcomes are better is unjudgeable in v1.
444
+ - **Installed but not enabled is a small net loss**: the `boost` tool registers as soon as the
445
+ plugin is assembled, and its schema costs a measured 399 tokens on every request (see the
446
+ breakdown in "Enable it") while yielding nothing.
447
+ - **No desktop profile** (design D6).
448
+ - Does not replace or take over DSH's compaction, pruning, or spill decisions (design N3);
449
+ projection changes only the model-visible content and keeps the original in the host spill.
450
+ - No model training or weight changes (N2); no attempt at the paper's 87.93% (N4).
451
+ - No 10% promise: 3.5% is the floor and 10% the ideal upper bound; the shadow week tells you
452
+ whether to proceed, but it cannot replace the range with a measurement (`shadow-report.mjs`
453
+ emits four ratios and no total-token denominator).
454
+
455
+ ## Documentation
456
+
457
+ These documents live in the **repository**, not in the npm tarball (`files` ships only `dist`,
458
+ `locale`, `cordis.patch.yml`, both READMEs, `LICENSE`, and `NOTICE`; `src/` is not shipped
459
+ either, and the `dist` source maps inline the sources). If you are reading on
460
+ the npm page, open them from the repository.
461
+
462
+ The source and docs live in the repository at
463
+ [github.com/SAXEM1997/dsh-boost](https://github.com/SAXEM1997/dsh-boost); `package.json` points
464
+ `repository`, `homepage`, and `bugs` at it. The document links below are repository-relative.
465
+
466
+ | Document | Contents |
467
+ |---|---|
468
+ | [Design](docs/superpowers/specs/2026-11-18-dsh-token-efficiency-design.md) | Goals, evidence, architecture, contracts, measurement, risks, release shape |
469
+ | [Host contracts appendix](docs/superpowers/plans/2026-11-18-host-contracts.md) | Interface reference copied line by line from the host sources |
470
+ | [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 gate, and the shadow week and stats recompute |
472
+
473
+ ## License
474
+
475
+ Apache-2.0. The mechanisms are ported from [HarnessMM](https://github.com/YuhuaJiang2002/HarnessMM)
476
+ (Apache-2.0); a `NOTICE` ships with the package.