@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.
package/README.md CHANGED
@@ -1,4 +1,4 @@
1
- # dsh-superagent
1
+ # dsh-superagent
2
2
 
3
3
  Long-horizon runs for [DeepSeek Harness](https://dshai.org): one goal in,
4
4
  model-planned parallel subtasks, one merged report — and the run survives a host
@@ -17,14 +17,14 @@ prints the cost once you give it a price for the route.
17
17
  planner and an aggregator on top. It is also the wrong tool for work that must
18
18
  finish inside a single turn, for a step that needs human approval in the middle,
19
19
  for anything that needs nested delegation (child depth is capped at 1), and for
20
- anyone who wants an in-host panel — this adds no UI, only five tools. Children run
20
+ anyone who wants an in-host panel — this adds no UI, only nine tools. Children run
21
21
  with the host's credentials and filesystem; this is not a sandbox.
22
22
 
23
23
  **Install and run.** Node `>= 24.9.0`, a tool-calling route, and that route's key
24
24
  in the environment:
25
25
 
26
26
  ```bash
27
- dsh plugin --profile web add @xiangyixie/dsh-superagent@0.9.3
27
+ dsh plugin --profile web add @xiangyixie/dsh-superagent@0.11.0
28
28
  ```
29
29
 
30
30
  Then ask the session for a run — a real call, not a sketch:
@@ -36,9 +36,9 @@ The reply ends `completed` with the merged report, or with
36
36
  covers the path from an empty machine, including the reason not to install npm's
37
37
  unrelated `dsh` package by name.
38
38
 
39
- It adds no in-host UI and patches no host code: the five `superagent_*` tools are
40
- the surface, plus two optional operator utilities (a terminal panel and an HTML
41
- report) that read the same run files.
39
+ It adds no in-host UI and patches no host code: the nine `superagent_*` tools are
40
+ the surface, plus four optional operator utilities (a terminal panel, an HTML
41
+ report, an install doctor, and a run archive) that read the same run files.
42
42
 
43
43
  Personal project, not affiliated with DeepSeek or the harness maintainers. MIT
44
44
  licensed, © 2026 Admire (LittleChenLiya); details in [License](#license).
@@ -73,7 +73,7 @@ your `PATH`, use `npx @deepseek-ai/dsh@0.2.2-rc.1` instead.
73
73
 
74
74
  ```bash
75
75
  # 1. install the plugin into a profile (web, headless, ... whatever you run)
76
- dsh plugin --profile web add @xiangyixie/dsh-superagent@0.9.3
76
+ dsh plugin --profile web add @xiangyixie/dsh-superagent@0.11.0
77
77
 
78
78
  # 2. confirm the bundle row exists in the merged config
79
79
  dsh --profile web --dump-config
@@ -204,16 +204,32 @@ Row config in `<profile>/cordis.patch.yml`:
204
204
  | `maxSubagentDepth` | `1` | How deep children may delegate. `1` forbids grandchildren; `provider-managed` leaves it to the backend. |
205
205
  | `maxSubtasks` | `8` | Cap on planned subtasks. A tool argument can only lower it, never raise it; hard max 16. |
206
206
  | `maxParallel` | `3` | Subtasks executing at once. A tool argument can only lower it; hard max 8. |
207
- | `maxActiveRuns` | `2` | Active runs per state directory, across profiles and hosts that share it; further `superagent_start` and `superagent_resume` calls are rejected. |
208
- | `attempts` | `2` | Attempts per subtask before it is marked failed. |
207
+ | `maxActiveRuns` | `2` | Active runs per state directory, across profiles and hosts that share it. A further `superagent_start` is rejected unless it passes `queue: true`, in which case it waits for a slot instead. `superagent_resume` is not counted and works when the cap is full, because it only finishes work that already exists. |
208
+ | `maxQueuedRuns` | `5` | Runs allowed to wait for a free slot at once; hard max 32. `0` turns queueing off, so every start over `maxActiveRuns` is rejected again. |
209
+ | `queueTimeoutMinutes` | `30` | How long a queued run waits before it fails without ever starting; nothing is spent. |
210
+ | `queueOnFull` | `false` | Queue every start that exceeds `maxActiveRuns`, not only the ones that pass `queue: true`. |
211
+ | `attempts` | `2` | Attempts per subtask before it is marked failed. A failure that looks transient (quota, rate limit, timeout, 5xx) waits 2s, then 4s, then 8s before the next attempt. |
209
212
  | `deadlineMinutes` | `120` | Wall-clock budget; on expiry the run ends `partial` or `failed`. |
210
213
  | `maxModelCallsPerRun` | `80` | Hard cap on child model calls per run; `0` disables. |
211
214
  | `maxTokensPerRun` | `2000000` | Hard cap on prompt + completion tokens per run; `0` disables. |
212
215
  | `pricing` | empty | Per-1M-token prices, keyed exactly as the usage log names the model (`provider/model`). Nothing is priced out of the box. |
213
216
  | `resultCapBytes` | `32768` | Bytes kept per subtask report. |
214
- | `notifyOnComplete` | `true` | Wake the owning session once when a run finishes while nobody is polling. |
217
+ | `notifyOnComplete` | `true` | Master switch for proactive messages. Off means the plugin never wakes the session. |
218
+ | `maxNotificationsPerHour` | `3` | Proactive messages allowed per hour. Runs above the cap are folded into one summary; `0` disables the cap. |
219
+ | `notifyRetries` | `2` | Extra delivery attempts when the host refuses a wake-up; messages for one session are delivered in order. |
220
+ | `notifyRetryDelayMs` | `2000` | First delay between those attempts; it doubles per attempt, capped at 60s. |
221
+ | `autoResumeRounds` | `1` | Extra rounds that retry subtasks which failed in a way that looks transient, before the failure is reported; `0` disables. |
222
+ | `childModelFallback` | none | Model used on such a retry (quota, rate limit, timeout). Unset keeps the configured route. |
223
+ | `memory` | `true` | Cross-run notebook. See [Cross-run memory](#cross-run-memory). |
224
+ | `memoryScope` | `default` | Notebook file per scope, so unrelated projects can stay apart. Run notes are written here; `rules` and `profile` are read into every run. |
225
+ | `memoryMaxEntries` | `60` | Compaction threshold: a write that would exceed it compacts the notebook down to this many notes (400 lines / 128 KB are hard caps too). |
226
+ | `memoryMaxAgeDays` | `30` | Notes older than this are ignored, then compacted away. |
227
+ | `memoryDigestEntries` | `12` | Notes injected into a prompt. |
228
+ | `memoryDigestChars` | `1600` | Character budget for the note part of that prompt. |
215
229
  | `keepRuns` | `0` | Delete terminal runs older than this many days at mount; `0` keeps everything. |
216
230
  | `controlPort` | off | Loopback port for the embedding surface; `0` picks a free one. See [docs/embedding.md](https://github.com/LittleChenLiya/dsh-superagent/blob/main/docs/embedding.md). |
231
+ | `workspaceIsolation` | `false` | Give every worker its own git worktree so parallel workers cannot overwrite each other. See [Per-worker workspace isolation](#per-worker-workspace-isolation). |
232
+ | `workspaceRoot` | host cwd | Repository the workers are isolated in when `workspaceIsolation` is on. Must be a git working tree with at least one commit. |
217
233
 
218
234
  ### Switching models
219
235
 
@@ -251,8 +267,82 @@ subagent start request has no tool filter, and its own `subagent` tool rejects a
251
267
  `toolFilter` config and points at agent presets. `childPreset` is therefore the
252
268
  supported way to narrow a child's tools; without a dedicated preset, workers
253
269
  inherit the session's tools. The `superagent_*` tools still exist in their tool
254
- list, but `superagent_start`, `superagent_resume`, and `superagent_cancel`
255
- refuse to run from a worker session; only the top-level agent manages runs.
270
+ list, but the run tools (`superagent_start`, `superagent_resume`, `superagent_cancel`,
271
+ `superagent_followup`, `superagent_answer`) refuse to run from a worker session;
272
+ only the top-level agent manages runs.
273
+
274
+ ### Per-worker workspace isolation
275
+
276
+ Parallel workers are independent agents, but by default they share one working
277
+ directory: two subtasks that edit the same file overwrite each other, and the
278
+ last writer wins. `workspaceIsolation` fixes that by giving each worker its own
279
+ checkout.
280
+
281
+ ```yaml
282
+ - id: superagent
283
+ config:
284
+ workspaceIsolation: true
285
+ workspaceRoot: /home/me/projects/api # or C:\work\api on Windows
286
+ ```
287
+
288
+ **Why git worktrees rather than a directory copy.** The hard half of isolation
289
+ is merging the results back. A worktree gives that for free: a real three-way
290
+ merge with conflict detection, both sides preserved as refs, and one command the
291
+ user can run to finish by hand. A recursive copy would either need a diff3
292
+ engine (a dependency this package does not have) or overwrite the main checkout,
293
+ which is the bug the feature exists to prevent. A worktree also shares the object
294
+ database and ignore rules, so a worker sees the real repository without a full
295
+ copy of it. Worktrees live under `<stateDir>/workspaces/<runId>/w<n>`; that
296
+ directory carries its own `.gitignore`, so a state directory inside a repository
297
+ does not leak worker checkouts into the user's next commit.
298
+
299
+ **What happens during a run.** Each worker is given
300
+ `superagent/<runId>-w<n>`, a branch created from the main checkout's `HEAD`. Its
301
+ prompt names the absolute path and forbids touching anything else, switching
302
+ branches, committing, merging, or pushing. When the worker finishes, the run
303
+ commits whatever it left in the checkout (so a model that forgot to commit still
304
+ loses nothing; git hooks are skipped so a pre-commit hook cannot block the merge)
305
+ and then merges the branches into the main checkout **one at a time**, after all
306
+ subtasks are done.
307
+
308
+ **What you see when a merge conflicts.** The merge is aborted, so the main
309
+ checkout is restored exactly as it was and no conflict markers are left in it.
310
+ The outcome is recorded on the run and printed by `superagent_status`:
311
+
312
+ ```
313
+ workspace conflict: [2] src/routes.js, src/index.js — branch superagent/20261115T101500-ab12-w2
314
+ kept at <stateDir>/workspaces/20261115T101500-ab12/w2; the main checkout was restored, so nothing
315
+ was lost. Resolve with: git -C "/home/me/projects/api" merge superagent/20261115T101500-ab12-w2
316
+ ```
317
+
318
+ The wake-up message for the run says the same in one line, because a conflict is
319
+ the one outcome that needs the user even when the run itself "completed". Nothing
320
+ is discarded: the branch and its checkout are kept until you merge or delete
321
+ them. Two more cases are reported the same way rather than silently dropped:
322
+
323
+ - the main checkout has uncommitted changes when the merge is due — every
324
+ branch is left unmerged, since merging into a dirty tree would mix your edits
325
+ with the workers' and make an abort restore the wrong state;
326
+ - the run was cancelled or hit its deadline before merging — the branches are
327
+ kept and a resume reuses the same worktrees.
328
+
329
+ **When isolation is not possible.** If `workspaceRoot` is not a git working tree,
330
+ git is not on `PATH`, or the repository has no commit yet, the run does not fail.
331
+ It falls back to the shared directory (the previous behaviour) and both
332
+ `superagent_status` and the notification say so:
333
+
334
+ ```
335
+ workspace: isolation was requested but is unavailable — /tmp/notes is not a git working tree,
336
+ so a per-worker worktree cannot be created; workers shared /tmp/notes, so their edits can
337
+ overwrite each other
338
+ ```
339
+
340
+ **Limits, stated plainly.** `dsh@0.2.2-rc.1` gives a child agent no `cwd` field,
341
+ so the plugin cannot hand a worker a directory at spawn time. Isolation is a
342
+ prompt contract plus a real branch: a worker that ignores the prompt can still
343
+ edit the main checkout, but that shows up in `git status` before any merge and
344
+ cannot damage a sibling's branch. With isolation off, behaviour is exactly what
345
+ it was before this option existed.
256
346
 
257
347
  ### Spending limits and prices
258
348
 
@@ -304,16 +394,201 @@ cost: at least ¥0.0041 (estimate; no price for haoduo/gpt-6.1-sol)
304
394
 
305
395
  ## Tools
306
396
 
307
- - `superagent_start(goal, max_subtasks?, max_parallel?, deadline_minutes?, wait_seconds?)`
308
- starts a run and returns immediately with a run id. `wait_seconds` blocks for
309
- a terminal state instead.
310
- - `superagent_status(run_id, wait_seconds?)` returns status, per-subtask outcome,
311
- measured token usage, estimated cost, and the final report.
397
+ - `superagent_start(goal, mode?, queue?, max_subtasks?, max_parallel?, deadline_minutes?, allow_duplicate?, wait_seconds?)`
398
+ starts a run and returns immediately with a run id. `mode: "direct"` runs the
399
+ goal on one worker with no planner and no aggregator, and returns that worker's
400
+ reply as the report unchanged — right for one self-contained lookup, edit,
401
+ query, or short piece of writing, wrong for a goal with parts that can run in
402
+ parallel. The default, `mode: "planned"`, does the full planner → workers →
403
+ merged report pipeline. A planned subtask may declare `dependsOn` another
404
+ subtask: the dependent waits for it and gets its report in its prompt, while
405
+ independent subtasks still run in parallel. A dependency cycle rejects the
406
+ plan before any work starts, and a dependency on a task the plan never
407
+ declared is skipped with the reason. Both modes produce the same run record,
408
+ quota, deadline, cancel, and usage accounting.
409
+ `queue: true` makes a start wait for a free slot when `maxActiveRuns` is in use
410
+ instead of failing: it returns `status: "queued"` with `queue.position` /
411
+ `queue.of`, starts automatically when an active run finishes, and fails after
412
+ `queueTimeoutMinutes` if no slot frees. At most `maxQueuedRuns` waits; a queued
413
+ run does not count against `maxActiveRuns` while it waits, and cancelling it
414
+ removes it from the line cleanly. Starting a goal that an
415
+ active run in the same session already covers returns that run id marked
416
+ `deduped: true` instead of paying for a second plan: the goal is compared after
417
+ trimming, collapsing runs of whitespace, and ignoring case, and the check runs
418
+ under a per-goal claim keyed in the state directory, so two processes that share
419
+ it still start one run. The match is per session, because two sessions may
420
+ legitimately ask for the same generic goal at once.
421
+ `allow_duplicate: true` starts another one. A finished run never blocks the same
422
+ goal from being started again. `wait_seconds` blocks for a terminal state and
423
+ keeps the `deduped` marker in its result.
424
+ - `superagent_status(run_id, wait_seconds?)` returns status, milestones,
425
+ per-subtask outcome, measured token usage, estimated cost, the report file
426
+ path, and the final report.
312
427
  - `superagent_list(limit?)` lists runs, newest first, plus the state directory's
313
428
  file count and size.
314
429
  - `superagent_cancel(run_id)` stops the run, from any process; see below.
315
- - `superagent_resume(run_id, wait_seconds?)` continues an `interrupted`, `failed`,
316
- `partial`, or `cancelled` run; completed subtasks are kept.
430
+ - `superagent_resume(run_id, wait_seconds?, force?)` continues an `interrupted`,
431
+ `failed`, `partial`, or `cancelled` run; completed subtasks are kept. Workers
432
+ are told what failed and to check what the earlier attempt already did. Only
433
+ the session that started the run may resume it. A resume is not counted
434
+ against `maxActiveRuns`, so it works when the cap is full; `force` is still
435
+ accepted but no longer needed. A `completed` run stays completed unless it
436
+ holds an answer that never reached a prompt — then resume reopens it, because
437
+ otherwise that decision would be stranded.
438
+ - `superagent_followup(run_id, message)` adds an instruction to a run that is
439
+ already executing, instead of starting a second run. It is **not** a live
440
+ channel to the children: the host has no way to append a message to a running
441
+ child activation, so the instruction is queued on the run and the next prompt
442
+ built for it carries it — the next worker spawn or the aggregation, whichever
443
+ comes first. Subtasks that are already running or finished keep their results
444
+ and never see it. The reply names that boundary, and status shows the same
445
+ thing; an instruction that arrives after the last boundary is recorded as
446
+ `never took effect` rather than looking delivered. A paused run
447
+ (`interrupted`, `failed`, `partial`, `cancelled`) keeps the instruction for
448
+ the next round, which starts when it is resumed; a `completed` run refuses it.
449
+ A run owned by another process is refused, because that owner's next save
450
+ would overwrite it. Only the session that started the run may add to it.
451
+ - `superagent_answer(run_id, attention_id?, answer, wait_seconds?)` answers one
452
+ structured attention item so that run continues with the decision. An active
453
+ run applies the answer at its next boundary; a finished run is reopened and
454
+ only its aggregation runs again, now with the answer in the prompt, so the
455
+ report reflects the decision instead of the user starting a new run.
456
+ `attention_id` is required when more than one question is open. An answer is
457
+ matched to the id, not to the array position: an id that was never asked, a
458
+ question already answered, and a question retired by a later resume are all
459
+ refused, and an answer whose text is another question's option names that
460
+ other id instead of guessing.
461
+ - `superagent_memory(action, key?, kind?, text?, scope?, query?, tags?, limit?)`
462
+ lists, searches, adds, corrects, or forgets notebook notes. `set` with an
463
+ existing key supersedes it; `forget` retracts it. `scope` addresses `rules`
464
+ (project rules), `profile` (user preferences), or the run scope. `search`
465
+ ranks notes against `query` (the current goal works well) and/or exact `tags`,
466
+ so a relevant old note is found instead of only the newest ones; notes can
467
+ carry `tags` when set. The tool is additive: the eight other tools keep their
468
+ arguments and output.
469
+ - `superagent_template(action, id?, params?, template?, limit?)` lists, shows,
470
+ expands, saves, or deletes a workflow template: a fixed goal skeleton with
471
+ required parameters, when it fits, and when it does not. `expand` returns one
472
+ ordinary goal string, which `superagent_start` plans exactly like a typed goal;
473
+ a missing or empty parameter is refused by name instead of defaulted. A
474
+ template cannot set limits, budgets, a mode, or an override, so using one never
475
+ widens what a run may do. Built-in ids are read-only; custom ones live under
476
+ the template directory in the state directory, and a failure there is logged
477
+ without disabling the run tools.
478
+
479
+ ## Progress, decisions, and artifacts
480
+
481
+ - **Milestones.** Every run records `plan_ready`, `running`, `aggregating`, and
482
+ `settled` with a timestamp, shown in `superagent_status`. They never produce a
483
+ proactive message; progress stays visible without becoming noisy.
484
+ - **Attention.** A worker or the aggregator may append one fenced `attention`
485
+ block with a question that only the user can answer. It is stripped from the
486
+ report, stored on the run as `attention.items`, shown as `needs your decision:`
487
+ in status, and leads the notification when the run finishes. Every item gets a
488
+ stable id (`q1`, `q2`, …) from a counter on the run, so a question means the
489
+ same thing across saves and resumes. The question, options, and reason are
490
+ collapsed to one line and capped at 500 / 200 / 300 characters, so the block
491
+ cannot inject a forged status or notification line. A block that is not valid
492
+ JSON or has no question is kept in the report, and status prints
493
+ `attention: <reason>` instead of hiding the request.
494
+ - **Answering.** `superagent_answer` records the decision on that item and lets
495
+ the run continue: an active run carries it into its next prompt, a terminal
496
+ run is reopened so the aggregation runs again with the answer. The question is
497
+ archived (not deleted) when a resume retires it, which is what lets a late
498
+ answer be refused with `expired at <time>` instead of being attached to
499
+ whatever is open now.
500
+ - **Instructions during a run.** `superagent_followup` appends to the same log.
501
+ The dialog is boundary-delivered by design: running children cannot be reached,
502
+ so each instruction records `appliedAt` / `appliedAtStage` when a prompt first
503
+ carries it, or `missedAt` when the run settled first. Status prints both, so
504
+ "delivered" and "waiting" are never confused.
505
+ - **Report file.** A terminal run writes its report to
506
+ `<stateDir>/reports/<runId>.md` with an atomic rename, so the outcome has a
507
+ path that can be opened or attached. The directory carries a `.gitignore` with
508
+ `*`, and the path is recorded in `run.artifacts` and shown in status.
509
+ - **Dependencies between subtasks.** The planner may give a subtask an id and a
510
+ `dependsOn` list; the dependent then waits (`waiting`) instead of starting,
511
+ and its prompt carries the finished dependency's report. Independent subtasks
512
+ still run in parallel. An unknown reference is `skipped` with the reason, a
513
+ failure skips everything downstream rather than reporting it as done, and a
514
+ cycle rejects the plan before any subtask starts. Status and the report show
515
+ waiting separately from running.
516
+
517
+ ## Cross-run memory
518
+
519
+ A run is isolated on purpose: planner and workers start empty. Without a
520
+ notebook, every run repeats work the last one already finished and rediscovers
521
+ the same traps. The plugin keeps two different things, and only one of them is
522
+ stored:
523
+
524
+ 1. **What happened** is derived from the run store at planning time. The six
525
+ most recent runs are rendered as one line each (date, status, completed
526
+ subtasks, goal, run id). Nothing is copied, so it cannot drift from the run
527
+ records.
528
+ 2. **What was learned** is a small curated notebook: decisions, pitfalls, next
529
+ steps, and which work was delegated. The aggregator returns it inside a
530
+ fenced `memory` block that is removed from the report before the user sees it.
531
+ A run that produces no block writes nothing; the plugin never invents a note.
532
+
533
+ **Storage.** `<stateDir>/memory/<scope>.jsonl`, one JSON object per line. A line
534
+ is `{v,id,ts,key,kind,text,runId,status}`; `key` is a short slug (`deploy-target`)
535
+ and `kind` is `decision`, `pitfall`, `next`, `dispatch`, or `note`. The directory
536
+ contains a `.gitignore` with `*`, so even a `stateDir` that points inside a
537
+ repository cannot commit the notebook. It is never listed in the package `files`
538
+ whitelist, so it never ships to npm.
539
+
540
+ **When it is written.** Once per run, at settle, only for a terminal run whose
541
+ report carried a block. A resume that settles the same run again is a no-op
542
+ because the store records the writing run id. A write failure is recorded on the
543
+ run (`memoryWrite.reason`) and never fails the run.
544
+
545
+ **When it is read.** Once at `superagent_start` (and again at `superagent_resume`,
546
+ since the aggregator will run again), before planning. The composed context is
547
+ stored on the run as `memory.digest`, injected into the planner and aggregator
548
+ prompts, and summarised in `superagent_status`.
549
+
550
+ **Layers.** Three scopes are read, in order: `rules` (project rules), `profile`
551
+ (user preferences), then `memoryScope` (what earlier runs learned). The first
552
+ two are curated with `superagent_memory` and are never written by a run, so a
553
+ rule cannot be overwritten by a model's observation. Each layer is labelled in
554
+ the prompt and bounded on its own; `memory.scopes` on the run lists what was
555
+ read.
556
+
557
+ **Size.** Each note is capped at 400 characters after redaction. A prompt sees at
558
+ most `memoryDigestEntries` notes inside `memoryDigestChars` characters, plus six
559
+ one-line run summaries, hard-capped at 2600 characters in total. The file is
560
+ compacted when a write would push it past `memoryMaxEntries` notes, 400 lines,
561
+ or 128 KB; compaction keeps the newest `memoryMaxEntries` notes.
562
+ Context cannot grow with the number of runs.
563
+
564
+ **Concurrency.** Within a process, writes to one scope are serialised. Across
565
+ processes, each batch is appended as one small `write` (no read-modify-write of
566
+ the whole file), compaction takes a lock file and replaces the file from a temp
567
+ file, and a truncated last line from a killed process is skipped. Two runs
568
+ finishing at once cannot overwrite each other's notes; a line may land in a
569
+ different order, and resolution is by timestamp, never by position.
570
+
571
+ **Search.** `superagent_memory` with `action: "search"` ranks notes by `query`
572
+ keywords and exact `tags` instead of returning the newest ones, and the planner
573
+ digest uses the same ranking against the run's goal. A relevant note from weeks
574
+ ago therefore still reaches the prompt when it matches, while unrelated notes do
575
+ not crowd out the budget. Notes can carry `tags` when set.
576
+
577
+ **Correction.** A newer note with the same key supersedes the old one. An
578
+ explicit `forget` writes a tombstone. Notes older than `memoryMaxAgeDays` stop
579
+ being injected and are dropped at the next compaction. Every note is shown with
580
+ its age and the digest tells the model the notes may be stale and must be
581
+ verified, so a wrong conclusion can be refuted by a later run instead of
582
+ becoming a permanent bias.
583
+
584
+ **Privacy.** Notes are written outside the repository by default
585
+ (`$DSH_HOME/state/superagent/memory`). Before storage, the plugin redacts API-key
586
+ shapes (`sk-…`, `Bearer …`, `ghp_…`, `AKIA…`), long hex/base64 blobs, email
587
+ addresses, and absolute home paths; it collapses a note to one line and caps it.
588
+ The aggregator is instructed not to record secrets, customer data, or the report
589
+ itself. A `stateDir` inside the installed package disables memory rather than
590
+ risk shipping it. If you point `stateDir` at a repository, the nested
591
+ `.gitignore` still keeps the files out of a default `git add`.
317
592
 
318
593
  ## Watch and report
319
594
 
@@ -323,8 +598,9 @@ _Top of a report rendered from 40 real host runs. The full page — timeline,
323
598
  swimlanes, call and cost curves, failure annotations, run table — is
324
599
  [docs/report-sample.html](https://github.com/LittleChenLiya/dsh-superagent/blob/main/docs/report-sample.html)._
325
600
 
326
- Two operator utilities ship with the package. They read the same durable run
327
- files as the tools, need no session, and add no runtime dependency.
601
+ Four operator utilities ship with the package, need no session, and add no
602
+ runtime dependency. `watch`, `report`, and `archive` read the same durable run
603
+ files as the tools; `doctor` inspects the install itself.
328
604
 
329
605
  Run them from the installed copy inside the profile:
330
606
 
@@ -335,16 +611,22 @@ node "$PKG/bin/report.js" --out report.html # self-contained HTML page
335
611
  ```
336
612
 
337
613
  If the profile's linker created bin links (npm does), the same commands are
338
- `node_modules/.bin/dsh-superagent-watch` and `node_modules/.bin/dsh-superagent-report`.
614
+ `node_modules/.bin/dsh-superagent-watch`, `node_modules/.bin/dsh-superagent-report`,
615
+ and `node_modules/.bin/dsh-superagent-doctor`.
339
616
 
340
- Both accept `--state-dir <path>`; it defaults to `$DSH_HOME/state/superagent`.
341
- Pass it when the plugin config sets a custom `stateDir`.
617
+ `watch`, `report`, and `archive` all accept `--state-dir <path>`; it defaults to
618
+ `$DSH_HOME/state/superagent`. Pass it when the plugin config sets a custom
619
+ `stateDir`.
342
620
 
343
621
  **`watch`** draws one line per run — id, status, calls used against the cap,
344
622
  elapsed time, what it is doing right now, and the parent session — in the
345
623
  alternate screen, and restores the cursor on Ctrl-C, SIGTERM, or a closed pipe.
346
624
  A status change repaints immediately; an idle panel reads one small file per
347
- second. `--once` prints a single plain frame, which is what
625
+ second. Runs alive at the same moment share a numbered gutter, so parallel work
626
+ is visible as a group instead of unrelated rows. A waiting row leads with the
627
+ run holding its slot, then the queue position, because a narrow cell clips from
628
+ the right and the holder is the actionable part. `--once` prints a single plain
629
+ frame, which is what
348
630
  [docs/e2e/transcripts/watch-panel.log](https://github.com/LittleChenLiya/dsh-superagent/blob/main/docs/e2e/transcripts/watch-panel.log)
349
631
  captures from 40 real runs.
350
632
 
@@ -352,16 +634,42 @@ captures from 40 real runs.
352
634
  no script, no font, no image, no network. It has a timeline with each run's
353
635
  start, end, and derived planning/work/merge phases; a swimlane chart whose lane
354
636
  count is the peak concurrency; cumulative model-call and cost curves; explicit
355
- failure, cancellation, and interruption annotations; and a run table.
637
+ failure, cancellation, and interruption annotations; and a run table. Each
638
+ worker's retry chain and its share of the run's wall clock are listed next to
639
+ its outcome, so an expensive flaky subtask is visible instead of only its final
640
+ failure.
356
641
  [docs/report-sample.html](https://github.com/LittleChenLiya/dsh-superagent/blob/main/docs/report-sample.html)
357
642
  is the 40-run report from the host e2e — open it directly, nothing is fetched —
358
643
  and
359
644
  [docs/e2e/transcripts/report-cli.log](https://github.com/LittleChenLiya/dsh-superagent/blob/main/docs/e2e/transcripts/report-cli.log)
360
645
  records the command plus a zero-external-reference audit.
361
646
 
362
- Neither utility is the install path: the plugin is installed with
647
+ **`doctor`** answers "it installed, why does nothing work?" before the host
648
+ does. It reads only: no install, no mount, no edit to the profile. One block per
649
+ check — imported files against the `files` whitelist, declared files against
650
+ what is on disk, the installed copy against the published tarball for its
651
+ version, the profile's bundle registration, and the nine registered tools — each
652
+ failure followed by the command that fixes it.
653
+
654
+ ```bash
655
+ PKG="${DSH_HOME:-$HOME/.dsh}/profiles/web/node_modules/@xiangyixie/dsh-superagent"
656
+ node "$PKG/bin/doctor.js" --profile web
657
+ node "$PKG/bin/doctor.js" --profile web --offline # skip the registry hash check
658
+ ```
659
+
660
+ Exit code is `0` when no check fails, `1` when one does, so it can gate a
661
+ deploy. `npm test` runs the same pack guard as
662
+ [`scripts/check-pack.mjs`](scripts/check-pack.mjs): every file reachable from
663
+ the entry points must appear in `npm pack --dry-run`, which is the check the
664
+ 0.9.x release lacked.
665
+
666
+ None of these utilities is the install path: the plugin is installed with
363
667
  `dsh plugin add`, never with `npm i -g`.
364
668
 
669
+ **`archive`** is the fourth utility. It prunes terminal runs and exports or
670
+ imports one run as a self-contained archive; see [Retention](#retention) and
671
+ [Archives](#archives).
672
+
365
673
  ## Embedding over local HTTP
366
674
 
367
675
  The tools require a session. If another UI or script must start and watch runs
@@ -399,7 +707,9 @@ only, and there is no remote or unauthenticated mode.
399
707
  One file per run: `$DSH_HOME/state/superagent/runs/<runId>.json`, written with a
400
708
  temp file plus rename, so a kill during a save cannot leave a half-written run.
401
709
  Statuses: `queued`, `planning`, `running`, `aggregating`, `completed`,
402
- `partial`, `failed`, `cancelled`, `interrupted`.
710
+ `partial`, `failed`, `cancelled`, `interrupted`. A run that is waiting for a free
711
+ slot also has `queued` as its status but carries `queue.waiting: true` with its
712
+ position in line; it is not active and does not count against `maxActiveRuns`.
403
713
 
404
714
  At mount the plugin marks a run as `interrupted` **only when it has no live
405
715
  owner** (see below) and resets its in-flight subtasks to `pending`.
@@ -415,8 +725,11 @@ run would make the surviving child keep spending while the file says
415
725
 
416
726
  Resuming is exclusive for the same reason. `superagent_resume` takes the same
417
727
  serial gate as `superagent_start`, claims `<runId>.lock` (created atomically),
418
- and refuses a run that still has a live owner or that would exceed
419
- `maxActiveRuns`.
728
+ refuses a run that still has a live owner, and refuses a caller that is not the
729
+ session in `parentSessionId`. It does not count against `maxActiveRuns`: a
730
+ resume finishes work that already exists, so a full cap never blocks it. `force`
731
+ (tool) or `force` / `override_quota` (HTTP) is still accepted for compatibility
732
+ and changes nothing.
420
733
 
421
734
  Three side files live next to the run:
422
735
 
@@ -425,6 +738,7 @@ Three side files live next to the run:
425
738
  | `<runId>.cancel` | A cancel was requested by some process. The owner polls it once per second and stops its children. Removed when the run ends. |
426
739
  | `<runId>.lock` | The process that is allowed to schedule this run. Created with `wx`, so exactly one process wins. A lock left by a dead local pid is broken immediately; a live local pid keeps it however long it has held it; a lock from another machine is broken once it is older than 10 minutes, since its pid cannot be checked. |
427
740
  | `<runId>.json.corrupt-<ts>` | The state file was not valid JSON and was moved aside, not deleted. The run is skipped by `superagent_list` and reported by id with this path. |
741
+ | `workspaces/<runId>/w<n>/` | A worker's git worktree when `workspaceIsolation` is on. Removed once its branch is merged or it produced no change; kept when a conflict left it for the user to merge. |
428
742
 
429
743
  If a run's file is damaged, nothing else breaks: other runs list normally, and
430
744
  starting a new run works. Inspect the `.corrupt-` file, then delete it. A file
@@ -461,10 +775,31 @@ that were mid-flight become `pending`, so `superagent_resume` continues the run.
461
775
  The heartbeat is refreshed every 30 seconds by the owning process, so a healthy
462
776
  run is never mistaken for an orphan.
463
777
 
464
- ### Notification boundaries
465
-
466
- `notifyOnComplete` writes one message back into the owning session when a run
467
- finishes. Two cases report instead of notifying:
778
+ ### Talking to the user
779
+
780
+ The plugin is quiet unless the user must hear something. This is a rule in code,
781
+ not only in this document:
782
+
783
+ - **Allowed to interrupt:** a run finished and delivered a result, a run failed,
784
+ or a run stopped half-way (`partial`, `interrupted`). A run the user cancelled
785
+ is never announced — the caller already knows.
786
+ - **Never pushed:** progress, subtask start/finish, retries, and memory writes.
787
+ They live in the run record, `superagent_status`, the watch panel, and the
788
+ report page; the user can look, but nothing pops up.
789
+ - **Self-heal first:** each subtask gets `attempts` tries, and a failure that
790
+ looks transient (quota, rate limit, timeout, 5xx) gets `autoResumeRounds`
791
+ more rounds, optionally on `childModelFallback`. Only what still fails is
792
+ reported, and the message says what was tried.
793
+ - **Bounded noise:** at most `maxNotificationsPerHour` proactive messages per
794
+ hour. Runs above the cap are buffered and folded into the next message as one
795
+ summary; `superagent_list` shows how many are waiting. If the message carrying
796
+ a folded batch cannot be delivered, the batch stays buffered and rides the
797
+ next one; it is dropped only after three failed deliveries.
798
+ - **Do not ask what is known:** the planner and aggregator receive the notebook
799
+ and are told to use it instead of asking the user for facts it already holds.
800
+
801
+ `notifyOnComplete` is the master switch. Two cases already report instead of
802
+ notifying:
468
803
 
469
804
  - a caller in the same host process was inside `superagent_status` and receives
470
805
  the terminal report itself (no message, to avoid duplicate noise). A poller in
@@ -483,10 +818,54 @@ live run as orphaned.
483
818
  ### Retention
484
819
 
485
820
  Nothing is deleted by default. Set `keepRuns` to a number of days to delete
486
- terminal runs older than that at mount; active runs are never touched, and the
487
- removed ids are logged. `superagent_list` prints the current file count and size,
821
+ terminal runs older than that at mount; active runs are never touched, the
822
+ removed ids are logged, and the matching `reports/<runId>.md` artifact is
823
+ removed with its run. `superagent_list` prints the current file count and size,
488
824
  so growth is visible before it becomes a problem.
489
825
 
826
+ To clean up on demand, `dsh-superagent-archive prune` plans first and deletes
827
+ second:
828
+
829
+ ```bash
830
+ node "$PKG/bin/archive.js" prune --older-than 30 # dry run
831
+ node "$PKG/bin/archive.js" prune --older-than 30 --status failed # dry run, one status
832
+ node "$PKG/bin/archive.js" prune --older-than 30 --confirm # delete
833
+ ```
834
+
835
+ The plan prints each run id, status, finish time, and the bytes it holds; the
836
+ summary gives the run, file, and byte totals. Without `--confirm` nothing is
837
+ deleted. Only terminal runs (`completed`, `partial`, `failed`, `cancelled`,
838
+ `interrupted`) are ever candidates: a run that is still active, or whose
839
+ `.lock` is held by another process, is listed as skipped and left alone. A run
840
+ inside the window, a run with no parsable timestamp, and a quarantined
841
+ `*.corrupt-*` file are kept as well.
842
+
843
+ ## Archives
844
+
845
+ `archive export` turns one run into evidence another person can open offline —
846
+ no host, no plugin, no network:
847
+
848
+ ```bash
849
+ node "$PKG/bin/archive.js" export <run-id> --out ./run-archive # directory
850
+ node "$PKG/bin/archive.js" export <run-id> --out ./run.html --format html # one page
851
+ node "$PKG/bin/archive.js" export <run-id> --out ./run.json --format bundle
852
+ ```
853
+
854
+ The directory contains `README.md` (summary, the merged report, a subtask
855
+ table, and a file index), `report.md` (the report as markdown), `run.json` (the
856
+ full durable record), `subtasks/` (one markdown page and one JSON file per
857
+ subtask), `guards.json` / `guards.md` (every decision a worker or the
858
+ aggregator stopped on), `usage.json` (token totals per child plus the cost the
859
+ operator prices produce), and `manifest.json` (archive metadata, sizes, and a
860
+ SHA-256 per file). `--format html` writes the same content as one self-contained
861
+ page with the bundle embedded; `--format bundle` writes only that JSON.
862
+
863
+ `archive import <path>` reads any of the three back into the local store for
864
+ review, restoring the run record and its report artifact. It never overwrites:
865
+ when a local run has the same id, the command fails before writing anything and
866
+ says so. An imported run is terminal, so it is listed and readable but never
867
+ resumed.
868
+
490
869
  ## Cancelling from another process
491
870
 
492
871
  `superagent_cancel` works even when the run was started by a different host
@@ -517,14 +896,14 @@ appears to "hang" until the ignored-abort child returns.
517
896
 
518
897
  | What you see | What it means | What to do |
519
898
  | --- | --- | --- |
520
- | `superagent_*` tools do not exist | The bundle row is not mounted, or the host refused to load the plugin. | Run `--dump-config` and check for the `@xiangyixie/dsh-superagent` block; reinstall with `dsh plugin --profile <p> add @xiangyixie/dsh-superagent@0.9.3` and read the host log for `[dsh-superagent]` lines. |
521
- | `Cannot find module .../lib/control.js` (or `watch.js` / `report.js`) and the plugin never activates | The copy in that profile is incomplete — an `add` that was interrupted leaves a partial extraction. The published package is not the cause: every version ships all eight `lib/` files. | Delete the plugin's directory under the profile's `node_modules` (scoped `@xiangyixie/dsh-superagent`, or unscoped `dsh-superagent` from an older tarball install) and run the same `add` command again, with the version number. Do not copy files in by hand. |
899
+ | `superagent_*` tools do not exist | The bundle row is not mounted, or the host refused to load the plugin. | Run `--dump-config` and check for the `@xiangyixie/dsh-superagent` block; reinstall with `dsh plugin --profile <p> add @xiangyixie/dsh-superagent@0.11.0` and read the host log for `[dsh-superagent]` lines. |
900
+ | `Cannot find module .../lib/control.js` (or `watch.js` / `report.js`) and the plugin never activates | The copy in that profile is incomplete — an `add` that was interrupted leaves a partial extraction. The published package is not the cause: every version ships all twelve `lib/` files. | Delete the plugin's directory under the profile's `node_modules` (scoped `@xiangyixie/dsh-superagent`, or unscoped `dsh-superagent` from an older tarball install) and run the same `add` command again, with the version number. Do not copy files in by hand. |
522
901
  | `[error] the model provider rejected the API key` | The key env var is missing in the process that started the host. | Export `DEEPSEEK_API_KEY` (the default route) or the variable your route names, then restart `dsh`. |
523
902
  | `MISSING_CREDENTIAL ... no API key for provider route "..."` | The profile's route has no credential in the environment. | Set the env var named for that route and restart. The error line names the route, so use that, not this page. |
524
903
  | `[error] the subagent service is unavailable` | The profile has no `subagents` service, so the plugin has nothing to spawn. | Use a profile built on the base bundle (`web` or `headless` from the stock image), or add the subagent plugin to the profile. |
525
904
  | `error: subagent provider "..." cannot enforce maxSubagentDepth` | The route's subagent backend cannot cap delegation. | Keep `provider: spawn`, or set `maxSubagentDepth: provider-managed` if you accept the backend's own limit. |
526
905
  | `error: the Windows file sandbox could not start a child process` | Host sandbox launcher failure (`windows-acl-run: ...`), not your goal or key. The subtask is retried once. | Retry the run; if it repeats, restart the host, or disable the Windows ACL sandbox in the profile, then run the `diagnose-windows-sandbox-acl` skill. |
527
- | `error: the run was not started because the active-run limit is already in use` | `maxActiveRuns` is full, including runs from another profile that shares the state directory. | Wait, cancel one, or raise `maxActiveRuns`. |
906
+ | `error: the run was not started because the active-run limit is already in use` | `maxActiveRuns` is full, including runs from another profile that shares the state directory, and the start did not ask to queue (or the queue itself is full). | Retry with `queue: true`, wait, cancel one, or raise `maxActiveRuns` / `maxQueuedRuns`. |
528
907
  | `error: the run stopped because it reached its spending cap` | `maxModelCallsPerRun` or `maxTokensPerRun` was hit. | Read the partial report; raise the cap in the config, then `superagent_resume` continues with the new limits. |
529
908
  | `usage: not recorded` | The run finished and no child session log could be read (moved `sessions` directory, or a run created before accounting). | Nothing to fix on old runs; new runs record usage. While a run is still active the line says accounting is pending instead. |
530
909
  | `usage note: N child session log(s) could not be read` | Part of the usage was unreadable; the token figures are a lower bound. The call budget still counted those children. | Check that `$DSH_HOME/sessions` exists and is readable by the host process. |
@@ -559,7 +938,8 @@ A run that fails *after* it was accepted keeps its report and shows `error:`
559
938
  subtask's text under the goal heading) and falls back to a deterministic merge
560
939
  when the aggregator fails or the budget is exhausted.
561
940
  - Retention is opt-in (`keepRuns`); by default state accumulates, at up to
562
- 32 KB per subtask plus the report per run.
941
+ 32 KB per subtask plus the report per run. `archive prune` removes terminal
942
+ runs on demand, as a dry run unless `--confirm` is given.
563
943
  - The HTTP embedding surface is loopback-only, opt-in, and token-authenticated;
564
944
  it cannot be exposed remotely, and there is no MCP server. A local process
565
945
  running as the same user can read the token, which is the same trust boundary
@@ -569,8 +949,8 @@ A run that fails *after* it was accepted keeps its report and shows `error:`
569
949
 
570
950
  The package is published as `@xiangyixie/dsh-superagent` — npm already has a
571
951
  `dsh-super-agent` that is too close to the unscoped name, so the scope keeps
572
- the name instead of renaming the project. The five tools are unchanged:
573
- `superagent_*`. The earlier working name was `dsh-longhaul` with `longhaul_*`
952
+ the name instead of renaming the project. The tools are unchanged:
953
+ `superagent_*` (with `superagent_memory` added in 0.10, additively). The earlier working name was `dsh-longhaul` with `longhaul_*`
574
954
  tools; nothing was ever published, so the old names do not exist anywhere and
575
955
  there is no alias layer. If you find an old snippet that calls `longhaul_start`,
576
956
  replace the prefix — the arguments are unchanged.