@xiangyixie/dsh-superagent 0.0.0-stage → 0.9.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 ADDED
@@ -0,0 +1,232 @@
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.
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.