dsh-boost 0.0.0-stage → 0.1.1

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