@deepslacker/dsh-task-progress 0.0.0-stage → 0.5.12

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.
@@ -0,0 +1,213 @@
1
+ /**
2
+ * dsh-task-progress — pure progress fold.
3
+ *
4
+ * One turn is one task. The fold keeps a plain-JSON state that doubles as the
5
+ * wire payload the Client reads (via the `taskProgress` session projection), so
6
+ * everything here stays synchronous, replayable, and reference-stable: an event
7
+ * this unit does not care about returns the same state object.
8
+ */
9
+
10
+ /** Phase vocabulary shared with the tool schema and the Client. */
11
+ export const PHASES = ['plan', 'execute', 'verify', 'deliver']
12
+
13
+ /** Maximum characters kept from a model-written milestone or next-node line. */
14
+ const LABEL_MAX = 60
15
+
16
+ /** State before any turn, and the reset template for a new turn. */
17
+ export const BLANK = Object.freeze({
18
+ v: 3,
19
+ turn: 0,
20
+ step: 0,
21
+ /** The model's own last report, -1 before the first one. */
22
+ modelPercent: -1,
23
+ /** Effective percent shown to people, -1 when unknown. */
24
+ percent: -1,
25
+ /** Where the effective percent came from. */
26
+ source: 'none',
27
+ phase: 'plan',
28
+ milestone: '',
29
+ next: '',
30
+ /** Model estimate of remaining minutes, 0 when not supplied. */
31
+ etaMin: 0,
32
+ /** The model lowered its estimate on purpose (scope discovered). */
33
+ revised: false,
34
+ todoDone: 0,
35
+ todoTotal: 0,
36
+ done: false,
37
+ /** Epoch ms of the turn start, or 0. */
38
+ startedAt: 0,
39
+ /** Epoch ms of the newest fact folded, or 0. */
40
+ updatedAt: 0,
41
+ })
42
+
43
+ /** Report drops larger than this need `revised`; otherwise they are clamped. */
44
+ const MAX_SILENT_DROP = 10
45
+
46
+ /** Todo-derived estimates stop here so a running task never reads as finished. */
47
+ const TODO_CEILING = 95
48
+
49
+ /** Clamp an unknown value into an integer range, or return `null`. */
50
+ function intIn(value, min, max) {
51
+ const number = typeof value === 'number' ? value : Number(value)
52
+ if (!Number.isFinite(number)) return null
53
+ const rounded = Math.round(number)
54
+ if (rounded < min || rounded > max) return null
55
+ return rounded
56
+ }
57
+
58
+ /** Trim one model-written label to a bounded single line. */
59
+ function label(value) {
60
+ if (typeof value !== 'string') return ''
61
+ return value.replace(/\s+/gu, ' ').trim().slice(0, LABEL_MAX)
62
+ }
63
+
64
+ /**
65
+ * Validate one `report_progress` argument object.
66
+ * @param args - parsed tool arguments (unknown shape).
67
+ * @returns the canonical report, or null when the call must be ignored.
68
+ */
69
+ export function normalizeReport(args) {
70
+ if (args === null || typeof args !== 'object' || Array.isArray(args)) return null
71
+ const percent = intIn(args.percent, 0, 100)
72
+ if (percent === null) return null
73
+ const phase = PHASES.includes(args.phase) ? args.phase : 'execute'
74
+ return {
75
+ percent,
76
+ phase,
77
+ milestone: label(args.milestone),
78
+ next: label(args.next),
79
+ etaMin: intIn(args.eta_min, 1, 600) ?? 0,
80
+ revised: args.revised === true,
81
+ }
82
+ }
83
+
84
+ /**
85
+ * Recompute the effective percent from the model report and the todo list.
86
+ * @param state - state whose inputs changed.
87
+ * @returns the same reference when the derived pair did not change.
88
+ */
89
+ function derive(state) {
90
+ let percent = -1
91
+ let source = 'none'
92
+ if (state.done) {
93
+ percent = 100
94
+ source = 'done'
95
+ } else if (state.modelPercent >= 0) {
96
+ percent = state.modelPercent
97
+ source = 'model'
98
+ } else if (state.todoTotal > 0) {
99
+ percent = Math.min(TODO_CEILING, Math.round((state.todoDone / state.todoTotal) * 100))
100
+ source = 'todo'
101
+ }
102
+ if (percent === state.percent && source === state.source) return state
103
+ return { ...state, percent, source }
104
+ }
105
+
106
+ /**
107
+ * Fold one session event into the progress state.
108
+ * @param state - state covering every earlier event.
109
+ * @param event - the next committed session event.
110
+ * @param options - deployment switches (`todoBaseline: false` disables the fallback).
111
+ * @returns the next state, or the same reference when the event is not ours.
112
+ */
113
+ export function applyProgress(state, event, options = {}) {
114
+ const todoBaseline = options.todoBaseline !== false
115
+ const current = state ?? BLANK
116
+ switch (event.type) {
117
+ case 'turn/start': {
118
+ const turn = event.data?.turn ?? 0
119
+ if (current.turn === turn && !current.done) return current
120
+ return derive({
121
+ ...BLANK,
122
+ turn,
123
+ step: 0,
124
+ startedAt: event.time ?? 0,
125
+ updatedAt: event.time ?? 0,
126
+ phase: 'plan',
127
+ })
128
+ }
129
+ case 'step/start': {
130
+ if ((event.data?.turn ?? -1) !== current.turn) return current
131
+ const step = event.data?.step ?? 0
132
+ if (current.step === step) return current
133
+ return { ...current, step }
134
+ }
135
+ case 'todo/write': {
136
+ if (!todoBaseline) return current
137
+ const todos = event.data?.todos
138
+ if (!Array.isArray(todos)) return current
139
+ let done = 0
140
+ for (const item of todos) {
141
+ if (item !== null && typeof item === 'object' && item.status === 'completed') done += 1
142
+ }
143
+ if (done === current.todoDone && todos.length === current.todoTotal) return current
144
+ return derive({
145
+ ...current,
146
+ todoDone: done,
147
+ todoTotal: todos.length,
148
+ updatedAt: event.time ?? current.updatedAt,
149
+ })
150
+ }
151
+ case 'tool/call': {
152
+ if (event.data?.name !== 'report_progress') return current
153
+ if ((event.data?.turn ?? -1) !== current.turn) return current
154
+ let args
155
+ try {
156
+ args = JSON.parse(event.data?.arguments ?? '')
157
+ } catch {
158
+ return current
159
+ }
160
+ const report = normalizeReport(args)
161
+ if (report === null) return current
162
+ // A silent large drop is almost always a fresh look at the same work;
163
+ // keep the change visible but bounded unless the model said it re-planned.
164
+ const floor = current.modelPercent - MAX_SILENT_DROP
165
+ const percent = !report.revised && current.modelPercent >= 0 && report.percent < floor
166
+ ? floor
167
+ : report.percent
168
+ return derive({
169
+ ...current,
170
+ modelPercent: percent,
171
+ phase: report.phase,
172
+ milestone: report.milestone || current.milestone,
173
+ next: report.next || current.next,
174
+ etaMin: report.etaMin,
175
+ revised: report.revised,
176
+ updatedAt: event.time ?? current.updatedAt,
177
+ })
178
+ }
179
+ case 'turn/end': {
180
+ if ((event.data?.turn ?? -1) !== current.turn || current.done) return current
181
+ return {
182
+ ...current,
183
+ done: true,
184
+ percent: 100,
185
+ source: 'done',
186
+ updatedAt: event.time ?? current.updatedAt,
187
+ }
188
+ }
189
+ default:
190
+ return current
191
+ }
192
+ }
193
+
194
+ /** Passthrough schema: state is produced here and replayed from our own cache. */
195
+ export const progressSchema = Object.freeze({
196
+ parse(value) {
197
+ return value ?? BLANK
198
+ },
199
+ })
200
+
201
+ /**
202
+ * Whether the report tool participates in one step.
203
+ * @param state - the session's current progress state (may be undefined).
204
+ * @param minStep - first step of a turn that offers the tool (1 = any step).
205
+ * @returns true when the turn is open and its step reached the gate.
206
+ */
207
+ export function shouldOfferProgressTool(state, minStep) {
208
+ if ((state?.turn ?? 0) <= 0) return false
209
+ // `minStep <= 1` means "any step of an open turn": the first pre-step of a
210
+ // turn can run before its `step/start`, so counting steps would hide the
211
+ // tool on exactly the step this setting exists for.
212
+ return minStep <= 1 || (state?.step ?? 0) >= minStep
213
+ }
package/lib/steps.js ADDED
@@ -0,0 +1,87 @@
1
+ /**
2
+ * dsh-task-progress — per-turn milestone rail.
3
+ *
4
+ * The evaluator names the milestone the open turn is on. When it names a new
5
+ * one, the previous milestone is finished; this reducer turns that sequence
6
+ * into a bounded list of steps with the time each step took. It is pure, and
7
+ * the Host keeps the result in memory so a page refresh re-reads the same rail.
8
+ */
9
+
10
+ /** How many nodes one turn keeps on its rail (the expanded list shows all of them). */
11
+ export const RAIL_MAX = 100
12
+
13
+ /** One open step before any milestone is known. */
14
+ export function blankRail(turn, startedAt) {
15
+ return { turn, startedAt: startedAt > 0 ? startedAt : 0, steps: [] }
16
+ }
17
+
18
+ /** Build one open step, clamping whatever the evaluator supplied. */
19
+ function newStep(label, percent, phase, at) {
20
+ const value = Number(percent)
21
+ return {
22
+ label,
23
+ percent: Number.isFinite(value) ? Math.max(0, Math.min(100, Math.round(value))) : 0,
24
+ phase: typeof phase === 'string' && phase !== '' ? phase : 'execute',
25
+ at,
26
+ endedAt: 0,
27
+ durationMs: 0,
28
+ }
29
+ }
30
+
31
+ /**
32
+ * Fold one observation of the effective milestone into the turn's rail.
33
+ *
34
+ * A step starts when it is first observed, and a changed label closes the
35
+ * open step at `at` and opens the next one there. Time before the first
36
+ * milestone was named belongs to no step, so a restart mid-turn cannot make
37
+ * the first node claim the whole turn.
38
+ *
39
+ * @param rail - the turn's current rail, or undefined for a new turn.
40
+ * @param observation - `{turn, label, percent, phase, at, startedAt}`.
41
+ * @returns a rail; the same reference when the observation changed nothing.
42
+ */
43
+ export function observeRail(rail, observation) {
44
+ const { turn, label, percent, phase, at, startedAt } = observation
45
+ const base = rail !== null && rail !== undefined && rail.turn === turn
46
+ ? rail
47
+ : blankRail(turn, startedAt)
48
+ if (typeof label !== 'string' || label === '') return base
49
+ const steps = base.steps
50
+ if (steps.length === 0) {
51
+ return { ...base, steps: [newStep(label, percent, phase, at)] }
52
+ }
53
+ const open = steps[steps.length - 1]
54
+ if (open.label === label) {
55
+ const nextPercent = Number.isFinite(Number(percent)) && percent >= 0 ? Math.round(percent) : open.percent
56
+ if (nextPercent === open.percent && phase === open.phase) return base
57
+ return { ...base, steps: [...steps.slice(0, -1), { ...open, percent: nextPercent, phase }] }
58
+ }
59
+ const closed = {
60
+ ...open,
61
+ endedAt: at,
62
+ durationMs: at > open.at ? at - open.at : 0,
63
+ }
64
+ const next = [...steps.slice(0, -1), closed, newStep(label, percent, phase, at)]
65
+ return { ...base, steps: next.slice(-RAIL_MAX) }
66
+ }
67
+
68
+ /**
69
+ * Close the open step when the turn ends. Idempotent, and records `closedAt`
70
+ * so the Host can drop an idle turn's rail after its linger.
71
+ * @param rail - the turn's rail.
72
+ * @param at - epoch ms of the turn end.
73
+ * @returns a rail; the same reference when it was already closed.
74
+ */
75
+ export function closeRail(rail, at) {
76
+ if (rail === null || rail === undefined || rail.steps.length === 0) return rail
77
+ const open = rail.steps[rail.steps.length - 1]
78
+ if (open.endedAt > 0) {
79
+ return rail.closedAt === undefined ? { ...rail, closedAt: open.endedAt } : rail
80
+ }
81
+ const endedAt = at > open.at ? at : open.at
82
+ return {
83
+ ...rail,
84
+ closedAt: endedAt,
85
+ steps: [...rail.steps.slice(0, -1), { ...open, endedAt, durationMs: endedAt - open.at }],
86
+ }
87
+ }
package/locale/en.json ADDED
@@ -0,0 +1,7 @@
1
+ {
2
+ "meta": {
3
+ "title": "Task progress",
4
+ "description": "Shows the running task's progress bar, phase, and next node, and marks every node the evaluator supersedes as a node with hover details and the time that node took. The session's sidebar row also carries a progress ring. The session's own model records checkpoints at nodes (report_progress); a side-channel evaluator fills in when it does not. Nothing is shown once the task ends or the session is idle.",
5
+ "detail": "docs/DETAIL.md"
6
+ }
7
+ }
package/locale/zh.json ADDED
@@ -0,0 +1,7 @@
1
+ {
2
+ "meta": {
3
+ "title": "任务进度",
4
+ "description": "在运行中的会话里显示当前任务的进度条、阶段和下一步;本轮里每出现一个新的节点,上一个节点就在进度条上留一个节点,悬停可看内容与耗时。会话行尾同时显示进度环。进度由会话内的模型在完成节点时自评(report_progress),尚未自评时由旁路评估器补位;任务结束或会话空闲后不再显示。",
5
+ "detail": "docs/DETAIL.zh.md"
6
+ }
7
+ }
package/package.json CHANGED
@@ -1,6 +1,59 @@
1
1
  {
2
2
  "name": "@deepslacker/dsh-task-progress",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.5.12",
4
+ "publishConfig": {
5
+ "access": "public"
6
+ },
7
+ "type": "module",
8
+ "description": "Shows the running task's progress with a node rail, a completed-task glyph, and node cards in the right sidebar, self-assessed by the session's own model at nodes.",
9
+ "exports": {
10
+ ".": "./index.js",
11
+ "./client": "./client.js",
12
+ "./locale/*.json": "./locale/*.json",
13
+ "./icon": "./icon.svg"
14
+ },
15
+ "scripts": {
16
+ "test": "node --test test/progress.test.mjs test/steps.test.mjs test/client.test.mjs",
17
+ "prepublishOnly": "npm test"
18
+ },
19
+ "files": [
20
+ "index.js",
21
+ "client.js",
22
+ "lib/*.js",
23
+ "cordis.patch.yml",
24
+ "locale/*.json",
25
+ "docs",
26
+ "icon.svg",
27
+ "README.md",
28
+ "README.en.md",
29
+ "CHANGELOG.md",
30
+ "LICENSE"
31
+ ],
32
+ "dsh": {
33
+ "bundle": {
34
+ "patch": "./cordis.patch.yml"
35
+ },
36
+ "client": {
37
+ "platform": "web",
38
+ "immediately": true,
39
+ "inject": [
40
+ "@deepseek-ai/dsh-client-ui-conversation",
41
+ "@deepseek-ai/dsh-client-ui-workspace"
42
+ ]
43
+ }
44
+ },
45
+ "license": "MIT",
46
+ "author": "DeepSlacking",
47
+ "repository": {
48
+ "type": "git",
49
+ "url": "git+https://github.com/DeepSlacking/dsh-task-progress.git"
50
+ },
51
+ "keywords": [
52
+ "deepseek-harness",
53
+ "dsh",
54
+ "cordis",
55
+ "plugin",
56
+ "progress",
57
+ "task"
58
+ ]
59
+ }