dsh-context-truth 0.1.3 → 0.3.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/CHANGELOG.md +233 -0
- package/README-en.md +94 -7
- package/README.md +163 -7
- package/lib/client.js +154 -0
- package/lib/index.js +1839 -46
- package/package.json +14 -1
- package/test/client.test.js +59 -0
- package/test/index.test.js +1352 -26
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,238 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.3.0
|
|
4
|
+
|
|
5
|
+
> **新增能力 3 的第二形态:交接式折叠(`foldMode: handoff`,实验性)。** 默认模式改为 `idle`
|
|
6
|
+
> (即本插件此前的空闲边界折叠)。详细的背景、实测与护栏见 README 的「交接式折叠」一节。
|
|
7
|
+
|
|
8
|
+
### 新增
|
|
9
|
+
|
|
10
|
+
* **`handoff` 折叠模式(实验性)**:读数到达准备点(`handoffAt` × 折叠点,默认 85%)时注入提醒,
|
|
11
|
+
给出唯一允许的交接档路径(`$DSH_HOME/handoffs/<sessionId>/<fold#>.handoff.md`,绝不进工作区);
|
|
12
|
+
模型写完档后调用新工具 `handoff_ready` 登记;该轮结束时插件真正调用 `compactNow()`;折叠后
|
|
13
|
+
`followup` **只激活一轮**,第一条指令就是先读档再继续。基线:143 次折叠里 81 次(57%)在折叠后
|
|
14
|
+
重新读取了自己刚写过的文件,合计 225 次——这个机制针对的就是这部分重复劳动。
|
|
15
|
+
* **设置卡**(`lib/client.js` + `package.json` 的 `dsh.client` / `exports["./client"]`):在插件页
|
|
16
|
+
注册 `plugins.bundle.config`(key = 包名),渲染“折叠模式”下拉框,读写走
|
|
17
|
+
`settings.describe()` / `settings.mutate()`。DSH 不会按 `Config` schema 自动生成插件设置表单,
|
|
18
|
+
没有这张卡时只能改 profile patch。
|
|
19
|
+
* 工具 `handoff_ready` 在所有模式下都注册(设置卡需要能随时切换模式),只在 `handoff` 模式下生效。
|
|
20
|
+
|
|
21
|
+
### 变更
|
|
22
|
+
|
|
23
|
+
* **默认模式改为 `idle`**:没写过 `foldMode` 的配置按 `idle` 解析(它就是此前的行为,当时由
|
|
24
|
+
`foldAtIdle: true` 打开);显式 `foldAtIdle: false` 仍解析为 `off`,不会被这次改默认值带走。
|
|
25
|
+
* **模式切换立即生效**:`foldMode` 是 volatile 配置,设置卡写进运行中的引用,插件每次调用重新解析
|
|
26
|
+
选项。实测:面板切到 `handoff` 后,运行中的实例在下一次调用就按 handoff 执行(`handoff_ready`
|
|
27
|
+
直接给出了本会话的交接档路径,而不是“不在 handoff 模式”的拒绝)。切换本身不会触发折叠。
|
|
28
|
+
* README/README-en:更正“不注册工具”“无客户端”“无落盘状态”等已过时的表述,补上工具、设置卡、
|
|
29
|
+
handoff 状态文件与实验性标签。
|
|
30
|
+
|
|
31
|
+
### 修复(均来自实机演练)
|
|
32
|
+
|
|
33
|
+
* **回收不再删掉激活目标**:准备轮 N+1 发生在激活轮 N 里,旧实现会把 fold N 的交接档当旧档删掉,
|
|
34
|
+
激活轮第一条 `read` 得到 `FS_NOT_FOUND`(实测时间线:激活 18:39:58.877 → 回收 18:40:03.431 →
|
|
35
|
+
读档 18:40:04.983)。现在按编号保留当前折叠的档。
|
|
36
|
+
* **提醒不再等人开口**:`agent.inject` 只排进下一次请求;提醒落在模型最后一步时,会话空闲后
|
|
37
|
+
要等人类发消息才会被读到(实测:18:48:04.482 注入,直到人发消息才出现)。现在轮末若已过准备点
|
|
38
|
+
且没登记,会用 `followup` 唤醒一轮把提醒送到,次数计入同一份提醒预算。
|
|
39
|
+
* **唤醒轮不再叠第二条提醒**:唤醒时把该轮记为“已提醒”,同一轮后续 step 不再注入。
|
|
40
|
+
* **`handoff prep` 日志的数值**:之前打印的是准备点却写成 “fold point”,现在打印真正的折叠点。
|
|
41
|
+
|
|
42
|
+
### 验证
|
|
43
|
+
|
|
44
|
+
* `npm run check` 通过;`npm test` **69/69**。
|
|
45
|
+
* 变异测试:去掉“保留当前折叠档”的判定 → 3 条测试失败;把轮末 `followup` 改成 `inject` → 1 条失败;
|
|
46
|
+
去掉唤醒轮的“已提醒”标记 → 1 条失败;每次恢复后按字节比对一致。
|
|
47
|
+
* 实机:准备提醒 → 写档 → 登记 → 轮末真实折叠(`folded … at the round end via service (fold #1)`)
|
|
48
|
+
→ 插件自行激活唯一一轮 → 激活轮首条动作是读档。
|
|
49
|
+
|
|
50
|
+
## 0.2.0
|
|
51
|
+
|
|
52
|
+
> **能力 3(空闲边界折叠)能否工作,取决于接缝对插件是否可达——而"可达"取决于挂载组合,不是
|
|
53
|
+
> "官方 vs 第三方"。**(这一节先后写错过两次,以下是 2026-10-12 的实测版。)
|
|
54
|
+
>
|
|
55
|
+
> 最终设计的三条,都是实测逼出来的:
|
|
56
|
+
> 1. **`inject` 只声明 `['systemPrompt','tokenMeter']`。** 声明 `compaction` 会让条目**永久
|
|
57
|
+
> pending**——插件完全不加载,第 1 个能力的占用行也一起消失。已向上游报告
|
|
58
|
+
> [deepseek-harness#9425](https://github.com/deepseek-ai/deepseek-harness/discussions/9425)。
|
|
59
|
+
> 2. **服务按候选链解析,不用 `ctx.get`**:`agent.ctx` → `ctx` → 已接线服务,取第一个**真的带
|
|
60
|
+
> `compactNow`** 的(不是"第一个不是 undefined 的"——对一个本 fiber 没有的服务做属性读取会返回
|
|
61
|
+
> **诊断字符串**,早期版本把那个字符串当成"找到了",于是引擎一直可达、折叠却永不触发)。
|
|
62
|
+
> 3. **启动那行诊断只反映插件自身 ctx 的可见性**,不能用来判断折叠能否工作:本 profile 现在打印的
|
|
63
|
+
> 正是 `compaction=undefined/none`,而折叠在 2026-10-12 成功跑了两次。
|
|
64
|
+
>
|
|
65
|
+
> 实测(本 profile:`dsh-dcp` **禁用**,profile patch 末尾重新启用官方
|
|
66
|
+
> `@deepseek-ai/dsh-compaction-basic`):
|
|
67
|
+
> - 2026-10-12 **16:07** 与 **21:46** 两次**自动**空闲折叠均成功,日志为
|
|
68
|
+
> `folded at idle via service (headroom=46558 margin=50000)` / `(headroom=43789 …)`;触发都落在
|
|
69
|
+
> 回合边界上(`turn/end` 之后 13–30 毫秒),占用分别从 631K / 634K 降到 178K / 205K。
|
|
70
|
+
> - 服务通道解析到的就是官方引擎,**它会真的调用 LLM 摘要**:21:46 那次用量为输入 600 +
|
|
71
|
+
> 缓存命中 633,600 + 输出 3,743(命中 **99.9%**,折叠区域 432,321 token,墙钟 21 秒)。
|
|
72
|
+
> - 因此 dcp 时代的结论("官方不可达、只有 dcp 可达")**作废**:那是在官方后端被 dcp 的 bundle
|
|
73
|
+
> patch 整个禁用的配置下测的——引擎压根没有挂载。
|
|
74
|
+
>
|
|
75
|
+
> **折叠请求有两条通道(`foldAtIdleMethod`)**:
|
|
76
|
+
> 1. **命令通道**:`ctx.commands.execute(agent, '/compact', [], signal)` —— 走**该 agent 的 realm
|
|
77
|
+
> 视图**,因此落到该会话本该用的那个后端上(与人类敲 `/compact` 完全一致),折叠风格与会话自身一致。
|
|
78
|
+
> 2. **服务通道**:候选链里第一个带 `compactNow` 的实现,也是 realm 没注册 `compact` 命令时唯一的
|
|
79
|
+
> 办法。本 profile 显式选 `service`(最可预测),实测可用。
|
|
80
|
+
> 命令通道失败(realm 无该命令、或拒绝)会**自动回退**到服务通道;两者都不通时只记一次说明日志。
|
|
81
|
+
>
|
|
82
|
+
> **与 dsh-dcp 的分工(若你挂它)**:它的轮数触发(`roundInterval`,默认每 50 条 assistant message、
|
|
83
|
+
> 在空闲边界)是**活动驱动**的,本插件是**压力驱动**的(余量进入窗口 5%、在同一个空闲边界执行);
|
|
84
|
+
> 任何一次折叠都会重置它的轮数时钟,所以两者不会互相打转。本 profile 已禁用它,配置与回退配方见
|
|
85
|
+
> profile patch 注释。
|
|
86
|
+
>
|
|
87
|
+
> **dsh-dcp 的"关掉官方后端 + 接管接缝"只作用于它自己所在的那一层**(我们一开始也写错了):
|
|
88
|
+
> 每个 agent preset 里还有一个 `cordis:group` realm,里面**各自挂着一份** `compaction-basic` +
|
|
89
|
+
> `command-compact`。所以同一进程里可能同时存在两个后端——这也正是那个坑的来源:**只关 dcp 而不
|
|
90
|
+
> 重开官方 = 零后端;只开 dcp 而不删重开行 = 双后端同时注册 `compaction`。改它们必须成对。**
|
|
91
|
+
|
|
92
|
+
- **Capability 3: fold at the idle boundary (`foldAtIdle`, off by default).** The host's automatic
|
|
93
|
+
compaction only fires when the meter *crosses* the point, and the behaviour a model adopts as it
|
|
94
|
+
approaches — batching round trips, refusing risky edits, stopping mid-iteration to commit WIP —
|
|
95
|
+
is precisely what keeps the reading below it. Measured on a live session: **four hours with no
|
|
96
|
+
fold, every turn 2–8 steps long, three consecutive "continue" instructions unable to finish the
|
|
97
|
+
same task**, the reading parked at `Under 10K tokens of headroom remain`, and the model declining
|
|
98
|
+
a patch to a 584 KB generator because "I can't verify much in 10K". The fix is not wording (four
|
|
99
|
+
rounds of that changed narration, not the equilibrium): it is *when* the fold happens. This
|
|
100
|
+
capability calls the official `compaction.compactNow()` at the model's own turn boundary
|
|
101
|
+
(`agent/status === 'idle'`) once the headroom is within 5% of the window. The engine only accepts
|
|
102
|
+
that call while the agent is idle, so the timing is the supported one; a fold pushes the headroom
|
|
103
|
+
back into the hundreds of thousands, so it fires **once per cycle**. Failure is logged and
|
|
104
|
+
swallowed, attempts are rate-limited, and a missing compaction service warns exactly once — a
|
|
105
|
+
trigger must never break a turn.
|
|
106
|
+
- **Configuration lives in the profile patch, and applies live.** The plugin exports a Schemastery
|
|
107
|
+
`Config` and the host registers it — the settings service reports `ns=context-truth`,
|
|
108
|
+
`applies=live`, and a `value` carrying the patch's override. But this DSH build has **no generic
|
|
109
|
+
renderer** for a third-party plugin's form: every plugin whose settings page exists (subagent,
|
|
110
|
+
shell, agent-loop, web-search) ships a hand-written card in its own *client* package, and the
|
|
111
|
+
generic `plugins.row.config` slot is registered by nobody. So the switches go where `subagent`'s
|
|
112
|
+
`maxDepth` goes:
|
|
113
|
+
```yaml
|
|
114
|
+
- id: context-truth
|
|
115
|
+
config:
|
|
116
|
+
foldAtIdle: true
|
|
117
|
+
```
|
|
118
|
+
Verified live: editing that row flipped `foldAtIdle` to `true` in the running config with **no
|
|
119
|
+
restart** (`patchReload: live`). Three host details are load-bearing, and the first attempt got all
|
|
120
|
+
three wrong — it rendered no form, then silently disabled capability 2:
|
|
121
|
+
- The settings service builds its form with `volatileForm(schema)`, which keeps only nodes marked
|
|
122
|
+
`.volatile()`. Every field carries the marker now; `enabled` is the deliberate exception, because
|
|
123
|
+
it decides whether the line is registered at all.
|
|
124
|
+
- A volatile change is committed **into the running reference** (`loader._commitVolatile` →
|
|
125
|
+
`updateVolatile`) rather than by reloading the plugin. Options are therefore resolved on every
|
|
126
|
+
use instead of snapshotted in `apply`, the listeners install unconditionally and gate themselves
|
|
127
|
+
per event, and a config value that arrives as a reference cell is unwrapped exactly as the host's
|
|
128
|
+
own adapters do (`plainOptions`). Without that, an edit in the patch would have changed nothing
|
|
129
|
+
until the next restart — a worse failure than a missing form, because it looks like it worked.
|
|
130
|
+
- **A field with no schema default is materialized as `[]`**, and for `compactionRules` `[]` means
|
|
131
|
+
"append nothing" — so adding the schema switched capability 2 off silently until the default was
|
|
132
|
+
given the real rules. A test now pins every schema default against `DEFAULT_OPTIONS`.
|
|
133
|
+
This costs the plugin its zero-dependency claim: `@deepseek-ai/schemastery` is now a declared peer
|
|
134
|
+
dependency (published on npm, and already shipped by every host that runs the plugin).
|
|
135
|
+
- **The idle fold's first live trigger folded nothing: `ctx.get` is not how a service is reached.**
|
|
136
|
+
At 22:44 the trigger itself was correct — inside the 5% margin, at an idle boundary — and the log
|
|
137
|
+
said so: `foldAtIdle is enabled but no compaction service is mounted; not folding`. `ctx.get(name)`
|
|
138
|
+
resolves through `ctx.reflect`, and it returned nothing for `compaction` from this plugin's context.
|
|
139
|
+
The occupancy line had been quietly surviving on the `contextPressure` projection fallback.
|
|
140
|
+
- **The wiring went through three designs; the first two are recorded here because their failure modes
|
|
141
|
+
are the trap.** (1) `ctx.get('compaction')` returned nothing — a service is not reached that way, and
|
|
142
|
+
the occupancy line had been quietly surviving on the `contextPressure` projection fallback. (2)
|
|
143
|
+
`ctx.inject(['compaction'], cb)` never ran its callback, and **declaring `compaction` in `inject`
|
|
144
|
+
left the entry pending forever** — the plugin did not load at all, taking capability 1 with it.
|
|
145
|
+
(3) the shipped design: `inject` stays `['systemPrompt','tokenMeter']`, and the fold resolves the
|
|
146
|
+
service through a **ranked candidate chain** (`agent.ctx` → `ctx` → wired service), taking the first
|
|
147
|
+
candidate that **actually carries `compactNow`** — never "the first that is not undefined", because
|
|
148
|
+
a property read for a service this fiber does not have answers with a **diagnostic string**. Services
|
|
149
|
+
are resolved **per use**, never snapshotted, and a one-line startup diagnostic reports what the
|
|
150
|
+
plugin's own context can see. Measured 2026-10-12: two automatic idle folds resolved the official
|
|
151
|
+
engine through that chain and completed (16:07 and 21:46) while the startup line printed
|
|
152
|
+
`compaction=undefined/none` — so the diagnostic is not a readiness check for capability 3.
|
|
153
|
+
- **Capability 2 rides the seam, byte-for-byte.** Captured on both 2026-10-12 folds: the trailing
|
|
154
|
+
directive on the wire is the patched one — **2,336 characters** (1,802 original + 534 of rules), all
|
|
155
|
+
three rule markers present, and the request lands **19 ms** after `compaction-cache: aligned` logs the
|
|
156
|
+
same call (21:46:08.085 / .104) — two plugins cross-validating each other on the same `llm/stream`
|
|
157
|
+
waterfall. The patched trailing message is **not frozen** (the plugin replaces the array slot, so the
|
|
158
|
+
engine's `deepFreeze` on the appended message does not apply). Cost: **+534 characters ≈ +134 tokens
|
|
159
|
+
(+0.09%)**, appended *after* the cached prefix, so that is the only fresh full-price input a fold adds.
|
|
160
|
+
- Five more tests (49 total): the idle fold's trigger and its guards (running agent, calm session,
|
|
161
|
+
in-flight attempt, missing service, rejected call), the pure decision function it is built on, the
|
|
162
|
+
wiring that delivers the service, a reference cell flipped at runtime to prove a settings change
|
|
163
|
+
lands without a reload, and the schema-default invariant above.
|
|
164
|
+
|
|
165
|
+
## 0.1.4
|
|
166
|
+
|
|
167
|
+
- **The `tight` band stopped talking about compaction, and this is the change that matters most.**
|
|
168
|
+
Three successive wordings were tried in the field: 0.1.3 ordered a hand-off, 0.1.4 described the
|
|
169
|
+
coming fold, and both made the model *narrate* compaction in its own replies and lose momentum —
|
|
170
|
+
worst in the one band that re-injects most often. A live session made it measurable: the tight
|
|
171
|
+
band was committed **333 times**, median gap 45s with runs of 4–20s, so the model read a fresh
|
|
172
|
+
fold notice every step or two. The default (`tightAdvice: 'none'`) now adds **no closing sentence
|
|
173
|
+
at all** — the numbers are the message — `'inform'` restores the 0.1.4 sentence and `'stop'` the
|
|
174
|
+
0.1.3 imperative.
|
|
175
|
+
- **The line says outright that it is telemetry, not a task — and not an allowance to draw down.**
|
|
176
|
+
The closing clause now reads "Background telemetry from the host, and the only authority on
|
|
177
|
+
context pressure: do not mention it, do not estimate or count it down yourself — it is restated
|
|
178
|
+
whenever it changes — and take no action about compaction; the host folds between steps
|
|
179
|
+
automatically." Both halves are evidence-driven. Compaction is host-owned and needs nothing from
|
|
180
|
+
the model, so saying so removes the impulse to plan or announce it — and a live session showed why
|
|
181
|
+
the second half is needed too: the model read the figure correctly, then spent it in its head
|
|
182
|
+
across the following steps (`30K → 28K → 16K → 10K → 7K → 5K`) while the host's number sat still at
|
|
183
|
+
`About 10K` (it is restated only when it changes). Twelve minutes later it announced "Context is
|
|
184
|
+
nearly exhausted (~5K)", a figure the host never reported. A measurement has to be labelled a
|
|
185
|
+
measurement.
|
|
186
|
+
- **The line now also answers "how much context do I have left".** It always printed the headroom to
|
|
187
|
+
the fold and never the free window. A live model answered the first question with the second figure
|
|
188
|
+
and announced "Very low context" at 10K of headroom while **350K of the window was free** — both
|
|
189
|
+
numbers true, only one of them an answer. Every band now carries `About 300K of the window is still
|
|
190
|
+
free`, and **no figure was removed**: dropping the headroom near the fold was considered and
|
|
191
|
+
rejected, because both endpoints (used, and the fold point) stay printed, so the model can subtract
|
|
192
|
+
them anyway — suppressing a derivable number would re-create the original bug's precondition (no
|
|
193
|
+
ground truth) exactly where speculation is most likely. Quantized onto the same display step as
|
|
194
|
+
`used`, so it adds no re-injection of its own; `freeClause: false` removes it.
|
|
195
|
+
- **The small bands now define what the fold is.** The numbers alone left a gap a live session walked
|
|
196
|
+
into: eleven seconds after the line said `Under 10K tokens of headroom remain before it`, the model
|
|
197
|
+
wrote "Very low context. I must do this in as few commands as possible, then a short answer." It had
|
|
198
|
+
read the figure correctly — it took "room before the fold" to mean "context left", while the window
|
|
199
|
+
still held 350K and the fold only reorganizes it. The `tight` band now adds "The fold is routine,
|
|
200
|
+
not the end of the window: older turns become a summary and work continues after it", and `critical`
|
|
201
|
+
the shorter "The window is not exhausted — work continues after the fold." Both are definitions,
|
|
202
|
+
not instructions — nothing to do, nowhere to go — so neither can become the 0.1.3 "hand off" nudge.
|
|
203
|
+
`foldClause: false` removes them.
|
|
204
|
+
- **The remaining-headroom step stays coarse near the point.** It used to shrink to 2K as the room
|
|
205
|
+
ran out — precisely where the line re-injects most — so the figure ticked on nearly every step.
|
|
206
|
+
The floor is now 10% of the window quantum (10K on a 1M window): within a few tens of thousands
|
|
207
|
+
of tokens the pace estimate is the useful signal, and a remainder smaller than one step still
|
|
208
|
+
renders honestly as `Under 10K`. Over a walk from 128K of headroom down to zero the line now
|
|
209
|
+
re-commits **11 times instead of 23**.
|
|
210
|
+
- **The remaining headroom is translated into this session's own pace.** In the `tight` and
|
|
211
|
+
`critical` bands the line reports how many more steps the headroom covers — `At this
|
|
212
|
+
session's recent rate that is roughly 6 more steps.` It is measured, not guessed: the per-step
|
|
213
|
+
growth is the median of recent deltas between step boundaries, taken from the host's own
|
|
214
|
+
`(turn, step)` counter together with the meter reading the line already reports.
|
|
215
|
+
- **A fold re-base discards the pace history instead of poisoning it.** After a compaction the
|
|
216
|
+
meter re-bases (measured in a live session: 200K → under 50K within three seconds); that
|
|
217
|
+
negative delta resets the samples, so the estimate disappears and is re-earned rather than
|
|
218
|
+
averaged against a stale baseline.
|
|
219
|
+
- **Bucketed, rounded down, and settled.** The figure is bucketed onto `1 / 2 / 3 / 5 / 8 / 13 / 20+`
|
|
220
|
+
— the same direction as the headroom itself, so the line never promises more remaining steps than
|
|
221
|
+
the session's own rate supports. The first build of this feature published the rung directly and
|
|
222
|
+
a live session showed why that fails: the raw count ranged 23–38 across consecutive steps,
|
|
223
|
+
straddled a `21 / 34` boundary, and flipped the line four times in 90 seconds — one snapshot
|
|
224
|
+
re-commit caused by nothing but the flip. The top rung is therefore open-ended (`20+`, where the
|
|
225
|
+
exact figure changes no decision), and the rung settles like a band: downward takes effect at once
|
|
226
|
+
(less room is never held back), upward must clear the higher rung by `paceMargin` (0.25) so a
|
|
227
|
+
straddling estimate cannot flip the line while a genuinely slower session still gets the higher
|
|
228
|
+
figure. Replayed against the observed sequence, the rung now renders once instead of five times.
|
|
229
|
+
- **Display-only.** It never moves a band edge, the threshold, or any decision to fold. With
|
|
230
|
+
`paceEstimate: false`, or on a host that exposes no step counter, the published line is
|
|
231
|
+
byte-for-byte what 0.1.3 produced.
|
|
232
|
+
- 42 unit tests (was 28): step-boundary sampling, re-assembly inside one step, fold re-basing,
|
|
233
|
+
median robustness against a 90K tool dump, rung rounding and settling (including a replay of the
|
|
234
|
+
observed flip sequence), the two `tight` wordings, and byte-identity when the pace feature is off.
|
|
235
|
+
|
|
3
236
|
## 0.1.3
|
|
4
237
|
|
|
5
238
|
Four changes, all from capturing a real compaction request in a live session (and from the host
|
package/README-en.md
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
|
|
5
5
|
> Give the model its **real** context occupancy — measured by the host and re-injected every turn — and stop the false claim "context is nearly exhausted" from surviving compaction.
|
|
6
6
|
|
|
7
|
-
A DSH (DeepSeek Harness) plugin ·
|
|
7
|
+
A DSH (DeepSeek Harness) plugin · one peer dependency (the host's own `schemastery`) · needs the host services `tokenMeter` and `compaction` (both shipped by `dsh-base`) · 1 tool (`handoff_ready`, used by handoff folding) · 1 client settings card · no build step · MIT
|
|
8
8
|
|
|
9
9
|
---
|
|
10
10
|
|
|
@@ -21,7 +21,7 @@ Worse, that wrong call **survives compaction**:
|
|
|
21
21
|
|
|
22
22
|
This plugin cuts both ends of that chain.
|
|
23
23
|
|
|
24
|
-
##
|
|
24
|
+
## Three capabilities
|
|
25
25
|
|
|
26
26
|
### 1. Measured occupancy line (on by default)
|
|
27
27
|
|
|
@@ -37,6 +37,18 @@ estimate it from the conversation's length.
|
|
|
37
37
|
|
|
38
38
|
Four bands (`ample` / `moderate` / `tight` / `critical`) keyed to the **auto-compaction point**, with 5% hysteresis. The `ample` band additionally declares that every earlier "context is nearly full" claim — including ones inside compacted checkpoints — is stale. A reading that rounds below one display step renders as `under 50K / 1.00M tokens used (under 5%)` — never as a `0` that would contradict the headroom printed on the same line.
|
|
39
39
|
|
|
40
|
+
**Headroom in steps**: the `tight` and `critical` bands translate the remaining headroom into this session's own pace — `At this session's recent rate that is roughly 6 more steps.` It is measured, not guessed: per-step growth is the **median** of the deltas between step boundaries, with the step number taken from the host's own `(turn, step)` counter. One 30K tool dump therefore cannot drag it, and a fold re-base (measured: 200K → under 50K within three seconds) clears the history instead of being averaged against it. The figure is bucketed onto `1 / 2 / 3 / 5 / 8 / 13 / 20+` and rounded **down**, the same direction as the headroom itself. The top rung is open-ended on purpose: in a live session the raw count ranged 23–38 across consecutive steps, straddling the old `21 / 34` boundary and flipping the line four times in 90 seconds — one snapshot re-commit caused by nothing but the flip — while above ~20 steps the exact figure changes no decision. The rung also settles like a band, asymmetrically: **downward at once** (less room is never held back), **upward only past `paceMargin` (25%)** above the higher rung, so a straddling estimate cannot flip the line and a genuinely slower session is never frozen at a low rung. It is display-only: it moves no band edge, threshold, or folding decision — switching it off reproduces the 0.1.3 line exactly.
|
|
41
|
+
|
|
42
|
+
**The `tight` band says nothing by default.** It reports the numbers (used, threshold, remainder, roughly how many steps) and adds **no closing sentence**. Three wordings were tried in the field — 0.1.3 ordered "finish the step, then hand off", 0.1.4 described the coming fold — and both made the model narrate compaction in its own replies and lose momentum, in the band that re-injects most often (measured: 333 commits, median gap 45s, runs of 4–20s). `tightAdvice: 'inform'` restores the 0.1.4 sentence, `'stop'` the 0.1.3 imperative.
|
|
43
|
+
|
|
44
|
+
**The line says outright that it is telemetry — and not an allowance to draw down.** Its closing clause is "Background telemetry from the host, and the only authority on context pressure: do not mention it, do not estimate or count it down yourself — it is restated whenever it changes — and take no action about compaction; the host folds between steps automatically." The second half is as evidence-driven as the first: a live model quoted the figure correctly for a while and then spent it in its head (`30K → 28K → 16K → 10K → 7K → 5K`) while the host's number sat still at `About 10K` (restated only when it changes), and twelve minutes later announced "Context is nearly exhausted (~5K)" — a figure the host never reported.
|
|
45
|
+
|
|
46
|
+
**The line answers "how much context do I have left" too.** It used to print only the headroom to the fold, never the free window — and a live model answered the first question with the second figure, announcing "Very low context" at 10K of headroom while **350K of the window was free**. Both numbers were true; only one was an answer. Every band now carries `About 300K of the window is still free`, and **no figure was removed**: dropping the headroom near the fold was considered and rejected, because both endpoints (used, and the fold point) stay printed, so the model can subtract them anyway — suppressing a derivable number would re-create the original bug's precondition (no ground truth) exactly where speculation is most likely. It shares the `used` display step, so it adds no re-injection of its own; `freeClause: false` removes it.
|
|
47
|
+
|
|
48
|
+
**The two small bands define what the fold is.** Numbers alone left a gap a live model walked into: eleven seconds after the line read `Under 10K tokens of headroom remain before it`, it wrote "Very low context. I must do this in as few commands as possible, then a short answer." It had read the figure correctly and took "room before the fold" for "context left", while the window still held 350K and the fold only replaces older turns with a summary. `tight` therefore carries a **definition** (not an instruction) — "The fold is routine, not the end of the window: older turns become a summary and work continues after it" — and `critical` the short form, "The window is not exhausted — work continues after the fold." Neither contains a task instruction, so neither can regress into the 0.1.3 "wrap up and hand off" nudge. `foldClause: false` removes them.
|
|
49
|
+
|
|
50
|
+
**The headroom step stays coarse near the point.** An earlier build shrank it to 2K as the room ran out — the exact band that re-injects most — so the figure ticked on nearly every step. The floor is now 10% of the window quantum (10K on a 1M window): within a few tens of thousands of tokens the pace estimate is the useful signal, and a remainder smaller than one step still renders honestly as `Under 10K`. Over a walk from 128K of headroom to zero, the line re-commits **11 times instead of 23**.
|
|
51
|
+
|
|
40
52
|
### 2. Compaction directive rules (on by default)
|
|
41
53
|
|
|
42
54
|
The last message of a compaction call is the summarizer directive. Through the **public `llm/stream` waterfall** the plugin appends two rules to its tail — tail-only, so the cached prefix stays byte-identical:
|
|
@@ -53,6 +65,45 @@ The last message of a compaction call is the summarizer directive. Through the *
|
|
|
53
65
|
|
|
54
66
|
The call is identified by the `purpose: 'compaction'` tag its caller sets. When a deployment sets no tag, the fallback requires the trailing message to **begin** with the directive — so a tool result that merely quotes the engine (a source dump, a log excerpt, a grep hit) is never patched by mistake, and can never spend the one-shot failure warning either.
|
|
55
67
|
|
|
68
|
+
**Measured (2026-10-12, two automatic folds in a long session)**: the request carried the **patched** directive — 2,336 characters on the wire (1,802 original + 534 of rules), all three rule markers present, and the request landed on the same seam **19 ms** after `compaction-cache: aligned` logged the same call (21:46:08.085 / 21:46:08.104) — two plugins cross-validating each other. Related confirmation: the patched trailing message is **not frozen**, because the plugin replaces the array slot rather than mutating the frozen object the engine appends.
|
|
69
|
+
|
|
70
|
+
**Cost**: the directive grows from 1,802 to 2,336 characters — **+534 characters ≈ +134 tokens (+0.09%)**. It is appended *after* the cached prefix, so those 134 tokens are the only fresh full-price input a fold adds.
|
|
71
|
+
|
|
72
|
+
### 3. Fold at the turn boundary: `idle` (default) / `handoff` (experimental)
|
|
73
|
+
|
|
74
|
+
The host's automatic compaction is a *crossing* trigger, and the behaviour a model adopts near the point — batching round trips, avoiding risky edits, stopping mid-iteration to commit WIP — is exactly what keeps the reading below it. Measured on one live session:
|
|
75
|
+
|
|
76
|
+
```
|
|
77
|
+
4 hours with no fold · every turn 2–8 steps long · three consecutive "continue"
|
|
78
|
+
instructions unable to finish the same task
|
|
79
|
+
the reading parked at "Under 10K tokens of headroom remain"
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
`foldMode` decides what this plugin does at the model's **own turn boundary** (`agent/status === 'idle'`):
|
|
83
|
+
|
|
84
|
+
| Mode | Behaviour |
|
|
85
|
+
|---|---|
|
|
86
|
+
| `off` | Report only, never fold. Use it to leave folding entirely to the host's pressure trigger. |
|
|
87
|
+
| `idle` | **Default.** When the reading comes within `foldAtIdleMarginPercent` (5% of the window by default — 50K on a 1M window) of the point, it calls the official `compaction.compactNow()`. The official engine only accepts that call while the agent is idle, which is exactly the moment this fires. The fold pushes the headroom back into the hundreds of thousands, so the condition stops holding: **one fold per cycle**. |
|
|
88
|
+
| `handoff` | **Experimental.** The model writes a handoff note first, then the fold runs, then exactly one turn is activated to read that note back. See below. |
|
|
89
|
+
|
|
90
|
+
> Compatibility: a config that never set `foldMode` resolves to `idle` (that is the behaviour this plugin always had, behind `foldAtIdle: true`); a config that explicitly set `foldAtIdle: false` still resolves to `off` and is not dragged along by the new default. An explicit `foldMode` always wins.
|
|
91
|
+
|
|
92
|
+
#### Handoff folding (`handoff`, experimental)
|
|
93
|
+
|
|
94
|
+
What actually costs a long task is not the summary but **the repeated work after the fold**: the model cannot know when it will be folded, then rebuilds its picture from the summary and redoes what it already did. Baseline (143 folds): **81 folds (57%) were followed by the model re-reading a file it had just written, 225 occurrences**.
|
|
95
|
+
|
|
96
|
+
The chain is:
|
|
97
|
+
|
|
98
|
+
1. At the **prep point** (`handoffAt` × the fold point, 85% by default) the plugin injects a reminder naming the **one** allowed note path (`$DSH_HOME/handoffs/<sessionId>/<fold#>.handoff.md`, never the workspace);
|
|
99
|
+
2. the model writes everything the post-fold self needs (goal, settled decisions, evidence, next action, dead ends) and calls `handoff_ready`;
|
|
100
|
+
3. at the end of that round the plugin calls `compactNow()`;
|
|
101
|
+
4. after the fold it uses `followup` to activate **exactly one** turn whose first instruction is to read that note before touching the task.
|
|
102
|
+
|
|
103
|
+
Guards: at most 3 reminders per cycle; if a round ends past the prep point with no note registered, the plugin **wakes** a round with `followup` to deliver the reminder (`agent.inject` only queues for the next request, so a reminder that lands on the model's last step would otherwise wait for a human — measured, and that is why the wake exists); notes are temporary, recycled when the next handoff is created with a 7-day sweep; a registered note whose fold did not happen is kept and never activates a turn.
|
|
104
|
+
|
|
105
|
+
**Switching modes takes effect immediately, with no restart**: `foldMode` is volatile config, the settings card writes straight into the running reference, and the plugin resolves its options per use (verified live: after the panel switched to `handoff`, the running instance acted on it on its next call). Switching does **not** trigger a fold by itself — the fold still waits for the reading to reach the point.
|
|
106
|
+
|
|
56
107
|
## Data sources (all host-measured — nothing is estimated)
|
|
57
108
|
|
|
58
109
|
| Item | Source |
|
|
@@ -84,7 +135,11 @@ Or write the row into a profile's own patch layer:
|
|
|
84
135
|
language: en # optional; 'en' (default) or 'zh'
|
|
85
136
|
```
|
|
86
137
|
|
|
87
|
-
The package ships `dsh.bundle.patch`, so listing it in a profile's `dsh.profile.bundles` assembles it too. **No
|
|
138
|
+
The package ships `dsh.bundle.patch`, so listing it in a profile's `dsh.profile.bundles` assembles it too. **No build step**: `lib/index.js` is both the source and the artifact.
|
|
139
|
+
|
|
140
|
+
**Host requirements**: `inject = ['systemPrompt', 'tokenMeter']` — **two**. `compaction` is *deliberately not declared*: declaring it left the entry **pending forever** (the plugin did not load at all, taking capability 1's occupancy line with it). Reported upstream as [#9425](https://github.com/deepseek-ai/deepseek-harness/discussions/9425).
|
|
141
|
+
|
|
142
|
+
Capability 3 resolves its engine itself, at fold time, through a **ranked candidate chain** — `agent.ctx` → `ctx` → wired service — taking the first candidate that **actually carries `compactNow`** (never simply "the first that is not undefined": a property read for a service this fiber does not have answers with a **diagnostic string**, which is a trap this plugin fell into once). So the startup line `compaction=undefined/none` reports **only what the plugin's own context can see — it does not mean folding is unavailable**: this profile prints exactly that, and both automatic folds on 2026-10-12 completed.
|
|
88
143
|
|
|
89
144
|
## Configuration (every key optional)
|
|
90
145
|
|
|
@@ -94,16 +149,47 @@ The package ships `dsh.bundle.patch`, so listing it in a profile's `dsh.profile.
|
|
|
94
149
|
| `language` | `en` | `en` / `zh` wording |
|
|
95
150
|
| `order` | `100` | Placement inside the runtime-context block (sandbox is 110, approval 115 — so it comes first) |
|
|
96
151
|
| `quantumPercent` | `5` | Display step as a percentage of the window; sets the re-injection cadence |
|
|
152
|
+
| `paceEstimate` | `true` | Translate the headroom into this session's pace (`tight` / `critical` bands) |
|
|
153
|
+
| `paceSamples` | `16` | Per-step deltas the median is taken over |
|
|
154
|
+
| `paceMinSamples` | `3` | Samples required before any estimate is shown |
|
|
155
|
+
| `paceMargin` | `0.25` | Margin a higher rung must clear before the line promises more steps |
|
|
97
156
|
| `thresholdRatio` | `0.8` | Mirror of `dsh-compaction-basic` |
|
|
98
157
|
| `headroomTokens` | `65536` | Mirror of `dsh-compaction-basic` |
|
|
99
158
|
| `reservedCompletionTokens` | `null` | `null` reads the routed request's own `maxTokens` |
|
|
100
159
|
| `moderateAt` / `tightAt` | `0.5` / `0.85` | Band edges, as a fraction of the compaction point |
|
|
101
160
|
| `hysteresis` | `0.05` | Margin required before leaving a band downward |
|
|
161
|
+
| `tightAdvice` | `none` | `tight` closing sentence: `none` adds none (default), `inform` states the cost, `stop` keeps the 0.1.3 imperative |
|
|
102
162
|
| `authoritative` | `true` | Append the "this line is the only authority" clause |
|
|
103
163
|
| `staleClaimClause` | `true` | Retire earlier "context is nearly full" claims in the calm band |
|
|
164
|
+
| `foldClause` | `true` | Define what the fold is in the `tight` / `critical` bands |
|
|
165
|
+
| `freeClause` | `true` | Report how much of the window is still unused |
|
|
104
166
|
| `logBandChanges` | `true` | Log one `ctx.logger.info` per band change |
|
|
105
167
|
| `patchCompactionPrompt` | `true` | Whether to extend the compaction directive |
|
|
106
168
|
| `compactionRules` | see above | Rule array; `[]` disables capability 2 |
|
|
169
|
+
| `foldMode` | `idle` | Turn-boundary fold mode: `off` / `idle` (default) / `handoff` (experimental). The settings card writes this key and the change is live |
|
|
170
|
+
| `handoffAt` | `0.85` | Prep point for the handoff reminder, as a fraction of the **fold point** (not the window) |
|
|
171
|
+
| `handoffDir` | `''` | Note directory; empty means `$DSH_HOME/handoffs`, a relative path also resolves under `$DSH_HOME`, never the workspace |
|
|
172
|
+
| `handoffReminders` | `3` | Reminders per cycle, wake included |
|
|
173
|
+
| `foldAtIdle` | `false` | Legacy switch, equivalent to `foldMode: idle`; an explicit `false` means `off`. Only matters for a config that never set `foldMode` |
|
|
174
|
+
| `foldAtIdleMarginPercent` | `5` | Fold once the headroom is within this percent of the window (50K on a 1M window) |
|
|
175
|
+
| `foldAtIdleMethod` | `auto` | Channel for the request: `auto` runs the session's own `/compact` first (realm view), then falls back to the ranked service chain; `command` / `service` force one. `service` is the most predictable of the two (this profile uses it) |
|
|
176
|
+
| `foldAtIdleCooldownMs` | `60000` | Minimum gap between attempts, so a failure cannot hammer the engine |
|
|
177
|
+
|
|
178
|
+
**Configuration goes in the profile patch** — the same place `subagent`'s `maxDepth` and `bash-terminal`'s `defaultShell` live:
|
|
179
|
+
|
|
180
|
+
```yaml
|
|
181
|
+
- id: context-truth # the id the bundle patch declares
|
|
182
|
+
name: dsh-context-truth
|
|
183
|
+
config:
|
|
184
|
+
foldMode: idle # off / idle (default) / handoff (experimental)
|
|
185
|
+
foldAtIdleMarginPercent: 5
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
A change takes effect **immediately**: the host's volatile mechanism writes the new value straight into the running config reference (`loader._commitVolatile`) instead of reloading the plugin, which is why the plugin resolves its options per use rather than snapshotting them at mount. Verified live: editing that row flipped the running config's `foldMode` with no restart (see "Switching modes takes effect immediately" above).
|
|
189
|
+
|
|
190
|
+
> **The settings card is not generated — this plugin ships one.** This DSH build does not render a form from a plugin's `Config` schema; the host only wires the *registrations* into plugin pages (`plugins.bundle.config` / `plugins.row.config`). Since 0.3.0 this package carries `lib/client.js` (declared through `dsh.client` and `exports["./client"]`), which registers `plugins.bundle.config` with key `dsh-context-truth` and renders a fold-mode select wired to `settings.describe()` / `settings.mutate()`. It appears in the plugin page's detail view. Without that card the only way to switch is the profile patch above.
|
|
191
|
+
|
|
192
|
+
`enabled` (the master switch) is best left to the on/off toggle on the plugin list — that one does reload the plugin.
|
|
107
193
|
|
|
108
194
|
## Cost (stated honestly)
|
|
109
195
|
|
|
@@ -117,23 +203,24 @@ What you get for it: the model stops halting or handing off because it *thinks*
|
|
|
117
203
|
|
|
118
204
|
## Compatibility & boundaries
|
|
119
205
|
|
|
120
|
-
* Measured on **dsh 0.2.0-rc.2**; only public seams are used (`systemPrompt.variable/context`, the `llm/stream` waterfall, the `tokenMeter` / `sessionProjections` services) —
|
|
206
|
+
* Measured on **dsh 0.2.0-rc.2**; only public seams are used (`systemPrompt.variable/context`, the `llm/stream` waterfall, the `tokenMeter` / `sessionProjections` services). One exception: the pace estimate reads the host's `agent.phase.{turn, step}` instance field, which is not documented — when it is absent the clause is omitted entirely and the line falls back to what 0.1.3 rendered, never to a guess.
|
|
121
207
|
* If an agent preset sets `includeRuntimeContext: false` (for example `liangshen`), the runtime suppresses **every** runtime-context contribution and capability 1 does not apply (capability 2 is unaffected).
|
|
122
208
|
* If a host froze the request envelope (**this version does not** — verified by capturing a real compaction request), capability 2 logs one warning and skips — it never breaks a model call. That warning is reserved for the engine's own tagged call, so a look-alike request can never silence a later real failure.
|
|
123
209
|
* **Mounting twice in one scope does not fail**: bundle assembly plus a runtime injection are two assembly paths for the same plugin; the second instance detects the taken name, stays silent (one `info` line) and the first keeps serving — it never becomes a failed plugin row.
|
|
124
|
-
* The plugin registers
|
|
210
|
+
* The plugin registers **one tool**, `handoff_ready` (register a handoff note). It is in the catalog in every mode so the settings card can switch modes at any time, but it costs nothing unless called; only handoff mode calls it. It is still one tool definition in the first-turn prefill — the only change this plugin makes to the tool catalog. Folding itself never goes through a model tool call (the plugin calls `compaction.compactNow()` directly), so in `off` / `idle` modes the model sees no folding activity at all.
|
|
211
|
+
* The plugin ships **one client module** (`lib/client.js`, the settings card). It only reads `settings.describe()` and writes `settings.mutate()`; it touches no workspace and makes no network requests.
|
|
125
212
|
|
|
126
213
|
## Verify
|
|
127
214
|
|
|
128
215
|
```sh
|
|
129
|
-
npm test #
|
|
216
|
+
npm test # 69 unit tests: banding, hysteresis, quantization, free window, fold definition, idle fold and its guards, live settings changes, schema-default parity, pace estimate, degradation, directive patching, look-alike rejection, idempotence, handoff folding (reminder, registration, round-end fold, single activation, restart recovery, recycling, round-end wake), client card shape
|
|
130
217
|
```
|
|
131
218
|
|
|
132
219
|
After installing, open a new session and send one message: expanding that turn's runtime context block should show `Context occupancy (host-measured): …`, and the log carries `context-truth: none -> ample (used=… window=1000000 compactionAt=678464)`.
|
|
133
220
|
|
|
134
221
|
## Uninstall
|
|
135
222
|
|
|
136
|
-
Remove the row from the profile patch / bundles list; a restart leaves nothing behind —
|
|
223
|
+
Remove the row from the profile patch / bundles list; a restart leaves nothing behind — with one exception: handoff mode writes notes and a state file under `$DSH_HOME/handoffs/<sessionId>/`, and deleting that directory clears them.
|
|
137
224
|
|
|
138
225
|
## License
|
|
139
226
|
|