@xiangyixie/dsh-superagent 0.9.2 → 0.10.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 CHANGED
@@ -1,5 +1,114 @@
1
1
  # Changelog
2
2
 
3
+ Doc-only releases: npm serves the README from the tarball, so a README edit is
4
+ invisible on the package page until something is published. When the edit
5
+ changes what a reader would do — install commands, limits, troubleshooting
6
+ steps — it gets its own patch version (0.9.2, 0.9.3). Typos and wording ride
7
+ along with the next code release. A doc-only version leaves `lib/` and `bin/`
8
+ byte-identical to the version before it, and the pinned install line in the
9
+ README is updated to the version being released.
10
+
11
+ ## 0.10.0 — 2026-11-15
12
+
13
+ The dispatch, progress, delivery, and memory layer. No runtime dependencies were
14
+ added, and the package still ships one file per module from `lib/`.
15
+
16
+ ### Added
17
+
18
+ - **Cross-run memory.** `<stateDir>/memory/<scope>.jsonl` keeps short notes the
19
+ aggregator writes (`decision`, `pitfall`, `next`, `dispatch`, `note`) plus the
20
+ six most recent runs derived from the run store. The digest is bounded
21
+ (12 notes / 1600 characters / 2600 characters total), compacted above 400
22
+ lines or 128 KB, and injected into the planner and aggregator prompts. A newer
23
+ note with the same key supersedes an older one, `forget` retracts it, and
24
+ notes older than 30 days expire. Secrets are redacted before storage; the
25
+ directory carries its own `.gitignore` and is never in the package.
26
+ - Added `superagent_memory` (`list`, `set`, `forget`). Existing tools keep their
27
+ arguments and output; this is the sixth tool.
28
+ - **Layered memory.** `rules` and `profile` scopes are read into planning and
29
+ aggregation ahead of the run scope; `superagent_memory` takes `scope`. A run
30
+ only writes its own scope, so a model cannot overwrite a project rule.
31
+ - **Duplicate dispatch is collapsed.** The same active goal (case and whitespace
32
+ ignored) returns the existing run id with `deduped: true`, under a per-goal
33
+ claim so two processes sharing a state directory cannot both start it. The
34
+ match is scoped to the owning session, so two sessions that ask for the same
35
+ generic goal still get their own runs. `allow_duplicate: true` on
36
+ `superagent_start` (or `allow_duplicate` on the control `start` body) opts
37
+ out. A `wait_seconds` call keeps the `deduped` marker in its result.
38
+ - **Transient backoff.** A rate-limit, quota, timeout, or 5xx failure now waits
39
+ 2s, then 4s, then 8s before the next attempt instead of retrying immediately.
40
+ - **Recovery note.** A resumed run tells each worker what failed and instructs it
41
+ to inspect files, `git status`, `git log`, and remote state before repeating an
42
+ externally visible action.
43
+ - **Structured attention.** A worker or the aggregator may append one fenced
44
+ `attention` block. It is stripped from the report, stored as `attention.items`,
45
+ shown as `needs your decision:` in status, and leads the notification.
46
+ - **Attention text is bounded.** Question, options, and reason are collapsed to
47
+ one line and capped at 500 / 200 / 300 characters, so neither status nor a
48
+ notification can be given forged extra lines. An invalid attention block is
49
+ not stripped silently: its raw text stays in the report and status prints
50
+ `attention: <reason>`.
51
+ - **Milestones.** `plan_ready`, `running`, `aggregating`, and `settled` are
52
+ recorded with timestamps and shown in `superagent_status`; nothing is pushed.
53
+ - **Report file.** A terminal report is written atomically to
54
+ `<stateDir>/reports/<runId>.md` (directory carries `.gitignore: *`), recorded
55
+ in `run.artifacts`, and shown in status. `keepRuns` pruning removes it together
56
+ with the run record.
57
+ - **Quiet by default.** Only a delivered, failed, or partially finished run may
58
+ wake the session; a cancelled run never does, and progress is never pushed.
59
+ `maxNotificationsPerHour` (default 3) buffers extra runs into one summary.
60
+ - **Notification outbox.** A refused wake-up is retried with backoff
61
+ (`notifyRetries`, `notifyRetryDelayMs`) and messages for one session stay in
62
+ order. A buffered batch is put back into `pending` when the send fails, so a
63
+ later message still carries those runs; it is dropped only after three failed
64
+ deliveries.
65
+ - **Self-heal before reporting.** A subtask failure that looks transient
66
+ (quota, rate limit, timeout, 5xx) gets `autoResumeRounds` (default 1) more
67
+ rounds, optionally on `childModelFallback`. The failure message now says what
68
+ was tried, and `self-heal:` appears in `superagent_status`.
69
+ - **`memoryMaxEntries` is a compaction trigger.** Exceeding it, 400 lines, or
70
+ 128 KB compacts the notebook on the next write.
71
+ - New config: `memory`, `memoryScope`, `memoryMaxEntries`, `memoryMaxAgeDays`,
72
+ `memoryDigestEntries`, `memoryDigestChars`, `maxNotificationsPerHour`,
73
+ `notifyRetries`, `notifyRetryDelayMs`, `autoResumeRounds`,
74
+ `childModelFallback`.
75
+
76
+ ### Changed
77
+
78
+ - **A resume is never refused by the concurrency quota.** A `superagent_resume`
79
+ only finishes work that already exists, so it is not counted against
80
+ `maxActiveRuns` and works even when the cap is full; only `superagent_start`
81
+ creates new spend and is subject to the cap. The resume is still
82
+ session-scoped: it may only be issued by the session named in the run's
83
+ `parentSessionId`. `force` (`force` or `override_quota` over HTTP) is still
84
+ accepted so an existing caller keeps working, but it no longer changes
85
+ anything.
86
+ - `superagent_status` gained the milestone line, the attention line, and the
87
+ report file path; `superagent_start` gained `allow_duplicate`; the control
88
+ `start` body gained `allow_duplicate`, and `resume` still accepts `force`.
89
+
90
+ ### Fixed
91
+
92
+ - Memory, notification, and report-artifact writes are fail-open or retried, so
93
+ a transient filesystem error cannot turn a finished run into a failed one; a
94
+ report that is already written stays on disk and is listed in status.
95
+ - Test suite: 157 tests, 0 failures; `npm test` and `node --test` discovery
96
+ agree.
97
+
98
+ ## 0.9.3 — 2026-11-14
99
+
100
+ Documentation only; no code change.
101
+
102
+ - Both install commands name the version (`@xiangyixie/dsh-superagent@0.9.3`),
103
+ and the Quickstart explains why: pnpm's minimum release age skips packages
104
+ published in the last few hours, so a bare `add` installs an older version and
105
+ still reports success. A bare install here resolved 0.9.0 while 0.9.2 was
106
+ current.
107
+ - Added the command that reports what actually landed:
108
+ `npm ls --prefix <DSH_HOME>/profiles/web @xiangyixie/dsh-superagent`.
109
+ - The troubleshooting rows for a missing tool and for
110
+ `Cannot find module .../lib/control.js` now carry the pinned reinstall command.
111
+
3
112
  ## 0.9.2 — 2026-11-14
4
113
 
5
114
  Documentation only; no code change. npm renders the README from the tarball, so
package/LICENSE CHANGED
@@ -1,21 +1,21 @@
1
- MIT License
2
-
3
- Copyright (c) 2026 Admire (LittleChenLiya)
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in all
13
- copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Admire (LittleChenLiya)
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -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 six 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
27
+ dsh plugin --profile web add @xiangyixie/dsh-superagent@0.10.0
28
28
  ```
29
29
 
30
30
  Then ask the session for a run — a real call, not a sketch:
@@ -36,7 +36,7 @@ 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
39
+ It adds no in-host UI and patches no host code: the six `superagent_*` tools are
40
40
  the surface, plus two optional operator utilities (a terminal panel and an HTML
41
41
  report) that read the same run files.
42
42
 
@@ -73,15 +73,25 @@ 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
76
+ dsh plugin --profile web add @xiangyixie/dsh-superagent@0.10.0
77
77
 
78
78
  # 2. confirm the bundle row exists in the merged config
79
79
  dsh --profile web --dump-config
80
80
  ```
81
81
 
82
- `add @xiangyixie/dsh-superagent` resolves the published package. For an offline
83
- machine or a pinned artifact, install a packed tarball instead — it is
84
- byte-identical to what the registry serves:
82
+ Name the version. Without one, pnpm's minimum release age policy skips releases
83
+ published in the last few hours and installs the newest older one, so a bare
84
+ `add` succeeds while giving you a version that is not current. If you would
85
+ rather track the newest release, add it to `minimumReleaseAgeExclude` in the
86
+ profile's `pnpm-workspace.yaml`; otherwise bump the number above. Check what
87
+ actually landed with:
88
+
89
+ ```bash
90
+ npm ls --prefix <DSH_HOME>/profiles/web @xiangyixie/dsh-superagent
91
+ ```
92
+
93
+ For an offline machine or a pinned artifact, install a packed tarball instead —
94
+ it is byte-identical to what the registry serves:
85
95
 
86
96
  ```bash
87
97
  npm pack # writes xiangyixie-dsh-superagent-<version>.tgz
@@ -194,14 +204,25 @@ Row config in `<profile>/cordis.patch.yml`:
194
204
  | `maxSubagentDepth` | `1` | How deep children may delegate. `1` forbids grandchildren; `provider-managed` leaves it to the backend. |
195
205
  | `maxSubtasks` | `8` | Cap on planned subtasks. A tool argument can only lower it, never raise it; hard max 16. |
196
206
  | `maxParallel` | `3` | Subtasks executing at once. A tool argument can only lower it; hard max 8. |
197
- | `maxActiveRuns` | `2` | Active runs per state directory, across profiles and hosts that share it; further `superagent_start` and `superagent_resume` calls are rejected. |
198
- | `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; further `superagent_start` calls are rejected. `superagent_resume` is not counted and works when the cap is full, because it only finishes work that already exists. |
208
+ | `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. |
199
209
  | `deadlineMinutes` | `120` | Wall-clock budget; on expiry the run ends `partial` or `failed`. |
200
210
  | `maxModelCallsPerRun` | `80` | Hard cap on child model calls per run; `0` disables. |
201
211
  | `maxTokensPerRun` | `2000000` | Hard cap on prompt + completion tokens per run; `0` disables. |
202
212
  | `pricing` | empty | Per-1M-token prices, keyed exactly as the usage log names the model (`provider/model`). Nothing is priced out of the box. |
203
213
  | `resultCapBytes` | `32768` | Bytes kept per subtask report. |
204
- | `notifyOnComplete` | `true` | Wake the owning session once when a run finishes while nobody is polling. |
214
+ | `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. |
217
+ | `notifyRetryDelayMs` | `2000` | First delay between those attempts; it doubles per attempt, capped at 60s. |
218
+ | `autoResumeRounds` | `1` | Extra rounds that retry subtasks which failed in a way that looks transient, before the failure is reported; `0` disables. |
219
+ | `childModelFallback` | none | Model used on such a retry (quota, rate limit, timeout). Unset keeps the configured route. |
220
+ | `memory` | `true` | Cross-run notebook. See [Cross-run memory](#cross-run-memory). |
221
+ | `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. |
222
+ | `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). |
223
+ | `memoryMaxAgeDays` | `30` | Notes older than this are ignored, then compacted away. |
224
+ | `memoryDigestEntries` | `12` | Notes injected into a prompt. |
225
+ | `memoryDigestChars` | `1600` | Character budget for the note part of that prompt. |
205
226
  | `keepRuns` | `0` | Delete terminal runs older than this many days at mount; `0` keeps everything. |
206
227
  | `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). |
207
228
 
@@ -294,16 +315,122 @@ cost: at least ¥0.0041 (estimate; no price for haoduo/gpt-6.1-sol)
294
315
 
295
316
  ## Tools
296
317
 
297
- - `superagent_start(goal, max_subtasks?, max_parallel?, deadline_minutes?, wait_seconds?)`
298
- starts a run and returns immediately with a run id. `wait_seconds` blocks for
299
- a terminal state instead.
300
- - `superagent_status(run_id, wait_seconds?)` returns status, per-subtask outcome,
301
- measured token usage, estimated cost, and the final report.
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. Starting a goal that an
320
+ active run in the same session already covers returns that run id marked
321
+ `deduped: true` instead of paying for a second plan: the goal is compared after
322
+ trimming, collapsing runs of whitespace, and ignoring case, and the check runs
323
+ under a per-goal claim keyed in the state directory, so two processes that share
324
+ it still start one run. The match is per session, because two sessions may
325
+ legitimately ask for the same generic goal at once.
326
+ `allow_duplicate: true` starts another one. A finished run never blocks the same
327
+ goal from being started again. `wait_seconds` blocks for a terminal state and
328
+ keeps the `deduped` marker in its result.
329
+ - `superagent_status(run_id, wait_seconds?)` returns status, milestones,
330
+ per-subtask outcome, measured token usage, estimated cost, the report file
331
+ path, and the final report.
302
332
  - `superagent_list(limit?)` lists runs, newest first, plus the state directory's
303
333
  file count and size.
304
334
  - `superagent_cancel(run_id)` stops the run, from any process; see below.
305
- - `superagent_resume(run_id, wait_seconds?)` continues an `interrupted`, `failed`,
306
- `partial`, or `cancelled` run; completed subtasks are kept.
335
+ - `superagent_resume(run_id, wait_seconds?, force?)` continues an `interrupted`,
336
+ `failed`, `partial`, or `cancelled` run; completed subtasks are kept. Workers
337
+ are told what failed and to check what the earlier attempt already did. Only
338
+ the session that started the run may resume it. A resume is not counted
339
+ against `maxActiveRuns`, so it works when the cap is full; `force` is still
340
+ accepted but no longer needed.
341
+ - `superagent_memory(action, key?, kind?, text?, scope?, limit?)` lists, adds,
342
+ corrects, or forgets notebook notes. `set` with an existing key supersedes it;
343
+ `forget` retracts it. `scope` addresses `rules` (project rules), `profile`
344
+ (user preferences), or the run scope. The tool is additive: the five run tools
345
+ keep their arguments and output.
346
+
347
+ ## Progress, decisions, and artifacts
348
+
349
+ - **Milestones.** Every run records `plan_ready`, `running`, `aggregating`, and
350
+ `settled` with a timestamp, shown in `superagent_status`. They never produce a
351
+ proactive message; progress stays visible without becoming noisy.
352
+ - **Attention.** A worker or the aggregator may append one fenced `attention`
353
+ block with a question that only the user can answer. It is stripped from the
354
+ report, stored on the run as `attention.items`, shown as `needs your decision:`
355
+ in status, and leads the notification when the run finishes. The question,
356
+ options, and reason are collapsed to one line and capped at 500 / 200 / 300
357
+ characters, so the block cannot inject a forged status or notification line.
358
+ A block that is not valid JSON or has no question is kept in the report, and
359
+ status prints `attention: <reason>` instead of hiding the request.
360
+ - **Report file.** A terminal run writes its report to
361
+ `<stateDir>/reports/<runId>.md` with an atomic rename, so the outcome has a
362
+ path that can be opened or attached. The directory carries a `.gitignore` with
363
+ `*`, and the path is recorded in `run.artifacts` and shown in status.
364
+
365
+ ## Cross-run memory
366
+
367
+ A run is isolated on purpose: planner and workers start empty. Without a
368
+ notebook, every run repeats work the last one already finished and rediscovers
369
+ the same traps. The plugin keeps two different things, and only one of them is
370
+ stored:
371
+
372
+ 1. **What happened** is derived from the run store at planning time. The six
373
+ most recent runs are rendered as one line each (date, status, completed
374
+ subtasks, goal, run id). Nothing is copied, so it cannot drift from the run
375
+ records.
376
+ 2. **What was learned** is a small curated notebook: decisions, pitfalls, next
377
+ steps, and which work was delegated. The aggregator returns it inside a
378
+ fenced `memory` block that is removed from the report before the user sees it.
379
+ A run that produces no block writes nothing; the plugin never invents a note.
380
+
381
+ **Storage.** `<stateDir>/memory/<scope>.jsonl`, one JSON object per line. A line
382
+ is `{v,id,ts,key,kind,text,runId,status}`; `key` is a short slug (`deploy-target`)
383
+ and `kind` is `decision`, `pitfall`, `next`, `dispatch`, or `note`. The directory
384
+ contains a `.gitignore` with `*`, so even a `stateDir` that points inside a
385
+ repository cannot commit the notebook. It is never listed in the package `files`
386
+ whitelist, so it never ships to npm.
387
+
388
+ **When it is written.** Once per run, at settle, only for a terminal run whose
389
+ report carried a block. A resume that settles the same run again is a no-op
390
+ because the store records the writing run id. A write failure is recorded on the
391
+ run (`memoryWrite.reason`) and never fails the run.
392
+
393
+ **When it is read.** Once at `superagent_start` (and again at `superagent_resume`,
394
+ since the aggregator will run again), before planning. The composed context is
395
+ stored on the run as `memory.digest`, injected into the planner and aggregator
396
+ prompts, and summarised in `superagent_status`.
397
+
398
+ **Layers.** Three scopes are read, in order: `rules` (project rules), `profile`
399
+ (user preferences), then `memoryScope` (what earlier runs learned). The first
400
+ two are curated with `superagent_memory` and are never written by a run, so a
401
+ rule cannot be overwritten by a model's observation. Each layer is labelled in
402
+ the prompt and bounded on its own; `memory.scopes` on the run lists what was
403
+ read.
404
+
405
+ **Size.** Each note is capped at 400 characters after redaction. A prompt sees at
406
+ most `memoryDigestEntries` notes inside `memoryDigestChars` characters, plus six
407
+ one-line run summaries, hard-capped at 2600 characters in total. The file is
408
+ compacted when a write would push it past `memoryMaxEntries` notes, 400 lines,
409
+ or 128 KB; compaction keeps the newest `memoryMaxEntries` notes.
410
+ Context cannot grow with the number of runs.
411
+
412
+ **Concurrency.** Within a process, writes to one scope are serialised. Across
413
+ processes, each batch is appended as one small `write` (no read-modify-write of
414
+ the whole file), compaction takes a lock file and replaces the file from a temp
415
+ file, and a truncated last line from a killed process is skipped. Two runs
416
+ finishing at once cannot overwrite each other's notes; a line may land in a
417
+ different order, and resolution is by timestamp, never by position.
418
+
419
+ **Correction.** A newer note with the same key supersedes the old one. An
420
+ explicit `forget` writes a tombstone. Notes older than `memoryMaxAgeDays` stop
421
+ being injected and are dropped at the next compaction. Every note is shown with
422
+ its age and the digest tells the model the notes may be stale and must be
423
+ verified, so a wrong conclusion can be refuted by a later run instead of
424
+ becoming a permanent bias.
425
+
426
+ **Privacy.** Notes are written outside the repository by default
427
+ (`$DSH_HOME/state/superagent/memory`). Before storage, the plugin redacts API-key
428
+ shapes (`sk-…`, `Bearer …`, `ghp_…`, `AKIA…`), long hex/base64 blobs, email
429
+ addresses, and absolute home paths; it collapses a note to one line and caps it.
430
+ The aggregator is instructed not to record secrets, customer data, or the report
431
+ itself. A `stateDir` inside the installed package disables memory rather than
432
+ risk shipping it. If you point `stateDir` at a repository, the nested
433
+ `.gitignore` still keeps the files out of a default `git add`.
307
434
 
308
435
  ## Watch and report
309
436
 
@@ -405,8 +532,11 @@ run would make the surviving child keep spending while the file says
405
532
 
406
533
  Resuming is exclusive for the same reason. `superagent_resume` takes the same
407
534
  serial gate as `superagent_start`, claims `<runId>.lock` (created atomically),
408
- and refuses a run that still has a live owner or that would exceed
409
- `maxActiveRuns`.
535
+ refuses a run that still has a live owner, and refuses a caller that is not the
536
+ session in `parentSessionId`. It does not count against `maxActiveRuns`: a
537
+ resume finishes work that already exists, so a full cap never blocks it. `force`
538
+ (tool) or `force` / `override_quota` (HTTP) is still accepted for compatibility
539
+ and changes nothing.
410
540
 
411
541
  Three side files live next to the run:
412
542
 
@@ -451,10 +581,31 @@ that were mid-flight become `pending`, so `superagent_resume` continues the run.
451
581
  The heartbeat is refreshed every 30 seconds by the owning process, so a healthy
452
582
  run is never mistaken for an orphan.
453
583
 
454
- ### Notification boundaries
455
-
456
- `notifyOnComplete` writes one message back into the owning session when a run
457
- finishes. Two cases report instead of notifying:
584
+ ### Talking to the user
585
+
586
+ The plugin is quiet unless the user must hear something. This is a rule in code,
587
+ not only in this document:
588
+
589
+ - **Allowed to interrupt:** a run finished and delivered a result, a run failed,
590
+ or a run stopped half-way (`partial`, `interrupted`). A run the user cancelled
591
+ is never announced — the caller already knows.
592
+ - **Never pushed:** progress, subtask start/finish, retries, and memory writes.
593
+ They live in the run record, `superagent_status`, the watch panel, and the
594
+ report page; the user can look, but nothing pops up.
595
+ - **Self-heal first:** each subtask gets `attempts` tries, and a failure that
596
+ looks transient (quota, rate limit, timeout, 5xx) gets `autoResumeRounds`
597
+ more rounds, optionally on `childModelFallback`. Only what still fails is
598
+ reported, and the message says what was tried.
599
+ - **Bounded noise:** at most `maxNotificationsPerHour` proactive messages per
600
+ hour. Runs above the cap are buffered and folded into the next message as one
601
+ summary; `superagent_list` shows how many are waiting. If the message carrying
602
+ a folded batch cannot be delivered, the batch stays buffered and rides the
603
+ next one; it is dropped only after three failed deliveries.
604
+ - **Do not ask what is known:** the planner and aggregator receive the notebook
605
+ and are told to use it instead of asking the user for facts it already holds.
606
+
607
+ `notifyOnComplete` is the master switch. Two cases already report instead of
608
+ notifying:
458
609
 
459
610
  - a caller in the same host process was inside `superagent_status` and receives
460
611
  the terminal report itself (no message, to avoid duplicate noise). A poller in
@@ -473,8 +624,9 @@ live run as orphaned.
473
624
  ### Retention
474
625
 
475
626
  Nothing is deleted by default. Set `keepRuns` to a number of days to delete
476
- terminal runs older than that at mount; active runs are never touched, and the
477
- removed ids are logged. `superagent_list` prints the current file count and size,
627
+ terminal runs older than that at mount; active runs are never touched, the
628
+ removed ids are logged, and the matching `reports/<runId>.md` artifact is
629
+ removed with its run. `superagent_list` prints the current file count and size,
478
630
  so growth is visible before it becomes a problem.
479
631
 
480
632
  ## Cancelling from another process
@@ -507,7 +659,8 @@ appears to "hang" until the ignored-abort child returns.
507
659
 
508
660
  | What you see | What it means | What to do |
509
661
  | --- | --- | --- |
510
- | `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` and read the host log for `[dsh-superagent]` lines. |
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.10.0` and read the host log for `[dsh-superagent]` lines. |
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 eleven `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. |
511
664
  | `[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`. |
512
665
  | `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. |
513
666
  | `[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. |
@@ -558,8 +711,8 @@ A run that fails *after* it was accepted keeps its report and shows `error:`
558
711
 
559
712
  The package is published as `@xiangyixie/dsh-superagent` — npm already has a
560
713
  `dsh-super-agent` that is too close to the unscoped name, so the scope keeps
561
- the name instead of renaming the project. The five tools are unchanged:
562
- `superagent_*`. The earlier working name was `dsh-longhaul` with `longhaul_*`
714
+ the name instead of renaming the project. The tools are unchanged:
715
+ `superagent_*` (with `superagent_memory` added in 0.10, additively). The earlier working name was `dsh-longhaul` with `longhaul_*`
563
716
  tools; nothing was ever published, so the old names do not exist anywhere and
564
717
  there is no alias layer. If you find an old snippet that calls `longhaul_start`,
565
718
  replace the prefix — the arguments are unchanged.
package/bin/report.js CHANGED
@@ -1,79 +1,79 @@
1
- #!/usr/bin/env node
2
- /**
3
- * `dsh-superagent-report` — render existing runs into one self-contained HTML
4
- * file: inline CSS, inline SVG, no scripts, no network.
5
- */
6
- import fsp from 'node:fs/promises'
7
- import path from 'node:path'
8
- import { buildReport } from '../lib/report.js'
9
- import { createStore, resolveStateRoot } from '../lib/store.js'
10
-
11
- const USAGE = `Usage: dsh-superagent-report [options]
12
-
13
- Render recorded runs into one self-contained HTML file.
14
-
15
- Options:
16
- --state-dir <path> run state directory (default: $DSH_HOME/state/superagent)
17
- --out <file> output path (default: superagent-report.html)
18
- --limit <n> newest runs to include, 0 for all (default: 50)
19
- --title <text> report heading (default: Superagent run report)
20
- -h, --help show this message`
21
-
22
- function valueOf(argv, index, flag) {
23
- const value = argv[index]
24
- if (value === undefined || value.startsWith('--')) {
25
- console.error(`${flag} needs a value\n\n${USAGE}`)
26
- process.exit(2)
27
- }
28
- return value
29
- }
30
-
31
- function parse(argv) {
32
- const options = { out: 'superagent-report.html', limit: 50 }
33
- for (let index = 0; index < argv.length; index++) {
34
- const arg = argv[index]
35
- if (arg === '--state-dir') options.stateDir = valueOf(argv, ++index, '--state-dir')
36
- else if (arg.startsWith('--state-dir=')) options.stateDir = arg.slice('--state-dir='.length)
37
- else if (arg === '--out') options.out = valueOf(argv, ++index, '--out')
38
- else if (arg.startsWith('--out=')) options.out = arg.slice('--out='.length)
39
- else if (arg === '--limit') options.limit = Number(valueOf(argv, ++index, '--limit'))
40
- else if (arg.startsWith('--limit=')) options.limit = Number(arg.slice('--limit='.length))
41
- else if (arg === '--title') options.title = valueOf(argv, ++index, '--title')
42
- else if (arg.startsWith('--title=')) options.title = arg.slice('--title='.length)
43
- else if (arg === '-h' || arg === '--help') {
44
- console.log(USAGE)
45
- process.exit(0)
46
- } else {
47
- console.error(`unknown argument: ${arg}\n\n${USAGE}`)
48
- process.exit(2)
49
- }
50
- }
51
- if (!Number.isInteger(options.limit) || options.limit < 0) {
52
- console.error(`--limit must be a non-negative integer\n\n${USAGE}`)
53
- process.exit(2)
54
- }
55
- return options
56
- }
57
-
58
- const options = parse(process.argv.slice(2))
59
- const store = createStore(resolveStateRoot(options.stateDir))
60
- await store.init()
61
- const runs = await store.list()
62
- if (runs.length === 0) {
63
- console.error(`no runs in ${store.root}; start one with the superagent_start tool first`)
64
- process.exit(1)
65
- }
66
-
67
- const selected = options.limit === 0 ? runs : runs.slice(0, options.limit)
68
- const html = buildReport(selected, { title: options.title, generatedAt: Date.now() })
69
- const out = path.resolve(options.out)
70
- try {
71
- await fsp.mkdir(path.dirname(out), { recursive: true })
72
- await fsp.writeFile(out, html, 'utf8')
73
- } catch (error) {
74
- console.error(`cannot write ${out}: ${error?.message ?? error}`)
75
- process.exit(1)
76
- }
77
-
78
- const size = Buffer.byteLength(html, 'utf8')
79
- console.log(`wrote ${out} (${(size / 1024).toFixed(1)} kB, ${selected.length} run${selected.length === 1 ? '' : 's'})`)
1
+ #!/usr/bin/env node
2
+ /**
3
+ * `dsh-superagent-report` — render existing runs into one self-contained HTML
4
+ * file: inline CSS, inline SVG, no scripts, no network.
5
+ */
6
+ import fsp from 'node:fs/promises'
7
+ import path from 'node:path'
8
+ import { buildReport } from '../lib/report.js'
9
+ import { createStore, resolveStateRoot } from '../lib/store.js'
10
+
11
+ const USAGE = `Usage: dsh-superagent-report [options]
12
+
13
+ Render recorded runs into one self-contained HTML file.
14
+
15
+ Options:
16
+ --state-dir <path> run state directory (default: $DSH_HOME/state/superagent)
17
+ --out <file> output path (default: superagent-report.html)
18
+ --limit <n> newest runs to include, 0 for all (default: 50)
19
+ --title <text> report heading (default: Superagent run report)
20
+ -h, --help show this message`
21
+
22
+ function valueOf(argv, index, flag) {
23
+ const value = argv[index]
24
+ if (value === undefined || value.startsWith('--')) {
25
+ console.error(`${flag} needs a value\n\n${USAGE}`)
26
+ process.exit(2)
27
+ }
28
+ return value
29
+ }
30
+
31
+ function parse(argv) {
32
+ const options = { out: 'superagent-report.html', limit: 50 }
33
+ for (let index = 0; index < argv.length; index++) {
34
+ const arg = argv[index]
35
+ if (arg === '--state-dir') options.stateDir = valueOf(argv, ++index, '--state-dir')
36
+ else if (arg.startsWith('--state-dir=')) options.stateDir = arg.slice('--state-dir='.length)
37
+ else if (arg === '--out') options.out = valueOf(argv, ++index, '--out')
38
+ else if (arg.startsWith('--out=')) options.out = arg.slice('--out='.length)
39
+ else if (arg === '--limit') options.limit = Number(valueOf(argv, ++index, '--limit'))
40
+ else if (arg.startsWith('--limit=')) options.limit = Number(arg.slice('--limit='.length))
41
+ else if (arg === '--title') options.title = valueOf(argv, ++index, '--title')
42
+ else if (arg.startsWith('--title=')) options.title = arg.slice('--title='.length)
43
+ else if (arg === '-h' || arg === '--help') {
44
+ console.log(USAGE)
45
+ process.exit(0)
46
+ } else {
47
+ console.error(`unknown argument: ${arg}\n\n${USAGE}`)
48
+ process.exit(2)
49
+ }
50
+ }
51
+ if (!Number.isInteger(options.limit) || options.limit < 0) {
52
+ console.error(`--limit must be a non-negative integer\n\n${USAGE}`)
53
+ process.exit(2)
54
+ }
55
+ return options
56
+ }
57
+
58
+ const options = parse(process.argv.slice(2))
59
+ const store = createStore(resolveStateRoot(options.stateDir))
60
+ await store.init()
61
+ const runs = await store.list()
62
+ if (runs.length === 0) {
63
+ console.error(`no runs in ${store.root}; start one with the superagent_start tool first`)
64
+ process.exit(1)
65
+ }
66
+
67
+ const selected = options.limit === 0 ? runs : runs.slice(0, options.limit)
68
+ const html = buildReport(selected, { title: options.title, generatedAt: Date.now() })
69
+ const out = path.resolve(options.out)
70
+ try {
71
+ await fsp.mkdir(path.dirname(out), { recursive: true })
72
+ await fsp.writeFile(out, html, 'utf8')
73
+ } catch (error) {
74
+ console.error(`cannot write ${out}: ${error?.message ?? error}`)
75
+ process.exit(1)
76
+ }
77
+
78
+ const size = Buffer.byteLength(html, 'utf8')
79
+ console.log(`wrote ${out} (${(size / 1024).toFixed(1)} kB, ${selected.length} run${selected.length === 1 ? '' : 's'})`)