@xiangyixie/dsh-superagent 0.0.0-stage → 0.9.1

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