@xiangyixie/dsh-superagent 0.10.0 → 0.12.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/lib/store.js CHANGED
@@ -1,402 +1,873 @@
1
- /**
2
- * Durable run storage for dsh-superagent.
3
- *
4
- * One JSON file per run under `<root>/runs/<runId>.json`. Writes are atomic
5
- * (temp file + rename) so a host crash mid-write cannot leave a half-written
6
- * run that blocks recovery.
7
- *
8
- * Sibling files carry signals that are safe to write from another process:
9
- * `<runId>.cancel` asks the owning process to stop the run, `<runId>.lock`
10
- * claims the right to schedule it so two processes cannot run the same one, and
11
- * `<runId>.json.corrupt-<ts>` keeps an unparsable state file instead of
12
- * deleting the evidence.
13
- *
14
- * @module dsh-superagent/store
15
- */
16
- import fsp from 'node:fs/promises'
17
- import os from 'node:os'
18
- import path from 'node:path'
19
-
20
- /** Statuses for a run that still owns live work. */
21
- export const ACTIVE_STATUSES = new Set(['queued', 'planning', 'running', 'aggregating'])
22
-
23
- /** Statuses after which a run will not change on its own. */
24
- export const TERMINAL_STATUSES = new Set(['completed', 'partial', 'failed', 'cancelled', 'interrupted'])
25
-
26
- /**
27
- * Prefix of a goal guard: the lock a start holds while it decides whether a run
28
- * for that goal already exists. It is keyed by the goal rather than by a run id,
29
- * so it has no run file of its own and the mount-time cleanup must leave it
30
- * alone instead of treating it as a lock left behind by a finished run.
31
- */
32
- export const GOAL_GUARD_PREFIX = 'goal-'
33
-
34
- const RUN_ID_PATTERN = /^[0-9A-Za-z][0-9A-Za-z-]{3,63}$/
35
- const STALE_TMP_MS = 10 * 60 * 1000
36
-
37
- /**
38
- * Resolve the state root. An explicit `stateDir` wins, then `$DSH_HOME`, then
39
- * the harness default `~/.dsh`.
40
- * @param {string | undefined} configured - plugin config `stateDir`.
41
- * @returns {string} absolute state root.
42
- */
43
- export function resolveStateRoot(configured) {
44
- if (typeof configured === 'string' && configured.trim()) return path.resolve(configured.trim())
45
- const home = process.env.DSH_HOME?.trim() || path.join(os.homedir(), '.dsh')
46
- return path.join(home, 'state', 'superagent')
47
- }
48
-
49
- /**
50
- * Build a store bound to one state root.
51
- * @param {string} root - absolute state root.
52
- * @param {{ warn?: (message: string) => void }} [options] - diagnostics sink.
53
- */
54
- export function createStore(root, options = {}) {
55
- const runsDir = path.join(root, 'runs')
56
- const warn = options.warn ?? (() => {})
57
- // Two saves of the same run can land in the same millisecond, so the temp
58
- // name needs a counter as well as a clock.
59
- let writeSeq = 0
60
- /** runId -> quarantine path, so status can explain a run it cannot parse. */
61
- const corrupt = new Map()
62
-
63
- const runFile = runId => path.join(runsDir, `${runId}.json`)
64
- const cancelFile = runId => path.join(runsDir, `${runId}.cancel`)
65
- const lockFile = runId => path.join(runsDir, `${runId}.lock`)
66
- const reportFile = runId => path.join(root, 'reports', `${runId}.md`)
67
- const ownerFile = path.join(root, '.owner')
68
-
69
- return {
70
- root,
71
- runsDir,
72
- ownerFile,
73
- corrupt,
74
-
75
- async init() {
76
- await fsp.mkdir(runsDir, { recursive: true })
77
- await this.cleanup()
78
- },
79
-
80
- /**
81
- * Remove temp files left by a killed process and sibling markers whose run
82
- * already reached a terminal state, so none of them can affect later runs.
83
- */
84
- async cleanup() {
85
- let names
86
- try {
87
- names = await fsp.readdir(runsDir)
88
- } catch {
89
- return
90
- }
91
- for (const name of names) {
92
- const file = path.join(runsDir, name)
93
- if (name.startsWith('.') && name.endsWith('.tmp')) {
94
- try {
95
- const stat = await fsp.stat(file)
96
- if (Date.now() - stat.mtimeMs > STALE_TMP_MS) await fsp.unlink(file)
97
- } catch {
98
- // Already gone; nothing to clean.
99
- }
100
- continue
101
- }
102
- const marker = ['.cancel', '.lock'].find(suffix => name.endsWith(suffix))
103
- if (!marker) continue
104
- // A goal guard is not a run lock and has no run file to read; its
105
- // holder releases it, or a later start breaks a dead holder's guard.
106
- if (name.startsWith(GOAL_GUARD_PREFIX) && marker === '.lock') continue
107
- let run = null
108
- let readable = true
109
- try {
110
- run = await this.read(name.slice(0, -marker.length))
111
- } catch {
112
- // An unreadable run file is not a reason to drop its control files.
113
- readable = false
114
- }
115
- if (!readable) continue
116
- if (!run || TERMINAL_STATUSES.has(run.status)) {
117
- try {
118
- await fsp.unlink(file)
119
- } catch {
120
- // Nothing to clean.
121
- }
122
- }
123
- }
124
- },
125
-
126
- /**
127
- * Read every readable run, newest first. A corrupt file is quarantined and
128
- * skipped rather than failing the whole listing; a file that cannot be read
129
- * at all is reported and skipped for the same reason.
130
- */
131
- async list() {
132
- let names
133
- try {
134
- names = await fsp.readdir(runsDir)
135
- } catch (error) {
136
- // A missing runs directory means initialization did not happen; saying
137
- // "no runs recorded" would hide that. Only an empty directory is empty.
138
- const code = error?.code ? `${error.code}: ` : ''
139
- throw new Error(
140
- `cannot read the run state directory ${runsDir} (${code}${error?.message ?? error}); `
141
- + 'the plugin could not initialize it, so no run can be listed or resumed',
142
- )
143
- }
144
- const runs = []
145
- for (const name of names) {
146
- if (!name.endsWith('.json') || name.startsWith('.')) continue
147
- try {
148
- const run = await this.read(name.slice(0, -'.json'.length))
149
- if (run) runs.push(run)
150
- } catch (error) {
151
- warn(`skipping run file ${name}: ${error?.message ?? error}`)
152
- }
153
- }
154
- runs.sort((a, b) => String(b.createdAt).localeCompare(String(a.createdAt)))
155
- return runs
156
- },
157
-
158
- /**
159
- * @param {string} runId - run identity.
160
- * @returns {Promise<object | null>} parsed run, or null when missing/invalid.
161
- * @throws when the file exists but cannot be read (EPERM, EMFILE, ENOSPC...).
162
- * Reporting that as "unknown run" would hide a real filesystem problem.
163
- */
164
- async read(runId) {
165
- if (!RUN_ID_PATTERN.test(String(runId))) return null
166
- // Windows can fail a read with EBUSY/EACCES for a moment while another
167
- // process replaces the file. Those are transient for a reader, so retry
168
- // before turning a poll into a hard error; real permission errors still
169
- // surface after the retries.
170
- for (let attempt = 1; ; attempt++) {
171
- try {
172
- const text = await fsp.readFile(runFile(runId), 'utf8')
173
- const run = JSON.parse(text)
174
- if (!run || typeof run !== 'object') {
175
- await this.quarantine(runId)
176
- return null
177
- }
178
- return run
179
- } catch (error) {
180
- if (error?.code === 'ENOENT') return null
181
- if (error instanceof SyntaxError) {
182
- const moved = await this.quarantine(runId)
183
- warn(`state file for run ${runId} was not valid JSON; kept at ${moved ?? 'the runs directory'}`)
184
- return null
185
- }
186
- const transient = ['EPERM', 'EACCES', 'EBUSY', 'EMFILE'].includes(error?.code)
187
- if (transient && attempt < 3) {
188
- await new Promise(resolve => setTimeout(resolve, 15 * attempt))
189
- continue
190
- }
191
- const code = error?.code ? `${error.code}: ` : ''
192
- throw new Error(`cannot read state for run ${runId} (${code}${error?.message ?? error})`)
193
- }
194
- }
195
- },
196
-
197
- /**
198
- * Move an unparsable state file aside so it neither blocks recovery nor
199
- * gets overwritten by the next save of the same id.
200
- * @param {string} runId - run identity.
201
- * @returns {Promise<string | null>} new path, or null when nothing moved.
202
- */
203
- async quarantine(runId) {
204
- const target = `${runFile(runId)}.corrupt-${Date.now()}`
205
- try {
206
- await fsp.rename(runFile(runId), target)
207
- corrupt.set(runId, target)
208
- return target
209
- } catch {
210
- return null
211
- }
212
- },
213
-
214
- /**
215
- * Atomically persist one run.
216
- * @param {object} run - run record with an `id`.
217
- */
218
- async write(run) {
219
- const file = runFile(run.id)
220
- const tmp = path.join(runsDir, `.${run.id}.${process.pid}.${++writeSeq}.tmp`)
221
- await fsp.writeFile(tmp, `${JSON.stringify(run, null, 2)}\n`, 'utf8')
222
- for (let attempt = 1; ; attempt++) {
223
- try {
224
- await fsp.rename(tmp, file)
225
- return
226
- } catch (error) {
227
- // A reader holding the destination open can fail the replace on Windows.
228
- if (attempt >= 5 || !['EPERM', 'EACCES', 'EBUSY'].includes(error?.code)) throw error
229
- await new Promise(resolve => setTimeout(resolve, 20 * attempt))
230
- }
231
- }
232
- },
233
-
234
- /**
235
- * Ask whichever process owns a run to stop it. This is a file, not IPC, so
236
- * it works across processes and survives a restart.
237
- * @param {string} runId - run identity.
238
- */
239
- async requestCancel(runId) {
240
- if (!RUN_ID_PATTERN.test(String(runId))) return false
241
- await fsp.writeFile(cancelFile(runId), `${JSON.stringify({ requestedAt: new Date().toISOString(), pid: process.pid })}\n`, 'utf8')
242
- return true
243
- },
244
-
245
- /**
246
- * @param {string} runId - run identity.
247
- * @returns {Promise<boolean>} true when a cancel was requested by any process.
248
- */
249
- async hasCancelRequest(runId) {
250
- try {
251
- await fsp.access(cancelFile(runId))
252
- return true
253
- } catch {
254
- return false
255
- }
256
- },
257
-
258
- /**
259
- * @param {string} runId - run identity.
260
- */
261
- async clearCancel(runId) {
262
- try {
263
- await fsp.unlink(cancelFile(runId))
264
- } catch {
265
- // Nothing to clear.
266
- }
267
- },
268
-
269
- cancelFile,
270
-
271
- /**
272
- * Claim the right to schedule one run. The lock is created with `wx`, so
273
- * exactly one process wins even when two profiles point at the same state
274
- * directory; the loser gets the holder instead of a second copy of the run.
275
- * @param {string} runId - run identity.
276
- * @param {{ pid: number, hostname: string, at: string }} holder - claimant.
277
- * @returns {Promise<{ acquired: boolean, holder: object | null }>}
278
- */
279
- async acquireLock(runId, holder) {
280
- if (!RUN_ID_PATTERN.test(String(runId))) return { acquired: false, holder: null }
281
- try {
282
- await fsp.writeFile(lockFile(runId), `${JSON.stringify(holder)}\n`, { encoding: 'utf8', flag: 'wx' })
283
- return { acquired: true, holder }
284
- } catch (error) {
285
- if (error?.code !== 'EEXIST') throw error
286
- return { acquired: false, holder: await this.readLock(runId) }
287
- }
288
- },
289
-
290
- /**
291
- * @param {string} runId - run identity.
292
- * @returns {Promise<object | null>} recorded holder, or null.
293
- */
294
- async readLock(runId) {
295
- if (!RUN_ID_PATTERN.test(String(runId))) return null
296
- try {
297
- const parsed = JSON.parse(await fsp.readFile(lockFile(runId), 'utf8'))
298
- return parsed && typeof parsed === 'object' ? parsed : null
299
- } catch {
300
- return null
301
- }
302
- },
303
-
304
- /**
305
- * @param {string} runId - run identity.
306
- */
307
- async releaseLock(runId) {
308
- try {
309
- await fsp.unlink(lockFile(runId))
310
- } catch {
311
- // Nothing to release.
312
- }
313
- },
314
-
315
- /**
316
- * Machine identity of the state directory, written once by the first
317
- * process that mounts it. Its presence tells later processes whether a pid
318
- * in a run file belongs to this machine (local) or possibly to another one
319
- * sharing the directory, where the pid is meaningless.
320
- * @returns {Promise<{ hostname?: string, createdAt?: string } | null>}
321
- */
322
- async readOwner() {
323
- try {
324
- const parsed = JSON.parse(await fsp.readFile(ownerFile, 'utf8'))
325
- return parsed && typeof parsed === 'object' ? parsed : null
326
- } catch {
327
- return null
328
- }
329
- },
330
-
331
- /**
332
- * @param {{ hostname: string, createdAt?: string }} owner - identity to record.
333
- */
334
- async writeOwner(owner) {
335
- try {
336
- await fsp.writeFile(ownerFile, `${JSON.stringify(owner, null, 2)}\n`, 'utf8')
337
- } catch (error) {
338
- warn(`cannot record the state directory owner in ${ownerFile}: ${error?.message ?? error}`)
339
- }
340
- },
341
-
342
- /**
343
- * Delete terminal runs older than `olderThanDays`, so an install that runs
344
- * for months does not accumulate state forever. Opt-in: called with a
345
- * positive number only when the user configured `keepRuns`.
346
- * @param {{ olderThanDays: number }} options - retention window.
347
- * @returns {Promise<{ removed: string[] }>} removed run ids.
348
- */
349
- async prune({ olderThanDays }) {
350
- const days = Number(olderThanDays)
351
- const removed = []
352
- if (!Number.isFinite(days) || days <= 0) return { removed }
353
- const cutoff = Date.now() - days * 86400000
354
- for (const run of await this.list()) {
355
- if (!TERMINAL_STATUSES.has(run.status)) continue
356
- const finished = Date.parse(run.finishedAt ?? run.updatedAt ?? run.createdAt)
357
- if (!Number.isFinite(finished) || finished > cutoff) continue
358
- try {
359
- await fsp.unlink(runFile(run.id))
360
- await this.clearCancel(run.id)
361
- await this.releaseLock(run.id)
362
- // The report artifact belongs to the run; leaving it behind would make
363
- // `keepRuns` bound the state directory for the runs but not the reports.
364
- await fsp.unlink(reportFile(run.id)).catch(error => {
365
- if (error?.code !== 'ENOENT') throw error
366
- })
367
- removed.push(run.id)
368
- } catch (error) {
369
- warn(`cannot prune run ${run.id}: ${error?.message ?? error}`)
370
- }
371
- }
372
- return { removed }
373
- },
374
-
375
- /**
376
- * Size of the state directory, for `superagent_list`.
377
- * @returns {Promise<{ bytes: number, files: number, corrupt: number }>} totals.
378
- */
379
- async stats() {
380
- const totals = { bytes: 0, files: 0, corrupt: 0 }
381
- let names
382
- try {
383
- names = await fsp.readdir(runsDir)
384
- } catch {
385
- return totals
386
- }
387
- for (const name of names) {
388
- try {
389
- const stat = await fsp.stat(path.join(runsDir, name))
390
- if (!stat.isFile()) continue
391
- totals.files++
392
- totals.bytes += stat.size
393
- if (name.includes('.corrupt-')) totals.corrupt++
394
- } catch {
395
- // A file removed mid-scan does not change the answer.
396
- }
397
- }
398
- return totals
399
- },
400
- }
401
- }
402
-
1
+ /**
2
+ * Durable run storage for dsh-superagent.
3
+ *
4
+ * One JSON file per run under `<root>/runs/<runId>.json`. Writes are atomic
5
+ * (temp file + rename) so a host crash mid-write cannot leave a half-written
6
+ * run that blocks recovery.
7
+ *
8
+ * Sibling files carry signals that are safe to write from another process:
9
+ * `<runId>.cancel` asks the owning process to stop the run, `<runId>.lock`
10
+ * claims the right to schedule it so two processes cannot run the same one, and
11
+ * `<runId>.json.corrupt-<ts>` keeps an unparsable state file instead of
12
+ * deleting the evidence.
13
+ *
14
+ * @module dsh-superagent/store
15
+ */
16
+ import { createHash } from 'node:crypto'
17
+ import fsp from 'node:fs/promises'
18
+ import os from 'node:os'
19
+ import path from 'node:path'
20
+
21
+ /** Format marker written into every exported archive. */
22
+ export const ARCHIVE_FORMAT = 'dsh-superagent/run-archive'
23
+
24
+ /** Archive layout version; `import` refuses a version it cannot read. */
25
+ export const ARCHIVE_FORMAT_VERSION = 1
26
+
27
+ /** Statuses for a run that still owns live work. */
28
+ export const ACTIVE_STATUSES = new Set(['queued', 'planning', 'running', 'aggregating'])
29
+
30
+ /** Statuses after which a run will not change on its own. */
31
+ export const TERMINAL_STATUSES = new Set(['completed', 'partial', 'failed', 'cancelled', 'interrupted'])
32
+
33
+ /**
34
+ * Prefix of a goal guard: the lock a start holds while it decides whether a run
35
+ * for that goal already exists. It is keyed by the goal rather than by a run id,
36
+ * so it has no run file of its own and the mount-time cleanup must leave it
37
+ * alone instead of treating it as a lock left behind by a finished run.
38
+ */
39
+ export const GOAL_GUARD_PREFIX = 'goal-'
40
+
41
+ const RUN_ID_PATTERN = /^[0-9A-Za-z][0-9A-Za-z-]{3,63}$/
42
+ const STALE_TMP_MS = 10 * 60 * 1000
43
+ const EMBEDDED_ARCHIVE = /<script[^>]*id="superagent-archive"[^>]*>([\s\S]*?)<\/script>/i
44
+
45
+ /**
46
+ * Turn a `--status` filter into a validated set. A typo must fail loudly:
47
+ * silently matching nothing would make an operator believe a prune ran.
48
+ * @param {string | string[] | undefined | null} value - comma list or array.
49
+ * @returns {Set<string> | null} allowed statuses, or null for "all terminal".
50
+ */
51
+ function normalizeStatuses(value) {
52
+ if (value === undefined || value === null) return null
53
+ const list = Array.isArray(value) ? value : String(value).split(',')
54
+ const statuses = [...new Set(list.map(item => String(item).trim().toLowerCase()).filter(Boolean))]
55
+ const terminal = [...TERMINAL_STATUSES].join(', ')
56
+ if (statuses.length === 0) throw new Error(`a status filter needs at least one status (terminal: ${terminal})`)
57
+ const unknown = statuses.filter(status => !TERMINAL_STATUSES.has(status))
58
+ if (unknown.length > 0) {
59
+ throw new Error(`status filter ${unknown.join(', ')} is not terminal; only ${terminal} runs can be pruned`)
60
+ }
61
+ return new Set(statuses)
62
+ }
63
+
64
+ /** Filesystem-safe fragment for a subtask title. */
65
+ function slugOf(text, fallback) {
66
+ const slug = String(text ?? '')
67
+ .toLowerCase()
68
+ .replace(/[^a-z0-9]+/g, '-')
69
+ .replace(/^-+|-+$/g, '')
70
+ .slice(0, 40)
71
+ .replace(/-+$/g, '')
72
+ return slug || fallback
73
+ }
74
+
75
+ /** One subtask as a standalone markdown page inside an export. */
76
+ function renderSubtaskMarkdown(subtask) {
77
+ const lines = [
78
+ `# Subtask ${subtask.index ?? '?'} — ${subtask.title || '(untitled)'}`,
79
+ '',
80
+ `- status: ${subtask.status}`,
81
+ `- attempts: ${subtask.attempts ?? 0}`,
82
+ `- started: ${subtask.startedAt ?? 'unknown'}`,
83
+ `- finished: ${subtask.finishedAt ?? 'not finished'}`,
84
+ `- child: ${subtask.childId ?? 'none'}`,
85
+ `- tokens: ${subtask.usage?.totalTokens ?? 0} across ${subtask.usage?.modelCalls ?? 0} model call(s)`,
86
+ ]
87
+ if (subtask.error) lines.push(`- error: ${subtask.error}`)
88
+ lines.push('', '## Prompt', '', subtask.prompt || '_No prompt recorded._')
89
+ lines.push('', '## Result', '', subtask.result || '_No result recorded._')
90
+ return `${lines.join('\n')}\n`
91
+ }
92
+
93
+ /** Guard/attention records as markdown; these are the run's interception trail. */
94
+ function renderGuardsMarkdown(guards, at) {
95
+ const lines = ['# Guard and attention records', '', `Recorded at: ${at ?? 'unknown'}`, '']
96
+ if (guards.issue) lines.push(`Issue: ${guards.issue}`, '')
97
+ if (guards.items.length === 0 && !guards.issue) lines.push('No worker or aggregator asked for a decision during this run.', '')
98
+ guards.items.forEach((item, index) => {
99
+ lines.push(`## ${index + 1}. ${item.source ?? 'unknown source'}`, '')
100
+ lines.push(`Question: ${item.question ?? '(none)'}`)
101
+ if (Array.isArray(item.options) && item.options.length > 0) {
102
+ lines.push('', 'Options:', ...item.options.map(option => `- ${option}`))
103
+ }
104
+ if (item.reason) lines.push('', `Reason: ${item.reason}`)
105
+ lines.push('')
106
+ })
107
+ return `${lines.join('\n').trimEnd()}\n`
108
+ }
109
+
110
+ /** Human-readable cost with the unpriced caveat stated, never guessed. */
111
+ function renderCost(cost) {
112
+ if (!cost || !Number.isFinite(cost.total)) return 'unpriced (no configured price for these models)'
113
+ const amount = `${cost.currency ?? 'USD'} ${cost.total.toFixed(4)}`
114
+ if (cost.complete === false) {
115
+ return `${amount} (partial; unpriced: ${(cost.unpriced ?? []).join(', ') || 'unknown'})`
116
+ }
117
+ return amount
118
+ }
119
+
120
+ /** One page a reader can open first; the report itself follows inline. */
121
+ function renderReadme(archive) {
122
+ const subtasks = archive.subtasks
123
+ const counts = {}
124
+ for (const subtask of subtasks) counts[subtask.status] = (counts[subtask.status] ?? 0) + 1
125
+ const breakdown = Object.entries(counts).map(([status, count]) => `${count} ${status}`).join(', ')
126
+ const lines = [
127
+ `# Superagent run ${archive.runId}`,
128
+ '',
129
+ `- goal: ${archive.goal || '(empty)'}`,
130
+ `- status: ${archive.status}`,
131
+ `- created: ${archive.createdAt ?? 'unknown'}`,
132
+ `- finished: ${archive.finishedAt ?? 'not finished'}`,
133
+ `- subtasks: ${subtasks.length}${breakdown ? ` (${breakdown})` : ''}`,
134
+ `- guards: ${archive.guards.items.length} decision request(s)${archive.guards.issue ? '; one attention block was unusable' : ''}`,
135
+ `- tokens: ${archive.usage?.totalTokens ?? 0} across ${archive.usage?.modelCalls ?? 0} model call(s)`,
136
+ `- cost: ${renderCost(archive.cost)}`,
137
+ '',
138
+ '## Report',
139
+ '',
140
+ archive.report || '_No merged report was recorded for this run._',
141
+ '',
142
+ '## Subtasks',
143
+ '',
144
+ ]
145
+ if (subtasks.length === 0) lines.push('_No subtasks recorded._')
146
+ else {
147
+ lines.push('| # | status | title | tokens |', '| --- | --- | --- | --- |')
148
+ for (const subtask of subtasks) {
149
+ const title = String(subtask.title ?? '').replace(/\|/g, '\\|')
150
+ lines.push(`| ${subtask.index ?? '-'} | ${subtask.status} | ${title} | ${subtask.usage?.totalTokens ?? '-'} |`)
151
+ }
152
+ }
153
+ lines.push(
154
+ '',
155
+ '## Files',
156
+ '',
157
+ 'Everything in this directory is part of the archive; nothing is fetched from the network.',
158
+ '',
159
+ '- `run.json` — the full durable run record as the store wrote it',
160
+ '- `report.md` — the final merged report',
161
+ '- `subtasks/` — each subtask as markdown (readable) and JSON (structured)',
162
+ '- `guards.json` / `guards.md` — worker and aggregator decisions the run stopped on',
163
+ '- `usage.json` — token totals per child, plus the cost the operator prices produce',
164
+ '- `manifest.json` — archive metadata, file sizes, and SHA-256 checksums',
165
+ )
166
+ return `${lines.join('\n')}\n`
167
+ }
168
+
169
+ /**
170
+ * Resolve the state root. An explicit `stateDir` wins, then `$DSH_HOME`, then
171
+ * the harness default `~/.dsh`.
172
+ * @param {string | undefined} configured - plugin config `stateDir`.
173
+ * @returns {string} absolute state root.
174
+ */
175
+ export function resolveStateRoot(configured) {
176
+ if (typeof configured === 'string' && configured.trim()) return path.resolve(configured.trim())
177
+ const home = process.env.DSH_HOME?.trim() || path.join(os.homedir(), '.dsh')
178
+ return path.join(home, 'state', 'superagent')
179
+ }
180
+
181
+ /**
182
+ * Build a store bound to one state root.
183
+ * @param {string} root - absolute state root.
184
+ * @param {{ warn?: (message: string) => void }} [options] - diagnostics sink.
185
+ */
186
+ export function createStore(root, options = {}) {
187
+ const runsDir = path.join(root, 'runs')
188
+ const warn = options.warn ?? (() => {})
189
+ // Two saves of the same run can land in the same millisecond, so the temp
190
+ // name needs a counter as well as a clock.
191
+ let writeSeq = 0
192
+ /** runId -> quarantine path, so status can explain a run it cannot parse. */
193
+ const corrupt = new Map()
194
+
195
+ const runFile = runId => path.join(runsDir, `${runId}.json`)
196
+ const cancelFile = runId => path.join(runsDir, `${runId}.cancel`)
197
+ const lockFile = runId => path.join(runsDir, `${runId}.lock`)
198
+ const reportFile = runId => path.join(root, 'reports', `${runId}.md`)
199
+ const ownerFile = path.join(root, '.owner')
200
+
201
+ /** File size, or null when the file does not exist (or is not a file). */
202
+ const sizeOf = async file => {
203
+ try {
204
+ const stat = await fsp.stat(file)
205
+ return stat.isFile() ? stat.size : null
206
+ } catch {
207
+ return null
208
+ }
209
+ }
210
+
211
+ /**
212
+ * A lock file is the cross-process claim on a run. Even a terminal run must
213
+ * be left alone while one exists: another process may be mid-write.
214
+ */
215
+ const isHeld = async runId => (await sizeOf(lockFile(runId))) !== null
216
+
217
+ /** The report text, preferring the run record and falling back to its artifact. */
218
+ const reportTextOf = async run => {
219
+ if (typeof run.report === 'string' && run.report.trim()) return run.report.trim()
220
+ try {
221
+ const text = await fsp.readFile(reportFile(run.id), 'utf8')
222
+ return text.trim() ? text.trim() : null
223
+ } catch {
224
+ return null
225
+ }
226
+ }
227
+
228
+ return {
229
+ root,
230
+ runsDir,
231
+ ownerFile,
232
+ corrupt,
233
+
234
+ async init() {
235
+ await fsp.mkdir(runsDir, { recursive: true })
236
+ await this.cleanup()
237
+ },
238
+
239
+ /**
240
+ * Remove temp files left by a killed process and sibling markers whose run
241
+ * already reached a terminal state, so none of them can affect later runs.
242
+ */
243
+ async cleanup() {
244
+ let names
245
+ try {
246
+ names = await fsp.readdir(runsDir)
247
+ } catch {
248
+ return
249
+ }
250
+ for (const name of names) {
251
+ const file = path.join(runsDir, name)
252
+ if (name.startsWith('.') && name.endsWith('.tmp')) {
253
+ try {
254
+ const stat = await fsp.stat(file)
255
+ if (Date.now() - stat.mtimeMs > STALE_TMP_MS) await fsp.unlink(file)
256
+ } catch {
257
+ // Already gone; nothing to clean.
258
+ }
259
+ continue
260
+ }
261
+ const marker = ['.cancel', '.lock'].find(suffix => name.endsWith(suffix))
262
+ if (!marker) continue
263
+ // A goal guard is not a run lock and has no run file to read; its
264
+ // holder releases it, or a later start breaks a dead holder's guard.
265
+ if (name.startsWith(GOAL_GUARD_PREFIX) && marker === '.lock') continue
266
+ let run = null
267
+ let readable = true
268
+ try {
269
+ run = await this.read(name.slice(0, -marker.length))
270
+ } catch {
271
+ // An unreadable run file is not a reason to drop its control files.
272
+ readable = false
273
+ }
274
+ if (!readable) continue
275
+ if (!run || TERMINAL_STATUSES.has(run.status)) {
276
+ try {
277
+ await fsp.unlink(file)
278
+ } catch {
279
+ // Nothing to clean.
280
+ }
281
+ }
282
+ }
283
+ },
284
+
285
+ /**
286
+ * Read every readable run, newest first. A corrupt file is quarantined and
287
+ * skipped rather than failing the whole listing; a file that cannot be read
288
+ * at all is reported and skipped for the same reason.
289
+ */
290
+ async list() {
291
+ let names
292
+ try {
293
+ names = await fsp.readdir(runsDir)
294
+ } catch (error) {
295
+ // A missing runs directory means initialization did not happen; saying
296
+ // "no runs recorded" would hide that. Only an empty directory is empty.
297
+ const code = error?.code ? `${error.code}: ` : ''
298
+ throw new Error(
299
+ `cannot read the run state directory ${runsDir} (${code}${error?.message ?? error}); `
300
+ + 'the plugin could not initialize it, so no run can be listed or resumed',
301
+ )
302
+ }
303
+ const runs = []
304
+ for (const name of names) {
305
+ if (!name.endsWith('.json') || name.startsWith('.')) continue
306
+ try {
307
+ const run = await this.read(name.slice(0, -'.json'.length))
308
+ if (run) runs.push(run)
309
+ } catch (error) {
310
+ warn(`skipping run file ${name}: ${error?.message ?? error}`)
311
+ }
312
+ }
313
+ runs.sort((a, b) => String(b.createdAt).localeCompare(String(a.createdAt)))
314
+ return runs
315
+ },
316
+
317
+ /**
318
+ * @param {string} runId - run identity.
319
+ * @returns {Promise<object | null>} parsed run, or null when missing/invalid.
320
+ * @throws when the file exists but cannot be read (EPERM, EMFILE, ENOSPC...).
321
+ * Reporting that as "unknown run" would hide a real filesystem problem.
322
+ */
323
+ async read(runId) {
324
+ if (!RUN_ID_PATTERN.test(String(runId))) return null
325
+ // Windows can fail a read with EBUSY/EACCES for a moment while another
326
+ // process replaces the file. Those are transient for a reader, so retry
327
+ // before turning a poll into a hard error; real permission errors still
328
+ // surface after the retries.
329
+ for (let attempt = 1; ; attempt++) {
330
+ try {
331
+ const text = await fsp.readFile(runFile(runId), 'utf8')
332
+ const run = JSON.parse(text)
333
+ if (!run || typeof run !== 'object') {
334
+ await this.quarantine(runId)
335
+ return null
336
+ }
337
+ return run
338
+ } catch (error) {
339
+ if (error?.code === 'ENOENT') return null
340
+ if (error instanceof SyntaxError) {
341
+ const moved = await this.quarantine(runId)
342
+ warn(`state file for run ${runId} was not valid JSON; kept at ${moved ?? 'the runs directory'}`)
343
+ return null
344
+ }
345
+ const transient = ['EPERM', 'EACCES', 'EBUSY', 'EMFILE'].includes(error?.code)
346
+ if (transient && attempt < 3) {
347
+ await new Promise(resolve => setTimeout(resolve, 15 * attempt))
348
+ continue
349
+ }
350
+ const code = error?.code ? `${error.code}: ` : ''
351
+ throw new Error(`cannot read state for run ${runId} (${code}${error?.message ?? error})`)
352
+ }
353
+ }
354
+ },
355
+
356
+ /**
357
+ * Move an unparsable state file aside so it neither blocks recovery nor
358
+ * gets overwritten by the next save of the same id.
359
+ * @param {string} runId - run identity.
360
+ * @returns {Promise<string | null>} new path, or null when nothing moved.
361
+ */
362
+ async quarantine(runId) {
363
+ const target = `${runFile(runId)}.corrupt-${Date.now()}`
364
+ try {
365
+ await fsp.rename(runFile(runId), target)
366
+ corrupt.set(runId, target)
367
+ return target
368
+ } catch {
369
+ return null
370
+ }
371
+ },
372
+
373
+ /**
374
+ * Atomically persist one run.
375
+ * @param {object} run - run record with an `id`.
376
+ */
377
+ async write(run) {
378
+ const file = runFile(run.id)
379
+ const tmp = path.join(runsDir, `.${run.id}.${process.pid}.${++writeSeq}.tmp`)
380
+ await fsp.writeFile(tmp, `${JSON.stringify(run, null, 2)}\n`, 'utf8')
381
+ for (let attempt = 1; ; attempt++) {
382
+ try {
383
+ await fsp.rename(tmp, file)
384
+ return
385
+ } catch (error) {
386
+ // A reader holding the destination open can fail the replace on Windows.
387
+ if (attempt >= 5 || !['EPERM', 'EACCES', 'EBUSY'].includes(error?.code)) throw error
388
+ await new Promise(resolve => setTimeout(resolve, 20 * attempt))
389
+ }
390
+ }
391
+ },
392
+
393
+ /**
394
+ * Ask whichever process owns a run to stop it. This is a file, not IPC, so
395
+ * it works across processes and survives a restart.
396
+ * @param {string} runId - run identity.
397
+ */
398
+ async requestCancel(runId) {
399
+ if (!RUN_ID_PATTERN.test(String(runId))) return false
400
+ await fsp.writeFile(cancelFile(runId), `${JSON.stringify({ requestedAt: new Date().toISOString(), pid: process.pid })}\n`, 'utf8')
401
+ return true
402
+ },
403
+
404
+ /**
405
+ * @param {string} runId - run identity.
406
+ * @returns {Promise<boolean>} true when a cancel was requested by any process.
407
+ */
408
+ async hasCancelRequest(runId) {
409
+ try {
410
+ await fsp.access(cancelFile(runId))
411
+ return true
412
+ } catch {
413
+ return false
414
+ }
415
+ },
416
+
417
+ /**
418
+ * @param {string} runId - run identity.
419
+ */
420
+ async clearCancel(runId) {
421
+ try {
422
+ await fsp.unlink(cancelFile(runId))
423
+ } catch {
424
+ // Nothing to clear.
425
+ }
426
+ },
427
+
428
+ cancelFile,
429
+
430
+ /**
431
+ * Claim the right to schedule one run. The lock is created with `wx`, so
432
+ * exactly one process wins even when two profiles point at the same state
433
+ * directory; the loser gets the holder instead of a second copy of the run.
434
+ * @param {string} runId - run identity.
435
+ * @param {{ pid: number, hostname: string, at: string }} holder - claimant.
436
+ * @returns {Promise<{ acquired: boolean, holder: object | null }>}
437
+ */
438
+ async acquireLock(runId, holder) {
439
+ if (!RUN_ID_PATTERN.test(String(runId))) return { acquired: false, holder: null }
440
+ try {
441
+ await fsp.writeFile(lockFile(runId), `${JSON.stringify(holder)}\n`, { encoding: 'utf8', flag: 'wx' })
442
+ return { acquired: true, holder }
443
+ } catch (error) {
444
+ if (error?.code !== 'EEXIST') throw error
445
+ return { acquired: false, holder: await this.readLock(runId) }
446
+ }
447
+ },
448
+
449
+ /**
450
+ * @param {string} runId - run identity.
451
+ * @returns {Promise<object | null>} recorded holder, or null.
452
+ */
453
+ async readLock(runId) {
454
+ if (!RUN_ID_PATTERN.test(String(runId))) return null
455
+ try {
456
+ const parsed = JSON.parse(await fsp.readFile(lockFile(runId), 'utf8'))
457
+ return parsed && typeof parsed === 'object' ? parsed : null
458
+ } catch {
459
+ return null
460
+ }
461
+ },
462
+
463
+ /**
464
+ * @param {string} runId - run identity.
465
+ */
466
+ async releaseLock(runId) {
467
+ try {
468
+ await fsp.unlink(lockFile(runId))
469
+ } catch {
470
+ // Nothing to release.
471
+ }
472
+ },
473
+
474
+ /**
475
+ * Machine identity of the state directory, written once by the first
476
+ * process that mounts it. Its presence tells later processes whether a pid
477
+ * in a run file belongs to this machine (local) or possibly to another one
478
+ * sharing the directory, where the pid is meaningless.
479
+ * @returns {Promise<{ hostname?: string, createdAt?: string } | null>}
480
+ */
481
+ async readOwner() {
482
+ try {
483
+ const parsed = JSON.parse(await fsp.readFile(ownerFile, 'utf8'))
484
+ return parsed && typeof parsed === 'object' ? parsed : null
485
+ } catch {
486
+ return null
487
+ }
488
+ },
489
+
490
+ /**
491
+ * @param {{ hostname: string, createdAt?: string }} owner - identity to record.
492
+ */
493
+ async writeOwner(owner) {
494
+ try {
495
+ await fsp.writeFile(ownerFile, `${JSON.stringify(owner, null, 2)}\n`, 'utf8')
496
+ } catch (error) {
497
+ warn(`cannot record the state directory owner in ${ownerFile}: ${error?.message ?? error}`)
498
+ }
499
+ },
500
+
501
+ /**
502
+ * Decide which runs a prune would remove, without touching anything.
503
+ *
504
+ * A run qualifies only when it is terminal, inside the age window, inside
505
+ * the optional status filter, and not claimed by a lock file. Active runs
506
+ * are never candidates, so the plan is safe to show before deleting.
507
+ *
508
+ * @param {{ olderThanDays?: number, statuses?: string[] | string }} [options] - window and filter.
509
+ * @returns {Promise<{
510
+ * candidates: { id: string, status: string, goal: string, finishedAt: string, bytes: number, files: { kind: string, path: string, bytes: number }[] }[],
511
+ * skipped: { id: string, status: string, reason: string }[],
512
+ * removed: string[], dryRun: boolean, bytes: number, files: number,
513
+ * }>} the plan; `removed` is always empty here.
514
+ */
515
+ async planPrune(options = {}) {
516
+ const days = Number(options.olderThanDays)
517
+ if (!Number.isFinite(days) || days <= 0) {
518
+ throw new Error('olderThanDays must be a positive number of days')
519
+ }
520
+ const wanted = normalizeStatuses(options.statuses)
521
+ const cutoff = Date.now() - days * 86400000
522
+ const candidates = []
523
+ const skipped = []
524
+ for (const run of await this.list()) {
525
+ if (!TERMINAL_STATUSES.has(run.status)) continue
526
+ if (wanted && !wanted.has(run.status)) continue
527
+ const finished = Date.parse(run.finishedAt ?? run.updatedAt ?? run.createdAt)
528
+ if (!Number.isFinite(finished) || finished > cutoff) continue
529
+ if (await isHeld(run.id)) {
530
+ skipped.push({ id: run.id, status: String(run.status), reason: 'held by another process' })
531
+ continue
532
+ }
533
+ const files = []
534
+ for (const [kind, file] of [['run', runFile(run.id)], ['cancel', cancelFile(run.id)], ['report', reportFile(run.id)]]) {
535
+ const bytes = await sizeOf(file)
536
+ if (bytes !== null) files.push({ kind, path: file, bytes })
537
+ }
538
+ candidates.push({
539
+ id: run.id,
540
+ status: String(run.status),
541
+ goal: String(run.goal ?? ''),
542
+ finishedAt: new Date(finished).toISOString(),
543
+ bytes: files.reduce((sum, file) => sum + file.bytes, 0),
544
+ files,
545
+ })
546
+ }
547
+ return {
548
+ candidates,
549
+ skipped,
550
+ removed: [],
551
+ dryRun: true,
552
+ bytes: candidates.reduce((sum, candidate) => sum + candidate.bytes, 0),
553
+ files: candidates.reduce((sum, candidate) => sum + candidate.files.length, 0),
554
+ }
555
+ },
556
+
557
+ /**
558
+ * Delete terminal runs older than `olderThanDays`, so an install that runs
559
+ * for months does not accumulate state forever.
560
+ *
561
+ * The CLI prune defaults to `dryRun: true`; the mount-time `keepRuns` call
562
+ * passes `dryRun: false` because the operator already opted in through the
563
+ * config. A locked or live run is never deleted.
564
+ *
565
+ * @param {{ olderThanDays: number, statuses?: string[] | string, dryRun?: boolean }} options - window, filter, and mode.
566
+ * @returns {Promise<object>} the plan plus `removed`, `failed`, and `deletedBytes`.
567
+ */
568
+ async prune({ olderThanDays, statuses, dryRun = false } = {}) {
569
+ const days = Number(olderThanDays)
570
+ if (!Number.isFinite(days) || days <= 0) {
571
+ return { candidates: [], skipped: [], removed: [], failed: [], dryRun, bytes: 0, deletedBytes: 0, files: 0 }
572
+ }
573
+ const plan = await this.planPrune({ olderThanDays: days, statuses })
574
+ if (dryRun) return { ...plan, failed: [], deletedBytes: 0 }
575
+ const removed = []
576
+ const failed = []
577
+ let deletedBytes = 0
578
+ for (const candidate of plan.candidates) {
579
+ try {
580
+ // Auxiliary files first: a failure then leaves the run record that
581
+ // names what could not be cleaned up, instead of an orphan report.
582
+ for (const file of candidate.files) {
583
+ if (file.kind === 'run') continue
584
+ await fsp.unlink(file.path).catch(error => {
585
+ if (error?.code !== 'ENOENT') throw error
586
+ })
587
+ }
588
+ await fsp.unlink(runFile(candidate.id)).catch(error => {
589
+ if (error?.code !== 'ENOENT') throw error
590
+ })
591
+ removed.push(candidate.id)
592
+ deletedBytes += candidate.bytes
593
+ } catch (error) {
594
+ failed.push({ id: candidate.id, error: String(error?.message ?? error) })
595
+ warn(`cannot prune run ${candidate.id}: ${error?.message ?? error}`)
596
+ }
597
+ }
598
+ return { ...plan, dryRun: false, removed, failed, deletedBytes }
599
+ },
600
+
601
+ /**
602
+ * Build the portable form of one run: metadata, the full record, the final
603
+ * report, structured subtask results, guard records, and usage/cost.
604
+ * @param {string} runId - run identity.
605
+ * @param {{ exportedAt?: string }} [options] - timestamp override for tests.
606
+ * @returns {Promise<object>} the archive payload.
607
+ * @throws when the run does not exist.
608
+ */
609
+ async buildArchive(runId, options = {}) {
610
+ const run = await this.read(runId)
611
+ if (!run) throw new Error(`no run ${runId} in ${this.root}`)
612
+ const report = await reportTextOf(run)
613
+ const subtasks = (Array.isArray(run.subtasks) ? run.subtasks : []).map(subtask => ({
614
+ index: subtask.index ?? null,
615
+ title: subtask.title ?? '',
616
+ status: subtask.status ?? 'unknown',
617
+ prompt: subtask.prompt ?? '',
618
+ result: subtask.result ?? null,
619
+ error: subtask.error ?? null,
620
+ attempts: subtask.attempts ?? 0,
621
+ childId: subtask.childId ?? null,
622
+ startedAt: subtask.startedAt ?? null,
623
+ finishedAt: subtask.finishedAt ?? null,
624
+ usage: subtask.usage ?? null,
625
+ }))
626
+ return {
627
+ format: ARCHIVE_FORMAT,
628
+ formatVersion: ARCHIVE_FORMAT_VERSION,
629
+ exportedAt: options.exportedAt ?? new Date().toISOString(),
630
+ generator: 'dsh-superagent',
631
+ runId: run.id,
632
+ goal: String(run.goal ?? ''),
633
+ status: String(run.status ?? 'unknown'),
634
+ createdAt: run.createdAt ?? null,
635
+ finishedAt: run.finishedAt ?? null,
636
+ usage: run.usage ?? null,
637
+ cost: run.cost ?? null,
638
+ guards: {
639
+ at: run.attention?.at ?? null,
640
+ issue: run.attention?.issue ?? null,
641
+ items: Array.isArray(run.attention?.items) ? run.attention.items : [],
642
+ },
643
+ report,
644
+ subtasks,
645
+ run,
646
+ }
647
+ },
648
+
649
+ /**
650
+ * Write one run as a self-contained archive.
651
+ *
652
+ * `dir` writes a readable directory (README, markdown report, per-subtask
653
+ * pages, guard and usage files, manifest with checksums). `bundle` writes a
654
+ * single JSON file, and `html` writes one self-contained page with the same
655
+ * bundle embedded so it can be read and imported offline.
656
+ *
657
+ * @param {string} runId - run identity.
658
+ * @param {string} target - directory for `dir`, file path otherwise.
659
+ * @param {{ format?: 'dir' | 'bundle' | 'html', exportedAt?: string }} [options] - layout.
660
+ * @returns {Promise<{ runId: string, format: string, out: string, bytes: number, files: { path: string, bytes: number }[] }>}
661
+ */
662
+ async exportRun(runId, target, options = {}) {
663
+ const format = options.format ?? 'dir'
664
+ if (!['dir', 'bundle', 'html'].includes(format)) {
665
+ throw new Error(`unknown archive format ${JSON.stringify(format)}; use dir, bundle, or html`)
666
+ }
667
+ const archive = await this.buildArchive(runId, options)
668
+ const out = path.resolve(String(target))
669
+
670
+ if (format === 'dir') {
671
+ // A stale file from a previous export must not be mistaken for part of
672
+ // this archive, and an unrelated directory must not be written into.
673
+ const existing = await fsp.readdir(out).catch(() => null)
674
+ if (existing && existing.length > 0) {
675
+ throw new Error(`refusing to overwrite ${out}: it already exists and is not empty; choose another --out`)
676
+ }
677
+ await fsp.mkdir(out, { recursive: true })
678
+ const files = []
679
+ const put = async (relative, body) => {
680
+ const buffer = Buffer.isBuffer(body) ? body : Buffer.from(String(body), 'utf8')
681
+ const file = path.join(out, relative)
682
+ await fsp.mkdir(path.dirname(file), { recursive: true })
683
+ await fsp.writeFile(file, buffer)
684
+ files.push({ path: relative, bytes: buffer.length, sha256: createHash('sha256').update(buffer).digest('hex') })
685
+ }
686
+ await put('run.json', `${JSON.stringify(archive.run, null, 2)}\n`)
687
+ if (archive.report) await put('report.md', `${archive.report.trimEnd()}\n`)
688
+ for (const subtask of archive.subtasks) {
689
+ const index = String(subtask.index ?? 0).padStart(2, '0')
690
+ const base = `subtasks/${index}-${slugOf(subtask.title, 'subtask')}`
691
+ await put(`${base}.md`, renderSubtaskMarkdown(subtask))
692
+ await put(`${base}.json`, `${JSON.stringify(subtask, null, 2)}\n`)
693
+ }
694
+ await put('guards.json', `${JSON.stringify(archive.guards, null, 2)}\n`)
695
+ await put('guards.md', renderGuardsMarkdown(archive.guards, archive.guards.at))
696
+ await put('usage.json', `${JSON.stringify({
697
+ total: archive.usage,
698
+ byChild: archive.run.usageByChild ?? {},
699
+ cost: archive.cost,
700
+ }, null, 2)}\n`)
701
+ await put('README.md', renderReadme(archive))
702
+ const manifest = {
703
+ format: ARCHIVE_FORMAT,
704
+ formatVersion: ARCHIVE_FORMAT_VERSION,
705
+ exportedAt: archive.exportedAt,
706
+ generator: archive.generator,
707
+ runId: archive.runId,
708
+ goal: archive.goal,
709
+ status: archive.status,
710
+ createdAt: archive.createdAt,
711
+ finishedAt: archive.finishedAt,
712
+ counts: { subtasks: archive.subtasks.length, guards: archive.guards.items.length },
713
+ totals: { files: files.length, bytes: files.reduce((sum, file) => sum + file.bytes, 0) },
714
+ files,
715
+ }
716
+ const body = `${JSON.stringify(manifest, null, 2)}\n`
717
+ await fsp.writeFile(path.join(out, 'manifest.json'), body, 'utf8')
718
+ const all = [...files, { path: 'manifest.json', bytes: Buffer.byteLength(body) }]
719
+ return { runId: archive.runId, format, out, bytes: all.reduce((sum, file) => sum + file.bytes, 0), files: all }
720
+ }
721
+
722
+ await fsp.mkdir(path.dirname(out), { recursive: true })
723
+ let body
724
+ if (format === 'bundle') {
725
+ body = `${JSON.stringify(archive, null, 2)}\n`
726
+ } else {
727
+ // Dynamic import keeps store.js independent of the renderer at load
728
+ // time; report.js already imports this module.
729
+ const { buildReport } = await import('./report.js')
730
+ const html = buildReport([archive.run], {
731
+ title: `Superagent run ${archive.runId}`,
732
+ generatedAt: Date.now(),
733
+ })
734
+ // `<` is escaped so a report containing "</script>" cannot end the tag.
735
+ const payload = JSON.stringify(archive).replace(/</g, '\\u003c')
736
+ body = html.replace(
737
+ '</body>',
738
+ `<script type="application/json" id="superagent-archive">${payload}</script>\n</body>`,
739
+ )
740
+ }
741
+ await fsp.writeFile(out, body, 'utf8')
742
+ const bytes = Buffer.byteLength(body, 'utf8')
743
+ return { runId: archive.runId, format, out, bytes, files: [{ path: path.basename(out), bytes }] }
744
+ },
745
+
746
+ /**
747
+ * Read an archive back into this store for review.
748
+ *
749
+ * Import never overwrites: a local run with the same id makes this throw
750
+ * before anything is written. The run record is restored byte-for-byte, so
751
+ * an export → import round trip can be compared with deep equality.
752
+ *
753
+ * @param {string} source - archive directory, bundle JSON, or html file.
754
+ * @returns {Promise<{ run: object, out: string, source: string, format: string }>}
755
+ * @throws when the archive is unreadable, incomplete, or collides locally.
756
+ */
757
+ async importRun(source) {
758
+ const origin = path.resolve(String(source))
759
+ const stat = await fsp.stat(origin).catch(error => {
760
+ throw new Error(`cannot read archive ${origin}: ${error?.message ?? error}`)
761
+ })
762
+ let archive
763
+ let format
764
+ if (stat.isDirectory()) {
765
+ format = 'dir'
766
+ const manifest = JSON.parse(await fsp.readFile(path.join(origin, 'manifest.json'), 'utf8').catch(error => {
767
+ throw new Error(`archive directory ${origin} has no readable manifest.json: ${error?.message ?? error}`)
768
+ }))
769
+ if (manifest?.format !== ARCHIVE_FORMAT) {
770
+ throw new Error(`${path.join(origin, 'manifest.json')} is not a ${ARCHIVE_FORMAT} archive`)
771
+ }
772
+ if (manifest.formatVersion !== ARCHIVE_FORMAT_VERSION) {
773
+ throw new Error(`archive format version ${manifest.formatVersion} is not supported (expected ${ARCHIVE_FORMAT_VERSION})`)
774
+ }
775
+ const run = JSON.parse(await fsp.readFile(path.join(origin, 'run.json'), 'utf8').catch(error => {
776
+ throw new Error(`archive ${origin} has no readable run.json: ${error?.message ?? error}`)
777
+ }))
778
+ // Verify the parts the manifest records, so a truncated copy is caught
779
+ // instead of silently imported as a different run.
780
+ for (const entry of Array.isArray(manifest.files) ? manifest.files : []) {
781
+ const buffer = await fsp.readFile(path.join(origin, entry.path)).catch(() => null)
782
+ if (!buffer) throw new Error(`archive ${origin} is missing ${entry.path}`)
783
+ if (typeof entry.sha256 === 'string') {
784
+ const digest = createHash('sha256').update(buffer).digest('hex')
785
+ if (digest !== entry.sha256) throw new Error(`archive file ${entry.path} does not match its manifest checksum`)
786
+ }
787
+ }
788
+ let report = null
789
+ try {
790
+ report = (await fsp.readFile(path.join(origin, 'report.md'), 'utf8')).trim() || null
791
+ } catch {
792
+ report = null
793
+ }
794
+ archive = { ...manifest, run, report }
795
+ } else {
796
+ const text = await fsp.readFile(origin, 'utf8')
797
+ if (/\.html?$/i.test(origin)) {
798
+ format = 'html'
799
+ const match = text.match(EMBEDDED_ARCHIVE)
800
+ if (!match) throw new Error(`${origin} has no embedded ${ARCHIVE_FORMAT} payload`)
801
+ archive = JSON.parse(match[1])
802
+ } else {
803
+ format = 'bundle'
804
+ try {
805
+ archive = JSON.parse(text)
806
+ } catch (error) {
807
+ throw new Error(`${origin} is not valid JSON: ${error?.message ?? error}`)
808
+ }
809
+ }
810
+ if (archive?.format !== ARCHIVE_FORMAT) throw new Error(`${origin} is not a ${ARCHIVE_FORMAT} archive`)
811
+ if (archive.formatVersion !== ARCHIVE_FORMAT_VERSION) {
812
+ throw new Error(`archive format version ${archive.formatVersion} is not supported (expected ${ARCHIVE_FORMAT_VERSION})`)
813
+ }
814
+ }
815
+
816
+ const run = archive.run
817
+ if (!run || typeof run !== 'object') throw new Error(`archive ${origin} carries no run record`)
818
+ const id = String(run.id ?? '')
819
+ if (!RUN_ID_PATTERN.test(id)) throw new Error(`archive ${origin} has no usable run id (got ${JSON.stringify(run.id)})`)
820
+ if (archive.runId && archive.runId !== id) {
821
+ throw new Error(`archive ${origin} names run ${archive.runId} but run.json is ${id}`)
822
+ }
823
+ if (await sizeOf(runFile(id)) !== null) {
824
+ throw new Error(
825
+ `run ${id} already exists in ${this.root}; import never overwrites — `
826
+ + 'remove it first, or import into another state directory',
827
+ )
828
+ }
829
+ if (typeof archive.report === 'string' && archive.report.trim() && !run.report) {
830
+ run.report = archive.report.trim()
831
+ }
832
+ await this.write(run)
833
+ if (typeof run.report === 'string' && run.report.trim()) {
834
+ // The report is also inside run.json, so a failed artifact write is a
835
+ // warning: the imported record is already complete without it.
836
+ try {
837
+ await fsp.mkdir(path.dirname(reportFile(id)), { recursive: true })
838
+ await fsp.writeFile(reportFile(id), `${run.report.trimEnd()}\n`, 'utf8')
839
+ } catch (error) {
840
+ warn(`imported run ${id} but could not write ${reportFile(id)}: ${error?.message ?? error}`)
841
+ }
842
+ }
843
+ return { run, out: runFile(id), source: origin, format }
844
+ },
845
+
846
+ /**
847
+ * Size of the state directory, for `superagent_list`.
848
+ * @returns {Promise<{ bytes: number, files: number, corrupt: number }>} totals.
849
+ */
850
+ async stats() {
851
+ const totals = { bytes: 0, files: 0, corrupt: 0 }
852
+ let names
853
+ try {
854
+ names = await fsp.readdir(runsDir)
855
+ } catch {
856
+ return totals
857
+ }
858
+ for (const name of names) {
859
+ try {
860
+ const stat = await fsp.stat(path.join(runsDir, name))
861
+ if (!stat.isFile()) continue
862
+ totals.files++
863
+ totals.bytes += stat.size
864
+ if (name.includes('.corrupt-')) totals.corrupt++
865
+ } catch {
866
+ // A file removed mid-scan does not change the answer.
867
+ }
868
+ }
869
+ return totals
870
+ },
871
+ }
872
+ }
873
+