dsh-context-truth 0.3.3 → 0.3.4

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,22 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.3.4
4
+
5
+ * **唤醒消息瘦身:完整提醒改由唤醒轮的 runtime context 承载。** 以前轮末唤醒把整段
6
+ `[handoff fold · prepare]` 塞进一条用户消息(实测 session-36125d3f…:最后一次请求时读数还没越过
7
+ 准备点 617,984,轮次结束后涨到 619,646 才越过,于是 prepare 通道没机会发,只有唤醒通道发了整段文案)。
8
+ 现在:
9
+ - 唤醒消息只有一行 `[handoff fold · wake]`,点明“本轮结束时会折叠”和唯一允许的交接档路径;
10
+ - `prepare` 在唤醒轮的**同一个请求**里重新发布完整提醒到 `context-truth:handoff` 块,清单不再以用户
11
+ 消息形式出现;
12
+ - 若唤醒轮开始时读数已回落到准备点以下(宿主先折了等),只保留那一行,并记一条
13
+ “wake round … is below the prep point now”日志说明原因。
14
+ * 测试:74(新增“唤醒轮读数已回落时只留一行”用例;三处变异分别失败 1 / 2 / 1 例后逐字节恢复)。
15
+ * **实机演练(2026-11-17 23:48)**:临时把准备点压到 178K、预算提到 5,轮末真实唤醒一次——日志
16
+ `handoff reminder 5/5 … woke the round`(15:48:14)与 `wake round … published the handoff reminder in
17
+ runtime context`(15:48:21)成对出现;会话里那条唤醒消息只有一行且含路径,完整清单出现在同一轮的
18
+ `context-truth:handoff` 块里。演练未写档,因此没有折叠;演练后配置已还原(thresholdRatio 0.8、预算 3)。
19
+
3
20
  ## 0.3.3
4
21
 
5
22
  * **README 记入权限模型带来的限制。** 交接档在 `$DSH_HOME/handoffs/…`,而模型的文件写入受会话权限沙箱约束
package/README-en.md CHANGED
@@ -106,7 +106,7 @@ The chain is:
106
106
  3. at the end of that round the plugin calls `compactNow()`;
107
107
  4. after the fold it uses `followup` to activate **exactly one** turn whose first instruction is to read that note before touching the task.
108
108
 
109
- 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 (dynamic context is only read by requests that actually happen, and a round that ends issues no further request, so the reminder 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.
109
+ 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` (dynamic context is only read by requests that actually happen, and a round that ends issues no further request, so the reminder would otherwise wait for a human — measured, and that is why the wake exists). The wake message is a **single line** naming the note path, and `prepare` re-publishes the full checklist into the runtime-context handoff block of that same request — so the transcript never gets the whole reminder as a user message. If the reading has already dropped below the prep point when the wake round starts (for example the host folded first), only the one-liner remains and the log says why. 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.
110
110
 
111
111
  **Known limitation: session permissions can block the note write.** Notes live under `$DSH_HOME/handoffs/…`, and the host sandboxes model file writes per session permission (`checkedTarget` in `@deepseek-ai/dsh-fs-sandbox`, which checks the target against the writable roots of the resolved mode):
112
112
 
@@ -234,7 +234,7 @@ What you get for it: the model stops halting or handing off because it *thinks*
234
234
  ## Verify
235
235
 
236
236
  ```sh
237
- npm test # 73 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, the handoff reminder travelling in runtime context rather than as a message, and a live mode switch dropping it
237
+ npm test # 74 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, the handoff reminder travelling in runtime context rather than as a message, and a live mode switch dropping it
238
238
  ```
239
239
 
240
240
  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)`.
package/README.md CHANGED
@@ -161,9 +161,12 @@ this in as few commands as possible, then a short answer."。数字它读对了
161
161
  4. 折叠后插件用 `followup` **只自动激活一轮**,第一条指令就是"先读这份档,再从它的下一步继续"。
162
162
 
163
163
  护栏:提醒每周期最多 3 次;某个回合结束时如果模型还没登记、但已过准备点,插件会用
164
- `followup` **唤醒**一轮把提醒送到(动态上下文只有在真的发生请求时才会被模型读到,轮次结束就没人
165
- 再发请求,提醒会一直等人类开口——实测踩过);交接档是临时文件,下一次交接生成时回收旧的、7 天兜底清理;
166
- 登记了档但没折成(引擎拒绝、被别的东西先折了)时不会激活,档保留。
164
+ `followup` **唤醒**一轮(动态上下文只有在真的发生请求时才会被模型读到,轮次结束就没人再发请求,
165
+ 提醒会一直等人类开口——实测踩过)。唤醒消息只有**一行**(点明交接档路径),完整清单由 `prepare` 在
166
+ 唤醒轮的**同一个请求**里重新发布到 runtime context 的 handoff 块——所以会话里不会出现整段提醒的用户消息;
167
+ 如果唤醒轮开始时读数已回落到准备点以下(例如宿主先折了),就只保留那一行并在日志里说明原因。
168
+ 交接档是临时文件,下一次交接生成时回收旧的、7 天兜底清理;登记了档但没折成(引擎拒绝、被别的东西
169
+ 先折了)时不会激活,档保留。
167
170
 
168
171
  **已知限制:会话权限能挡住交接档写入。** 交接档在 `$DSH_HOME/handoffs/…`,而宿主按会话权限给模型的文件写入设了沙箱
169
172
  (`@deepseek-ai/dsh-fs-sandbox` 的 `checkedTarget`:按权限模式判断目标是否落在可写根内):
@@ -333,7 +336,7 @@ runtime-context 快照**字节不变就不会重发**,所以读数按台阶量
333
336
  ## 验证
334
337
 
335
338
  ```sh
336
- npm test # 73 项单测:分档/迟滞/量化/自由窗口/折叠定义/空闲折叠与护栏/配置热更新/schema 默认值一致性/节奏估算/降级/摘要改写/形似请求排除/幂等/交接式折叠(提醒、登记、轮末折叠、单次激活、重启恢复、回收、轮末唤醒)/客户端设置卡结构/交接提醒走 runtime context 而非消息,以及实时切模式后提醒随模式消失
339
+ npm test # 74 项单测:分档/迟滞/量化/自由窗口/折叠定义/空闲折叠与护栏/配置热更新/schema 默认值一致性/节奏估算/降级/摘要改写/形似请求排除/幂等/交接式折叠(提醒、登记、轮末折叠、单次激活、重启恢复、回收、轮末唤醒)/客户端设置卡结构/交接提醒走 runtime context 而非消息,以及实时切模式后提醒随模式消失
337
340
  ```
338
341
 
339
342
  装好后开一个新会话发一条消息,展开该轮的 runtime context 块应看到
package/lib/index.js CHANGED
@@ -1630,6 +1630,28 @@ function handoffPrepMessage({ path, trigger, recycled, options }) {
1630
1630
  ].join('\n')
1631
1631
  }
1632
1632
 
1633
+ /**
1634
+ * Wake message: one line that opens the round.
1635
+ *
1636
+ * The full reminder travels as the `context-truth:handoff` runtime-context block
1637
+ * of that same round (`prepare` publishes it), because a message that starts a
1638
+ * turn is also the only thing the model is guaranteed to read before the
1639
+ * request. The path is repeated here so the message stays actionable even if the
1640
+ * block cannot render (for example a fold-mode change in between).
1641
+ */
1642
+ function handoffWakeMessage({ path, options }) {
1643
+ if (options.language === 'zh') {
1644
+ return [
1645
+ '[交接式折叠 · 唤醒] 本轮结束时会折叠,所以现在补一份交接档。',
1646
+ `完整提醒(唯一允许的路径与分节清单)在 runtime context 的 handoff 块里;路径必须是:${path}`,
1647
+ ].join('\n')
1648
+ }
1649
+ return [
1650
+ '[handoff fold · wake] This round is folded when it ends, so write the handoff note now.',
1651
+ `The full reminder (the one allowed path and the section checklist) is in the handoff runtime-context block; the path must be exactly: ${path}`,
1652
+ ].join('\n')
1653
+ }
1654
+
1633
1655
  /** Activation message: read the note first, then finish the interrupted work. */
1634
1656
  function handoffActivationMessage({ path, foldNo, options }) {
1635
1657
  if (options.language === 'zh') {
@@ -1890,6 +1912,48 @@ function installHandoffFold(ctx, resolve, services, notices) {
1890
1912
  )
1891
1913
  }
1892
1914
 
1915
+ /**
1916
+ * Publish the full prep reminder for the request that is being assembled.
1917
+ *
1918
+ * Both delivery paths share it: the mid-round trigger below, and the wake round
1919
+ * (whose message is only a one-liner, so the checklist has to ride runtime
1920
+ * context). Returns the published payload, or `null` when the reading is no
1921
+ * longer past the prep point — the wake round then keeps just its one-line
1922
+ * message instead of nagging about a fold that is no longer due.
1923
+ */
1924
+ function publishPrep(state, options, sessionId, session) {
1925
+ const trigger = handoffTrigger(readOccupancy(ctx, session, options, services.meter), options)
1926
+ if (!trigger.prepare) {
1927
+ logLine(
1928
+ ctx,
1929
+ 'info',
1930
+ 'context-truth: wake round for %s is below the prep point now (used=%s of %s); the one-line wake stands alone',
1931
+ sessionId,
1932
+ trigger.used,
1933
+ trigger.threshold,
1934
+ )
1935
+ return null
1936
+ }
1937
+ const root = handoffRoot(options)
1938
+ const path = handoffPathFor(root, sessionId, state.foldNo + 1)
1939
+ const doomed = handoffReapable(root, sessionId, [path, handoffPathFor(root, sessionId, state.foldNo)])
1940
+ notices.set(sessionId, handoffPrepMessage({ path, trigger, recycled: doomed.length, options }))
1941
+ // Same ordering as the mid-round path: publish first, reap after, so a failed
1942
+ // delivery never costs the model its previous note for nothing.
1943
+ const recycled = deleteFiles(doomed)
1944
+ logLine(
1945
+ ctx,
1946
+ 'info',
1947
+ 'context-truth: wake round for %s published the handoff reminder in runtime context (used=%s of %s, recycled=%s) -> %s',
1948
+ sessionId,
1949
+ trigger.used,
1950
+ trigger.threshold,
1951
+ recycled,
1952
+ path,
1953
+ )
1954
+ return { path, trigger, recycled }
1955
+ }
1956
+
1893
1957
  /**
1894
1958
  * Step 1: remind the model while it can still act. Runs inside the
1895
1959
  * `agent/request` waterfall, so it stays synchronous and swallows everything —
@@ -1918,6 +1982,11 @@ function installHandoffFold(ctx, resolve, services, notices) {
1918
1982
  // 唤醒轮的第一条消息就是提醒,把它记成“本轮已提醒”,否则同一轮第二个
1919
1983
  // request 会再注入一条(实机 01:39:07 唤醒 2/3,01:39:17 又注入 3/3)。
1920
1984
  state.reminderTurn = turn === undefined ? null : turn
1985
+ // 唤醒消息只是一行入口;完整提醒在这里重新发布,由**本请求**的
1986
+ // runtime-context 块渲染(`context-truth:handoff`)。唤醒轮一定有请求,
1987
+ // 所以这条通道在这里是可用的 —— 这也是 A 方案能消掉“整段提醒变成用户
1988
+ // 消息”的原因。✗ 不要在这里提前 return,否则本轮只剩那一行短消息。
1989
+ publishPrep(state, options, sessionId, session)
1921
1990
  persist(options, sessionId, state)
1922
1991
  return
1923
1992
  }
@@ -2008,7 +2077,11 @@ function installHandoffFold(ctx, resolve, services, notices) {
2008
2077
  const path = handoffPathFor(root, sessionId, state.foldNo + 1)
2009
2078
  const doomed = handoffReapable(root, sessionId, [path, handoffPathFor(root, sessionId, state.foldNo)])
2010
2079
  try {
2011
- agent.followup(handoffMessage(handoffPrepMessage({ path, trigger, recycled: doomed.length, options })))
2080
+ // Short on purpose: the wake message only opens the round. The full
2081
+ // reminder is published into runtime context by `prepare` on that round's
2082
+ // first request, so the transcript shows a one-liner instead of the whole
2083
+ // checklist (see `handoffWakeMessage`).
2084
+ agent.followup(handoffMessage(handoffWakeMessage({ path, options })))
2012
2085
  } catch (error) {
2013
2086
  logLine(ctx, 'warn', 'context-truth: could not wake %s with the handoff reminder: %s', sessionId, messageOf(error))
2014
2087
  return
@@ -2577,6 +2650,7 @@ export const internals = {
2577
2650
  handoffRoot,
2578
2651
  handoffPathFor,
2579
2652
  handoffPrepMessage,
2653
+ handoffWakeMessage,
2580
2654
  handoffActivationMessage,
2581
2655
  handoffReapable,
2582
2656
  sweepHandoffs,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-context-truth",
3
- "version": "0.3.3",
3
+ "version": "0.3.4",
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",
@@ -8,7 +8,7 @@ import { apply, internals, name, inject, Config, CONTEXT_NAME, VARIABLE_NAME, HA
8
8
 
9
9
  const { resolveOptions, readOccupancy, settleBand, quantize, quantizeHeadroom, headroomDisplayStep, render, patchCompactionInstruction, patchCompactionRequest, isCompactionRequest, isTaggedCompactionRequest, messageText, DEFAULT_OPTIONS, DEFAULT_COMPACTION_RULES, PACE_LADDER, median, nextPaceState, samplePace, paceSteps, paceRung, settlePace, paceSentence, tightClause, foldClause, shouldFoldAtIdle, backendIdentity } = internals
10
10
 
11
- const { resolveFoldMode, handoffTrigger, handoffRoot, handoffPathFor, handoffPrepMessage, handoffActivationMessage, handoffReapable, sweepHandoffs, handoffFileChars, safeSegment, sessionIdOf, isDelegate, samePath, HANDOFF_TOOL_NAME, HANDOFF_MIN_CHARS, HANDOFF_MAX_AGE_MS, HANDOFF_STATE_FILE } = internals
11
+ const { resolveFoldMode, handoffTrigger, handoffRoot, handoffPathFor, handoffPrepMessage, handoffWakeMessage, handoffActivationMessage, handoffReapable, sweepHandoffs, handoffFileChars, safeSegment, sessionIdOf, isDelegate, samePath, HANDOFF_TOOL_NAME, HANDOFF_MIN_CHARS, HANDOFF_MAX_AGE_MS, HANDOFF_STATE_FILE } = internals
12
12
 
13
13
  /** A 1M window reserving the DeepSeek adapter's default 256K completion tokens. */
14
14
  const WINDOW = 1000000
@@ -1430,6 +1430,13 @@ test('the prep point is a fraction of the fold point, and only handoff mode prep
1430
1430
  const enPrep = handoffPrepMessage({ path, trigger, recycled: 0, options: enOptions })
1431
1431
  assert.ok(enPrep.includes(path))
1432
1432
  assert.match(enPrep, /temporary file/)
1433
+ const enWake = handoffWakeMessage({ path, options: enOptions })
1434
+ assert.match(enWake, /\[handoff fold · wake\]/)
1435
+ assert.ok(enWake.includes(path), 'the wake line still names the exact path')
1436
+ assert.ok(!enWake.includes('Write a handoff note for the post-fold you'), 'the wake line is not the checklist')
1437
+ const zhWake = handoffWakeMessage({ path, options: zhOptions })
1438
+ assert.match(zhWake, /交接式折叠 · 唤醒/)
1439
+ assert.ok(zhWake.includes(path))
1433
1440
  const enActivation = handoffActivationMessage({ path, foldNo: 1, options: enOptions })
1434
1441
  assert.ok(enActivation.includes(path))
1435
1442
  assert.match(enActivation, /only auto-activated turn/)
@@ -1547,12 +1554,17 @@ test('a round that ends past the prep point wakes one reminder turn, bounded by
1547
1554
  await idleBoundary(registered, agent)
1548
1555
  assert.equal(agent.followed.length, 1)
1549
1556
 
1550
- // The wake round starts: the wake message IS this round's reminder, so neither
1551
- // channel may stack a second copy in it.
1557
+ // The wake round starts: its message is a one-liner, and the checklist rides
1558
+ // that round's runtime-context block instead of the transcript.
1559
+ const wake = agent.followed[0].content[0].text
1560
+ assert.match(wake, /\[handoff fold · wake\]/)
1561
+ assert.ok(!wake.includes('Write a handoff note for the post-fold you'), 'the checklist must not travel as a message')
1562
+ assert.ok(wake.includes(handoffPathFor(root, 'session-nonote', 1)), 'the one-liner still names the path')
1552
1563
  await requestStep(registered, agent, 2)
1553
- assert.doesNotMatch(handoffBlock(registered, agent), /handoff fold · prepare/, 'no duplicate reminder in the wake round')
1564
+ assert.match(handoffBlock(registered, agent), /handoff fold · prepare/, 'the wake round carries the full reminder in runtime context')
1565
+ assert.ok(handoffBlock(registered, agent).includes('Write a handoff note for the post-fold you'))
1554
1566
  await requestStep(registered, agent, 2, 2)
1555
- assert.doesNotMatch(handoffBlock(registered, agent), /handoff fold · prepare/, 'and none on a later step of the same wake round')
1567
+ assert.doesNotMatch(handoffBlock(registered, agent), /handoff fold · prepare/, 'and it is retired on the next request')
1556
1568
  assert.equal(agent.injected.length, 0)
1557
1569
 
1558
1570
  // Still no note: the budget allows one more wake, then it stops.
@@ -1565,6 +1577,29 @@ test('a round that ends past the prep point wakes one reminder turn, bounded by
1565
1577
  assert.ok(logs.some(([, message]) => String(message).includes('budget spent')))
1566
1578
  })
1567
1579
 
1580
+ test('a wake round that is no longer past the point keeps only its one-liner', async (t) => {
1581
+ const root = scratchRoot(t)
1582
+ const { box, meter } = movableMeter(600000)
1583
+ const logs = []
1584
+ const agent = handoffAgent(handoffSession('session-late'))
1585
+ const { ctx, registered } = stubContext({ meter, logs, compaction: { compactNow: () => Promise.resolve({}) } })
1586
+ apply(ctx, { foldMode: 'handoff', handoffDir: root })
1587
+
1588
+ await requestStep(registered, agent, 1)
1589
+ await idleBoundary(registered, agent)
1590
+ assert.equal(agent.followed.length, 1, 'the round was woken')
1591
+
1592
+ // Something else folded first, or the reading collapsed: the wake round must not
1593
+ // carry a reminder for a fold that is no longer due.
1594
+ box.used = 100000
1595
+ await requestStep(registered, agent, 2)
1596
+ assert.doesNotMatch(handoffBlock(registered, agent), /handoff fold · prepare/, 'no reminder below the point')
1597
+ assert.ok(
1598
+ logs.some(([, message]) => String(message).includes('below the prep point now')),
1599
+ 'the degraded wake round says why',
1600
+ )
1601
+ })
1602
+
1568
1603
  test('a failed fold keeps the note and activates nothing', async (t) => {
1569
1604
  const root = scratchRoot(t)
1570
1605
  const { box, meter } = movableMeter(600000)