dsh-plan-steps 0.0.0-stage → 0.1.2

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/client.js ADDED
@@ -0,0 +1,518 @@
1
+ window.__ModuleLoader__.load({
2
+ id: 'dsh-plan-steps',
3
+ factory(require) {
4
+ const React = require('react')
5
+ const h = React.createElement
6
+
7
+ const TOKENS = {
8
+ title: 'var(--dsw-alias-label-primary, currentColor)',
9
+ secondary: 'var(--dsw-alias-label-tertiary, #8b8f96)',
10
+ accent: 'var(--dsw-alias-state-business-primary, #7c8cff)',
11
+ done: 'var(--dsw-alias-state-success-primary, #2ea043)',
12
+ idle: 'var(--dsw-alias-border-l2, rgba(127,127,127,0.35))',
13
+ card: 'var(--dsw-specific-menu, transparent)',
14
+ hover: 'var(--dsw-alias-interactive-bg-hover, rgba(127,127,127,0.12))',
15
+ radius: 'var(--dsw-radius-lg, 12px)',
16
+ }
17
+
18
+ // Material Symbols (google/material-design-icons, Apache-2.0), inlined as
19
+ // path data so the panel renders offline.
20
+ const ICONS = {
21
+ checklist:
22
+ 'M222-200 80-342l56-56 85 85 170-170 56 57-225 226Zm0-320L80-662l56-56 85 85 170-170 56 57-225 226Zm298 240v-80h360v80H520Zm0-320v-80h360v80H520Z',
23
+ check:
24
+ 'm424-408-86-86q-11-11-28-11t-28 11q-11 11-11 28t11 28l114 114q12 12 28 12t28-12l226-226q11-11 11-28t-11-28q-11-11-28-11t-28 11L424-408Zm56 328q-83 0-156-31.5T197-197q-54-54-85.5-127T80-480q0-83 31.5-156T197-763q54-54 127-85.5T480-880q83 0 156 31.5T763-763q54 54 85.5 127T880-480q0 83-31.5 156T763-197q-54 54-127 85.5T480-80Z',
25
+ chevronDown: 'M480-345 240-585l56-56 184 184 184-184 56 56-240 240Z',
26
+ chevronUp: 'm296-345-56-56 240-240 240 240-56 56-184-184-184 184Z',
27
+ }
28
+
29
+ function Icon({ name, size, color }) {
30
+ return h(
31
+ 'svg',
32
+ {
33
+ viewBox: '0 -960 960 960',
34
+ width: size,
35
+ height: size,
36
+ fill: 'currentColor',
37
+ 'aria-hidden': true,
38
+ style: { flex: 'none', color, display: 'block' },
39
+ },
40
+ h('path', { d: ICONS[name] }),
41
+ )
42
+ }
43
+
44
+ /** A stored item's level and visible text: a sub-step carries ​. */
45
+ function readItem(item) {
46
+ const raw = String(item?.content ?? '')
47
+ const nested = raw.startsWith('​')
48
+ return { ...item, content: nested ? raw.slice(1) : raw, level: nested ? 1 : 0 }
49
+ }
50
+
51
+ /** Position of the current step: the first open item. */
52
+ function positionOf(todos) {
53
+ const done = todos.filter((item) => item.status === 'completed').length
54
+ const current = todos.find((item) => item.status === 'in_progress') ?? null
55
+ const total = todos.length
56
+ const index = current === null ? Math.min(done + 1, total) : todos.indexOf(current) + 1
57
+ return { done, total, index, current }
58
+ }
59
+
60
+ /**
61
+ * Segmented progress, painted by POSITION rather than by count: a two-level
62
+ * list can hold a pending phase between completed sub-steps, so "done"
63
+ * alone would put the accent on the wrong cell.
64
+ */
65
+ function Bar({ items, index }) {
66
+ const allDone = items.every((item) => item.status === 'completed')
67
+ const cells = []
68
+ for (let i = 0; i < items.length; i += 1) {
69
+ const position = i + 1
70
+ const current = !allDone && position === index
71
+ const filled = items[i].status === 'completed'
72
+ cells.push(
73
+ h('span', {
74
+ key: i,
75
+ style: {
76
+ width: '14px',
77
+ height: '4px',
78
+ borderRadius: '2px',
79
+ background: current ? TOKENS.accent : filled ? TOKENS.done : TOKENS.idle,
80
+ },
81
+ }),
82
+ )
83
+ }
84
+ return h('span', { style: { display: 'inline-flex', gap: '3px', alignItems: 'center', flex: 'none' } }, cells)
85
+ }
86
+
87
+ function Glyph({ status }) {
88
+ const color = status === 'completed' ? TOKENS.done : status === 'in_progress' ? TOKENS.accent : TOKENS.idle
89
+ return h(
90
+ 'span',
91
+ {
92
+ style: {
93
+ width: '16px',
94
+ height: '16px',
95
+ flex: 'none',
96
+ display: 'grid',
97
+ placeItems: 'center',
98
+ color,
99
+ fontSize: '13px',
100
+ lineHeight: 1,
101
+ },
102
+ },
103
+ status === 'completed' ? '✓' : status === 'in_progress' ? '◍' : '○',
104
+ )
105
+ }
106
+
107
+ function TaskPanel({ useProjection }) {
108
+ // The shipped projection keeps only content and status, so the level rides
109
+ // inside the content as a zero-width marker and is stripped here.
110
+ const todos = (useProjection('todos') ?? []).map(readItem)
111
+ const [open, setOpen] = React.useState(false)
112
+ if (todos.length === 0) return null
113
+ const { done, total, index, current } = positionOf(todos)
114
+ const label = '计划 · 第 ' + String(index) + ' / ' + String(total) + ' 步'
115
+ const headline = current === null ? (done === total ? '全部完成' : '') : current.content
116
+ return h(
117
+ 'section',
118
+ {
119
+ 'data-testid': 'todo-panel',
120
+ 'aria-label': '计划',
121
+ style: {
122
+ width: '100%',
123
+ maxWidth: 'var(--dsh-composer-card-max-width)',
124
+ margin: '0 auto',
125
+ borderRadius: TOKENS.radius,
126
+ background: TOKENS.card,
127
+ color: TOKENS.title,
128
+ fontSize: '13px',
129
+ overflow: 'hidden',
130
+ },
131
+ },
132
+ h(
133
+ 'button',
134
+ {
135
+ type: 'button',
136
+ 'aria-expanded': open,
137
+ onClick: () => setOpen(!open),
138
+ style: {
139
+ width: '100%',
140
+ display: 'flex',
141
+ alignItems: 'center',
142
+ gap: '10px',
143
+ padding: '6px 12px',
144
+ background: 'transparent',
145
+ border: 'none',
146
+ color: 'inherit',
147
+ font: 'inherit',
148
+ textAlign: 'left',
149
+ cursor: 'pointer',
150
+ },
151
+ },
152
+ h('span', { style: { color: TOKENS.secondary, flex: 'none', display: 'grid' } }, h(Icon, { name: 'checklist', size: 18 })),
153
+ h('span', { style: { fontWeight: 500, flex: 'none' } }, label),
154
+ h(
155
+ 'span',
156
+ {
157
+ style: {
158
+ flex: 'auto',
159
+ minWidth: 0,
160
+ overflow: 'hidden',
161
+ textOverflow: 'ellipsis',
162
+ whiteSpace: 'nowrap',
163
+ color: TOKENS.secondary,
164
+ },
165
+ },
166
+ headline,
167
+ ),
168
+ h(Bar, { items: todos, index }),
169
+ h(
170
+ 'span',
171
+ {
172
+ 'aria-hidden': true,
173
+ style: { color: TOKENS.secondary, flex: 'none', display: 'grid' },
174
+ },
175
+ h(Icon, { name: open ? 'chevronUp' : 'chevronDown', size: 18 }),
176
+ ),
177
+ ),
178
+ open
179
+ ? h(
180
+ 'ul',
181
+ {
182
+ style: {
183
+ listStyle: 'none',
184
+ margin: 0,
185
+ padding: '4px 14px 10px',
186
+ display: 'flex',
187
+ flexDirection: 'column',
188
+ gap: '10px',
189
+ maxHeight: '180px',
190
+ overflowY: 'auto',
191
+ },
192
+ },
193
+ todos.map((todo, i) => {
194
+ const nested = (todo.level ?? 0) === 1
195
+ const color = TOKENS.title
196
+ const index = i + 1
197
+ return h(
198
+ 'li',
199
+ {
200
+ key: i,
201
+ style: {
202
+ display: 'flex',
203
+ alignItems: 'center',
204
+ gap: '10px',
205
+ fontSize: '13px',
206
+ lineHeight: '22px',
207
+ paddingLeft: nested ? '28px' : '0',
208
+ color,
209
+ opacity: todo.status === 'completed' ? 0.55 : 1,
210
+ },
211
+ },
212
+ todo.status === 'completed'
213
+ ? h(Icon, { name: 'check', size: 20, color: TOKENS.done })
214
+ : h(
215
+ 'svg',
216
+ {
217
+ width: 20,
218
+ height: 20,
219
+ viewBox: '0 0 20 20',
220
+ 'aria-hidden': true,
221
+ style: { flex: '0 0 20px', display: 'block' },
222
+ },
223
+ h('circle', {
224
+ cx: 10,
225
+ cy: 10,
226
+ r: 9,
227
+ fill: 'none',
228
+ stroke: todo.status === 'in_progress' ? TOKENS.accent : TOKENS.idle,
229
+ strokeWidth: 1,
230
+ }),
231
+ h(
232
+ 'text',
233
+ {
234
+ x: 10,
235
+ y: 10,
236
+ dy: '0.35em',
237
+ textAnchor: 'middle',
238
+ fontSize: 10,
239
+ fill: todo.status === 'in_progress' ? TOKENS.accent : TOKENS.secondary,
240
+ fontFamily: 'inherit',
241
+ },
242
+ String(index),
243
+ ),
244
+ ),
245
+ h(
246
+ 'span',
247
+ {
248
+ style: {
249
+ minWidth: 0,
250
+ overflow: 'hidden',
251
+ textOverflow: 'ellipsis',
252
+ whiteSpace: 'nowrap',
253
+ fontWeight: nested ? 400 : 600,
254
+ },
255
+ },
256
+ todo.content,
257
+ ),
258
+ )
259
+ }),
260
+ )
261
+ : null,
262
+ )
263
+ }
264
+
265
+ /** The sign-off row: position + current step for one complete_step call. */
266
+ function resultText(block) {
267
+ const parts = []
268
+ if (Array.isArray(block?.content)) {
269
+ for (const part of block.content) {
270
+ if (part && part.type === 'text' && typeof part.text === 'string') parts.push(part.text)
271
+ }
272
+ }
273
+ if (parts.length === 0 && typeof block?.output === 'string') parts.push(block.output)
274
+ return parts.join('\n')
275
+ }
276
+
277
+ function readPosition(text) {
278
+ if (typeof text !== 'string' || text === '') return null
279
+ if (/Every step in the task list is now complete/.test(text)) return { done: true }
280
+ const next = /the next step is (\d+) "([^"]*)"/.exec(text)
281
+ if (next === null) return null
282
+ const index = Number(next[1])
283
+ // Prefer the stated total: in a two-level list the current phase can sit
284
+ // before its own completed sub-steps, so "index - 1 + open" undercounts.
285
+ const stated = /\((\d+) open of (\d+)\)/.exec(text)
286
+ if (stated !== null) {
287
+ const openCount = Number(stated[1])
288
+ return { index, current: next[2], open: openCount, total: Number(stated[2]), done: false }
289
+ }
290
+ const open = /\((\d+) open\)/.exec(text)
291
+ const openCount = open === null ? 0 : Number(open[1])
292
+ return { index, current: next[2], open: openCount, total: index - 1 + openCount, done: false }
293
+ }
294
+
295
+ function StepRow({ block }) {
296
+ try {
297
+ const position = readPosition(resultText(block))
298
+ if (position === null) {
299
+ return h('div', { style: { padding: '6px 2px', fontSize: '12px', opacity: 0.75 } }, '完成一步')
300
+ }
301
+ if (position.done === true) {
302
+ return h('div', { style: { padding: '6px 2px', fontSize: '13px', fontWeight: 600 } }, '计划 · 全部完成')
303
+ }
304
+ const done = position.total - position.open
305
+ const items = Array.from({ length: position.total }, (_, i) => ({
306
+ status: i < done ? 'completed' : i === done ? 'in_progress' : 'pending',
307
+ }))
308
+ return h(
309
+ 'div',
310
+ { style: { padding: '6px 2px', fontSize: '13px', display: 'flex', alignItems: 'center', gap: '10px' } },
311
+ h('span', { style: { whiteSpace: 'nowrap', fontWeight: 600 } }, '计划 · 第 ' + String(position.index) + ' / ' + String(position.total) + ' 步'),
312
+ h(
313
+ 'span',
314
+ { style: { minWidth: 0, overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' } },
315
+ position.current,
316
+ ),
317
+ h(Bar, { items, index: done + 1 }),
318
+ )
319
+ } catch (error) {
320
+ return h('div', { style: { padding: '6px 2px', fontSize: '12px', opacity: 0.7 } }, '完成一步')
321
+ }
322
+ }
323
+
324
+ /** The settings card shown on the plugin page. */
325
+ const SETTINGS_NS = 'settings.planSteps'
326
+ const SETTINGS_TEXT = {
327
+ zh: {
328
+ title: '计划步骤',
329
+ guard: '完成必须签核',
330
+ guardHint: '不允许直接改列表把任务标成完成,必须逐项签核',
331
+ hold: '未完成时继续工作',
332
+ holdHint: '一轮要结束时若还有未完成任务,自动拉回来继续(每轮一次)',
333
+ restore: '跨轮保留进度',
334
+ restoreHint: '每轮开始时重建任务面板,否则要等下一次写入才显示',
335
+ },
336
+ en: {
337
+ title: 'Plan steps',
338
+ guard: 'Completions need a sign-off',
339
+ guardHint: 'An item cannot be closed by rewriting the list; sign each one off',
340
+ hold: 'Keep working while items are open',
341
+ holdHint: 'A turn that is about to end with open items is pulled back once',
342
+ restore: 'Keep the panel across turns',
343
+ restoreHint: 'Rebuild the task panel at the start of a turn',
344
+ },
345
+ }
346
+
347
+ const SETTINGS_ROWS = [
348
+ ['guardUnsignedCompletions', 'guard', 'guardHint'],
349
+ ['holdOpenList', 'hold', 'holdHint'],
350
+ ['restorePanel', 'restore', 'restoreHint'],
351
+ ]
352
+
353
+ /** The three switches, shared by the row page and the bundle section. */
354
+ function Toggles({ value, writable, onToggle, label }) {
355
+ return h(
356
+ 'div',
357
+ { style: { display: 'flex', flexDirection: 'column', gap: '12px' } },
358
+ SETTINGS_ROWS.map(([key, dictKey, hintKey]) => {
359
+ const on = value[key] !== false
360
+ return h(
361
+ 'div',
362
+ { key, style: { display: 'flex', alignItems: 'center', justifyContent: 'space-between', gap: '12px' } },
363
+ h(
364
+ 'div',
365
+ { style: { display: 'flex', flexDirection: 'column', gap: '2px', minWidth: 0 } },
366
+ h('span', { style: { fontSize: '13px' } }, label(dictKey)),
367
+ h(
368
+ 'span',
369
+ { style: { fontSize: '12px', lineHeight: '16px', color: 'var(--dsw-alias-label-tertiary, #8b8f96)' } },
370
+ label(hintKey),
371
+ ),
372
+ ),
373
+ h(
374
+ 'button',
375
+ {
376
+ type: 'button',
377
+ role: 'switch',
378
+ 'aria-checked': on,
379
+ disabled: writable === false,
380
+ onClick: () => onToggle(key, !on),
381
+ style: {
382
+ width: '36px',
383
+ height: '20px',
384
+ flex: 'none',
385
+ borderRadius: '999px',
386
+ border: 'none',
387
+ cursor: writable === false ? 'default' : 'pointer',
388
+ background: on ? 'var(--dsw-alias-state-business-primary, #4c8dff)' : 'var(--dsw-alias-border-l2, rgba(127,127,127,0.4))',
389
+ position: 'relative',
390
+ transition: 'background 120ms ease',
391
+ },
392
+ },
393
+ h('span', {
394
+ style: {
395
+ position: 'absolute',
396
+ top: '2px',
397
+ left: on ? '18px' : '2px',
398
+ width: '16px',
399
+ height: '16px',
400
+ borderRadius: '50%',
401
+ background: '#fff',
402
+ transition: 'left 120ms ease',
403
+ },
404
+ }),
405
+ ),
406
+ )
407
+ }),
408
+ )
409
+ }
410
+
411
+ /** The row's own Configure page; the owner hands it {view, form}. */
412
+ function SettingsCard({ form, view, label }) {
413
+ if (view !== 'page' || form === undefined) return null
414
+ const state = form.state ?? {}
415
+ return h(Toggles, {
416
+ value: state.value ?? {},
417
+ writable: state.writable !== false,
418
+ onToggle: (key, next) => void form.mutate([{ op: 'set', path: [key], value: next }], state.revision),
419
+ label,
420
+ })
421
+ }
422
+
423
+ /** The same switches as a section on the bundle's own page. */
424
+ function DetailSection({ form, label }) {
425
+ const snapshot = React.useSyncExternalStore(
426
+ (listener) => form.subscribe(listener),
427
+ () => form.getSnapshot(),
428
+ )
429
+ const value = snapshot?.value ?? {}
430
+ return h(Toggles, {
431
+ value,
432
+ writable: snapshot?.writable !== false,
433
+ onToggle: (key, next) => void form.set(key, next),
434
+ label,
435
+ })
436
+ }
437
+
438
+ return {
439
+ inject: ['slots', 'configForms', 'locale'],
440
+ apply(ctx) {
441
+ // The plugin page shows a card a plugin contributes; a Config alone only
442
+ // validates and persists. Register the card while the Host serves this
443
+ // entry, and drive it through the same form the Host projects.
444
+ try {
445
+ const t = ctx.locale === undefined ? (key) => SETTINGS_TEXT.zh[key] : ctx.locale.bind(SETTINGS_NS)
446
+ if (ctx.locale !== undefined) ctx.locale.register(SETTINGS_NS, SETTINGS_TEXT)
447
+ // The row's own page: plugins.row.config is keyed by
448
+ // "<package name>#<row id>" and the owner hands the page its form.
449
+ ctx.effect(
450
+ () =>
451
+ ctx.slots.inject('plugins.row.config', () => {
452
+ document.documentElement.dataset.planCard = 'registered'
453
+ return ctx.slots.register(
454
+ {
455
+ name: 'plugins.row.config',
456
+ key: 'dsh-plan-steps#plan-steps',
457
+ label: () => t('title'),
458
+ inject: () => ({ label: (key) => t(key) }),
459
+ },
460
+ SettingsCard,
461
+ )
462
+ }),
463
+ 'plan-steps: row settings',
464
+ )
465
+ const form = ctx.configForms.get('plan-steps')
466
+ if (form !== undefined && form !== null) {
467
+ ctx.effect(
468
+ () =>
469
+ ctx.slots.inject('plugins.bundle.config', () =>
470
+ ctx.slots.register(
471
+ {
472
+ name: 'plugins.bundle.config',
473
+ key: 'dsh-plan-steps',
474
+ inject: () => ({ form, label: (key) => t(key) }),
475
+ },
476
+ DetailSection,
477
+ ),
478
+ ),
479
+ 'plan-steps: bundle config',
480
+ )
481
+ }
482
+ } catch (error) {
483
+ document.documentElement.dataset.planCard = 'error: ' + String(error && error.message)
484
+ console.warn('[plan-steps] settings card unavailable', error)
485
+ }
486
+
487
+ document.documentElement.dataset.planSteps = 'applied'
488
+ // The shipped panel is a list entry on conversation.input.dock with id
489
+ // 'todo'; claiming the same id at a lower priority replaces it.
490
+ ctx.slots.inject('conversation.input.dock', () => {
491
+ try {
492
+ const dispose = ctx.slots.register(
493
+ {
494
+ name: 'conversation.input.dock',
495
+ id: 'todo',
496
+ order: 0,
497
+ priority: -1,
498
+ },
499
+ TaskPanel,
500
+ )
501
+ document.documentElement.dataset.planSteps = 'registered'
502
+ return dispose
503
+ } catch (error) {
504
+ document.documentElement.dataset.planSteps = 'failed: ' + String(error && error.message)
505
+ return undefined
506
+ }
507
+ })
508
+ ctx.slots.inject('tool.call.toolview', () => {
509
+ try {
510
+ return ctx.slots.register({ name: 'tool.call.toolview', key: 'complete_step' }, StepRow)
511
+ } catch (error) {
512
+ return undefined
513
+ }
514
+ })
515
+ },
516
+ }
517
+ },
518
+ })
@@ -0,0 +1,7 @@
1
+ - insert:
2
+ - id: plan-steps
3
+ name: dsh-plan-steps
4
+ config:
5
+ guardUnsignedCompletions: true
6
+ holdOpenList: true
7
+ restorePanel: true
package/docs/DETAIL.md ADDED
@@ -0,0 +1,161 @@
1
+ # Plan steps
2
+
3
+ The built-in `todo_write` tool records a whole-list snapshot and nothing else: a
4
+ completed item exists only because the model remembered to re-send the table
5
+ with a different status, and nothing checks that the two agree.
6
+
7
+ This plugin turns a completion into a host transaction:
8
+
9
+ - **`complete_step`** signs exactly one item off. It refuses an item that is not
10
+ the current `in_progress` one, appends the advanced list as a `todo/write`
11
+ snapshot — the same event the shipped tool writes, so the task panel and every
12
+ log reader see the step close — and names the step that became current. The
13
+ model never re-sends the table to record progress.
14
+ - **A tool guard** refuses a `todo_write` that turns an item `completed` when the
15
+ host's list still has it open. Closing an item has one legal path.
16
+ - **A turn-stopping hold** steers the model back when a turn is about to close
17
+ with open items. The steering message is authored as
18
+ `source.kind: 'system-prompt'`, not as the user speaking.
19
+ - **`wait_for_user`** is the sanctioned way out: a turn that declares what it is
20
+ waiting for is not held back. The declaration lasts one turn.
21
+ - **Host task state** rides the request while the list has open items, so a fold
22
+ that drops the model's own `todo_write` does not leave it guessing. It is
23
+ re-sent only when the visible window no longer carries it.
24
+
25
+ The host list is the latest `todo/write` event in the session log, so a fold, a
26
+ fork, or a restarted process derives the same list. Nothing is cached in plugin
27
+ memory. A host whose todo tool writes no event falls back to replaying the
28
+ `todo_write` and `complete_step` calls.
29
+
30
+ ## What the model sees
31
+
32
+ Signing a step off:
33
+
34
+ ```json
35
+ { "step": "probe C", "result": "probe C verified" }
36
+ ```
37
+
38
+ > Step "probe C" done: probe C verified The host advanced the list; the next
39
+ > step is 2 "probe D". (1 open)
40
+
41
+ Closing an item behind the host's back:
42
+
43
+ > blocked: todo "probe D" is newly completed with no complete_step sign-off.
44
+ > Call complete_step for it first — the host marks it completed and advances the
45
+ > list for you — or send todo_write again leaving that item in_progress.
46
+
47
+ Ending a turn with open items:
48
+
49
+ > Your task list still has 2 open step(s); the current one is "...". Keep working
50
+ > on it, and call complete_step the moment a step is finished. If you are waiting
51
+ > on the user, call wait_for_user with one line naming what you need — that is
52
+ > what lets the turn end with the item still open. Do not end a turn that still
53
+ > has work you can do.
54
+
55
+ The request carries the list itself:
56
+
57
+ > Host task state. This list is the host's, not a message you sent; sign a step
58
+ > off with complete_step once it is finished.
59
+ > 1. "..." [completed]
60
+ > 2. "..." [in_progress]
61
+
62
+ ## Configuration
63
+
64
+ Environment variables, read when the plugin activates:
65
+
66
+ | Variable | Default | Effect |
67
+ | --- | --- | --- |
68
+ | `PLAN_STEPS_GUARD` | on | `0` stops the `todo_write` guard. |
69
+ | `PLAN_STEPS_HOLD` | on | `0` stops the turn-stopping hold. |
70
+ | `PLAN_STEPS_RESTORE` | on | `0` stops writing the open list back at the start of a turn. |
71
+
72
+ The tools stay registered either way.
73
+
74
+ ## Tests
75
+
76
+ ```sh
77
+ node --test test/
78
+ ```
79
+
80
+ Nineteen cases over the pure helpers: name normalisation, step resolution
81
+ (`step_id` before name before position), the flat and two-level advance rules
82
+ (next sibling, phase sign-off last, phase with open sub-steps refused, next
83
+ phase's first sub-step), serial validation (single current item, phase made
84
+ current too early, pending work with no current item), call replay, step
85
+ identity, the stored-state parser, and the state block — plus the four
86
+ continuity rules a rewrite must respect (id preserved, current item kept and not
87
+ regressed, completed history in place, first write and additive replan allowed).
88
+
89
+ ## Verification
90
+
91
+ Checked in a live session:
92
+
93
+ - Two-item list, sign the first item off — the reply names the second as the
94
+ next step.
95
+ - A `todo_write` closing the second item directly — refused.
96
+ - Sign the second item off — the reply reports every step complete.
97
+ - End a turn with two items still open — the turn did not close; a steering
98
+ message arrived and the work continued.
99
+ - Signing an item off writes a `todo/write` snapshot (checked in the session
100
+ log), so the task panel reads the advance without a `todo_write` call.
101
+ - The steering message is recorded with `source.kind: 'system-prompt'`.
102
+ - The next step's request carried the host task state block.
103
+
104
+ ## Deliberate non-goals
105
+
106
+ Three things a fuller implementation would have are left out on purpose. Each
107
+ one is a decision, not a gap waiting to be found.
108
+
109
+ **No step ids.** The shipped task list stores a name and a status, so the name
110
+ is the only identity an item has. This plugin could mint ids in a side table
111
+ keyed by name — but a rename breaks that key anyway, and owning an id would mean
112
+ owning the list's write format, which is the shipped tool's job. The guard's
113
+ "completed count first, names second" rule is the cheapest thing that still
114
+ distinguishes a relabel from a completion.
115
+
116
+ **The hold is soft.** A turn is pulled back at most once, and a second stop is
117
+ allowed. DSH has no core "waiting on the user" state a gate could key on, so a
118
+ hard gate would have to infer intent from text — and a model that is genuinely
119
+ blocked would be trapped in a loop it cannot leave. One hold plus `wait_for_user`
120
+ gets the behaviour without that failure mode: a model that ignores the list still
121
+ ends its turn, just visibly.
122
+
123
+ **The panel stays the shipped one.** The `todos` projection resets at
124
+ `turn/start` by design, so this plugin writes the open list back at the boundary
125
+ instead of replacing the panel. Owning a cross-turn panel means a Client module,
126
+ a wire view and a second source of truth in the UI; that is a different plugin,
127
+ and two panels showing different lists would be worse than one that restores.
128
+
129
+ A fourth omission is not a decision but an accepted consequence: any other writer
130
+ of `todo/write` — plan mode seeding, a direct `todo_write` — replaces the list
131
+ wholesale. The host reads the last snapshot, so the two views realign at the next
132
+ write; nothing drifts permanently.
133
+
134
+ ## Limits
135
+
136
+ - The turn-start restore runs on a macrotask because appending inside the
137
+ `turn/start` dispatch does not land. That is an observed host behaviour, not a
138
+ contract: a failed early write logs one warning per session and the pre-step
139
+ restore still runs, so a host change degrades to a one-step delay rather than
140
+ a blank panel.
141
+ - The hold fires at most once per turn. A model that refuses to update its list
142
+ still finishes its turn on the second stop; the plugin reports the list rather
143
+ than trapping the session.
144
+ - `wait_for_user` cannot tell a real wait from a convenient one: it trusts the
145
+ declaration. A turn that declares a wait and then keeps working simply skips
146
+ one hold.
147
+ - The client still decides how a `system-prompt`-sourced message looks. If it
148
+ draws a user bubble, the content is at least attributed to the host in the log.
149
+ - The shipped task projection resets on `turn/start`, so the panel shows the
150
+ list only once this turn has written one.
151
+ - Item identity is the item's name, because the shipped task list has no step
152
+ ids. A rewrite that adds no completion may rename freely; one that adds a
153
+ completion is checked name by name, so renaming *and* closing in one write is
154
+ still refused.
155
+ - The list is read through the plugin's own `sessionProjections` unit
156
+ (`plan-steps/todos`); `deriveMessages()` is still read directly for the
157
+ visible-window check, and a host without the projection seam falls back to
158
+ `Session.snapshotEvents()`, which the core deprecates.
159
+ - The state block is injected at most once per visible window; when a step is
160
+ signed off, the list in the request is one snapshot behind until the next
161
+ window or until the model reads the tool result.