dsh-context-truth 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/CHANGELOG.md ADDED
@@ -0,0 +1,24 @@
1
+ # Changelog
2
+
3
+ ## 0.1.0
4
+
5
+ First release.
6
+
7
+ - **Measured occupancy line**: a dynamic runtime-context contribution rendered from
8
+ `tokenMeter.measure(session).totalTokens` (falling back to the `contextPressure`
9
+ projection), with the auto-compaction point derived exactly the way
10
+ `dsh-compaction-basic` derives it. Four bands (ample / moderate / tight / critical)
11
+ with hysteresis, quantized display steps so an unchanged reading never re-injects,
12
+ and a headroom figure that always rounds down — it never promises more room than the
13
+ session has.
14
+ - **Compaction directive rules**: the summarizer's trailing directive is extended
15
+ through the public `llm/stream` waterfall (tail-only; the cached prefix is byte-identical)
16
+ so a summary stops carrying the assistant's own guesses about its remaining budget
17
+ forward as established background.
18
+ - Zero dependencies, no build step, no tools, no client bundle.
19
+ - Bilingual docs: `README.md` (简体中文) and `README-en.md` (English), switched by the
20
+ language line under the title.
21
+ - Mounting twice in one scope (bundle assembly plus a runtime injection of the same
22
+ package) leaves the second instance inert instead of failing.
23
+ - 21 unit tests: banding, hysteresis, quantization, conservative headroom, degradation on a
24
+ broken meter, directive patching, idempotence, duplicate mounts, and the disabled/interceptor paths.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 dsh-context-truth deepseekv41flash
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README-en.md ADDED
@@ -0,0 +1,137 @@
1
+ # dsh-context-truth
2
+
3
+ [English](README-en.md) · [简体中文](README.md)
4
+
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
+
7
+ A DSH (DeepSeek Harness) plugin · zero dependencies · no tools · no UI · no build step · MIT
8
+
9
+ ---
10
+
11
+ ## The problem it solves
12
+
13
+ **DSH never tells the model how many tokens it has used.** The model can only guess from how long the conversation feels, so on a long session it announces "context is nearly exhausted" while the real occupancy is **17%** — stops doing write work, and hands the task to a subagent.
14
+
15
+ Worse, that wrong call **survives compaction**:
16
+
17
+ 1. the model writes "my context is nearly exhausted";
18
+ 2. the sentence lands in a compaction summary (verbatim from a real session: `- Session budget is nearly exhausted; ...`);
19
+ 3. the checkpoint's fixed preamble reads *"Treat the captured context as **established background**"*;
20
+ 4. so every compaction re-injects the false belief as established background — and it is **never corrected** when the real occupancy falls back.
21
+
22
+ This plugin cuts both ends of that chain.
23
+
24
+ ## Two capabilities
25
+
26
+ ### 1. Measured occupancy line (on by default)
27
+
28
+ One dynamic runtime-context line, rendered every turn from the host's own token meter:
29
+
30
+ ```
31
+ Context occupancy (host-measured): 300K / 1.00M tokens used (30%). Automatic compaction
32
+ fires at 678K (68% of the window). About 378K tokens of headroom remain before it.
33
+ There is still real headroom — keep going, and keep durable notes or commits current as
34
+ you work. This host-measured line is the only authority on context pressure; never
35
+ estimate it from the conversation's length.
36
+ ```
37
+
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.
39
+
40
+ ### 2. Compaction directive rules (on by default)
41
+
42
+ The last message of a compaction call (`purpose: 'compaction'`) 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:
43
+
44
+ ```
45
+ - Never record the assistant's own statements about its remaining context, token budget, or
46
+ context-window pressure (for example "context is nearly exhausted", "running out of budget",
47
+ "hand off before context runs out"). Those readings are measured by the host and delivered
48
+ separately; a model's guess about them is not a durable fact.
49
+ - Never record a plan to stop, defer, or hand off work whose only justification was context
50
+ pressure. Record the actual task state instead.
51
+ ```
52
+
53
+ ## Data sources (all host-measured — nothing is estimated)
54
+
55
+ | Item | Source |
56
+ |---|---|
57
+ | Used | `tokenMeter.measure(session).totalTokens` — the host's price for the next request, and the exact number auto-compaction compares against |
58
+ | Window | `session.requestContext().contextWindow` |
59
+ | Fallback | the `contextPressure` projection (provider-reported prompt-side usage) — **the same figure the Web UI's context ring renders** |
60
+ | Compaction point | `min(window × thresholdRatio, window − reserved completion − headroom)`, the same formula `dsh-compaction-basic` uses |
61
+ | Summarizer directive | the last message of the `purpose: 'compaction'` request at the `llm/stream` waterfall |
62
+
63
+ ## Install
64
+
65
+ ```sh
66
+ # npm
67
+ dsh plugin --profile web add dsh-context-truth
68
+
69
+ # or straight from the repository
70
+ dsh plugin --profile web add github:deepseekv41flash/dsh-context-truth
71
+ ```
72
+
73
+ Or write the row into a profile's own patch layer:
74
+
75
+ ```yaml
76
+ # <DSH home>/profiles/<profile>/cordis.patch.yml
77
+ - insert:
78
+ - id: context-truth
79
+ name: dsh-context-truth
80
+ config:
81
+ language: en # optional; 'en' (default) or 'zh'
82
+ ```
83
+
84
+ The package ships `dsh.bundle.patch`, so listing it in a profile's `dsh.profile.bundles` assembles it too. **No dependencies and no build step**: `lib/index.js` is both the source and the artifact.
85
+
86
+ ## Configuration (every key optional)
87
+
88
+ | Key | Default | Meaning |
89
+ |---|---|---|
90
+ | `enabled` | `true` | Master switch for capability 1 |
91
+ | `language` | `en` | `en` / `zh` wording |
92
+ | `order` | `100` | Placement inside the runtime-context block (sandbox is 110, approval 115 — so it comes first) |
93
+ | `quantumPercent` | `5` | Display step as a percentage of the window; sets the re-injection cadence |
94
+ | `thresholdRatio` | `0.8` | Mirror of `dsh-compaction-basic` |
95
+ | `headroomTokens` | `65536` | Mirror of `dsh-compaction-basic` |
96
+ | `reservedCompletionTokens` | `null` | `null` reads the routed request's own `maxTokens` |
97
+ | `moderateAt` / `tightAt` | `0.5` / `0.85` | Band edges, as a fraction of the compaction point |
98
+ | `hysteresis` | `0.05` | Margin required before leaving a band downward |
99
+ | `authoritative` | `true` | Append the "this line is the only authority" clause |
100
+ | `staleClaimClause` | `true` | Retire earlier "context is nearly full" claims in the calm band |
101
+ | `logBandChanges` | `true` | Log one `ctx.logger.info` per band change |
102
+ | `patchCompactionPrompt` | `true` | Whether to extend the compaction directive |
103
+ | `compactionRules` | see above | Rule array; `[]` disables capability 2 |
104
+
105
+ ## Cost (stated honestly)
106
+
107
+ The runtime-context snapshot is **not re-injected while its bytes are unchanged**, so readings are quantized. Measured on a 1M window with the 678K compaction point and `quantumPercent: 5`:
108
+
109
+ * one full cycle (0 → 678K) changes the text **52 times**, roughly once per 13K tokens;
110
+ * the occupancy line is ≈ **124 tokens**, plus the other sections of the same snapshot ≈ 250 tokens;
111
+ * together that is **< 2%** of the cycle's budget.
112
+
113
+ What you get for it: the model stops halting or handing off because it *thinks* it is running out of context. Raise `quantumPercent` to spend less.
114
+
115
+ ## Compatibility & boundaries
116
+
117
+ * Measured on **dsh 0.2.0-rc.2**; only public seams are used (`systemPrompt.variable/context`, the `llm/stream` waterfall, the `tokenMeter` / `sessionProjections` services) — no private fields.
118
+ * 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).
119
+ * If a host froze the request envelope (this version does not), capability 2 logs one warning and skips — it never breaks a model call.
120
+ * **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.
121
+ * The plugin registers no tools and does not touch the tool catalog, so it adds nothing to the first-turn prefill.
122
+
123
+ ## Verify
124
+
125
+ ```sh
126
+ npm test # 21 unit tests: banding, hysteresis, quantization, degradation, directive patching, idempotence
127
+ ```
128
+
129
+ 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)`.
130
+
131
+ ## Uninstall
132
+
133
+ Remove the row from the profile patch / bundles list; a restart leaves nothing behind — no tools, no client, no state on disk.
134
+
135
+ ## License
136
+
137
+ MIT
package/README.md CHANGED
@@ -1,3 +1,145 @@
1
- # Temporary Holding Version
1
+ # dsh-context-truth
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ [English](README-en.md) · [简体中文](README.md)
4
+
5
+ > 让模型知道自己**真实的**上下文占用——每轮由宿主实测回填,并且不让"上下文快用完了"这句错话被压缩摘要继承下去。
6
+
7
+ DSH(DeepSeek Harness)插件 · 零依赖 · 零工具 · 零 UI · 免构建 · MIT
8
+
9
+ ---
10
+
11
+ ## 它解决什么问题
12
+
13
+ **DSH 从不把 token 用量告诉模型。** 模型只能靠"这个会话好像很长了"来猜,于是长会话里它会
14
+ 在真实占用 **17%** 的时候宣布"上下文见底了",停止写操作、把活儿甩给子代理。
15
+
16
+ 更糟的是这个错判会**跨压缩存活**:
17
+
18
+ 1. 模型自己写下"我的上下文快用尽了";
19
+ 2. 这句话进入压缩摘要(实测某会话摘要原文:`- Session budget is nearly exhausted; ...`);
20
+ 3. 检查点的固定引导语是 *"Treat the captured context as **established background**"*;
21
+ 4. 于是每压缩一次,这个错误信念就被当作既定背景重新注入一次——**永远不会因为真实占用回落而被纠正**。
22
+
23
+ 本插件同时掐断这条链的两端。
24
+
25
+ ## 两个能力
26
+
27
+ ### 1. 实测占用回填(默认开)
28
+
29
+ 一条动态 runtime-context,每轮由宿主自己的 token meter 渲染:
30
+
31
+ ```
32
+ Context occupancy (host-measured): 300K / 1.00M tokens used (30%). Automatic compaction
33
+ fires at 678K (68% of the window). About 378K tokens of headroom remain before it.
34
+ There is still real headroom — keep going, and keep durable notes or commits current as
35
+ you work. This host-measured line is the only authority on context pressure; never
36
+ estimate it from the conversation's length.
37
+ ```
38
+
39
+ 四档语气(`ample` / `moderate` / `tight` / `critical`)按**自动压缩阈值**的比例分档,
40
+ 带 5% 迟滞;`ample` 档额外声明"此前所有'上下文快满了'的说法(含压缩检查点里的)都已作废"。
41
+
42
+ ### 2. 压缩指令补规则(默认开)
43
+
44
+ 压缩摘要调用(`purpose: 'compaction'`)的最后一条消息就是摘要指令。本插件通过**公开的
45
+ `llm/stream` 瀑布**在它末尾追加两条规则,只改尾巴、不动被缓存的前缀:
46
+
47
+ ```
48
+ - Never record the assistant's own statements about its remaining context, token budget, or
49
+ context-window pressure (for example "context is nearly exhausted", "running out of budget",
50
+ "hand off before context runs out"). Those readings are measured by the host and delivered
51
+ separately; a model's guess about them is not a durable fact.
52
+ - Never record a plan to stop, defer, or hand off work whose only justification was context
53
+ pressure. Record the actual task state instead.
54
+ ```
55
+
56
+ ## 数据来源(都是宿主的真实数字,没有估算)
57
+
58
+ | 项目 | 来源 |
59
+ |---|---|
60
+ | 已用 | `tokenMeter.measure(session).totalTokens` —— 宿主对下一次请求的计价,也是自动压缩实际比较的那个数 |
61
+ | 窗口 | `session.requestContext().contextWindow` |
62
+ | 兜底 | `contextPressure` 投影(provider 上报的 prompt 侧用量)——**与 Web UI 那个上下文环同源** |
63
+ | 自动压缩点 | `min(window × thresholdRatio, window − 保留输出 − headroom)`,与 `dsh-compaction-basic` 同式 |
64
+ | 摘要指令 | `llm/stream` 瀑布里 `purpose: 'compaction'` 请求的最后一条消息 |
65
+
66
+ ## 安装
67
+
68
+ ```sh
69
+ # npm
70
+ dsh plugin --profile web add dsh-context-truth
71
+ ```
72
+
73
+ 或直接写进 profile 的 patch 层:
74
+
75
+ ```yaml
76
+ # <DSH home>/profiles/<profile>/cordis.patch.yml
77
+ - insert:
78
+ - id: context-truth
79
+ name: dsh-context-truth
80
+ config:
81
+ language: zh # 可选:中文文案
82
+ ```
83
+
84
+ 本包带 `dsh.bundle.patch`,作为 bundle 列进 profile 的 `dsh.profile.bundles` 也会自动装配。
85
+ **没有任何依赖、不需要构建**:`lib/index.js` 同时是源码和产物。
86
+
87
+ ## 配置(全部可选)
88
+
89
+ | 键 | 默认 | 说明 |
90
+ |---|---|---|
91
+ | `enabled` | `true` | 总开关(只关第 1 个能力) |
92
+ | `language` | `en` | `en` / `zh` 文案语言 |
93
+ | `order` | `100` | 在 runtime-context 里的排序(沙箱 110、审批 115,所以在最前) |
94
+ | `quantumPercent` | `5` | 显示台阶(窗口百分比),决定重发频率 |
95
+ | `thresholdRatio` | `0.8` | 与 `dsh-compaction-basic` 对齐 |
96
+ | `headroomTokens` | `65536` | 同上 |
97
+ | `reservedCompletionTokens` | `null` | 默认读路由请求自身的 `maxTokens` |
98
+ | `moderateAt` / `tightAt` | `0.5` / `0.85` | 分档边界(相对自动压缩点) |
99
+ | `hysteresis` | `0.05` | 降档迟滞 |
100
+ | `authoritative` | `true` | 是否附加"本行是唯一权威"那句 |
101
+ | `staleClaimClause` | `true` | 是否在 calm 档声明旧说法作废 |
102
+ | `logBandChanges` | `true` | 分档变化时写一条 `ctx.logger.info` |
103
+ | `patchCompactionPrompt` | `true` | 是否给压缩指令补规则 |
104
+ | `compactionRules` | 见上 | 规则数组;`[]` 关闭本能力 |
105
+
106
+ ## 代价(照实说)
107
+
108
+ runtime-context 快照**字节不变就不会重发**,所以读数按台阶量化。实测(1M 窗口、678K 压缩点、
109
+ `quantumPercent: 5`):
110
+
111
+ * 一个完整周期(0 → 678K)文字变化 **52 次**,约每 13K tokens 一次;
112
+ * 单条占用行 ≈ **124 tokens**,加上同一条快照里其它 section ≈ 250 tokens;
113
+ * 合计约占该周期预算 **< 2%**。
114
+
115
+ 换来的是模型不再因为"以为自己快没上下文了"而停手或甩锅。要更省可以调大 `quantumPercent`。
116
+
117
+ ## 兼容性与边界
118
+
119
+ * 在 **dsh 0.2.0-rc.2** 上实测;只用公开接缝(`systemPrompt.variable/context`、`llm/stream` 瀑布、
120
+ `tokenMeter` / `sessionProjections` 服务),不读私有字段。
121
+ * 若某个 agent preset 设置了 `includeRuntimeContext: false`(例如 `liangshen`),运行时会抑制
122
+ **所有** runtime-context 贡献,此时第 1 个能力不生效(第 2 个不受影响)。
123
+ * 若宿主把请求信封冻结(本版没有),第 2 个能力会打一条 warn 并跳过,绝不阻断模型调用。
124
+ * **同一作用域挂载两次不会失败**:bundle 装配 + 运行时注入是同一插件的两条装配路径,
125
+ 第二个实例检测到重名后保持静默(只记一条 info),由第一个实例继续服务——不会变成
126
+ 一行 failed 的插件记录。
127
+ * 本插件不注册任何工具、不改工具目录,因此不增加首轮 prefill。
128
+
129
+ ## 验证
130
+
131
+ ```sh
132
+ npm test # 21 项单测:分档/迟滞/量化/降级/摘要改写/幂等/重复挂载
133
+ ```
134
+
135
+ 装好后开一个新会话发一条消息,展开该轮的 runtime context 块应看到
136
+ `Context occupancy (host-measured): …`;日志里会有
137
+ `context-truth: none -> ample (used=… window=1000000 compactionAt=678464)`。
138
+
139
+ ## 卸载
140
+
141
+ 从 profile patch / bundles 里删掉那一行即可,重启即净——没有工具、没有客户端、没有落盘状态。
142
+
143
+ ## License
144
+
145
+ MIT
@@ -0,0 +1,27 @@
1
+ # dsh-context-truth bundle layer — applied automatically when a profile lists this
2
+ # package in dsh.profile.bundles (declared by dsh.bundle.patch in package.json), or
3
+ # inserted by hand into a profile's own cordis.patch.yml.
4
+ #
5
+ # Every config key is optional; the defaults are shown. Both capabilities can be
6
+ # switched off independently.
7
+ - insert:
8
+ - id: context-truth
9
+ name: dsh-context-truth
10
+ # config:
11
+ # # capability 1 — the measured occupancy line
12
+ # enabled: true
13
+ # language: en # en | zh
14
+ # order: 100 # before sandbox (110) and approval (115)
15
+ # quantumPercent: 5 # % of the window per display step
16
+ # thresholdRatio: 0.8 # mirror of dsh-compaction-basic's policy
17
+ # headroomTokens: 65536 # mirror of dsh-compaction-basic's policy
18
+ # reservedCompletionTokens: null # null = the routed request's own maxTokens
19
+ # moderateAt: 0.5 # band edges, as a fraction of the compaction point
20
+ # tightAt: 0.85
21
+ # hysteresis: 0.05
22
+ # authoritative: true # append the "only authority" clause
23
+ # staleClaimClause: true # retire earlier "context is nearly full" claims
24
+ # logBandChanges: true
25
+ # # capability 2 — the compaction directive rules
26
+ # patchCompactionPrompt: true
27
+ # compactionRules: [] # override the default two rules; [] disables the append