@xiangyixie/dsh-superagent 0.9.0 → 0.9.2

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,232 +1,259 @@
1
- # Changelog
2
-
3
- ## 0.9.0 — 2026-11-14
4
-
5
- Hardening pass before the first publish. No behaviour change for the happy
6
- path except the new spending caps, the cost line, and two operator utilities.
7
-
8
- ### Published as `@xiangyixie/dsh-superagent`
9
-
10
- - npm already carries a `dsh-super-agent` that its similarity check treats as
11
- the same name as the unscoped one, so the first release goes out under the
12
- author scope. The project, the repository, the plugin row id (`superagent`),
13
- the five tools (`superagent_*`), the state directory, and both bin names are
14
- unchanged; only the install specifier differs:
15
- `dsh plugin --profile web add @xiangyixie/dsh-superagent`.
16
-
17
- ### Watch panel and HTML report
18
-
19
- - `dsh-superagent-watch` draws one line per run — id, status, calls used against
20
- the cap, elapsed, current activity, parent session — in the alternate screen.
21
- A status change repaints within 200 ms; an idle panel costs one small file
22
- read per second. Ctrl-C, SIGTERM, and a closed pipe restore the cursor and
23
- leave the alternate screen; `--once` prints one plain frame and never takes
24
- over the screen.
25
- - `dsh-superagent-report` renders recorded runs into one self-contained HTML
26
- file: inline CSS and inline SVG, no script, no font, no image, no network. It
27
- contains a timeline with each run's start, end, and derived
28
- planning/work/merge phases; swimlanes whose count is the peak concurrency;
29
- cumulative model-call and cost curves; explicit failure, cancellation, and
30
- interruption annotations; and a run table.
31
- - Neither utility adds a dependency. The package is still `dependencies: {}`;
32
- the tarball grows from 11 to 15 files (73.4 kB packed, 240.7 kB unpacked).
33
-
34
- ### Embedding surface (local HTTP)
35
-
36
- - New opt-in `controlPort` exposes the five operations as JSON over loopback:
37
- `GET /`, `GET /health`, `GET /runs`, `GET /runs/:id`, `POST /runs`,
38
- `POST /runs/:id/cancel`, `POST /runs/:id/resume`. Off by default; `0` picks a
39
- free port. Another UI can start and watch runs without importing `lib/`.
40
- - Bound to `127.0.0.1` only, with a per-process bearer token written to
41
- `<stateDir>/control.json` (mode `0600`), a `Host` check that blocks DNS
42
- rebinding, no CORS headers, a 64 KB body cap, and a 60 s limit on receiving a
43
- request (a 300 s long poll is unaffected: the wait happens while the response
44
- is produced).
45
- - Every route goes through the same orchestrator as the tools: quota, budgets,
46
- run locks, cross-process cancel, and recovery behave identically. `POST /runs`
47
- requires `session_id` of a live session; a run still needs a real parent agent
48
- for its children, and a missing session is refused as `no-session` rather than
49
- started without an owner.
50
- - Replies carry the same `text` as the tool result, plus the stored run object
51
- (`schemaVersion: 1`). Transport errors have their own ids (`unauthorized`,
52
- `forbidden-host`, `no-session`, `body-too-large`, …) so a client can tell a
53
- bad token from a broken run.
54
- - The contract, security model, and client examples are in
55
- [docs/embedding.md](https://github.com/LittleChenLiya/dsh-superagent/blob/main/docs/embedding.md);
56
- verified against real `dsh@0.2.2-rc.1` with 17 checks in
57
- `docs/e2e/transcripts/control-plane.log`, plus a two-host cross-process cancel
58
- run in `docs/e2e/transcripts/cross-cancel.log`.
59
- - Review fixes before release: a dispose that lands while the port is still
60
- binding now closes it instead of leaving an orphaned listener; a failed
61
- discovery write closes the server instead of running unreachable; `/health`
62
- does no state work, so a liveness probe cannot reclaim runs; a blank goal is
63
- a 400 `no-goal` and a profile without a subagent service is a 503
64
- `no-subagents` instead of a 500.
65
- - A second review pass added: the plane starts only after the state directory
66
- exists (a fresh `DSH_HOME` used to leave it off for the whole host lifetime);
67
- discovery files carry a per-plane `instanceId`, so a reloaded plugin does not
68
- delete the newer plane's file; a concurrent `start()` shares one listener;
69
- `GET /runs?limit` also limits the returned array; a missing goal is reported
70
- before a missing session; a worker session is refused by `superagent_cancel`
71
- as well; and a malformed `controlPort` (`""`, `" "`, `true`) can no longer
72
- coerce to an accidental listener.
73
-
74
- ### Renamed to `dsh-superagent`
75
-
76
- - The package, repository, plugin row id (`superagent`), default state
77
- directory (`state/superagent`), log prefix, and all five tools
78
- (`superagent_*`) moved from the working name `dsh-longhaul`.
79
- - Nothing was ever published under the old name, so there is no migration and
80
- no compatibility alias: `longhaul_*` calls simply do not exist. A run started
81
- under the old default state directory is still readable by pointing
82
- `stateDir` at it.
83
-
84
- ### Cancellation
85
-
86
- - `superagent_cancel` now stops the run when it is called from a different
87
- process. The caller writes a `<runId>.cancel` marker; the owning process polls
88
- it once per second, aborts its children, disposes their activations, and
89
- records `cancelled`. The caller waits up to 5 s and reports
90
- `cancel requested ... not confirmed` instead of claiming a success it cannot
91
- observe.
92
- - Recovery converts a marked run to `cancelled` rather than `interrupted`, and
93
- `superagent_resume` clears a stale marker.
94
-
95
- ### Spending
96
-
97
- - New hard budgets `maxModelCallsPerRun` (80) and `maxTokensPerRun` (2,000,000),
98
- checked before every child spawn. Hitting one stops spawning: the run ends
99
- `partial` when at least one subtask finished and `failed` when none did, keeps
100
- the reports that did finish, and leaves the rest `pending` for a resume.
101
- - A tool's `max_subtasks` / `max_parallel` / `deadline_minutes` can narrow the
102
- configured cap but never widen it: the config stays the operator's control.
103
- - New `pricing` table (per 1M tokens, per model) and a `cost` field on every
104
- run. Unpriced models are named and excluded instead of being estimated.
105
- - `usage: not recorded` now explains why instead of printing two bare words.
106
-
107
- ### Robustness
108
-
109
- - A run file that is not valid JSON is quarantined as
110
- `<runId>.json.corrupt-<ts>` and skipped by listings; asking for it by id
111
- reports the quarantine path. Stale `.tmp` files (over 10 minutes) and cancel
112
- markers for terminal runs are removed at mount.
113
- - Orphaned runs no longer hold the active-run quota: a run with a heartbeat
114
- older than 90 s is reclaimed, using the owner pid only when the state
115
- directory belongs to this machine, and recording the exact basis on the run.
116
- - Tool errors are now `[error] <sentence>` / `hint: <next step>` /
117
- `detail: <untouched host message>`, covering 19 known failure shapes,
118
- including the Windows ACL sandbox launcher.
119
-
120
- ### Notifications and retention
121
-
122
- - The notify outcome is recorded on the run (`delivered`, `reason`) and shown
123
- by `superagent_status` / `superagent_list` when a finished run could not reach its
124
- session.
125
- - New opt-in `keepRuns` deletes terminal runs older than N days at mount.
126
- `superagent_list` prints the state directory's file count and size.
127
-
128
- ### Concurrency and recovery
129
-
130
- - Mount-time recovery no longer rewrites a run that another process is still
131
- running. Ownership is decided once, in `ownership()`: a fresh heartbeat, a
132
- live local pid, or a live local process holding the run lock all veto
133
- reclamation. Two profiles can share one state directory without overwriting
134
- each other's runs.
135
- - `superagent_resume` is now exclusive. It takes the same serial gate as
136
- `superagent_start`, claims `<runId>.lock` atomically, re-reads the run under
137
- that lock, refuses a run that still has a live owner, and applies the
138
- `maxActiveRuns` check. Two concurrent resumes, or a resume in a second
139
- process, can no longer run the same subtasks twice.
140
- - A lock left by a dead process on this machine is broken immediately; a live
141
- local process keeps its lock however long the run takes; a lock from another
142
- machine is broken after 10 minutes, because its pid cannot be checked.
143
- - `maxActiveRuns` is clamped to an integer (1–8), so a config value such as
144
- `"abc"` falls back to the default instead of making the quota `NaN`.
145
- - A cancel from another process is reported by `superagent_status` as
146
- `cancel requested ... not confirmed` (read from the marker) instead of being
147
- invisible until the owner saves.
148
- - A child whose provider never answers can no longer pin a run in
149
- `planning`/`running`: the spawn is abortable, so cancel and the deadline take
150
- effect, and a child that appears after the abort is disposed at once.
151
- - The terminal status and its notify outcome are written in a single save, so a
152
- reader never sees a finished run without its notify row. Waking the session is
153
- bounded (15 s) and the heartbeat keeps running until the terminal write lands,
154
- so a slow wake-up cannot make another process reclaim a live run.
155
- - Resuming a run now rebuilds `limits` from the current config while keeping
156
- the spend so far, so raising a cap and resuming actually works.
157
- - `runtime`, `saveChains`, and remembered child ids are released when a run
158
- ends instead of growing for the life of the host.
159
-
160
- ### Child safety
161
-
162
- - Children are capped with `maxSubagentDepth: 1` by default (passed to the host
163
- as `maxDepth`); a provider that cannot enforce it fails the start with an
164
- explicit error rather than running unbounded. `childPreset` is the supported
165
- way to narrow a child's tools. dsh 0.2.2-rc.1 has no per-run tool allowlist —
166
- its start request has no tool filter — so the plugin documents that limit
167
- instead of pretending to enforce one.
168
-
169
- ### Real-host end-to-end (2026-11-14)
170
-
171
- The first run against a real `dsh@0.2.2-rc.1` host (keyless stub model, full
172
- record in `docs/e2e-2026-11-14.md`) found four behaviours that the offline
173
- suite could not see:
174
-
175
- - **A graceful host shutdown buried resumable work as `failed`.** When the
176
- `subagents` service disappears mid-run (a one-shot headless turn ends),
177
- children throw "service unavailable". That used to burn both attempts and
178
- settle the run `failed`. It is now recognised as the host going away: the
179
- unfinished subtasks stay `pending`, no attempts are spent, and the run
180
- settles `interrupted` with `note: the host shut down while this run was
181
- active`. `superagent_resume` picks it up in the next host.
182
- - **A dead pid was ignored for 90 s.** `ownership()` trusted a fresh heartbeat
183
- before checking the owner pid, so a `kill -9` left the run `running` for a
184
- minute and a half on the very machine that could prove the pid was gone. On
185
- a run written by this machine, a dead pid now wins over the heartbeat; a run
186
- from another machine on a shared directory still trusts the heartbeat.
187
- - **A reclaimed run claimed its cost was unknown.** Recovery now republishes
188
- `run.usage` from `usageByChild` and recomputes `cost`, so an interrupted run
189
- shows the money already spent instead of "not computed".
190
- - **Per-subtask usage was often `null` after a normal run.** The read at child
191
- completion can race the log flush; the settle pass now writes the final
192
- per-child snapshot back onto each subtask.
193
-
194
- Also: the plugin no longer ships a price for `qwen-flash` (the README already
195
- promised that nothing is priced out of the box); the table is empty unless the
196
- profile configures one.
197
-
198
-
199
- ### Install and first run
200
-
201
- - Requirements corrected to what `dsh@0.2.2-rc.1` needs: Node `>=24.9.0`, and
202
- the default route's `DEEPSEEK_API_KEY` (not a DashScope key).
203
- - Quickstart no longer tells people to `npm i -g dsh` (that is an unrelated
204
- package); it uses `npx @deepseek-ai/dsh@0.2.2-rc.1` and
205
- `dsh plugin --profile web add @xiangyixie/dsh-superagent`.
206
- - `usage: accounting pending` while a run is active; `usage: not recorded` only
207
- on a finished run whose logs are unreadable. `interrupted` runs print the
208
- `superagent_resume` next step, cancelled runs show unstarted subtasks as
209
- `skipped`, and elapsed time separates running time from downtime.
210
- - Pricing keys match `provider/model` exactly, then by bare model name, so a
211
- `qwen-flash` entry also prices `dashscope/qwen-flash`.
212
- - An unusable state directory is reported by every tool instead of appearing as
213
- an empty run list; `ENOENT`/`ENOTDIR` are classified as filesystem errors.
214
- - Missing credentials and unknown model ids have their own classifications and
215
- hints. The auth hint names the default route's key first.
216
- - The plugin mounts even without the `subagents` service (that dependency is
217
- optional), and `superagent_start` then explains what is missing instead of the
218
- five tools silently disappearing.
219
- - `exports` only advertises the plugin entry point; the undocumented internal
220
- subpaths that shipped without types are gone.
221
-
222
- ### Tests
223
-
224
- - 86 offline tests (`npm test`): fake store, fake child spawner, no network, no
225
- API key. Covers cross-process cancel, orphan reclamation in both local and
226
- shared modes, concurrent and cross-process resume, resume quotas and limit
227
- rebuilding, budgets with and without readable usage logs, pricing keys, a
228
- child that ignores abort, notify ordering, corrupted state, a missing state
229
- directory, retention, error text, usage-log reading, the HTTP control plane
230
- (auth, transport errors, discovery lifecycle, start/stop races), and a full
231
- plugin mount. Polling-based tests were rewritten around event gates; five
232
- consecutive full runs pass.
1
+ # Changelog
2
+
3
+ ## 0.9.2 — 2026-11-14
4
+
5
+ Documentation only; no code change. npm renders the README from the tarball, so
6
+ this version exists to put the rewritten opening on the package page.
7
+
8
+ - The first screen now answers three questions in order: what the plugin is for,
9
+ when it is the wrong tool, and the first command to run after installing.
10
+ - `Naming` moved from the top to just above `Development`. The copyright line
11
+ and the "personal project, not affiliated with DeepSeek" statement moved to
12
+ the top, where they are read.
13
+ - `Known limits` gained the isolation boundary: children use the host's
14
+ credentials and filesystem and are only as sandboxed as the host makes them.
15
+
16
+ ## 0.9.1 — 2026-11-14
17
+
18
+ Metadata-only release. No code or behaviour change; the only file contents that
19
+ differ are `package.json`, `README.md`, and this changelog.
20
+
21
+ - Added the `author` field (`Admire (LittleChenLiya)`), matching the copyright
22
+ line in `LICENSE`. The registry metadata carries it from this version on
23
+ (`npm view @xiangyixie/dsh-superagent author`); the npmjs.com package page has
24
+ no separate Author row in its current layout — it lists Collaborators — so the
25
+ visible credit is the copyright line in the README's License section.
26
+ - The README "License" section now names the copyright holder, links
27
+ `LICENSE`, and says that the npm scope `@xiangyixie` and the GitHub account
28
+ `LittleChenLiya` are the same author.
29
+
30
+ ## 0.9.0 — 2026-11-14
31
+
32
+ Hardening pass before the first publish. No behaviour change for the happy
33
+ path except the new spending caps, the cost line, and two operator utilities.
34
+
35
+ ### Published as `@xiangyixie/dsh-superagent`
36
+
37
+ - npm already carries a `dsh-super-agent` that its similarity check treats as
38
+ the same name as the unscoped one, so the first release goes out under the
39
+ author scope. The project, the repository, the plugin row id (`superagent`),
40
+ the five tools (`superagent_*`), the state directory, and both bin names are
41
+ unchanged; only the install specifier differs:
42
+ `dsh plugin --profile web add @xiangyixie/dsh-superagent`.
43
+
44
+ ### Watch panel and HTML report
45
+
46
+ - `dsh-superagent-watch` draws one line per run — id, status, calls used against
47
+ the cap, elapsed, current activity, parent session — in the alternate screen.
48
+ A status change repaints within 200 ms; an idle panel costs one small file
49
+ read per second. Ctrl-C, SIGTERM, and a closed pipe restore the cursor and
50
+ leave the alternate screen; `--once` prints one plain frame and never takes
51
+ over the screen.
52
+ - `dsh-superagent-report` renders recorded runs into one self-contained HTML
53
+ file: inline CSS and inline SVG, no script, no font, no image, no network. It
54
+ contains a timeline with each run's start, end, and derived
55
+ planning/work/merge phases; swimlanes whose count is the peak concurrency;
56
+ cumulative model-call and cost curves; explicit failure, cancellation, and
57
+ interruption annotations; and a run table.
58
+ - Neither utility adds a dependency. The package is still `dependencies: {}`;
59
+ the tarball grows from 11 to 15 files (73.4 kB packed, 240.7 kB unpacked).
60
+
61
+ ### Embedding surface (local HTTP)
62
+
63
+ - New opt-in `controlPort` exposes the five operations as JSON over loopback:
64
+ `GET /`, `GET /health`, `GET /runs`, `GET /runs/:id`, `POST /runs`,
65
+ `POST /runs/:id/cancel`, `POST /runs/:id/resume`. Off by default; `0` picks a
66
+ free port. Another UI can start and watch runs without importing `lib/`.
67
+ - Bound to `127.0.0.1` only, with a per-process bearer token written to
68
+ `<stateDir>/control.json` (mode `0600`), a `Host` check that blocks DNS
69
+ rebinding, no CORS headers, a 64 KB body cap, and a 60 s limit on receiving a
70
+ request (a 300 s long poll is unaffected: the wait happens while the response
71
+ is produced).
72
+ - Every route goes through the same orchestrator as the tools: quota, budgets,
73
+ run locks, cross-process cancel, and recovery behave identically. `POST /runs`
74
+ requires `session_id` of a live session; a run still needs a real parent agent
75
+ for its children, and a missing session is refused as `no-session` rather than
76
+ started without an owner.
77
+ - Replies carry the same `text` as the tool result, plus the stored run object
78
+ (`schemaVersion: 1`). Transport errors have their own ids (`unauthorized`,
79
+ `forbidden-host`, `no-session`, `body-too-large`, …) so a client can tell a
80
+ bad token from a broken run.
81
+ - The contract, security model, and client examples are in
82
+ [docs/embedding.md](https://github.com/LittleChenLiya/dsh-superagent/blob/main/docs/embedding.md);
83
+ verified against real `dsh@0.2.2-rc.1` with 17 checks in
84
+ `docs/e2e/transcripts/control-plane.log`, plus a two-host cross-process cancel
85
+ run in `docs/e2e/transcripts/cross-cancel.log`.
86
+ - Review fixes before release: a dispose that lands while the port is still
87
+ binding now closes it instead of leaving an orphaned listener; a failed
88
+ discovery write closes the server instead of running unreachable; `/health`
89
+ does no state work, so a liveness probe cannot reclaim runs; a blank goal is
90
+ a 400 `no-goal` and a profile without a subagent service is a 503
91
+ `no-subagents` instead of a 500.
92
+ - A second review pass added: the plane starts only after the state directory
93
+ exists (a fresh `DSH_HOME` used to leave it off for the whole host lifetime);
94
+ discovery files carry a per-plane `instanceId`, so a reloaded plugin does not
95
+ delete the newer plane's file; a concurrent `start()` shares one listener;
96
+ `GET /runs?limit` also limits the returned array; a missing goal is reported
97
+ before a missing session; a worker session is refused by `superagent_cancel`
98
+ as well; and a malformed `controlPort` (`""`, `" "`, `true`) can no longer
99
+ coerce to an accidental listener.
100
+
101
+ ### Renamed to `dsh-superagent`
102
+
103
+ - The package, repository, plugin row id (`superagent`), default state
104
+ directory (`state/superagent`), log prefix, and all five tools
105
+ (`superagent_*`) moved from the working name `dsh-longhaul`.
106
+ - Nothing was ever published under the old name, so there is no migration and
107
+ no compatibility alias: `longhaul_*` calls simply do not exist. A run started
108
+ under the old default state directory is still readable by pointing
109
+ `stateDir` at it.
110
+
111
+ ### Cancellation
112
+
113
+ - `superagent_cancel` now stops the run when it is called from a different
114
+ process. The caller writes a `<runId>.cancel` marker; the owning process polls
115
+ it once per second, aborts its children, disposes their activations, and
116
+ records `cancelled`. The caller waits up to 5 s and reports
117
+ `cancel requested ... not confirmed` instead of claiming a success it cannot
118
+ observe.
119
+ - Recovery converts a marked run to `cancelled` rather than `interrupted`, and
120
+ `superagent_resume` clears a stale marker.
121
+
122
+ ### Spending
123
+
124
+ - New hard budgets `maxModelCallsPerRun` (80) and `maxTokensPerRun` (2,000,000),
125
+ checked before every child spawn. Hitting one stops spawning: the run ends
126
+ `partial` when at least one subtask finished and `failed` when none did, keeps
127
+ the reports that did finish, and leaves the rest `pending` for a resume.
128
+ - A tool's `max_subtasks` / `max_parallel` / `deadline_minutes` can narrow the
129
+ configured cap but never widen it: the config stays the operator's control.
130
+ - New `pricing` table (per 1M tokens, per model) and a `cost` field on every
131
+ run. Unpriced models are named and excluded instead of being estimated.
132
+ - `usage: not recorded` now explains why instead of printing two bare words.
133
+
134
+ ### Robustness
135
+
136
+ - A run file that is not valid JSON is quarantined as
137
+ `<runId>.json.corrupt-<ts>` and skipped by listings; asking for it by id
138
+ reports the quarantine path. Stale `.tmp` files (over 10 minutes) and cancel
139
+ markers for terminal runs are removed at mount.
140
+ - Orphaned runs no longer hold the active-run quota: a run with a heartbeat
141
+ older than 90 s is reclaimed, using the owner pid only when the state
142
+ directory belongs to this machine, and recording the exact basis on the run.
143
+ - Tool errors are now `[error] <sentence>` / `hint: <next step>` /
144
+ `detail: <untouched host message>`, covering 19 known failure shapes,
145
+ including the Windows ACL sandbox launcher.
146
+
147
+ ### Notifications and retention
148
+
149
+ - The notify outcome is recorded on the run (`delivered`, `reason`) and shown
150
+ by `superagent_status` / `superagent_list` when a finished run could not reach its
151
+ session.
152
+ - New opt-in `keepRuns` deletes terminal runs older than N days at mount.
153
+ `superagent_list` prints the state directory's file count and size.
154
+
155
+ ### Concurrency and recovery
156
+
157
+ - Mount-time recovery no longer rewrites a run that another process is still
158
+ running. Ownership is decided once, in `ownership()`: a fresh heartbeat, a
159
+ live local pid, or a live local process holding the run lock all veto
160
+ reclamation. Two profiles can share one state directory without overwriting
161
+ each other's runs.
162
+ - `superagent_resume` is now exclusive. It takes the same serial gate as
163
+ `superagent_start`, claims `<runId>.lock` atomically, re-reads the run under
164
+ that lock, refuses a run that still has a live owner, and applies the
165
+ `maxActiveRuns` check. Two concurrent resumes, or a resume in a second
166
+ process, can no longer run the same subtasks twice.
167
+ - A lock left by a dead process on this machine is broken immediately; a live
168
+ local process keeps its lock however long the run takes; a lock from another
169
+ machine is broken after 10 minutes, because its pid cannot be checked.
170
+ - `maxActiveRuns` is clamped to an integer (1–8), so a config value such as
171
+ `"abc"` falls back to the default instead of making the quota `NaN`.
172
+ - A cancel from another process is reported by `superagent_status` as
173
+ `cancel requested ... not confirmed` (read from the marker) instead of being
174
+ invisible until the owner saves.
175
+ - A child whose provider never answers can no longer pin a run in
176
+ `planning`/`running`: the spawn is abortable, so cancel and the deadline take
177
+ effect, and a child that appears after the abort is disposed at once.
178
+ - The terminal status and its notify outcome are written in a single save, so a
179
+ reader never sees a finished run without its notify row. Waking the session is
180
+ bounded (15 s) and the heartbeat keeps running until the terminal write lands,
181
+ so a slow wake-up cannot make another process reclaim a live run.
182
+ - Resuming a run now rebuilds `limits` from the current config while keeping
183
+ the spend so far, so raising a cap and resuming actually works.
184
+ - `runtime`, `saveChains`, and remembered child ids are released when a run
185
+ ends instead of growing for the life of the host.
186
+
187
+ ### Child safety
188
+
189
+ - Children are capped with `maxSubagentDepth: 1` by default (passed to the host
190
+ as `maxDepth`); a provider that cannot enforce it fails the start with an
191
+ explicit error rather than running unbounded. `childPreset` is the supported
192
+ way to narrow a child's tools. dsh 0.2.2-rc.1 has no per-run tool allowlist —
193
+ its start request has no tool filter — so the plugin documents that limit
194
+ instead of pretending to enforce one.
195
+
196
+ ### Real-host end-to-end (2026-11-14)
197
+
198
+ The first run against a real `dsh@0.2.2-rc.1` host (keyless stub model, full
199
+ record in `docs/e2e-2026-11-14.md`) found four behaviours that the offline
200
+ suite could not see:
201
+
202
+ - **A graceful host shutdown buried resumable work as `failed`.** When the
203
+ `subagents` service disappears mid-run (a one-shot headless turn ends),
204
+ children throw "service unavailable". That used to burn both attempts and
205
+ settle the run `failed`. It is now recognised as the host going away: the
206
+ unfinished subtasks stay `pending`, no attempts are spent, and the run
207
+ settles `interrupted` with `note: the host shut down while this run was
208
+ active`. `superagent_resume` picks it up in the next host.
209
+ - **A dead pid was ignored for 90 s.** `ownership()` trusted a fresh heartbeat
210
+ before checking the owner pid, so a `kill -9` left the run `running` for a
211
+ minute and a half on the very machine that could prove the pid was gone. On
212
+ a run written by this machine, a dead pid now wins over the heartbeat; a run
213
+ from another machine on a shared directory still trusts the heartbeat.
214
+ - **A reclaimed run claimed its cost was unknown.** Recovery now republishes
215
+ `run.usage` from `usageByChild` and recomputes `cost`, so an interrupted run
216
+ shows the money already spent instead of "not computed".
217
+ - **Per-subtask usage was often `null` after a normal run.** The read at child
218
+ completion can race the log flush; the settle pass now writes the final
219
+ per-child snapshot back onto each subtask.
220
+
221
+ Also: the plugin no longer ships a price for `qwen-flash` (the README already
222
+ promised that nothing is priced out of the box); the table is empty unless the
223
+ profile configures one.
224
+
225
+
226
+ ### Install and first run
227
+
228
+ - Requirements corrected to what `dsh@0.2.2-rc.1` needs: Node `>=24.9.0`, and
229
+ the default route's `DEEPSEEK_API_KEY` (not a DashScope key).
230
+ - Quickstart no longer tells people to `npm i -g dsh` (that is an unrelated
231
+ package); it uses `npx @deepseek-ai/dsh@0.2.2-rc.1` and
232
+ `dsh plugin --profile web add @xiangyixie/dsh-superagent`.
233
+ - `usage: accounting pending` while a run is active; `usage: not recorded` only
234
+ on a finished run whose logs are unreadable. `interrupted` runs print the
235
+ `superagent_resume` next step, cancelled runs show unstarted subtasks as
236
+ `skipped`, and elapsed time separates running time from downtime.
237
+ - Pricing keys match `provider/model` exactly, then by bare model name, so a
238
+ `qwen-flash` entry also prices `dashscope/qwen-flash`.
239
+ - An unusable state directory is reported by every tool instead of appearing as
240
+ an empty run list; `ENOENT`/`ENOTDIR` are classified as filesystem errors.
241
+ - Missing credentials and unknown model ids have their own classifications and
242
+ hints. The auth hint names the default route's key first.
243
+ - The plugin mounts even without the `subagents` service (that dependency is
244
+ optional), and `superagent_start` then explains what is missing instead of the
245
+ five tools silently disappearing.
246
+ - `exports` only advertises the plugin entry point; the undocumented internal
247
+ subpaths that shipped without types are gone.
248
+
249
+ ### Tests
250
+
251
+ - 86 offline tests (`npm test`): fake store, fake child spawner, no network, no
252
+ API key. Covers cross-process cancel, orphan reclamation in both local and
253
+ shared modes, concurrent and cross-process resume, resume quotas and limit
254
+ rebuilding, budgets with and without readable usage logs, pricing keys, a
255
+ child that ignores abort, notify ordering, corrupted state, a missing state
256
+ directory, retention, error text, usage-log reading, the HTTP control plane
257
+ (auth, transport errors, discovery lifecycle, start/stop races), and a full
258
+ plugin mount. Polling-based tests were rewritten around event gates; five
259
+ consecutive full runs pass.
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.