@xiangyixie/dsh-superagent 0.9.3 → 0.11.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.
@@ -0,0 +1,433 @@
1
+ /**
2
+ * Per-worker working-directory isolation for dsh-superagent.
3
+ *
4
+ * Why git worktrees instead of a directory copy: the merge-back step is the
5
+ * hard half of isolation, and git already owns a three-way merge with conflict
6
+ * detection, a durable record of both sides, and one command the user can run
7
+ * to finish by hand. A plain recursive copy would need a diff3 implementation
8
+ * (a dependency) or would silently overwrite the main checkout (the bug this
9
+ * feature exists to fix). A worktree is also cheap: it shares the object
10
+ * database and the ignore rules, so a worker sees the same repository.
11
+ *
12
+ * The one honest limitation: dsh 0.2.2-rc.1 `startActivation` has no `cwd`
13
+ * field, so a child process cannot be *given* a directory by the host. Isolation
14
+ * is therefore enforced in two parts — a prompt contract that names the absolute
15
+ * worktree path and forbids touching anything else, plus a real branch per
16
+ * worker so whatever the worker wrote is captured and merged back with git
17
+ * rather than trusted. A worker that ignores the contract still cannot damage a
18
+ * sibling worker's branch; it would just edit the main checkout, which
19
+ * `git status` on the main directory then shows before any merge happens.
20
+ *
21
+ * Nothing here imports the host: git is spawned directly, so the module is
22
+ * testable against real temporary repositories.
23
+ *
24
+ * @module dsh-superagent/workspace
25
+ */
26
+ import { execFile } from 'node:child_process'
27
+ import fsp from 'node:fs/promises'
28
+ import path from 'node:path'
29
+ import { promisify } from 'node:util'
30
+
31
+ const execFileAsync = promisify(execFile)
32
+
33
+ /** Attempts for a git call that lost a race for one of git's own lock files. */
34
+ const LOCK_ATTEMPTS = 6
35
+ /** First backoff for such a race; each retry doubles it. */
36
+ const LOCK_BACKOFF_MS = 120
37
+
38
+ /**
39
+ * Environment for every git call: never prompt (a worker's terminal is not
40
+ * attached), never page, and keep output parseable.
41
+ */
42
+ function gitEnv() {
43
+ return {
44
+ ...process.env,
45
+ GIT_TERMINAL_PROMPT: '0',
46
+ GIT_PAGER: 'cat',
47
+ GIT_OPTIONAL_LOCKS: '0',
48
+ }
49
+ }
50
+
51
+ /**
52
+ * Run one git command.
53
+ *
54
+ * A missing binary and a failing command are different problems — the first
55
+ * disables isolation, the second is a repository state the user must see — so
56
+ * the missing-binary case gets its own error code instead of a generic string.
57
+ *
58
+ * @param {string} cwd - directory to run in.
59
+ * @param {string[]} args - git arguments.
60
+ * @param {{ exec?: Function }} [options] - command runner, injectable for tests.
61
+ * @returns {Promise<{ ok: boolean, code: number | string, stdout: string, stderr: string }>}
62
+ */
63
+ async function git(cwd, args, { exec = execFileAsync } = {}) {
64
+ try {
65
+ const { stdout, stderr } = await exec('git', args, {
66
+ cwd,
67
+ env: gitEnv(),
68
+ windowsHide: true,
69
+ timeout: 60 * 1000,
70
+ maxBuffer: 8 * 1024 * 1024,
71
+ })
72
+ return { ok: true, code: 0, stdout: String(stdout ?? ''), stderr: String(stderr ?? '') }
73
+ } catch (error) {
74
+ if (typeof error?.code === 'string' && ['ENOENT', 'EACCES'].includes(error.code)) {
75
+ const missing = new Error('git is not available on PATH, so a per-worker worktree cannot be created')
76
+ missing.code = 'git-missing'
77
+ throw missing
78
+ }
79
+ return {
80
+ ok: false,
81
+ code: error?.code ?? 1,
82
+ stdout: String(error?.stdout ?? ''),
83
+ stderr: String(error?.stderr ?? error?.message ?? error),
84
+ }
85
+ }
86
+ }
87
+
88
+ /** First non-empty line of a git error, collapsed for a status line. */
89
+ function firstLine(text) {
90
+ const lines = String(text ?? '').split('\n').map(line => line.trim()).filter(Boolean)
91
+ // git prints progress ("Preparing worktree ...") before the line that says
92
+ // what actually went wrong, so prefer an explicit fatal/error line.
93
+ return lines.find(line => /fatal:|error:/i.test(line)) ?? lines[0] ?? ''
94
+ }
95
+
96
+ /**
97
+ * Compare filesystem paths the way the OS does. git reports worktree paths with
98
+ * forward slashes on Windows, which never equals a native `path.resolve`.
99
+ */
100
+ function samePath(value) {
101
+ const resolved = path.resolve(String(value))
102
+ return process.platform === 'win32' ? resolved.replace(/\\/g, '/').toLowerCase() : resolved
103
+ }
104
+
105
+ /** A quoted path, so a directory with spaces can be pasted into a shell. */
106
+ function quote(value) {
107
+ return `"${String(value).replace(/"/g, '')}"`
108
+ }
109
+
110
+ /** True when a failed git call lost a race for a lock instead of failing. */
111
+ function looksLikeLockRace(result) {
112
+ return /index\.lock|locked|another git process|Unable to create|already exists|cannot lock/i
113
+ .test(`${result.stderr} ${result.stdout}`)
114
+ }
115
+
116
+ /**
117
+ * Build a workspace manager bound to one repository.
118
+ *
119
+ * @param {object} options - manager settings.
120
+ * @param {string} options.root - directory that holds every worker worktree.
121
+ * @param {string} options.baseDir - the main checkout workers are isolated from.
122
+ * @param {string | null} [options.branchPrefix] - branch namespace for workers.
123
+ * @param {(message: string) => void} [options.log] - diagnostics sink.
124
+ * @param {(ms: number) => Promise<void>} [options.sleep] - backoff, injectable.
125
+ * @param {Function} [options.exec] - command runner, injectable for tests.
126
+ */
127
+ export function createWorkspaceManager({
128
+ root,
129
+ baseDir,
130
+ branchPrefix = 'superagent',
131
+ log = () => {},
132
+ sleep = ms => new Promise(resolve => setTimeout(resolve, ms)),
133
+ exec = execFileAsync,
134
+ }) {
135
+ // Two workers starting at the same moment both call `prepare`, and git's
136
+ // own worktree bookkeeping is not safe under concurrent writers. A promise
137
+ // chain costs nothing here (prepare is one fast command) and removes a
138
+ // flake that retries alone would only make rarer.
139
+ let prepareChain = Promise.resolve()
140
+ let probed = null
141
+
142
+ const run = (cwd, args) => git(cwd, args, { exec })
143
+
144
+ /**
145
+ * Decide once whether this directory can host worker worktrees.
146
+ *
147
+ * Only a usable answer is cached: a failure is cheap to re-check, and caching
148
+ * it would keep reporting yesterday's missing repository after the user fixed
149
+ * it in the same host process.
150
+ *
151
+ * @returns {Promise<{ ok: boolean, base: string, baseDir: string, reason: string | null }>}
152
+ */
153
+ async function probe() {
154
+ if (probed) return probed
155
+ const unavailable = reason => ({ ok: false, base: null, baseDir, reason })
156
+ if (typeof baseDir !== 'string' || !baseDir.trim()) {
157
+ return unavailable('no workspace directory is configured (set workspaceRoot to the repository the workers should edit)')
158
+ }
159
+ let inside
160
+ try {
161
+ inside = await run(baseDir, ['rev-parse', '--is-inside-work-tree'])
162
+ } catch (error) {
163
+ return unavailable(error?.message ?? String(error))
164
+ }
165
+ if (!inside.ok || inside.stdout.trim() !== 'true') {
166
+ return unavailable(`${baseDir} is not a git working tree, so a per-worker worktree cannot be created`)
167
+ }
168
+ const toplevel = await run(baseDir, ['rev-parse', '--show-toplevel'])
169
+ if (!toplevel.ok) {
170
+ return unavailable(`cannot resolve the repository root of ${baseDir}: ${firstLine(toplevel.stderr)}`)
171
+ }
172
+ const base = toplevel.stdout.trim() || baseDir
173
+ // `worktree add` checks out a commit; a repository with no commit has none.
174
+ const head = await run(base, ['rev-parse', '--verify', 'HEAD'])
175
+ if (!head.ok) {
176
+ return unavailable(`the repository at ${base} has no commit yet, so there is no revision to branch a worker from`)
177
+ }
178
+ try {
179
+ await fsp.mkdir(root, { recursive: true })
180
+ // The state directory may itself live inside a repository. An ignore file
181
+ // here keeps a worker's checkout out of the user's next `git add -A`,
182
+ // exactly like the reports directory does.
183
+ const ignore = path.join(root, '.gitignore')
184
+ await fsp.writeFile(ignore, '*\n', { flag: 'wx' }).catch(error => {
185
+ if (error?.code !== 'EEXIST') throw error
186
+ })
187
+ } catch (error) {
188
+ return unavailable(`cannot create the worktree root ${root}: ${error?.message ?? error}`)
189
+ }
190
+ probed = { ok: true, base, baseDir: base, reason: null }
191
+ return probed
192
+ }
193
+
194
+ /** Paths git already has checked out, so a resume reuses its worktree. */
195
+ async function registeredWorktrees() {
196
+ const listed = await run(baseDir, ['worktree', 'list', '--porcelain'])
197
+ if (!listed.ok) return new Set()
198
+ const paths = new Set()
199
+ for (const line of listed.stdout.split('\n')) {
200
+ if (line.startsWith('worktree ')) paths.add(samePath(line.slice('worktree '.length).trim()))
201
+ }
202
+ return paths
203
+ }
204
+
205
+ /**
206
+ * Create (or reuse) one worker's isolated checkout.
207
+ *
208
+ * @param {{ runId: string, index: number, title?: string }} spec - worker identity.
209
+ * @returns {Promise<{ ok: boolean, dir: string, branch: string, base: string, reused: boolean, reason: string | null }>}
210
+ */
211
+ function prepare({ runId, index }) {
212
+ const task = prepareChain.then(() => prepareNow({ runId, index }))
213
+ prepareChain = task.catch(() => {})
214
+ return task
215
+ }
216
+
217
+ async function prepareNow({ runId, index }) {
218
+ const verdict = await probe()
219
+ if (!verdict.ok) {
220
+ return { ok: false, dir: null, branch: null, base: verdict.baseDir ?? null, reused: false, reason: verdict.reason }
221
+ }
222
+ const dir = path.join(root, runId, `w${index}`)
223
+ const branch = `${branchPrefix}/${runId}-w${index}`
224
+ const existing = await registeredWorktrees()
225
+ if (existing.has(samePath(dir))) {
226
+ // A resumed run must not throw away what an earlier attempt wrote.
227
+ return { ok: true, dir, branch, base: verdict.base, reused: true, reason: null }
228
+ }
229
+ let last = null
230
+ for (let attempt = 1; attempt <= LOCK_ATTEMPTS; attempt++) {
231
+ const added = await run(verdict.base, ['worktree', 'add', '-b', branch, dir, 'HEAD'])
232
+ if (added.ok) {
233
+ return { ok: true, dir, branch, base: verdict.base, reused: false, reason: null }
234
+ }
235
+ last = added
236
+ if (!looksLikeLockRace(added) || attempt === LOCK_ATTEMPTS) break
237
+ log(`worktree add for subtask ${index} lost a git lock race (attempt ${attempt}); retrying`)
238
+ await sleep(LOCK_BACKOFF_MS * attempt)
239
+ }
240
+ const branchExists = await run(verdict.base, ['rev-parse', '--verify', '--quiet', `refs/heads/${branch}`])
241
+ if (branchExists.ok && /already exists/.test(last?.stderr ?? '')) {
242
+ // The branch survived an earlier run but its directory is gone: re-attach
243
+ // it instead of refusing to isolate this worker at all.
244
+ const attached = await run(verdict.base, ['worktree', 'add', dir, branch])
245
+ if (attached.ok) {
246
+ return { ok: true, dir, branch, base: verdict.base, reused: true, reason: null }
247
+ }
248
+ last = attached
249
+ }
250
+ return {
251
+ ok: false,
252
+ dir,
253
+ branch,
254
+ base: verdict.base,
255
+ reused: false,
256
+ reason: `cannot create a worktree for worker ${index}: ${firstLine(last?.stderr) || 'git worktree add failed'}`,
257
+ }
258
+ }
259
+
260
+ /**
261
+ * Commit what a worker left in its checkout so the branch holds the work.
262
+ *
263
+ * Workers are not asked to commit: a model that forgets would otherwise lose
264
+ * its work. Hooks are skipped so a repository's pre-commit hook cannot block
265
+ * the merge-back (or rewrite files behind the worker's back).
266
+ *
267
+ * @param {{ dir: string, branch: string, index: number, title?: string }} spec - worker workspace.
268
+ * @returns {Promise<{ status: 'committed'|'no-changes'|'failed', files: string[], commit: string | null, detail: string | null }>}
269
+ */
270
+ async function harvest({ dir, branch, index, title = '' }) {
271
+ const status = await run(dir, ['status', '--porcelain'])
272
+ if (!status.ok) {
273
+ return { status: 'failed', files: [], commit: null, detail: `cannot read the worker checkout: ${firstLine(status.stderr)}` }
274
+ }
275
+ const changed = status.stdout.split('\n').map(line => line.slice(3).trim()).filter(Boolean)
276
+ if (changed.length === 0) return { status: 'no-changes', files: [], commit: null, detail: null }
277
+ const staged = await run(dir, ['add', '-A'])
278
+ if (!staged.ok) {
279
+ return { status: 'failed', files: changed, commit: null, detail: `cannot stage the worker changes: ${firstLine(staged.stderr)}` }
280
+ }
281
+ const message = `superagent: worker ${index}${title ? ` — ${title}` : ''}`
282
+ const committed = await run(dir, [
283
+ '-c', 'user.name=dsh-superagent',
284
+ '-c', 'user.email=superagent@localhost',
285
+ 'commit', '--no-verify', '-m', message,
286
+ ])
287
+ if (!committed.ok) {
288
+ return { status: 'failed', files: changed, commit: null, detail: `cannot commit the worker changes: ${firstLine(committed.stderr)}` }
289
+ }
290
+ const sha = await run(dir, ['rev-parse', '--short', 'HEAD'])
291
+ return { status: 'committed', files: changed, commit: sha.ok ? sha.stdout.trim() : null, detail: null }
292
+ }
293
+
294
+ /** Remove one worker checkout and, when its branch is already merged, the branch. */
295
+ async function release({ dir, branch }) {
296
+ await run(baseDir, ['worktree', 'remove', '--force', dir])
297
+ if (branch) await run(baseDir, ['branch', '-d', branch])
298
+ }
299
+
300
+ /**
301
+ * Merge every harvested worker branch into the main checkout, one at a time.
302
+ *
303
+ * A conflict is never resolved by the plugin and never discarded: the merge is
304
+ * aborted (so the main checkout is exactly as it was), the file list is
305
+ * recorded, and the worker's branch and checkout are kept so the user can run
306
+ * the printed `git merge` themselves. That is the difference between a visible
307
+ * conflict and a lost subtask.
308
+ *
309
+ * @param {Array<{ index: number, title?: string, dir: string, branch: string }>} workers - ready branches.
310
+ * @returns {Promise<Array<object>>} one outcome per worker.
311
+ */
312
+ async function mergeAll(workers) {
313
+ const outcomes = []
314
+ if (workers.length === 0) return outcomes
315
+ const verdict = await probe()
316
+ if (!verdict.ok) {
317
+ return workers.map(worker => ({
318
+ index: worker.index,
319
+ branch: worker.branch,
320
+ dir: worker.dir,
321
+ status: 'unavailable',
322
+ files: [],
323
+ detail: verdict.reason,
324
+ }))
325
+ }
326
+ const dirty = await run(verdict.base, ['status', '--porcelain'])
327
+ if (!dirty.ok) {
328
+ return workers.map(worker => ({
329
+ index: worker.index,
330
+ branch: worker.branch,
331
+ dir: worker.dir,
332
+ status: 'skipped',
333
+ files: [],
334
+ detail: `cannot read the main checkout: ${firstLine(dirty.stderr)}`,
335
+ }))
336
+ }
337
+ if (dirty.stdout.trim()) {
338
+ // Merging into a checkout with uncommitted work would mix the user's edits
339
+ // with the workers' and make an abort restore the wrong state, so leave
340
+ // both sides untouched and say what to do.
341
+ const detail = 'the main working directory has uncommitted changes, so its state is left exactly as it was; '
342
+ + 'commit or stash them, then merge the kept branch'
343
+ return workers.map(worker => ({
344
+ index: worker.index,
345
+ branch: worker.branch,
346
+ dir: worker.dir,
347
+ status: 'skipped',
348
+ files: [],
349
+ detail,
350
+ }))
351
+ }
352
+
353
+ for (const worker of workers) {
354
+ const merged = await run(verdict.base, [
355
+ // The merge commit needs an identity; a host that never configured git
356
+ // user.name must not turn a clean merge into a failure.
357
+ '-c', 'user.name=dsh-superagent',
358
+ '-c', 'user.email=superagent@localhost',
359
+ 'merge', '--no-ff', '--no-edit', '-m', `superagent: merge worker ${worker.index}`, worker.branch,
360
+ ])
361
+ if (merged.ok) {
362
+ await release(worker)
363
+ outcomes.push({ index: worker.index, branch: worker.branch, dir: null, status: 'merged', files: [], detail: null })
364
+ continue
365
+ }
366
+ const conflicted = await run(verdict.base, ['diff', '--name-only', '--diff-filter=U'])
367
+ const files = conflicted.stdout.split('\n').map(line => line.trim()).filter(Boolean)
368
+ const aborted = await run(verdict.base, ['merge', '--abort'])
369
+ if (!aborted.ok) {
370
+ log(`cannot abort the failed merge of ${worker.branch}: ${firstLine(aborted.stderr)}`)
371
+ }
372
+ outcomes.push({
373
+ index: worker.index,
374
+ branch: worker.branch,
375
+ dir: worker.dir,
376
+ status: files.length > 0 ? 'conflict' : 'failed',
377
+ files,
378
+ detail: files.length > 0
379
+ ? `the change conflicts with work already in ${verdict.base}; the main checkout was restored and the branch kept`
380
+ : firstLine(merged.stderr) || 'git merge failed',
381
+ })
382
+ }
383
+ return outcomes
384
+ }
385
+
386
+ return { probe, prepare, harvest, mergeAll, release, root, baseDir }
387
+ }
388
+
389
+ /**
390
+ * Render the workspace section of a run for `superagent_status` and the
391
+ * notification. Kept here, next to the outcomes it describes, so the wording
392
+ * cannot drift from what mergeAll actually recorded.
393
+ *
394
+ * @param {object | null} workspace - `run.workspace`.
395
+ * @returns {string[]} zero or more lines.
396
+ */
397
+ export function describeWorkspace(workspace) {
398
+ if (!workspace || typeof workspace !== 'object') return []
399
+ if (workspace.mode === 'unavailable') {
400
+ return [
401
+ `workspace: isolation was requested but is unavailable — ${workspace.reason}; `
402
+ + `workers shared ${workspace.base ?? 'the main directory'}, so their edits can overwrite each other`,
403
+ ]
404
+ }
405
+ if (workspace.mode !== 'git-worktree') return []
406
+ const merges = Array.isArray(workspace.merges) ? workspace.merges : []
407
+ const lines = [
408
+ `workspace: each worker ran in its own git worktree under ${workspace.root ?? workspace.base} `
409
+ + `(main checkout ${workspace.base})`,
410
+ ]
411
+ if (workspace.deferred) {
412
+ lines.push(`workspace: not merged — ${workspace.deferred}`)
413
+ }
414
+ for (const failure of Array.isArray(workspace.failures) ? workspace.failures : []) {
415
+ lines.push(`workspace: [${failure.index}] could not get its own checkout — ${failure.reason}; it ran in the shared directory`)
416
+ }
417
+ for (const merge of merges) {
418
+ if (merge.status === 'merged') {
419
+ lines.push(`workspace: [${merge.index}] merged back (${merge.branch})`)
420
+ } else if (merge.status === 'no-changes') {
421
+ lines.push(`workspace: [${merge.index}] changed no files`)
422
+ } else if (merge.status === 'conflict') {
423
+ lines.push(
424
+ `workspace conflict: [${merge.index}] ${merge.files?.join(', ') || 'unmerged files'} — `
425
+ + `branch ${merge.branch} kept at ${merge.dir}; the main checkout was restored, so nothing was lost. `
426
+ + `Resolve with: git -C ${quote(workspace.base)} merge ${merge.branch}`,
427
+ )
428
+ } else {
429
+ lines.push(`workspace: [${merge.index}] not merged (${merge.status}) — ${merge.detail ?? 'no detail'}${merge.branch ? `; branch ${merge.branch} kept` : ''}`)
430
+ }
431
+ }
432
+ return lines
433
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@xiangyixie/dsh-superagent",
3
- "version": "0.9.3",
3
+ "version": "0.11.0",
4
4
  "description": "Long-horizon autonomous runs for DeepSeek Harness: one goal, model-planned parallel subtasks, one merged report, durable across restarts.",
5
5
  "author": "Admire (LittleChenLiya)",
6
6
  "type": "module",
@@ -15,7 +15,9 @@
15
15
  "main": "lib/index.js",
16
16
  "bin": {
17
17
  "dsh-superagent-watch": "bin/watch.js",
18
- "dsh-superagent-report": "bin/report.js"
18
+ "dsh-superagent-report": "bin/report.js",
19
+ "dsh-superagent-doctor": "bin/doctor.js",
20
+ "dsh-superagent-archive": "bin/archive.js"
19
21
  },
20
22
  "exports": {
21
23
  ".": "./lib/index.js",
@@ -32,11 +34,21 @@
32
34
  "lib/store.js",
33
35
  "lib/errors.js",
34
36
  "lib/usage.js",
37
+ "lib/cost.js",
38
+ "lib/ledger.js",
35
39
  "lib/control.js",
40
+ "lib/memory.js",
41
+ "lib/notify.js",
42
+ "lib/lock.js",
43
+ "lib/templates.js",
36
44
  "lib/watch.js",
37
45
  "lib/report.js",
46
+ "lib/workspace.js",
47
+ "lib/doctor.js",
38
48
  "bin/watch.js",
39
49
  "bin/report.js",
50
+ "bin/doctor.js",
51
+ "bin/archive.js",
40
52
  "cordis.patch.yml",
41
53
  "CHANGELOG.md",
42
54
  "README.md"
@@ -47,7 +59,8 @@
47
59
  "dsh": ">=0.2.2-rc.1 <0.3.0-0"
48
60
  },
49
61
  "scripts": {
50
- "test": "node --test test/orchestrator.test.mjs test/store.test.mjs test/errors.test.mjs test/plugin.test.mjs test/usage.test.mjs test/control.test.mjs test/watch.test.mjs test/report.test.mjs"
62
+ "test": "node --test test/orchestrator.test.mjs test/direct-and-queue.test.mjs test/dialog.test.mjs test/workspace.test.mjs test/store.test.mjs test/errors.test.mjs test/plugin.test.mjs test/usage.test.mjs test/cost.test.mjs test/ledger.test.mjs test/control.test.mjs test/watch.test.mjs test/report.test.mjs test/memory.test.mjs test/notify.test.mjs test/templates.test.mjs test/archive.test.mjs test/doctor.test.mjs test/pack.test.mjs",
63
+ "check-pack": "node scripts/check-pack.mjs"
51
64
  },
52
65
  "keywords": [
53
66
  "dsh",