@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 +109 -0
- package/LICENSE +21 -21
- package/README.md +181 -28
- package/bin/report.js +79 -79
- package/bin/watch.js +57 -57
- package/cordis.patch.yml +9 -9
- package/lib/control.js +495 -494
- package/lib/errors.js +205 -199
- package/lib/index.js +1104 -822
- package/lib/lock.js +107 -0
- package/lib/memory.js +503 -0
- package/lib/notify.js +257 -0
- package/lib/orchestrator.js +670 -16
- package/lib/report.js +733 -733
- package/lib/store.js +402 -385
- package/lib/usage.js +152 -152
- package/lib/watch.js +458 -458
- package/package.json +5 -2
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
|
|
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
|
|
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
|
-
|
|
83
|
-
|
|
84
|
-
|
|
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`
|
|
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` |
|
|
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.
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
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`,
|
|
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
|
-
|
|
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
|
-
###
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
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,
|
|
477
|
-
removed ids are logged
|
|
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
|
|
562
|
-
`superagent_
|
|
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'})`)
|