dsh-context-truth 0.3.0 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,15 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.3.1
4
+
5
+ * **`handoff_ready` 只在 `handoff` 模式下注册。** `off` / `idle` 下它从工具目录里移除(用
6
+ `tools.register()` 返回的注销 disposer),切回 handoff 时在**下一个请求**重新注册;插件被销毁时
7
+ 也会注销。`off` / `idle` 的工具目录与没有这个能力时完全一致,不再为首轮 prefill 承担一个
8
+ 永远只会拒绝的工具定义。
9
+ * 日志分别记 `handoff_ready registered (fold mode is handoff)` /
10
+ `handoff_ready removed (fold mode is <mode>)`,模式切换在日志里可见。
11
+ * 测试:70(新增“工具跟随实时模式”用例;变异“去掉注销调用”恰好只让它失败,恢复后字节一致)。
12
+
3
13
  ## 0.3.0
4
14
 
5
15
  > **新增能力 3 的第二形态:交接式折叠(`foldMode: handoff`,实验性)。** 默认模式改为 `idle`
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 · 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
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 in handoff mode (`handoff_ready`) · 1 client settings card · no build step · MIT
8
8
 
9
9
  ---
10
10
 
@@ -207,7 +207,7 @@ What you get for it: the model stops halting or handing off because it *thinks*
207
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).
208
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.
209
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.
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.
210
+ * The plugin registers **one tool only in `handoff` mode**: `handoff_ready` (register a handoff note). In `off` / `idle` it is removed from the tool catalog again, so the catalog is exactly what a deployment without this capability has; a switch lands on the **next request** (the plugin reconciles inside `agent/request` through the disposer `tools.register()` returns). Folding itself never goes through a model tool call (the plugin calls `compaction.compactNow()` directly), so in `off` / `idle` modes the model sees neither the tool nor any folding activity.
211
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.
212
212
 
213
213
  ## Verify
package/README.md CHANGED
@@ -6,7 +6,7 @@
6
6
 
7
7
  > 让模型知道自己**真实的**上下文占用——每轮由宿主实测回填,并且不让"上下文快用完了"这句错话被压缩摘要继承下去。
8
8
 
9
- DSH(DeepSeek Harness)插件 · 单一 peer 依赖(宿主自带的 `schemastery`)· 需要宿主服务 `tokenMeter` 与 `compaction`(标准部署的 `dsh-base` 自带)· 1 个工具(`handoff_ready`,交接式折叠用)· 1 个客户端设置卡片 · 免构建 · MIT
9
+ DSH(DeepSeek Harness)插件 · 单一 peer 依赖(宿主自带的 `schemastery`)· 需要宿主服务 `tokenMeter` 与 `compaction`(标准部署的 `dsh-base` 自带)· handoff 模式下 1 个工具(`handoff_ready`)· 1 个客户端设置卡片 · 免构建 · MIT
10
10
 
11
11
  ---
12
12
 
@@ -283,10 +283,11 @@ runtime-context 快照**字节不变就不会重发**,所以读数按台阶量
283
283
  * **同一作用域挂载两次不会失败**:bundle 装配 + 运行时注入是同一插件的两条装配路径,
284
284
  第二个实例检测到重名后保持静默(只记一条 info),由第一个实例继续服务——不会变成
285
285
  一行 failed 的插件记录。
286
- * 本插件注册 **1 个工具**:`handoff_ready`(交接档登记)。它在所有模式下都会出现在工具目录里
287
- (设置卡需要能随时切换模式),不产生额外调用;只有 handoff 模式会用它。工具定义很小,但仍算
288
- **一次首轮 prefill** 的成本——这是本插件唯一改工具目录的地方。折叠本身不经过模型工具调用
289
- (插件直接调 `compaction.compactNow()`),所以 `off`/`idle` 模式下模型侧看不到任何折叠活动。
286
+ * 本插件**只在 `handoff` 模式下注册 1 个工具**:`handoff_ready`(交接档登记)。
287
+ `off` / `idle` 下它会从工具目录里移除,工具目录与没有这个能力时完全一致;切换在**下一个请求**生效
288
+ (插件在 `agent/request` 里对账,用的是 `tools.register()` 返回的注销 disposer)。
289
+ 折叠本身不经过模型工具调用(插件直接调 `compaction.compactNow()`),所以 `off`/`idle` 模式下
290
+ 模型侧看不到任何折叠活动,也没有这个工具。
290
291
  * 本插件带 **1 个客户端模块**(`lib/client.js`,插件页的设置卡)。它只读 `settings.describe()`、
291
292
  写 `settings.mutate()`,不碰工作区、不发网络请求。
292
293
 
package/lib/index.js CHANGED
@@ -1849,6 +1849,10 @@ function installHandoffFold(ctx, resolve, services) {
1849
1849
  */
1850
1850
  function prepare(agent, turn) {
1851
1851
  const options = resolve()
1852
+ // The tool catalog follows the mode even for a session this scope does not
1853
+ // remind (a delegate, an unnamed session): `off`/`idle` must never advertise a
1854
+ // tool the mode cannot honour.
1855
+ syncHandoffTool(options)
1852
1856
  if (options.foldMode !== 'handoff') return
1853
1857
  const session = agent === null || agent === undefined ? undefined : agent.session
1854
1858
  if (session === null || session === undefined) return
@@ -2230,11 +2234,16 @@ function installHandoffFold(ctx, resolve, services) {
2230
2234
  }
2231
2235
  }
2232
2236
 
2233
- // The tool exists in every mode: the settings form toggles `foldMode` live, and a
2234
- // tool that only appears after a reload would leave handoff mode unrunnable on the
2235
- // very session that just turned it on. Its description is one line for that reason.
2237
+ // The handoff tool follows the live `foldMode`: `tools.register()` returns the
2238
+ // disposer that unregisters it, so `off`/`idle` deployments carry no extra tool
2239
+ // at all instead of shipping a definition whose body always refuses. The initial
2240
+ // state is reconciled here, and every `prepare` (one per request) keeps it in
2241
+ // step after a settings change.
2236
2242
  const tools = safeGet(ctx, 'tools')
2237
- if (tools === undefined || typeof tools.register !== 'function' || typeof ctx.effect !== 'function') {
2243
+ const toolsUsable = tools !== undefined && typeof tools.register === 'function'
2244
+ let toolDisposer = null
2245
+
2246
+ if (!toolsUsable) {
2238
2247
  logLine(
2239
2248
  ctx,
2240
2249
  'warn',
@@ -2242,13 +2251,50 @@ function installHandoffFold(ctx, resolve, services) {
2242
2251
  HANDOFF_TOOL_NAME,
2243
2252
  )
2244
2253
  } else {
2254
+ // Mode switching is not the only way the row goes away: a reload or a disposed
2255
+ // fiber must not leave the registration behind.
2256
+ ctx.effect(
2257
+ () => () => {
2258
+ if (toolDisposer === null) return
2259
+ const dispose = toolDisposer
2260
+ toolDisposer = null
2261
+ dispose()
2262
+ },
2263
+ `context-truth: ${HANDOFF_TOOL_NAME} cleanup`,
2264
+ )
2265
+ }
2266
+
2267
+ /**
2268
+ * Register the handoff tool only while the fold mode is `handoff`.
2269
+ *
2270
+ * `tools.register()` returns the exact disposer that unregisters the tool
2271
+ * (`dsh-tools` `register()`), so the tool can follow a live `foldMode` without a
2272
+ * reload. Reconciled from `prepare`, which runs inside the `agent/request`
2273
+ * waterfall, so a switch lands on the next request rather than the next process.
2274
+ *
2275
+ * @param options - resolved options for this call.
2276
+ */
2277
+ function syncHandoffTool(options) {
2278
+ if (!toolsUsable) return
2279
+ const want = options.foldMode === 'handoff'
2280
+ if (want === (toolDisposer !== null)) return
2245
2281
  try {
2246
- ctx.effect(() => tools.register(toolDefinition()), `context-truth: ${HANDOFF_TOOL_NAME}`)
2282
+ if (want) {
2283
+ toolDisposer = tools.register(toolDefinition())
2284
+ logLine(ctx, 'info', 'context-truth: %s registered (fold mode is handoff)', HANDOFF_TOOL_NAME)
2285
+ } else {
2286
+ const dispose = toolDisposer
2287
+ toolDisposer = null
2288
+ dispose()
2289
+ logLine(ctx, 'info', 'context-truth: %s removed (fold mode is %s)', HANDOFF_TOOL_NAME, options.foldMode)
2290
+ }
2247
2291
  } catch (error) {
2248
- logLine(ctx, 'warn', 'context-truth: could not register %s: %s', HANDOFF_TOOL_NAME, messageOf(error))
2292
+ logLine(ctx, 'warn', 'context-truth: could not sync %s with the fold mode: %s', HANDOFF_TOOL_NAME, messageOf(error))
2249
2293
  }
2250
2294
  }
2251
2295
 
2296
+ syncHandoffTool(resolve())
2297
+
2252
2298
  // Prep runs inside a waterfall: synchronous, and it must never throw — its return
2253
2299
  // value is the model call's configuration.
2254
2300
  ctx.on('agent/request', (payload, next) => {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-context-truth",
3
- "version": "0.3.0",
3
+ "version": "0.3.1",
4
4
  "description": "DeepSeek Harness plugin: tells the model its real, host-measured context occupancy every turn — and keeps compaction summaries from carrying false \"context is nearly exhausted\" claims.",
5
5
  "keywords": [
6
6
  "deepseek-harness",
@@ -18,16 +18,24 @@ const THRESHOLD = 678464
18
18
 
19
19
  /** Minimal ctx capturing what the plugin registers. */
20
20
  function stubContext({ used, meter, projections, compaction, commands, logs, tools } = {}) {
21
- const registered = { variable: undefined, context: undefined, listeners: {}, injections: [], tools: [], effects: [], timers: [] }
21
+ const registered = { variable: undefined, context: undefined, listeners: {}, injections: [], tools: [], effects: [], disposers: [], timers: [] }
22
22
  const tokenMeter = meter === undefined ? { measure: () => ({ totalTokens: used }) } : meter
23
23
  // A host always mounts the tools service, so the stub does too: without it the
24
24
  // handoff tool cannot register and every log assertion would see that warning.
25
+ // `register` returns the disposer a real host returns, so a test can observe the
26
+ // tool following a live fold-mode switch.
25
27
  const toolsService =
26
28
  tools === undefined
27
29
  ? {
28
30
  register: (definition) => {
29
31
  registered.tools.push(definition)
30
- return () => {}
32
+ let live = true
33
+ return () => {
34
+ if (!live) return
35
+ live = false
36
+ const index = registered.tools.indexOf(definition)
37
+ if (index >= 0) registered.tools.splice(index, 1)
38
+ }
31
39
  },
32
40
  }
33
41
  : tools
@@ -82,7 +90,9 @@ function stubContext({ used, meter, projections, compaction, commands, logs, too
82
90
  effect: (callback, label) => {
83
91
  registered.effects.push(label)
84
92
  const dispose = callback()
85
- return typeof dispose === 'function' ? dispose : () => {}
93
+ const disposer = typeof dispose === 'function' ? dispose : () => {}
94
+ registered.disposers.push(disposer)
95
+ return disposer
86
96
  },
87
97
  setInterval: (callback, ms) => {
88
98
  registered.timers.push({ callback, ms })
@@ -1283,6 +1293,38 @@ test('foldMode: absent means idle, an explicit opt-out or mode wins', () => {
1283
1293
  assert.equal(shouldFoldAtIdle({ used: 640000, threshold: THRESHOLD, window: WINDOW }, resolveOptions({ foldMode: 'idle' })).fold, true)
1284
1294
  })
1285
1295
 
1296
+ test('the handoff tool follows the live fold mode', async (t) => {
1297
+ const root = scratchRoot(t)
1298
+ const { meter } = movableMeter(600000)
1299
+ const agent = handoffAgent(handoffSession('session-tool'))
1300
+ const config = { foldMode: 'off', handoffDir: root }
1301
+ const { ctx, registered } = stubContext({ meter, compaction: { compactNow: () => Promise.resolve({}) } })
1302
+ const hasTool = () => registered.tools.some((definition) => definition.name === HANDOFF_TOOL_NAME)
1303
+
1304
+ apply(ctx, config)
1305
+ assert.equal(hasTool(), false, 'off mode must not advertise handoff_ready')
1306
+
1307
+ config.foldMode = 'idle'
1308
+ await requestStep(registered, agent, 1)
1309
+ assert.equal(hasTool(), false, 'idle mode must not advertise handoff_ready')
1310
+
1311
+ config.foldMode = 'handoff'
1312
+ await requestStep(registered, agent, 2)
1313
+ assert.equal(hasTool(), true, 'handoff mode must register the tool on the next request')
1314
+
1315
+ config.foldMode = 'off'
1316
+ await requestStep(registered, agent, 3)
1317
+ assert.equal(hasTool(), false, 'switching away must remove it again')
1318
+
1319
+ // Teardown must not leave the row behind: the registration lives on the tools
1320
+ // service's layer, so only the returned disposer (or this cleanup) removes it.
1321
+ config.foldMode = 'handoff'
1322
+ await requestStep(registered, agent, 4)
1323
+ assert.equal(hasTool(), true)
1324
+ for (const dispose of registered.disposers.slice().reverse()) dispose()
1325
+ assert.equal(hasTool(), false, 'disposing the plugin must unregister the tool')
1326
+ })
1327
+
1286
1328
  test('handoff notes live under $DSH_HOME, one directory per session, never the workspace', () => {
1287
1329
  const env = { DSH_HOME: join(tmpdir(), 'ct-home') }
1288
1330
  const base = resolveOptions({ foldMode: 'handoff' })
@@ -1708,9 +1750,20 @@ test('handoff_ready refuses everything it cannot honour', async (t) => {
1708
1750
  return registered.tools.find((definition) => definition.name === HANDOFF_TOOL_NAME)
1709
1751
  }
1710
1752
 
1711
- // Outside handoff mode the tool exists (so the live switch has something to
1712
- // switch to) and refuses instead of registering anything.
1713
- assert.match(toolFor({}).execute({}, { agent }), /only applies in handoff fold mode/)
1753
+ // Outside handoff mode the tool is not registered at all, so the catalog only
1754
+ // carries what the current mode can honour.
1755
+ assert.equal(toolFor({}), undefined, 'off must not advertise handoff_ready')
1756
+ assert.equal(toolFor({ foldMode: 'idle' }), undefined, 'idle must not advertise handoff_ready')
1757
+
1758
+ // Defense in depth: a call already in flight when the mode flips must refuse
1759
+ // rather than register against a mode that no longer wants a handoff.
1760
+ const live = { foldMode: 'handoff', handoffDir: root }
1761
+ const liveCtx = stubContext({ used: 600000, compaction: { compactNow: () => Promise.resolve({}) } })
1762
+ apply(liveCtx.ctx, live)
1763
+ const inFlight = liveCtx.registered.tools.find((definition) => definition.name === HANDOFF_TOOL_NAME)
1764
+ live.foldMode = 'off'
1765
+ assert.match(inFlight.execute({}, { agent }), /only applies in handoff fold mode/)
1766
+ live.foldMode = 'handoff'
1714
1767
 
1715
1768
  const tool = toolFor({ foldMode: 'handoff' })
1716
1769
  const notePath = handoffPathFor(root, 'session-refuse', 1)