@jakedowns/progress-tool-opencode-plugin 0.0.0-stage → 2.14.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/src/tree.ts ADDED
@@ -0,0 +1,433 @@
1
+ /**
2
+ * Tree helpers shared by the TUI and GUI parts.
3
+ *
4
+ * Entries may carry a `parentId`, forming a dependency tree. Rendering rolls
5
+ * children up under their parent and sorts the most severe status first.
6
+ */
7
+
8
+ import type { ProgressEntry, ProgressState, TreeNode } from "./types.js";
9
+
10
+ const STATUS_ORDER: Record<string, number> = {
11
+ error: 4,
12
+ running: 3,
13
+ waiting: 2,
14
+ done: 1,
15
+ };
16
+
17
+ /**
18
+ * Normalize title/detail text from the state file for display.
19
+ *
20
+ * The MCP server stores plain newlines, but older entries and hand-written
21
+ * state files may still contain an escaped `\\n`, an extra-escaped `\\\\n`,
22
+ * an escaped unicode newline, or HTML `<br>` tags. Accept every form and
23
+ * return plain `\n` so the TUI and GUI render identical line breaks.
24
+ */
25
+ export function normalizeProgressText(value: string | null | undefined): string {
26
+ if (value == null) return "";
27
+ let text = String(value);
28
+ text = text.replace(/\r\n?/g, "\n");
29
+ text = text.replace(/\\u000[ad]/gi, "\n");
30
+ text = text.replace(/\\r\\n|\\n|\\r/gi, "\n");
31
+ text = text.replace(/<br\s*\/?>/gi, "\n");
32
+ text = text
33
+ .split("\n")
34
+ .map((line) => line.replace(/[ \t]+$/g, ""))
35
+ .join("\n");
36
+ return text.replace(/\n{3,}/g, "\n\n").trim();
37
+ }
38
+
39
+ /** Collapse normalized text to one line for compact host rows and status lines. */
40
+ export function oneLineText(value: string | null | undefined): string {
41
+ return normalizeProgressText(value)
42
+ .replace(/\s*\n+\s*/g, " ")
43
+ .replace(/[ \t]+/g, " ")
44
+ .trim();
45
+ }
46
+
47
+ export function entriesOf(state: ProgressState | undefined | null): Record<string, ProgressEntry> {
48
+ const entries = state?.entries;
49
+ return entries && typeof entries === "object" ? entries : {};
50
+ }
51
+
52
+ /**
53
+ * Build a dependency tree from the flat entry map.
54
+ *
55
+ * Parent links may use either the state map key (for example
56
+ * `session-123:build`) or the entry's bare `id`. Both resolve.
57
+ */
58
+ export function buildTree(entries: Record<string, ProgressEntry>): TreeNode[] {
59
+ const byKey = new Map<string, ProgressEntry>();
60
+ const keyById = new Map<string, string>();
61
+
62
+ for (const [key, entry] of Object.entries(entries)) {
63
+ if (!entry || typeof entry !== "object") continue;
64
+ byKey.set(key, {
65
+ ...entry,
66
+ title: normalizeProgressText(entry.title),
67
+ detail:
68
+ entry.detail == null ? entry.detail : normalizeProgressText(entry.detail),
69
+ });
70
+ if (entry.id && !keyById.has(entry.id)) keyById.set(entry.id, key);
71
+ }
72
+
73
+ const childrenByKey = new Map<string, string[]>();
74
+ for (const key of byKey.keys()) childrenByKey.set(key, []);
75
+
76
+ const roots: string[] = [];
77
+ for (const [key, entry] of byKey) {
78
+ const parentKey = entry.parentId
79
+ ? byKey.has(entry.parentId)
80
+ ? entry.parentId
81
+ : keyById.get(entry.parentId)
82
+ : undefined;
83
+
84
+ if (parentKey && parentKey !== key) {
85
+ childrenByKey.get(parentKey)?.push(key);
86
+ } else {
87
+ roots.push(key);
88
+ }
89
+ }
90
+
91
+ const compare = (a: string, b: string) => {
92
+ const ea = byKey.get(a);
93
+ const eb = byKey.get(b);
94
+ const severity = (STATUS_ORDER[eb?.status ?? ""] ?? 0) - (STATUS_ORDER[ea?.status ?? ""] ?? 0);
95
+ if (severity !== 0) return severity;
96
+ return (eb?.updatedAt ?? 0) - (ea?.updatedAt ?? 0);
97
+ };
98
+
99
+ for (const children of childrenByKey.values()) children.sort(compare);
100
+ roots.sort(compare);
101
+
102
+ const seen = new Set<string>();
103
+ const node = (key: string): TreeNode => {
104
+ const entry = byKey.get(key)!;
105
+ // Guard against cycles in hand-written state files.
106
+ seen.add(key);
107
+ const children = (childrenByKey.get(key) ?? [])
108
+ .filter((child) => !seen.has(child))
109
+ .map(node);
110
+
111
+ // Roll up parent status/progress from children (bootvine-inspired).
112
+ let status = entry.status;
113
+ let progress = entry.progress;
114
+ let updatedAt = entry.updatedAt;
115
+
116
+ if (children.length > 0) {
117
+ const statuses = children.map((child) => child.status);
118
+ if (statuses.includes("error")) status = "error";
119
+ else if (statuses.includes("running")) status = "running";
120
+ else if (statuses.includes("waiting")) status = "waiting";
121
+ else if (statuses.every((child) => child === "done")) status = "done";
122
+
123
+ const childProgresses = children
124
+ .map((child) => child.progress)
125
+ .filter((value): value is number => typeof value === "number" && Number.isFinite(value));
126
+ if (progress == null && childProgresses.length > 0) {
127
+ progress = childProgresses.reduce((a, b) => a + b, 0) / childProgresses.length;
128
+ }
129
+
130
+ const latestChild = children.reduce((latest, child) => Math.max(latest, child.updatedAt ?? 0), 0);
131
+ if (latestChild > (updatedAt ?? 0)) updatedAt = latestChild;
132
+ }
133
+
134
+ return { ...entry, key, children, status, progress, updatedAt, reportedAt: entry.updatedAt };
135
+ };
136
+
137
+ return roots.map(node);
138
+ }
139
+
140
+ /** Depth-first flatten, parents before children. */
141
+ export function flattenTree(nodes: readonly TreeNode[]): TreeNode[] {
142
+ const out: TreeNode[] = [];
143
+ const visit = (node: TreeNode) => {
144
+ out.push(node);
145
+ for (const child of node.children) visit(child);
146
+ };
147
+ for (const node of nodes) visit(node);
148
+ return out;
149
+ }
150
+
151
+ /** Depth-first flatten with each node's depth, for indented menus. */
152
+ export function flattenTreeWithDepth(
153
+ nodes: readonly TreeNode[],
154
+ depth = 0
155
+ ): Array<{ node: TreeNode; depth: number }> {
156
+ const out: Array<{ node: TreeNode; depth: number }> = [];
157
+ for (const node of nodes) {
158
+ out.push({ node, depth });
159
+ out.push(...flattenTreeWithDepth(node.children, depth + 1));
160
+ }
161
+ return out;
162
+ }
163
+
164
+ /**
165
+ * Rows for a collapsible tree view: every root is always shown; a root's
166
+ * descendants are included unless that root is in `collapsed`. Collapsing is
167
+ * top-level only (descendants have no independent toggle), which keeps the
168
+ * menu readable on long trees without a nested state model.
169
+ */
170
+ export function visibleRows(
171
+ roots: readonly TreeNode[],
172
+ collapsed: Record<string, boolean>
173
+ ): Array<{ node: TreeNode; depth: number }> {
174
+ const out: Array<{ node: TreeNode; depth: number }> = [];
175
+ for (const root of roots) {
176
+ out.push({ node: root, depth: 0 });
177
+ if (!collapsed[root.key]) {
178
+ out.push(...flattenTreeWithDepth(root.children, 1));
179
+ }
180
+ }
181
+ return out;
182
+ }
183
+
184
+ /** How many descendants (all depths) a node has. */
185
+ export function countDescendants(node: Pick<TreeNode, "children">): number {
186
+ return (node.children ?? []).reduce(
187
+ (total, child) => total + 1 + countDescendants(child),
188
+ 0
189
+ );
190
+ }
191
+
192
+ /**
193
+ * Collapse state for root rows: collapsed by default, expanded when the
194
+ * user toggled it (overrides) or when `expandByDefault` is configured.
195
+ * Roots without children are omitted (nothing to collapse).
196
+ */
197
+ export function collapsedRootMap(
198
+ roots: readonly TreeNode[],
199
+ expandByDefault: boolean,
200
+ overrides: Record<string, boolean>
201
+ ): Record<string, boolean> {
202
+ const map: Record<string, boolean> = {};
203
+ for (const root of roots) {
204
+ if (!root.children || root.children.length === 0) continue;
205
+ map[root.key] = !(overrides[root.key] ?? expandByDefault);
206
+ }
207
+ return map;
208
+ }
209
+
210
+ /**
211
+ * Headline counts for the pill: active (running/waiting), done, and dismissed.
212
+ * Computed over the session-scoped entry set, before view filtering, so the
213
+ * numbers describe the store rather than the current visibility.
214
+ */
215
+ export function summarizeEntries(entries: Record<string, ProgressEntry>): {
216
+ active: number;
217
+ done: number;
218
+ dismissed: number;
219
+ } {
220
+ let active = 0;
221
+ let done = 0;
222
+ let dismissed = 0;
223
+ for (const entry of Object.values(entries)) {
224
+ if (!entry || typeof entry !== "object") continue;
225
+ if (entry.status === "running" || entry.status === "waiting") active++;
226
+ if (entry.status === "done") done++;
227
+ if (entry.dismissed) dismissed++;
228
+ }
229
+ return { active, done, dismissed };
230
+ }
231
+
232
+ export function countActive(nodes: readonly TreeNode[]): number {
233
+ return flattenTree(nodes).filter((node) => node.status === "running" || node.status === "waiting").length;
234
+ }
235
+
236
+ /**
237
+ * Per-root dismissal snapshot for views that let users hide a task tree.
238
+ *
239
+ * Revival semantics, scoped to the dismissed task itself:
240
+ * - A direct re-report of the task's own id (fresh milestone or lifecycle
241
+ * restart) always revives it: `reportedAt` moves past the snapshot.
242
+ * - A non-terminal dismissal (running/waiting) also revives when the
243
+ * rolled-up status changes (waiting/done/error, or a new child flips it).
244
+ * - A terminal dismissal (done/error) stays hidden through child activity —
245
+ * appended children flipping the parent's rolled-up status do NOT revive
246
+ * it — with one carve-out: a child failing (rolled-up status becomes
247
+ * "error") still revives a done-dismissed tree, because a failure must
248
+ * not silently scroll away. An error-dismissed tree revives only on a
249
+ * direct re-report.
250
+ * - Sibling roots and unrelated updates never revive anything.
251
+ */
252
+ export type Dismissal = { status: string; at: number };
253
+
254
+ export function isDismissed(root: TreeNode, map: Record<string, Dismissal>): boolean {
255
+ const d = map[root.key];
256
+ if (!d) return false;
257
+ // The task itself was re-reported (new milestone or fresh lifecycle).
258
+ if ((root.reportedAt ?? 0) > d.at) return false;
259
+ const wasTerminal = d.status === "done" || d.status === "error";
260
+ // Non-terminal: any rolled-up status change revives. Terminal: only a
261
+ // failure appearing in the subtree revives a done-dismissed tree.
262
+ if (!wasTerminal || root.status === "error") {
263
+ if ((root.status ?? "") !== d.status) return false;
264
+ }
265
+ return true;
266
+ }
267
+
268
+ /** Snapshot every given root for "Dismiss all". */
269
+ export function dismissalsFor(
270
+ roots: readonly TreeNode[],
271
+ prev: Record<string, Dismissal>
272
+ ): Record<string, Dismissal> {
273
+ const next = { ...prev };
274
+ for (const root of roots) {
275
+ next[root.key] = { status: root.status ?? "", at: root.reportedAt ?? 0 };
276
+ }
277
+ return next;
278
+ }
279
+
280
+ export type BarStyle = "blocks" | "emoji";
281
+
282
+ export interface BarOptions {
283
+ /** `blocks` (default) or `emoji` for the meme-style bar. */
284
+ style?: BarStyle;
285
+ /** Segments in the bar. Defaults to 10 for blocks and 6 for emoji. */
286
+ segments?: number;
287
+ /** Denominator shown in the fraction, e.g. 420. Defaults to 100. */
288
+ total?: number;
289
+ }
290
+
291
+ export interface VisibilityOptions {
292
+ /** How long a completed task stays visible before the view hides it. Defaults to 8000ms. */
293
+ successHoldMs?: number;
294
+ /** Show completed tasks at all. Defaults to true. */
295
+ showDone?: boolean;
296
+ /**
297
+ * Auto-hide completed tasks after `successHoldMs` (the old behavior).
298
+ * Defaults to FALSE: a done entry the user never dismissed stays visible
299
+ * until it is dismissed or pruned, including across plugin reloads.
300
+ */
301
+ autoHideDone?: boolean;
302
+ /** Show only the current session's tasks (default) or every session. */
303
+ scope?: "session" | "all";
304
+ }
305
+
306
+ export interface BarParts {
307
+ bar: string;
308
+ done: number;
309
+ total: number;
310
+ fraction: string;
311
+ style: BarStyle;
312
+ }
313
+
314
+ function clampProgress(progress: number | null | undefined): number {
315
+ return progress == null ? 0 : Math.max(0, Math.min(1, progress));
316
+ }
317
+
318
+ /** Copy host plugin options into a plain object; the host's proxy may not outlive setup. */
319
+ export function normalizeBarOptions(raw: unknown): BarOptions {
320
+ const options = (raw ?? {}) as Record<string, unknown>;
321
+ return {
322
+ style: options.barStyle === "emoji" ? "emoji" : "blocks",
323
+ segments:
324
+ typeof options.barSegments === "number" && options.barSegments > 0
325
+ ? options.barSegments
326
+ : undefined,
327
+ total:
328
+ typeof options.barTotal === "number" && options.barTotal > 0
329
+ ? options.barTotal
330
+ : undefined,
331
+ };
332
+ }
333
+
334
+ /**
335
+ * Resolve the view refresh interval (ms) from plugin options.
336
+ * Defaults to 1000ms; floored at 100ms so a typo cannot hot-loop the poller.
337
+ */
338
+ export function normalizeRefreshMs(raw: unknown, fallback = 1000): number {
339
+ const options = (raw ?? {}) as Record<string, unknown>;
340
+ const value = options.refreshMs ?? options.intervalMs;
341
+ if (typeof value === "number" && Number.isFinite(value) && value >= 100) return value;
342
+ return fallback;
343
+ }
344
+
345
+ /** Copy visibility options into a plain object. */
346
+ export function normalizeVisibilityOptions(raw: unknown): VisibilityOptions {
347
+ const options = (raw ?? {}) as Record<string, unknown>;
348
+ return {
349
+ successHoldMs:
350
+ typeof options.successHoldMs === "number" && options.successHoldMs >= 0
351
+ ? options.successHoldMs
352
+ : undefined,
353
+ showDone: options.showDone !== false,
354
+ // Default OFF: never-dismissed done entries stay visible.
355
+ autoHideDone: options.autoHideDone === true,
356
+ scope: options.scope === "all" ? "all" : "session",
357
+ };
358
+ }
359
+
360
+ /**
361
+ * Keep entries belonging to one session. Entries without a session are hidden
362
+ * by default, so a global/legacy report cannot leak into every chat.
363
+ */
364
+ export function scopeEntries(
365
+ entries: Record<string, ProgressEntry>,
366
+ sessionID: string | undefined,
367
+ options: VisibilityOptions = {}
368
+ ): Record<string, ProgressEntry> {
369
+ if (options.scope === "all") return entries;
370
+ if (!sessionID) return {};
371
+ const prefix = `${sessionID}:`;
372
+ const scoped: Record<string, ProgressEntry> = {};
373
+ for (const [key, entry] of Object.entries(entries)) {
374
+ if (!entry || typeof entry !== "object") continue;
375
+ if (entry.sessionId === sessionID || key.startsWith(prefix)) scoped[key] = entry;
376
+ }
377
+ return scoped;
378
+ }
379
+
380
+ /**
381
+ * Drop completed entries once their success confirmation has been visible long
382
+ * enough — ONLY when `autoHideDone` is enabled (default off). By default a
383
+ * done entry the user never dismissed stays visible until dismissed or pruned
384
+ * (including across plugin reloads); `showDone: false` hides all completed
385
+ * entries regardless.
386
+ */
387
+ export function visibleEntries(
388
+ entries: Record<string, ProgressEntry>,
389
+ now: number,
390
+ options: VisibilityOptions = {}
391
+ ): Record<string, ProgressEntry> {
392
+ const hold = options.successHoldMs ?? 8000;
393
+ const showDone = options.showDone !== false;
394
+ const autoHideDone = options.autoHideDone === true;
395
+ const visible: Record<string, ProgressEntry> = {};
396
+ for (const [key, entry] of Object.entries(entries)) {
397
+ if (!entry || typeof entry !== "object") continue;
398
+ if (entry.status === "done") {
399
+ if (!showDone) continue;
400
+ if (autoHideDone && now - (entry.updatedAt ?? 0) >= hold) continue;
401
+ }
402
+ visible[key] = entry;
403
+ }
404
+ return visible;
405
+ }
406
+
407
+ /**
408
+ * Build a progress bar in either the ASCII block style or the emoji style:
409
+ *
410
+ * blocks: [██████░░░░] 60%
411
+ * emoji: 🟩⬛️⬛️⬛️⬛️⬛️(69/420)
412
+ */
413
+ export function barParts(progress: number | null | undefined, options: BarOptions = {}): BarParts {
414
+ const style: BarStyle = options.style === "emoji" ? "emoji" : "blocks";
415
+ const segments = options.segments ?? (style === "emoji" ? 6 : 10);
416
+ const total = options.total ?? 100;
417
+ const value = clampProgress(progress);
418
+ const filled = Math.round(value * segments);
419
+ const bar =
420
+ style === "emoji"
421
+ ? "🟩".repeat(filled) + "⬛️".repeat(Math.max(0, segments - filled))
422
+ : "█".repeat(filled) + "░".repeat(Math.max(0, segments - filled));
423
+ const done = Math.round(value * total);
424
+ return { bar, done, total, fraction: `(${done}/${total})`, style };
425
+ }
426
+
427
+ export function renderBar(progress: number | null | undefined, width = 10): string {
428
+ return barParts(progress, { segments: width }).bar;
429
+ }
430
+
431
+ export function progressLabel(progress: number | null | undefined): string | null {
432
+ return progress == null ? null : `${Math.round(progress * 100)}%`;
433
+ }
package/src/tui.tsx ADDED
@@ -0,0 +1,151 @@
1
+ /**
2
+ * OpenCode Progress Plugin — TUI part.
3
+ *
4
+ * Reads the shared state file directly (the TUI runs locally) and renders:
5
+ * - a compact one-line summary in the composer footer,
6
+ * - a dependency tree above the composer.
7
+ */
8
+
9
+ import { For, Show, createSignal } from "solid-js";
10
+ import { Plugin, usePlugin } from "@opencode/plugin/tui";
11
+ import { readProgressState } from "./state.js";
12
+ import {
13
+ buildTree,
14
+ barParts,
15
+ countActive,
16
+ normalizeBarOptions,
17
+ normalizeRefreshMs,
18
+ normalizeVisibilityOptions,
19
+ progressLabel,
20
+ scopeEntries,
21
+ visibleEntries,
22
+ type BarOptions,
23
+ type VisibilityOptions,
24
+ } from "./tree.js";
25
+ import type { ProgressStatus, ProgressState, TreeNode } from "./types.js";
26
+
27
+ const [state, setState] = createSignal<ProgressState>(readProgressState());
28
+
29
+ let pollers = 0;
30
+ let timer: ReturnType<typeof setInterval> | undefined;
31
+ let barOptions: BarOptions = {};
32
+ let visibilityOptions: VisibilityOptions = {};
33
+
34
+ function startPolling(refreshMs: number): () => void {
35
+ pollers += 1;
36
+ setState(readProgressState());
37
+ if (!timer) {
38
+ timer = setInterval(() => setState(readProgressState()), refreshMs);
39
+ }
40
+ return () => {
41
+ pollers -= 1;
42
+ if (pollers <= 0) {
43
+ if (timer) clearInterval(timer);
44
+ timer = undefined;
45
+ pollers = 0;
46
+ }
47
+ };
48
+ }
49
+
50
+ function glyph(status: ProgressStatus): string {
51
+ if (status === "done") return "✓";
52
+ if (status === "error") return "✗";
53
+ if (status === "waiting") return "◐";
54
+ return "●";
55
+ }
56
+
57
+ function ProgressNode(props: { node: TreeNode; depth: number }) {
58
+ const ctx = usePlugin();
59
+ const indent = () => (props.depth === 0 ? "" : "└─ ");
60
+ const detailIndent = () => " · ";
61
+
62
+ const label = () => {
63
+ const parts = barParts(props.node.progress, barOptions);
64
+ if (parts.style === "emoji") {
65
+ const suffix =
66
+ props.node.status === "done" ? " ✓" : props.node.status === "error" ? " ✗" : "";
67
+ return `${props.node.title}: ${parts.bar}${parts.fraction}${suffix}`;
68
+ }
69
+ const pct = progressLabel(props.node.progress);
70
+ return `${glyph(props.node.status)} [${parts.bar}] ${props.node.title}${pct ? ` ${pct}` : ""}`;
71
+ };
72
+
73
+ return (
74
+ <box flexDirection="column" paddingLeft={props.depth === 0 ? 0 : 2}>
75
+ <text fg={ctx.theme.text.base} wrapMode="word">
76
+ <span fg={ctx.theme.text.muted}>{indent()}</span>
77
+ {label()}
78
+ </text>
79
+ <Show when={props.node.detail}>
80
+ <text fg={ctx.theme.text.muted} wrapMode="word">
81
+ {`${detailIndent()}${props.node.detail}`}
82
+ </text>
83
+ </Show>
84
+ <For each={props.node.children}>
85
+ {(child) => <ProgressNode node={child} depth={props.depth + 1} />}
86
+ </For>
87
+ </box>
88
+ );
89
+ }
90
+
91
+ function ProgressTree(props: { sessionID: string }) {
92
+ const ctx = usePlugin();
93
+ const roots = () =>
94
+ buildTree(
95
+ visibleEntries(
96
+ scopeEntries(state().entries ?? {}, props.sessionID, visibilityOptions),
97
+ Date.now(),
98
+ visibilityOptions
99
+ )
100
+ ).slice(0, 4);
101
+
102
+ return (
103
+ <Show when={roots().length > 0}>
104
+ <box flexDirection="column" paddingLeft={1} paddingRight={1} paddingTop={1}>
105
+ <text fg={ctx.theme.text.muted}>progress</text>
106
+ <For each={roots()}>{(node) => <ProgressNode node={node} depth={0} />}</For>
107
+ </box>
108
+ </Show>
109
+ );
110
+ }
111
+
112
+ function FooterStatus() {
113
+ const ctx = usePlugin();
114
+ const summary = () => {
115
+ const roots = buildTree(state().entries ?? {});
116
+ const active = countActive(roots);
117
+ return active > 0 ? `${active} active task${active === 1 ? "" : "s"}` : "";
118
+ };
119
+
120
+ return (
121
+ <Show when={summary()}>
122
+ <text fg={ctx.theme.text.muted}>{summary()}</text>
123
+ </Show>
124
+ );
125
+ }
126
+
127
+ export default Plugin.define({
128
+ id: "opencode-progress.tui",
129
+ setup(context) {
130
+ barOptions = normalizeBarOptions(context.options);
131
+ visibilityOptions = normalizeVisibilityOptions(context.options);
132
+ const stopPolling = startPolling(normalizeRefreshMs(context.options));
133
+ if (context.options?.notifyOnLoad === true) {
134
+ context.ui.toast.show({ message: "Progress plugin loaded", variant: "success" });
135
+ }
136
+ const unregisterTree = context.ui.slot({
137
+ append: "session.composer.top",
138
+ render: ({ sessionID }) => <ProgressTree sessionID={sessionID} />,
139
+ });
140
+ const unregisterFooter = context.ui.slot({
141
+ append: "home.footer.status",
142
+ render: () => <FooterStatus />,
143
+ });
144
+
145
+ return () => {
146
+ unregisterTree?.();
147
+ unregisterFooter?.();
148
+ stopPolling();
149
+ };
150
+ },
151
+ });
package/src/types.ts ADDED
@@ -0,0 +1,48 @@
1
+ /**
2
+ * Shared types for the progress plugin parts.
3
+ *
4
+ * Kept dependency-free so the GUI bundle can import it without pulling in
5
+ * Node built-ins.
6
+ */
7
+
8
+ export type ProgressStatus = "running" | "done" | "error" | "waiting";
9
+
10
+ export interface ProgressEntry {
11
+ id: string;
12
+ sessionId?: string;
13
+ status: ProgressStatus;
14
+ /** Task label; may contain `\n` line breaks. */
15
+ title: string;
16
+ /** Optional detail; may contain `\n` line breaks. */
17
+ detail?: string | null;
18
+ /** 0..1 fraction, or null when unknown. */
19
+ progress?: number | null;
20
+ parentId?: string | null;
21
+ startedAt?: number;
22
+ createdAt?: number;
23
+ updatedAt?: number;
24
+ /**
25
+ * View-plane metadata: a user dismissed this task, with the rolled-up
26
+ * status at dismiss time. Written by the plugin (atomic + locked, spec
27
+ * §4.3/§4.4), preserved by agent/relay upserts, cleared on lifecycle
28
+ * restart. Revival semantics live in tree.ts `isDismissed`.
29
+ */
30
+ dismissed?: { status: string; at: number } | null;
31
+ }
32
+
33
+ export interface ProgressState {
34
+ entries: Record<string, ProgressEntry>;
35
+ version?: number;
36
+ }
37
+
38
+ export interface TreeNode extends ProgressEntry {
39
+ /** Stable key from the state file map (may be session-scoped). */
40
+ key: string;
41
+ children: TreeNode[];
42
+ /**
43
+ * The entry's own stored `updatedAt`, before buildTree projects the latest
44
+ * child update onto `updatedAt`. Dismissal logic uses this to tell "the
45
+ * agent re-reported this task" apart from "a child ticked / a sibling moved".
46
+ */
47
+ reportedAt?: number;
48
+ }