dsh-todo-freshness 0.2.0 → 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/README.md CHANGED
@@ -6,7 +6,7 @@ DSH 的任务卡片("任务 1 进行中 · 5 待处理")只是**最后一次
6
6
 
7
7
  **Host(`index.js`)**
8
8
 
9
- - 注册一个会话投影 `todoFreshness`,从既有事件里折叠出:上次写清单是第几轮第几步、之后又跑了多少次工具调用、清单里还剩几项没有结论、这一轮是不是已经结束。
9
+ - 注册一个会话投影 `todoFreshness`,从既有事件里折叠出:上次写清单是什么时候、之后又跑了多少次工具调用、其中有多少次真的改了文件、清单里还剩几项没有结论、这一轮是不是已经结束。
10
10
  - 在 `tools/post-execute` 上挂一个建议:当清单里还有未完成项、且从上次回写起已经连续跑了默认 6 次(以及 14 次)工具调用时,往下一步注入一条提醒,要求模型用真实状态整表重写。次数可配置,见下文。
11
11
  - 不写 `todo/write`,不把 `pending` 改成 `completed`。没干完就是没干完。
12
12
 
@@ -15,6 +15,7 @@ DSH 的任务卡片("任务 1 进行中 · 5 待处理")只是**最后一次
15
15
  - 在 `conversation.input.dock` 的 order 1 注册一条提示条,只在两种情况下出现:
16
16
  - `stale`:清单里还有未完成项,但已经连续超过阈值次工具调用没有回写;
17
17
  - `closedWithUnfinished`:这一轮已经结束,清单却还留着未完成项。
18
+ - 提示条只报测得的事实——"清单 12 分钟前写下,之后有 8 次文件改动"——不说"这些活已经做完了"。哪一项做完了插件无从得知,能从事件里数出来的只有"清单没动、但代码动了",所以它就说这一句。
18
19
  - 正常更新清单时它不出现,不会和内置的任务卡片抢位置。鼠标悬停可以看到当前生效的阈值。
19
20
 
20
21
  ## 为什么这么设计
@@ -26,7 +27,7 @@ DSH 的任务卡片("任务 1 进行中 · 5 待处理")只是**最后一次
26
27
  | 轮次结束时把遗留项一律标成 `completed` | 面板永远干净 | 没做完的活也显示完成,等于伪造结果 |
27
28
  | 如实标注 + 催模型回写 | 面板可能仍然显示未完成 | 但它显示的确实是真话 |
28
29
 
29
- 这个插件走第二条。清单"对不上"时你看到的是明确的"这份清单还没跟上",而不是一个看起来还在进行的假进度。
30
+ 这个插件走第二条。清单"对不上"时你看到的是可核对的差距(几分钟前写的、之后改了几次文件),而不是一个看起来还在进行的假进度,也不是一句替你下结论的"还没跟上"。
30
31
 
31
32
  ## 配置
32
33
 
@@ -53,6 +54,7 @@ DSH 的任务卡片("任务 1 进行中 · 5 待处理")只是**最后一次
53
54
 
54
55
  - 提醒只是建议。模型可以不理会它,这时面板依旧停在旧状态——插件不会替它决定。
55
56
  - 阈值是经验值。默认 6 次是按"一次工具调用大概推进一个子任务"估的,实际任务粒度不同的话用 `staleCalls` 调。
57
+ - 触发看的是工具调用总数,提示条里引用的却是文件改动次数。读文件、跑 shell 也算调用但不会改代码,所以在连续跑命令的阶段,计数会先于真实进度到达阈值——把 `staleCalls` 调大就是给这类阶段留余量。
56
58
  - 投影 key `todoFreshness` 是本插件私有的;卸载后它从会话状态里消失,不影响内置的 `todos`。
57
59
 
58
60
  ## 安装
package/client.js CHANGED
@@ -74,6 +74,11 @@ window.__ModuleLoader__.load({
74
74
  * The staleness note. Renders nothing while the list still matches the work,
75
75
  * and one line when the built-in card describes a moment that has passed.
76
76
  * `todoFreshness` is this bundle's own projection; `todos` is the built-in one.
77
+ *
78
+ * The line reports what was measured — how long ago the list was written and
79
+ * how many edits landed since — rather than asserting that work "is done".
80
+ * The plugin cannot know which item finished; it can only know that the tree
81
+ * moved while the list stood still, and that is what it says.
77
82
  */
78
83
  function FreshnessNote({ useProjection, t }) {
79
84
  const freshness = useProjection('todoFreshness')
@@ -83,6 +88,16 @@ window.__ModuleLoader__.load({
83
88
  if (unfinished === 0) return null
84
89
  const closed = (freshness.closedWithUnfinished ?? 0) > 0
85
90
  if (!freshness.stale && !closed) return null
91
+ const edits = freshness.mutationsSinceWrite ?? 0
92
+ const written = freshness.writeTime ?? 0
93
+ const minutes = written > 0 ? Math.max(1, Math.round((Date.now() - written) / 60000)) : 0
94
+ // A quiet list is not evidence of anything, so the note only claims what
95
+ // the counters support; with no edits to point at it falls back to the age.
96
+ const text = closed
97
+ ? t('note.closed')
98
+ : edits > 0 && minutes > 0
99
+ ? t('note.stale', { edits, minutes })
100
+ : minutes > 0 ? t('note.age', { minutes }) : t('note.plain')
86
101
  const threshold = freshness.staleCalls
87
102
  return h('section', {
88
103
  style: styles.root,
@@ -94,22 +109,26 @@ window.__ModuleLoader__.load({
94
109
  },
95
110
  h('div', { style: styles.body },
96
111
  h('span', { style: styles.glyph }, h(Glyph)),
97
- h('span', { style: styles.text }, closed ? t('note.closed') : t('note.stale')),
112
+ h('span', { style: styles.text }, text),
98
113
  h('span', { style: styles.count }, t('note.count', { unfinished }))))
99
114
  }
100
115
 
101
116
  const dictionaries = {
102
117
  zh: {
103
- 'note.stale': '这份清单还没跟上已经做完的工作',
118
+ 'note.stale': '清单 {minutes} 分钟前写下,之后有 {edits} 次文件改动',
119
+ 'note.age': '清单已经 {minutes} 分钟没有回写',
120
+ 'note.plain': '这份清单可能已经落后于进度',
104
121
  'note.closed': '这一轮已经结束,清单停在旧状态',
105
122
  'note.count': '还有 {unfinished} 项没有结论',
106
- 'note.hint': '清单连续 {threshold} 次工具调用没有回写',
123
+ 'note.hint': '连续 {threshold} 次文件改动没有回写时提示',
107
124
  },
108
125
  en: {
109
- 'note.stale': 'This list has not caught up with the work already done',
126
+ 'note.stale': 'List written {minutes}m ago, {edits} file edits since',
127
+ 'note.age': 'List not rewritten for {minutes} minutes',
128
+ 'note.plain': 'This list may be behind the work',
110
129
  'note.closed': 'This turn ended and the list still shows old statuses',
111
130
  'note.count': '{unfinished} without a verdict',
112
- 'note.hint': '{threshold} tool calls since the list was last written',
131
+ 'note.hint': 'shown after {threshold} file edits without a rewrite',
113
132
  },
114
133
  }
115
134
 
package/index.js CHANGED
@@ -24,21 +24,29 @@ import {
24
24
  } from './lib/fold.js'
25
25
 
26
26
  /**
27
- * The reminder both thresholds send: state the drift, ask for a truthful
28
- * rewrite, and forbid the shortcut that would silence it.
27
+ * The reminder both thresholds send. It states the measured fact — how many file
28
+ * edits landed since the list was written — instead of claiming the list is
29
+ * wrong. A claim the model can check is likelier to be acted on than an
30
+ * assertion it may disagree with.
31
+ * @param calls - tool calls since the list was last written.
32
+ * @param edits - file edits among those calls.
29
33
  */
30
- const NUDGE_TEXT = 'Your todo list has not been updated for a while and no longer reflects what you have '
31
- + 'done. Call `todo_write` with the COMPLETE list and the true status of every item before continuing. '
32
- + 'Do not mark unfinished work `completed` just to clear the panel.'
34
+ function nudgeText(calls, edits) {
35
+ return `The todo list has not been rewritten in ${calls} tool calls (${edits} of them edited files). `
36
+ + 'If the work has moved on, call `todo_write` with the COMPLETE list and the true status of every item. '
37
+ + 'Do not mark unfinished work `completed` just to clear the panel.'
38
+ }
33
39
 
34
40
  /**
35
41
  * The advisory nudge, stamped with a producer source so history shows it as
36
42
  * injected context rather than as something the user said.
43
+ * @param calls - tool calls since the list was last written.
44
+ * @param edits - file edits among those calls.
37
45
  * @returns a frozen user message carrying one notice.
38
46
  */
39
- function nudgeMessage() {
47
+ function nudgeMessage(calls, edits) {
40
48
  return createUserMessage({
41
- content: [{ type: 'text', text: NUDGE_TEXT }],
49
+ content: [{ type: 'text', text: nudgeText(calls, edits ?? 0) }],
42
50
  source: { kind: 'todo-freshness', form: 'notice', summary: 'todo list out of date' },
43
51
  })
44
52
  }
@@ -130,14 +138,17 @@ export async function apply(ctx, config) {
130
138
  view: state => ({ ...state, staleCalls: chosen.staleCalls }),
131
139
  summary: false,
132
140
  },
133
- stateVersion: 1,
141
+ // v2 counts edits instead of calls and carries the list's write time. An
142
+ // older checkpoint has neither field, and arithmetic on a missing counter
143
+ // yields NaN, which would silently disable the whole projection.
144
+ stateVersion: 2,
134
145
  })
135
146
 
136
147
  if (!chosen.nudge || chosen.nudgeAt.length === 0) return
137
148
 
138
- // Process-local dedup: the tool-call count already reminded at, per live
139
- // Agent. The projection is a pure fold and must not record that a nudge went
140
- // out, or the note would change shape depending on who read it.
149
+ // Process-local dedup: the edit count already reminded at, per live Agent. The
150
+ // projection is a pure fold and must not record that a nudge went out, or the
151
+ // note would change shape depending on who read it.
141
152
  const nudged = new WeakMap()
142
153
 
143
154
  // The reminder rides the model-facing surface as injected context, which lands
@@ -155,7 +166,7 @@ export async function apply(ctx, config) {
155
166
  nudged.set(agent, at)
156
167
  return {
157
168
  ...decision,
158
- additionalContexts: [...(decision.additionalContexts ?? []), nudgeMessage()],
169
+ additionalContexts: [...(decision.additionalContexts ?? []), nudgeMessage(at, state.mutationsSinceWrite)],
159
170
  }
160
171
  })
161
172
  }
package/lib/fold.js CHANGED
@@ -12,6 +12,15 @@ export const STALE_CALLS = 6
12
12
  /** Default tool-call counts, measured from the last write, that each earn one nudge. */
13
13
  export const NUDGE_AT = [6, 14]
14
14
 
15
+ /**
16
+ * Tool calls that edit files. Counted for the note's evidence only — never for
17
+ * the staleness trigger — so that a list can be described as "written 5 minutes
18
+ * and 8 edits ago" rather than with a call count nobody can verify. Shell calls
19
+ * are deliberately absent: `rm` and `sed` are indistinguishable from `ls` at
20
+ * this layer, so counting them would overstate what actually changed.
21
+ */
22
+ export const MUTATING_TOOLS = new Set(['edit', 'write', 'apply_patch', 'multiedit', 'multi_edit'])
23
+
15
24
  /**
16
25
  * The nudge schedule that follows a given staleness threshold: the flip point
17
26
  * itself, then roughly twice as far out for a list that stalled again after
@@ -38,8 +47,10 @@ export function emptyState(turn = 0) {
38
47
  active: 0,
39
48
  pending: 0,
40
49
  writeSeq: -1,
50
+ writeTime: 0,
41
51
  callsSinceWrite: 0,
42
52
  stepsSinceWrite: 0,
53
+ mutationsSinceWrite: 0,
43
54
  closedWithUnfinished: 0,
44
55
  stale: false,
45
56
  }
@@ -53,6 +64,12 @@ export function unfinished(state) {
53
64
  /**
54
65
  * Recompute the derived `stale` flag. Returns a new object only when the flag
55
66
  * actually moves, so an unchanged list does not republish.
67
+ *
68
+ * The trigger stays on total tool calls, which is what `staleCalls` has meant
69
+ * since 0.1.0 — redefining it as edits would silently tighten every profile that
70
+ * already set a value. Edits are counted alongside it, but only as evidence the
71
+ * note can quote: "8 edits since this list was written" is something the reader
72
+ * can check in the transcript, while "20 calls" is not.
56
73
  * @param state - state carrying the latest counters.
57
74
  * @param staleCalls - tool calls without a write that make the list stale.
58
75
  * @returns the state with a correct `stale` flag.
@@ -68,7 +85,7 @@ export function settled(state, staleCalls = STALE_CALLS) {
68
85
  * Build a fold bound to one staleness threshold. The threshold is a deployment
69
86
  * choice, not session data, so it stays in this closure instead of the published
70
87
  * state: the wire shape is the same whichever value a profile configures.
71
- * @param staleCalls - tool calls without a write that make the list stale.
88
+ * @param staleCalls - mutating calls without a write that make the list stale.
72
89
  * @returns the fold for that threshold.
73
90
  */
74
91
  export function createFold(staleCalls = STALE_CALLS) {
@@ -99,9 +116,15 @@ export function createFold(staleCalls = STALE_CALLS) {
99
116
  step: event.data.step,
100
117
  stepsSinceWrite: state.stepsSinceWrite + 1,
101
118
  }, staleCalls)
102
- case 'tool/call':
119
+ case 'tool/call': {
103
120
  if (!state.list) return state
104
- return settled({ ...state, callsSinceWrite: state.callsSinceWrite + 1 }, staleCalls)
121
+ const mutates = MUTATING_TOOLS.has(event.data?.name)
122
+ return settled({
123
+ ...state,
124
+ callsSinceWrite: state.callsSinceWrite + 1,
125
+ mutationsSinceWrite: state.mutationsSinceWrite + (mutates ? 1 : 0),
126
+ }, staleCalls)
127
+ }
105
128
  case 'todo/write': {
106
129
  const todos = Array.isArray(event.data?.todos) ? event.data.todos : []
107
130
  const count = status => todos.filter(todo => todo.status === status).length
@@ -112,8 +135,10 @@ export function createFold(staleCalls = STALE_CALLS) {
112
135
  active: count('in_progress'),
113
136
  pending: count('pending'),
114
137
  writeSeq: event.seq ?? -1,
138
+ writeTime: event.time ?? 0,
115
139
  callsSinceWrite: 0,
116
140
  stepsSinceWrite: 0,
141
+ mutationsSinceWrite: 0,
117
142
  closedWithUnfinished: 0,
118
143
  stale: false,
119
144
  }, staleCalls)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-todo-freshness",
3
- "version": "0.2.0",
3
+ "version": "0.3.0",
4
4
  "type": "module",
5
5
  "description": "Says out loud when the DSH task list is a stale snapshot instead of live progress, and nudges the model to write back.",
6
6
  "license": "MIT",