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.
- package/LICENSE +202 -0
- package/NOTICE +29 -0
- package/README.en.md +476 -0
- package/README.md +408 -2
- package/cordis.patch.yml +40 -0
- package/dist/admission/fixed-cost.d.ts +23 -0
- package/dist/admission/fixed-cost.js +61 -0
- package/dist/admission/fixed-cost.js.map +1 -0
- package/dist/admission/ledger.d.ts +113 -0
- package/dist/admission/ledger.js +176 -0
- package/dist/admission/ledger.js.map +1 -0
- package/dist/admission/retrieval.d.ts +65 -0
- package/dist/admission/retrieval.js +162 -0
- package/dist/admission/retrieval.js.map +1 -0
- package/dist/admission/usage.d.ts +75 -0
- package/dist/admission/usage.js +124 -0
- package/dist/admission/usage.js.map +1 -0
- package/dist/config.d.ts +43 -0
- package/dist/config.js +103 -0
- package/dist/config.js.map +1 -0
- package/dist/gate/binding.d.ts +113 -0
- package/dist/gate/binding.js +297 -0
- package/dist/gate/binding.js.map +1 -0
- package/dist/gate/decide.d.ts +82 -0
- package/dist/gate/decide.js +163 -0
- package/dist/gate/decide.js.map +1 -0
- package/dist/gate/guard.d.ts +69 -0
- package/dist/gate/guard.js +195 -0
- package/dist/gate/guard.js.map +1 -0
- package/dist/gate/invalidate.d.ts +112 -0
- package/dist/gate/invalidate.js +111 -0
- package/dist/gate/invalidate.js.map +1 -0
- package/dist/gate/plan.d.ts +86 -0
- package/dist/gate/plan.js +222 -0
- package/dist/gate/plan.js.map +1 -0
- package/dist/hooks/clock.d.ts +68 -0
- package/dist/hooks/clock.js +82 -0
- package/dist/hooks/clock.js.map +1 -0
- package/dist/hooks/execute.d.ts +79 -0
- package/dist/hooks/execute.js +128 -0
- package/dist/hooks/execute.js.map +1 -0
- package/dist/hooks/llm-stream.d.ts +276 -0
- package/dist/hooks/llm-stream.js +1008 -0
- package/dist/hooks/llm-stream.js.map +1 -0
- package/dist/hooks/pending.d.ts +89 -0
- package/dist/hooks/pending.js +115 -0
- package/dist/hooks/pending.js.map +1 -0
- package/dist/hooks/post-execute.d.ts +247 -0
- package/dist/hooks/post-execute.js +1776 -0
- package/dist/hooks/post-execute.js.map +1 -0
- package/dist/hooks/session-state.d.ts +158 -0
- package/dist/hooks/session-state.js +168 -0
- package/dist/hooks/session-state.js.map +1 -0
- package/dist/hooks/synthesize.d.ts +74 -0
- package/dist/hooks/synthesize.js +100 -0
- package/dist/hooks/synthesize.js.map +1 -0
- package/dist/host/loader.d.ts +23 -0
- package/dist/host/loader.js +31 -0
- package/dist/host/loader.js.map +1 -0
- package/dist/host/platform.d.ts +18 -0
- package/dist/host/platform.js +19 -0
- package/dist/host/platform.js.map +1 -0
- package/dist/host/root.d.ts +18 -0
- package/dist/host/root.js +43 -0
- package/dist/host/root.js.map +1 -0
- package/dist/index.d.ts +13 -0
- package/dist/index.js +866 -0
- package/dist/index.js.map +1 -0
- package/dist/projection/apply.d.ts +174 -0
- package/dist/projection/apply.js +137 -0
- package/dist/projection/apply.js.map +1 -0
- package/dist/projection/canonicalise.d.ts +43 -0
- package/dist/projection/canonicalise.js +43 -0
- package/dist/projection/canonicalise.js.map +1 -0
- package/dist/projection/counters.d.ts +65 -0
- package/dist/projection/counters.js +88 -0
- package/dist/projection/counters.js.map +1 -0
- package/dist/projection/truncate.d.ts +47 -0
- package/dist/projection/truncate.js +57 -0
- package/dist/projection/truncate.js.map +1 -0
- package/dist/prompt/protocol.d.ts +45 -0
- package/dist/prompt/protocol.js +56 -0
- package/dist/prompt/protocol.js.map +1 -0
- package/dist/receipts/store.d.ts +198 -0
- package/dist/receipts/store.js +734 -0
- package/dist/receipts/store.js.map +1 -0
- package/dist/scope/doc.d.ts +117 -0
- package/dist/scope/doc.js +158 -0
- package/dist/scope/doc.js.map +1 -0
- package/dist/scope/resolve.d.ts +91 -0
- package/dist/scope/resolve.js +146 -0
- package/dist/scope/resolve.js.map +1 -0
- package/dist/scope/store.d.ts +135 -0
- package/dist/scope/store.js +573 -0
- package/dist/scope/store.js.map +1 -0
- package/dist/selector/jev.d.ts +93 -0
- package/dist/selector/jev.js +171 -0
- package/dist/selector/jev.js.map +1 -0
- package/dist/tools/boost.d.ts +367 -0
- package/dist/tools/boost.js +768 -0
- package/dist/tools/boost.js.map +1 -0
- package/dist/tools/family.d.ts +26 -0
- package/dist/tools/family.js +26 -0
- package/dist/tools/family.js.map +1 -0
- package/dist/types.d.ts +113 -0
- package/dist/types.js +21 -0
- package/dist/types.js.map +1 -0
- package/locale/en.json +6 -0
- package/locale/zh.json +6 -0
- 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.
|