@xiangyixie/dsh-superagent 0.10.0 → 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/CHANGELOG.md +210 -87
- package/README.md +276 -38
- package/bin/archive.js +185 -0
- package/bin/doctor.js +84 -0
- package/lib/cost.js +267 -0
- package/lib/doctor.js +876 -0
- package/lib/index.js +1547 -1104
- package/lib/ledger.js +270 -0
- package/lib/memory.js +736 -503
- package/lib/orchestrator.js +1377 -183
- package/lib/report.js +1068 -733
- package/lib/store.js +873 -402
- package/lib/templates.js +690 -0
- package/lib/watch.js +810 -458
- package/lib/workspace.js +433 -0
- package/package.json +13 -3
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
|
|
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.
|
|
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
|
|
40
|
-
the surface, plus
|
|
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.
|
|
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,7 +204,10 @@ 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
|
|
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`. |
|
|
208
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. |
|
|
@@ -212,8 +215,8 @@ Row config in `<profile>/cordis.patch.yml`:
|
|
|
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
217
|
| `notifyOnComplete` | `true` | Master switch for proactive messages. Off means the plugin never wakes the session. |
|
|
215
|
-
| `maxNotificationsPerHour` | `3` | Proactive messages allowed per hour. Runs above the cap are folded into one summary; `0` disables the cap. |
|
|
216
|
-
| `notifyRetries` | `2` | Extra delivery attempts when the host refuses a wake-up; messages for one session are delivered in order. |
|
|
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. |
|
|
217
220
|
| `notifyRetryDelayMs` | `2000` | First delay between those attempts; it doubles per attempt, capped at 60s. |
|
|
218
221
|
| `autoResumeRounds` | `1` | Extra rounds that retry subtasks which failed in a way that looks transient, before the failure is reported; `0` disables. |
|
|
219
222
|
| `childModelFallback` | none | Model used on such a retry (quota, rate limit, timeout). Unset keeps the configured route. |
|
|
@@ -225,6 +228,8 @@ Row config in `<profile>/cordis.patch.yml`:
|
|
|
225
228
|
| `memoryDigestChars` | `1600` | Character budget for the note part of that prompt. |
|
|
226
229
|
| `keepRuns` | `0` | Delete terminal runs older than this many days at mount; `0` keeps everything. |
|
|
227
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. |
|
|
228
233
|
|
|
229
234
|
### Switching models
|
|
230
235
|
|
|
@@ -262,8 +267,82 @@ subagent start request has no tool filter, and its own `subagent` tool rejects a
|
|
|
262
267
|
`toolFilter` config and points at agent presets. `childPreset` is therefore the
|
|
263
268
|
supported way to narrow a child's tools; without a dedicated preset, workers
|
|
264
269
|
inherit the session's tools. The `superagent_*` tools still exist in their tool
|
|
265
|
-
list, but `superagent_start`, `superagent_resume`,
|
|
266
|
-
refuse to run from a worker session;
|
|
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.
|
|
267
346
|
|
|
268
347
|
### Spending limits and prices
|
|
269
348
|
|
|
@@ -315,8 +394,24 @@ cost: at least ¥0.0041 (estimate; no price for haoduo/gpt-6.1-sol)
|
|
|
315
394
|
|
|
316
395
|
## Tools
|
|
317
396
|
|
|
318
|
-
- `superagent_start(goal, max_subtasks?, max_parallel?, deadline_minutes?, allow_duplicate?, wait_seconds?)`
|
|
319
|
-
starts a run and returns immediately with a run id.
|
|
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
|
|
320
415
|
active run in the same session already covers returns that run id marked
|
|
321
416
|
`deduped: true` instead of paying for a second plan: the goal is compared after
|
|
322
417
|
trimming, collapsing runs of whitespace, and ignoring case, and the check runs
|
|
@@ -337,12 +432,49 @@ cost: at least ¥0.0041 (estimate; no price for haoduo/gpt-6.1-sol)
|
|
|
337
432
|
are told what failed and to check what the earlier attempt already did. Only
|
|
338
433
|
the session that started the run may resume it. A resume is not counted
|
|
339
434
|
against `maxActiveRuns`, so it works when the cap is full; `force` is still
|
|
340
|
-
accepted but no longer needed.
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
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.
|
|
346
478
|
|
|
347
479
|
## Progress, decisions, and artifacts
|
|
348
480
|
|
|
@@ -352,15 +484,35 @@ cost: at least ¥0.0041 (estimate; no price for haoduo/gpt-6.1-sol)
|
|
|
352
484
|
- **Attention.** A worker or the aggregator may append one fenced `attention`
|
|
353
485
|
block with a question that only the user can answer. It is stripped from the
|
|
354
486
|
report, stored on the run as `attention.items`, shown as `needs your decision:`
|
|
355
|
-
in status, and leads the notification when the run finishes.
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
status
|
|
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.
|
|
360
505
|
- **Report file.** A terminal run writes its report to
|
|
361
506
|
`<stateDir>/reports/<runId>.md` with an atomic rename, so the outcome has a
|
|
362
507
|
path that can be opened or attached. The directory carries a `.gitignore` with
|
|
363
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.
|
|
364
516
|
|
|
365
517
|
## Cross-run memory
|
|
366
518
|
|
|
@@ -416,6 +568,12 @@ file, and a truncated last line from a killed process is skipped. Two runs
|
|
|
416
568
|
finishing at once cannot overwrite each other's notes; a line may land in a
|
|
417
569
|
different order, and resolution is by timestamp, never by position.
|
|
418
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
|
+
|
|
419
577
|
**Correction.** A newer note with the same key supersedes the old one. An
|
|
420
578
|
explicit `forget` writes a tombstone. Notes older than `memoryMaxAgeDays` stop
|
|
421
579
|
being injected and are dropped at the next compaction. Every note is shown with
|
|
@@ -440,8 +598,9 @@ _Top of a report rendered from 40 real host runs. The full page — timeline,
|
|
|
440
598
|
swimlanes, call and cost curves, failure annotations, run table — is
|
|
441
599
|
[docs/report-sample.html](https://github.com/LittleChenLiya/dsh-superagent/blob/main/docs/report-sample.html)._
|
|
442
600
|
|
|
443
|
-
|
|
444
|
-
|
|
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.
|
|
445
604
|
|
|
446
605
|
Run them from the installed copy inside the profile:
|
|
447
606
|
|
|
@@ -452,16 +611,22 @@ node "$PKG/bin/report.js" --out report.html # self-contained HTML page
|
|
|
452
611
|
```
|
|
453
612
|
|
|
454
613
|
If the profile's linker created bin links (npm does), the same commands are
|
|
455
|
-
`node_modules/.bin/dsh-superagent-watch
|
|
614
|
+
`node_modules/.bin/dsh-superagent-watch`, `node_modules/.bin/dsh-superagent-report`,
|
|
615
|
+
and `node_modules/.bin/dsh-superagent-doctor`.
|
|
456
616
|
|
|
457
|
-
|
|
458
|
-
Pass it when the plugin config sets a custom
|
|
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`.
|
|
459
620
|
|
|
460
621
|
**`watch`** draws one line per run — id, status, calls used against the cap,
|
|
461
622
|
elapsed time, what it is doing right now, and the parent session — in the
|
|
462
623
|
alternate screen, and restores the cursor on Ctrl-C, SIGTERM, or a closed pipe.
|
|
463
624
|
A status change repaints immediately; an idle panel reads one small file per
|
|
464
|
-
second.
|
|
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
|
|
465
630
|
[docs/e2e/transcripts/watch-panel.log](https://github.com/LittleChenLiya/dsh-superagent/blob/main/docs/e2e/transcripts/watch-panel.log)
|
|
466
631
|
captures from 40 real runs.
|
|
467
632
|
|
|
@@ -469,16 +634,42 @@ captures from 40 real runs.
|
|
|
469
634
|
no script, no font, no image, no network. It has a timeline with each run's
|
|
470
635
|
start, end, and derived planning/work/merge phases; a swimlane chart whose lane
|
|
471
636
|
count is the peak concurrency; cumulative model-call and cost curves; explicit
|
|
472
|
-
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.
|
|
473
641
|
[docs/report-sample.html](https://github.com/LittleChenLiya/dsh-superagent/blob/main/docs/report-sample.html)
|
|
474
642
|
is the 40-run report from the host e2e — open it directly, nothing is fetched —
|
|
475
643
|
and
|
|
476
644
|
[docs/e2e/transcripts/report-cli.log](https://github.com/LittleChenLiya/dsh-superagent/blob/main/docs/e2e/transcripts/report-cli.log)
|
|
477
645
|
records the command plus a zero-external-reference audit.
|
|
478
646
|
|
|
479
|
-
|
|
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
|
|
480
667
|
`dsh plugin add`, never with `npm i -g`.
|
|
481
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
|
+
|
|
482
673
|
## Embedding over local HTTP
|
|
483
674
|
|
|
484
675
|
The tools require a session. If another UI or script must start and watch runs
|
|
@@ -516,7 +707,9 @@ only, and there is no remote or unauthenticated mode.
|
|
|
516
707
|
One file per run: `$DSH_HOME/state/superagent/runs/<runId>.json`, written with a
|
|
517
708
|
temp file plus rename, so a kill during a save cannot leave a half-written run.
|
|
518
709
|
Statuses: `queued`, `planning`, `running`, `aggregating`, `completed`,
|
|
519
|
-
`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`.
|
|
520
713
|
|
|
521
714
|
At mount the plugin marks a run as `interrupted` **only when it has no live
|
|
522
715
|
owner** (see below) and resets its in-flight subtasks to `pending`.
|
|
@@ -545,6 +738,7 @@ Three side files live next to the run:
|
|
|
545
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. |
|
|
546
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. |
|
|
547
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. |
|
|
548
742
|
|
|
549
743
|
If a run's file is damaged, nothing else breaks: other runs list normally, and
|
|
550
744
|
starting a new run works. Inspect the `.corrupt-` file, then delete it. A file
|
|
@@ -629,6 +823,49 @@ removed ids are logged, and the matching `reports/<runId>.md` artifact is
|
|
|
629
823
|
removed with its run. `superagent_list` prints the current file count and size,
|
|
630
824
|
so growth is visible before it becomes a problem.
|
|
631
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
|
+
|
|
632
869
|
## Cancelling from another process
|
|
633
870
|
|
|
634
871
|
`superagent_cancel` works even when the run was started by a different host
|
|
@@ -659,14 +896,14 @@ appears to "hang" until the ignored-abort child returns.
|
|
|
659
896
|
|
|
660
897
|
| What you see | What it means | What to do |
|
|
661
898
|
| --- | --- | --- |
|
|
662
|
-
| `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.
|
|
663
|
-
| `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
|
|
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. |
|
|
664
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`. |
|
|
665
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. |
|
|
666
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. |
|
|
667
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. |
|
|
668
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. |
|
|
669
|
-
| `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. |
|
|
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`. |
|
|
670
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. |
|
|
671
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. |
|
|
672
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. |
|
|
@@ -701,7 +938,8 @@ A run that fails *after* it was accepted keeps its report and shows `error:`
|
|
|
701
938
|
subtask's text under the goal heading) and falls back to a deterministic merge
|
|
702
939
|
when the aggregator fails or the budget is exhausted.
|
|
703
940
|
- Retention is opt-in (`keepRuns`); by default state accumulates, at up to
|
|
704
|
-
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.
|
|
705
943
|
- The HTTP embedding surface is loopback-only, opt-in, and token-authenticated;
|
|
706
944
|
it cannot be exposed remotely, and there is no MCP server. A local process
|
|
707
945
|
running as the same user can read the token, which is the same trust boundary
|