@xiangyixie/dsh-superagent 0.10.0 → 0.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,4 +1,4 @@
1
- # Changelog
1
+ # Changelog
2
2
 
3
3
  Doc-only releases: npm serves the README from the tarball, so a README edit is
4
4
  invisible on the package page until something is published. When the edit
@@ -8,93 +8,291 @@ along with the next code release. A doc-only version leaves `lib/` and `bin/`
8
8
  byte-identical to the version before it, and the pinned install line in the
9
9
  README is updated to the version being released.
10
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
-
11
+ ## 0.12.0 — 2026-11-15
12
+
13
+ ### Added
14
+
15
+ - **Worker safety guard.** Child tool calls are now checked on the host's
16
+ `tools/pre-execute` / `ctx.tools.guard` pipeline. Writes are limited to the
17
+ child's workspace and the OS temp directory; credential stores and
18
+ `.git/config` / `.git/hooks` are refused for reading and writing; system
19
+ directories are refused for writing. Default command rules block disk
20
+ formatting, system scheduler and registry changes, writes into system
21
+ directories, destructive recursive deletes whose target is `/`, `~`, `.`,
22
+ `..`, a wildcard, or outside the workspace, permission nukes, and commands
23
+ that name a credential store. `guard.allowCommands` is an explicit,
24
+ audited override. Blocked calls surface in `superagent_status` and in a
25
+ `## Safety guard` report section. See “Worker safety guard” in the README
26
+ for the full defaults and their rationale.
27
+ - **Permission policy.** `<stateDir>/policy.json` (or `policyFile`) lets a person
28
+ say which paths may be written, which commands may run, which action classes
29
+ need a human, and what the default level is per run. The file accepts `//`,
30
+ `#`, and `/* */` comments, validates against a schema, and reports every
31
+ problem with file, line, and column. It only tightens: deny wins, explicit
32
+ allow entries record what they relaxed, and an invalid policy fails closed. A
33
+ start the policy denies is refused before any run record exists; a start held
34
+ for confirmation needs `approve_policy: true`, which is logged.
35
+ - **Audit trail.** Append-only JSONL at `<stateDir>/audit/audit.jsonl`: tool
36
+ calls, path writes, commands, blocks, approvals, attention decisions, and run
37
+ lifecycle, each with run id, subtask id, actor, timestamp, decision, result,
38
+ and duration. Appends are serialized in-process and locked across processes;
39
+ a torn tail or a damaged line is reported and skipped instead of hiding the
40
+ log. `audit: false` turns the trail off without changing run behaviour.
41
+ - **`superagent_audit`** queries by run, subtask, kind, decision, result, target,
42
+ and time window, and exports the matching events as one JSONL or CSV file.
43
+ - `createAuditor(...).attachGuard(fn)` is the seam for a separate path/command
44
+ guard: it can tighten a decision, never relax one.
45
+ - `superagent_inject(run_id, message, subtask_index?, wait_seconds?)` steers a
46
+ running child instead of waiting for the next prompt. It calls the host's
47
+ documented live channel (`subagents.sendMessage`, which lands in the same
48
+ `Agent` inbox that `steer`/`inject` expose), so the message is claimed at the
49
+ child's next pre-step and becomes part of its next model request. A child
50
+ that had already decided to stop runs one more turn to read it. Receipts
51
+ record `latencyMs` from acceptance to the claim, or a `missedReason` when the
52
+ child is cancelled, disposed, or finishes before another boundary. On a real
53
+ `dsh@0.2.2-rc.1` host the measured delay was 2986 ms with a 4 s child step
54
+ and 6978 ms with an 8 s step, i.e. bounded by the remainder of the running
55
+ step, not by the plugin. A host without that channel degrades to the followup
56
+ queue and the reply labels it as such.
57
+ - **Multi-device sync over git.** `dsh-superagent-sync` turns the state
58
+ directory into a repository and carries it between machines through any git
59
+ remote — no server, no account, no dependency. `init <remote>` writes a
60
+ managed `.gitignore` block (credentials, locks, cancel markers, quarantine
61
+ files, temp files, logs, machine identity) and makes the first commit;
62
+ `pull` fetches and merges, stashing uncommitted local work first and saying
63
+ so; `push` commits local state and pushes, reporting a rejection instead of
64
+ forcing; `status` reports ahead/behind counts, uncommitted files, stashes,
65
+ and conflicted paths. A conflict stops the merge with both sides kept and the
66
+ paths listed — nothing is resolved automatically. Run records were already
67
+ one file per run, so ordinary concurrent work on two machines does not
68
+ collide; the remaining shared surface is an append-only memory scope. The
69
+ README documents the limits: no realtime channel, no cross-machine lock, no
70
+ key distribution.
71
+ - **Local workspace panel.** `workbenchPort` (off by default, loopback only)
72
+ serves an IDE-shaped page from `public/workbench.html`: file tree, text editor,
73
+ diff preview before save, and a run view that lists the files a run changed.
74
+ The plugin reads and edits the filesystem itself, so no host API is involved.
75
+ Every request needs the per-process bearer token in `workbench.json`; absolute
76
+ paths, traversal, symlinks out of the root, the state directory, binaries, and
77
+ files above 512 KB are refused with a reason. Saving requires the hash and
78
+ mtime the editor read, so an external edit is never overwritten.
79
+ - `dsh-superagent-workbench` runs the same panel standalone, with `--root`,
80
+ `--port`, and `--state-dir`; no host is required.
81
+ - Run records now carry `changes` (recorded when the panel is on), which is what
82
+ the panel's run view reads and diffs against `git HEAD`.
83
+
84
+ ## 0.11.0 — 2026-11-15
85
+
86
+ Runs became something you can talk back to and shape: instructions and answers
87
+ reach a run that already exists, planned subtasks can depend on each other,
88
+ workers can be isolated in their own worktrees, and the panel and report show
89
+ parallel structure instead of opaque rows. Runs are now priced down to the
90
+ subtask, spending is kept in a ledger, common goals start from a template, and
91
+ an install can check itself. No runtime dependencies were added, and the package
92
+ still ships one file per module from `lib/`.
93
+
94
+ ### Added
95
+
96
+ - **Direct mode.** `superagent_start` takes `mode: "direct"`: one worker does the
97
+ whole goal, with no planner, no aggregation, and no self-heal round, and its
98
+ reply becomes the report verbatim. The run record, quota, deadline, cancel,
99
+ budget, milestones, and per-child usage accounting are identical to a planned
100
+ run. `mode: "planned"` is the default and unchanged.
101
+ - **Queueing instead of a hard failure.** `superagent_start` takes
102
+ `queue: true`: when `maxActiveRuns` is in use the run returns
103
+ `status: "queued"` with `queue.position` / `queue.of`, and starts automatically
104
+ when an active run finishes. Waiting runs do not count against
105
+ `maxActiveRuns`, are persisted with an owner heartbeat, start oldest first, and
106
+ renumber when one is cancelled. `maxQueuedRuns` (default 5, 0 disables) caps the
107
+ line and `queueTimeoutMinutes` (default 30) fails a run that never got a slot,
108
+ without spending anything. `queueOnFull: true` makes queueing the default for
109
+ every start; without it a start that does not pass `queue: true` still gets the
110
+ speed quota error.
111
+ - **Relevance-ranked memory recall.** `superagent_memory` takes
112
+ `action: "search"` with `query` and/or `tags`; a new note supersedes the older
113
+ one with the same key, and the planner digest now ranks notes against the run's
114
+ goal instead of only taking the newest ones.
115
+ - `superagent_followup(run_id, message)` appends an instruction to an active
116
+ run. It stays next-prompt by design: the next worker spawn or the aggregation
117
+ carries it, whichever comes first, and subtasks already running or finished
118
+ keep their results. Each instruction records `appliedAt` / `appliedAtStage`,
119
+ or `missedAt` with a reason when the run settled before another boundary ran.
120
+ A paused run keeps the instruction for its next resume; a completed run
121
+ refuses it. A run owned by another process is refused rather than written,
122
+ because that owner's next save would erase it.
123
+ - `superagent_answer(run_id, attention_id?, answer, wait_seconds?)` answers one
124
+ structured attention item. Attention items now carry stable ids (`q1`, `q2`, …)
125
+ from a per-run counter; the answer is recorded on that item and the run
126
+ continues — an active run at its next boundary, a terminal run by reopening so
127
+ its aggregation runs again with the decision. A question retired by a resume
128
+ is archived to `attentionHistory` with `expiredAt`, so a late answer is
129
+ refused as expired instead of being matched to whatever is open now. Unknown
130
+ ids, already answered questions, and an answer whose text is another
131
+ question's option are refused with the id to use instead.
132
+ - **Per-worker workspace isolation.** `workspaceIsolation: true` gives every
133
+ worker its own git worktree on `superagent/<runId>-w<n>`, harvested into a
134
+ commit and merged back into the main checkout one at a time. A conflict aborts
135
+ the merge, keeps both branches, and is reported by status and the wake-up
136
+ message. When isolation is unavailable the run continues in the shared
137
+ directory and says so.
138
+ - **Dependency-aware plans.** The planner may give a subtask an id and a
139
+ `dependsOn` list. The dependent waits (`waiting`) instead of starting, and its
140
+ prompt carries the finished dependency's report; independent subtasks still
141
+ run in parallel. A dependency on an undeclared task is `skipped` with the
142
+ reason, a failure skips everything downstream instead of reporting it as done,
143
+ and a cycle rejects the plan before any subtask starts. Status, notifications,
144
+ and reports distinguish waiting from running.
145
+ - **Parallel structure in the panel and the report.** Runs alive at the same
146
+ moment share a numbered gutter in `watch`, so concurrent work is visible as a
147
+ group, and a waiting row leads with the run holding its slot and its queue
148
+ position. The HTML report lists each worker's retry chain and its share of the
149
+ run's wall clock next to the outcome.
150
+ - **Documentation site.** `docs/site/` holds a quickstart, a comparison page,
151
+ and a single-file landing page; nothing in `lib/` changed for it.
152
+ - **Per-run and per-subtask pricing.** `pricing` in the plugin config maps a
153
+ model to input/output prices per million tokens. Every run and every subtask
154
+ now carries a `cost` with micro-unit totals, and status, the panel, and the
155
+ report print it (`cost ¥0.3519+`). A model absent from the table is reported as
156
+ `unpriced` — never as `0.0000`, and a total that mixes priced and unpriced work
157
+ is printed with a trailing `+` so it cannot be read as complete.
158
+ - **Spend ledger.** `lib/ledger.js` keeps a durable per-run spend record, mounted
159
+ from settled runs so a restart backfills what no tool was watching, and
160
+ `superagent_status` reports the rolling spend and how many runs in the window
161
+ were only partially priced.
162
+ - **Workflow templates.** `superagent_template` lists, shows, and expands a
163
+ reusable goal template (built-ins plus files under the template directory), so
164
+ a common goal is expanded into its steps instead of being retyped. Templates
165
+ are optional: a template directory that cannot be created is logged and the
166
+ run tools keep working.
167
+ - **Install self-check.** `dsh-superagent-doctor` reports, without installing or
168
+ editing anything, whether every imported file is in the `files` whitelist and
169
+ on disk, whether the installed copy matches its published tarball, whether the
170
+ profile registers the bundle row, and whether all nine tools are registered.
171
+ Every failure prints the command that fixes it. `npm test` also asserts that
172
+ `npm pack --dry-run` ships every file reachable from the entry points
173
+ (`scripts/check-pack.mjs`), which is the check the 0.9.x tarball lacked.
174
+ - **Run archives.** `dsh-superagent-archive` (`bin/archive.js`) adds three
175
+ subcommands. `prune` lists terminal runs older than `--older-than <days>`,
176
+ optionally filtered by `--status`, with the files and bytes it would remove;
177
+ it deletes nothing unless `--confirm` is given, and it never touches a run
178
+ that is still active or whose `.lock` another process holds. `export` writes
179
+ one run as a self-contained directory (README with the report, `report.md`,
180
+ `run.json`, per-subtask markdown and JSON, guard records, `usage.json`, and a
181
+ manifest with a SHA-256 per file), as one JSON bundle, or as one offline HTML
182
+ page with the bundle embedded. `import` reads any of those back into the
183
+ store and refuses to overwrite a local run with the same id. `store.js` gained
184
+ `planPrune`, `buildArchive`, `exportRun`, and `importRun`; `prune` gained
185
+ `dryRun` and `statuses` and now returns the plan alongside `removed`. No
186
+ runtime dependency was added.
187
+ - New config: `queueOnFull`, `maxQueuedRuns`, `queueTimeoutMinutes`,
188
+ `workspaceIsolation`, `workspaceRoot`, `pricing`.
189
+
190
+ ### Changed
191
+
192
+ - A single completed subtask still short-circuits aggregation, unless the run
193
+ has instructions or answers: then the aggregation prompt is built, because
194
+ otherwise reopening the run would return the old report and silently drop the
195
+ decision.
196
+ - `superagent_resume` reopens a `completed` run only when it holds an answer
197
+ that never reached a prompt; every other completed run keeps its existing
198
+ no-op behaviour. Without this, an answer that could not be applied (quota or
199
+ lock) would be stranded behind a "resume the run" instruction that did
200
+ nothing.
201
+ - Status prints the attention id, any recorded answer, and how many instructions
202
+ were applied, are waiting, or never took effect; notifications lead with the
203
+ question id so `superagent_answer` can be called directly.
204
+
205
+
206
+
207
+
208
+
209
+ ## 0.10.0 — 2026-11-15
210
+
211
+ The dispatch, progress, delivery, and memory layer. No runtime dependencies were
212
+ added, and the package still ships one file per module from `lib/`.
213
+
214
+ ### Added
215
+
216
+ - **Cross-run memory.** `<stateDir>/memory/<scope>.jsonl` keeps short notes the
217
+ aggregator writes (`decision`, `pitfall`, `next`, `dispatch`, `note`) plus the
218
+ six most recent runs derived from the run store. The digest is bounded
219
+ (12 notes / 1600 characters / 2600 characters total), compacted above 400
220
+ lines or 128 KB, and injected into the planner and aggregator prompts. A newer
221
+ note with the same key supersedes an older one, `forget` retracts it, and
222
+ notes older than 30 days expire. Secrets are redacted before storage; the
223
+ directory carries its own `.gitignore` and is never in the package.
224
+ - Added `superagent_memory` (`list`, `set`, `forget`). Existing tools keep their
225
+ arguments and output; this is the sixth tool.
226
+ - **Layered memory.** `rules` and `profile` scopes are read into planning and
227
+ aggregation ahead of the run scope; `superagent_memory` takes `scope`. A run
228
+ only writes its own scope, so a model cannot overwrite a project rule.
229
+ - **Duplicate dispatch is collapsed.** The same active goal (case and whitespace
230
+ ignored) returns the existing run id with `deduped: true`, under a per-goal
231
+ claim so two processes sharing a state directory cannot both start it. The
232
+ match is scoped to the owning session, so two sessions that ask for the same
233
+ generic goal still get their own runs. `allow_duplicate: true` on
234
+ `superagent_start` (or `allow_duplicate` on the control `start` body) opts
235
+ out. A `wait_seconds` call keeps the `deduped` marker in its result.
236
+ - **Transient backoff.** A rate-limit, quota, timeout, or 5xx failure now waits
237
+ 2s, then 4s, then 8s before the next attempt instead of retrying immediately.
238
+ - **Recovery note.** A resumed run tells each worker what failed and instructs it
239
+ to inspect files, `git status`, `git log`, and remote state before repeating an
240
+ externally visible action.
241
+ - **Structured attention.** A worker or the aggregator may append one fenced
242
+ `attention` block. It is stripped from the report, stored as `attention.items`,
243
+ shown as `needs your decision:` in status, and leads the notification.
244
+ - **Attention text is bounded.** Question, options, and reason are collapsed to
245
+ one line and capped at 500 / 200 / 300 characters, so neither status nor a
246
+ notification can be given forged extra lines. An invalid attention block is
247
+ not stripped silently: its raw text stays in the report and status prints
248
+ `attention: <reason>`.
249
+ - **Milestones.** `plan_ready`, `running`, `aggregating`, and `settled` are
250
+ recorded with timestamps and shown in `superagent_status`; nothing is pushed.
251
+ - **Report file.** A terminal report is written atomically to
252
+ `<stateDir>/reports/<runId>.md` (directory carries `.gitignore: *`), recorded
253
+ in `run.artifacts`, and shown in status. `keepRuns` pruning removes it together
254
+ with the run record.
255
+ - **Quiet by default.** Only a delivered, failed, or partially finished run may
256
+ wake the session; a cancelled run never does, and progress is never pushed.
257
+ `maxNotificationsPerHour` (default 3) buffers extra runs into one summary.
258
+ - **Notification outbox.** A refused wake-up is retried with backoff
259
+ (`notifyRetries`, `notifyRetryDelayMs`) and messages for one session stay in
260
+ order. A buffered batch is put back into `pending` when the send fails, so a
261
+ later message still carries those runs; it is dropped only after three failed
262
+ deliveries.
263
+ - **Self-heal before reporting.** A subtask failure that looks transient
264
+ (quota, rate limit, timeout, 5xx) gets `autoResumeRounds` (default 1) more
265
+ rounds, optionally on `childModelFallback`. The failure message now says what
266
+ was tried, and `self-heal:` appears in `superagent_status`.
267
+ - **`memoryMaxEntries` is a compaction trigger.** Exceeding it, 400 lines, or
268
+ 128 KB compacts the notebook on the next write.
269
+ - New config: `memory`, `memoryScope`, `memoryMaxEntries`, `memoryMaxAgeDays`,
270
+ `memoryDigestEntries`, `memoryDigestChars`, `maxNotificationsPerHour`,
271
+ `notifyRetries`, `notifyRetryDelayMs`, `autoResumeRounds`,
272
+ `childModelFallback`.
273
+
274
+ ### Changed
275
+
276
+ - **A resume is never refused by the concurrency quota.** A `superagent_resume`
277
+ only finishes work that already exists, so it is not counted against
278
+ `maxActiveRuns` and works even when the cap is full; only `superagent_start`
279
+ creates new spend and is subject to the cap. The resume is still
280
+ session-scoped: it may only be issued by the session named in the run's
281
+ `parentSessionId`. `force` (`force` or `override_quota` over HTTP) is still
282
+ accepted so an existing caller keeps working, but it no longer changes
283
+ anything.
284
+ - `superagent_status` gained the milestone line, the attention line, and the
285
+ report file path; `superagent_start` gained `allow_duplicate`; the control
286
+ `start` body gained `allow_duplicate`, and `resume` still accepts `force`.
287
+
288
+ ### Fixed
289
+
290
+ - Memory, notification, and report-artifact writes are fail-open or retried, so
291
+ a transient filesystem error cannot turn a finished run into a failed one; a
292
+ report that is already written stays on disk and is listed in status.
293
+ - Test suite: 168 tests, 0 failures; `npm test` and `node --test` discovery
294
+ agree.
295
+
98
296
  ## 0.9.3 — 2026-11-14
99
297
 
100
298
  Documentation only; no code change.