@xiangyixie/dsh-superagent 0.10.0 → 0.11.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
@@ -8,93 +8,216 @@ 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.11.0 — 2026-11-15
12
+
13
+ Runs became something you can talk back to and shape: instructions and answers
14
+ reach a run that already exists, planned subtasks can depend on each other,
15
+ workers can be isolated in their own worktrees, and the panel and report show
16
+ parallel structure instead of opaque rows. Runs are now priced down to the
17
+ subtask, spending is kept in a ledger, common goals start from a template, and
18
+ an install can check itself. No runtime dependencies were added, and the package
19
+ still ships one file per module from `lib/`.
20
+
21
+ ### Added
22
+
23
+ - **Direct mode.** `superagent_start` takes `mode: "direct"`: one worker does the
24
+ whole goal, with no planner, no aggregation, and no self-heal round, and its
25
+ reply becomes the report verbatim. The run record, quota, deadline, cancel,
26
+ budget, milestones, and per-child usage accounting are identical to a planned
27
+ run. `mode: "planned"` is the default and unchanged.
28
+ - **Queueing instead of a hard failure.** `superagent_start` takes
29
+ `queue: true`: when `maxActiveRuns` is in use the run returns
30
+ `status: "queued"` with `queue.position` / `queue.of`, and starts automatically
31
+ when an active run finishes. Waiting runs do not count against
32
+ `maxActiveRuns`, are persisted with an owner heartbeat, start oldest first, and
33
+ renumber when one is cancelled. `maxQueuedRuns` (default 5, 0 disables) caps the
34
+ line and `queueTimeoutMinutes` (default 30) fails a run that never got a slot,
35
+ without spending anything. `queueOnFull: true` makes queueing the default for
36
+ every start; without it a start that does not pass `queue: true` still gets the
37
+ speed quota error.
38
+ - **Relevance-ranked memory recall.** `superagent_memory` takes
39
+ `action: "search"` with `query` and/or `tags`; a new note supersedes the older
40
+ one with the same key, and the planner digest now ranks notes against the run's
41
+ goal instead of only taking the newest ones.
42
+ - `superagent_followup(run_id, message)` appends an instruction to an active
43
+ run. There is no host interface for appending a message to a running child
44
+ activation, so delivery is boundary-scoped and the reply says so: the next
45
+ worker spawn or the aggregation carries it, whichever comes first, and
46
+ subtasks already running or finished keep their results. Each instruction
47
+ records `appliedAt` / `appliedAtStage`, or `missedAt` with a reason when the
48
+ run settled before another boundary ran. A paused run keeps the instruction
49
+ for its next resume; a completed run refuses it. A run owned by another
50
+ process is refused rather than written, because that owner's next save would
51
+ erase it.
52
+ - `superagent_answer(run_id, attention_id?, answer, wait_seconds?)` answers one
53
+ structured attention item. Attention items now carry stable ids (`q1`, `q2`, …)
54
+ from a per-run counter; the answer is recorded on that item and the run
55
+ continues — an active run at its next boundary, a terminal run by reopening so
56
+ its aggregation runs again with the decision. A question retired by a resume
57
+ is archived to `attentionHistory` with `expiredAt`, so a late answer is
58
+ refused as expired instead of being matched to whatever is open now. Unknown
59
+ ids, already answered questions, and an answer whose text is another
60
+ question's option are refused with the id to use instead.
61
+ - **Per-worker workspace isolation.** `workspaceIsolation: true` gives every
62
+ worker its own git worktree on `superagent/<runId>-w<n>`, harvested into a
63
+ commit and merged back into the main checkout one at a time. A conflict aborts
64
+ the merge, keeps both branches, and is reported by status and the wake-up
65
+ message. When isolation is unavailable the run continues in the shared
66
+ directory and says so.
67
+ - **Dependency-aware plans.** The planner may give a subtask an id and a
68
+ `dependsOn` list. The dependent waits (`waiting`) instead of starting, and its
69
+ prompt carries the finished dependency's report; independent subtasks still
70
+ run in parallel. A dependency on an undeclared task is `skipped` with the
71
+ reason, a failure skips everything downstream instead of reporting it as done,
72
+ and a cycle rejects the plan before any subtask starts. Status, notifications,
73
+ and reports distinguish waiting from running.
74
+ - **Parallel structure in the panel and the report.** Runs alive at the same
75
+ moment share a numbered gutter in `watch`, so concurrent work is visible as a
76
+ group, and a waiting row leads with the run holding its slot and its queue
77
+ position. The HTML report lists each worker's retry chain and its share of the
78
+ run's wall clock next to the outcome.
79
+ - **Documentation site.** `docs/site/` holds a quickstart, a comparison page,
80
+ and a single-file landing page; nothing in `lib/` changed for it.
81
+ - **Per-run and per-subtask pricing.** `pricing` in the plugin config maps a
82
+ model to input/output prices per million tokens. Every run and every subtask
83
+ now carries a `cost` with micro-unit totals, and status, the panel, and the
84
+ report print it (`cost ¥0.3519+`). A model absent from the table is reported as
85
+ `unpriced` — never as `0.0000`, and a total that mixes priced and unpriced work
86
+ is printed with a trailing `+` so it cannot be read as complete.
87
+ - **Spend ledger.** `lib/ledger.js` keeps a durable per-run spend record, mounted
88
+ from settled runs so a restart backfills what no tool was watching, and
89
+ `superagent_status` reports the rolling spend and how many runs in the window
90
+ were only partially priced.
91
+ - **Workflow templates.** `superagent_template` lists, shows, and expands a
92
+ reusable goal template (built-ins plus files under the template directory), so
93
+ a common goal is expanded into its steps instead of being retyped. Templates
94
+ are optional: a template directory that cannot be created is logged and the
95
+ run tools keep working.
96
+ - **Install self-check.** `dsh-superagent-doctor` reports, without installing or
97
+ editing anything, whether every imported file is in the `files` whitelist and
98
+ on disk, whether the installed copy matches its published tarball, whether the
99
+ profile registers the bundle row, and whether all nine tools are registered.
100
+ Every failure prints the command that fixes it. `npm test` also asserts that
101
+ `npm pack --dry-run` ships every file reachable from the entry points
102
+ (`scripts/check-pack.mjs`), which is the check the 0.9.x tarball lacked.
103
+ - **Run archives.** `dsh-superagent-archive` (`bin/archive.js`) adds three
104
+ subcommands. `prune` lists terminal runs older than `--older-than <days>`,
105
+ optionally filtered by `--status`, with the files and bytes it would remove;
106
+ it deletes nothing unless `--confirm` is given, and it never touches a run
107
+ that is still active or whose `.lock` another process holds. `export` writes
108
+ one run as a self-contained directory (README with the report, `report.md`,
109
+ `run.json`, per-subtask markdown and JSON, guard records, `usage.json`, and a
110
+ manifest with a SHA-256 per file), as one JSON bundle, or as one offline HTML
111
+ page with the bundle embedded. `import` reads any of those back into the
112
+ store and refuses to overwrite a local run with the same id. `store.js` gained
113
+ `planPrune`, `buildArchive`, `exportRun`, and `importRun`; `prune` gained
114
+ `dryRun` and `statuses` and now returns the plan alongside `removed`. No
115
+ runtime dependency was added.
116
+ - New config: `queueOnFull`, `maxQueuedRuns`, `queueTimeoutMinutes`,
117
+ `workspaceIsolation`, `workspaceRoot`, `pricing`.
118
+
119
+ ### Changed
120
+
121
+ - A single completed subtask still short-circuits aggregation, unless the run
122
+ has instructions or answers: then the aggregation prompt is built, because
123
+ otherwise reopening the run would return the old report and silently drop the
124
+ decision.
125
+ - `superagent_resume` reopens a `completed` run only when it holds an answer
126
+ that never reached a prompt; every other completed run keeps its existing
127
+ no-op behaviour. Without this, an answer that could not be applied (quota or
128
+ lock) would be stranded behind a "resume the run" instruction that did
129
+ nothing.
130
+ - Status prints the attention id, any recorded answer, and how many instructions
131
+ were applied, are waiting, or never took effect; notifications lead with the
132
+ question id so `superagent_answer` can be called directly.
133
+
134
+ ## 0.10.0 — 2026-11-15
135
+
136
+ The dispatch, progress, delivery, and memory layer. No runtime dependencies were
137
+ added, and the package still ships one file per module from `lib/`.
138
+
139
+ ### Added
140
+
141
+ - **Cross-run memory.** `<stateDir>/memory/<scope>.jsonl` keeps short notes the
142
+ aggregator writes (`decision`, `pitfall`, `next`, `dispatch`, `note`) plus the
143
+ six most recent runs derived from the run store. The digest is bounded
144
+ (12 notes / 1600 characters / 2600 characters total), compacted above 400
145
+ lines or 128 KB, and injected into the planner and aggregator prompts. A newer
146
+ note with the same key supersedes an older one, `forget` retracts it, and
147
+ notes older than 30 days expire. Secrets are redacted before storage; the
148
+ directory carries its own `.gitignore` and is never in the package.
149
+ - Added `superagent_memory` (`list`, `set`, `forget`). Existing tools keep their
150
+ arguments and output; this is the sixth tool.
151
+ - **Layered memory.** `rules` and `profile` scopes are read into planning and
152
+ aggregation ahead of the run scope; `superagent_memory` takes `scope`. A run
153
+ only writes its own scope, so a model cannot overwrite a project rule.
154
+ - **Duplicate dispatch is collapsed.** The same active goal (case and whitespace
155
+ ignored) returns the existing run id with `deduped: true`, under a per-goal
156
+ claim so two processes sharing a state directory cannot both start it. The
157
+ match is scoped to the owning session, so two sessions that ask for the same
158
+ generic goal still get their own runs. `allow_duplicate: true` on
159
+ `superagent_start` (or `allow_duplicate` on the control `start` body) opts
160
+ out. A `wait_seconds` call keeps the `deduped` marker in its result.
161
+ - **Transient backoff.** A rate-limit, quota, timeout, or 5xx failure now waits
162
+ 2s, then 4s, then 8s before the next attempt instead of retrying immediately.
163
+ - **Recovery note.** A resumed run tells each worker what failed and instructs it
164
+ to inspect files, `git status`, `git log`, and remote state before repeating an
165
+ externally visible action.
166
+ - **Structured attention.** A worker or the aggregator may append one fenced
167
+ `attention` block. It is stripped from the report, stored as `attention.items`,
168
+ shown as `needs your decision:` in status, and leads the notification.
169
+ - **Attention text is bounded.** Question, options, and reason are collapsed to
170
+ one line and capped at 500 / 200 / 300 characters, so neither status nor a
171
+ notification can be given forged extra lines. An invalid attention block is
172
+ not stripped silently: its raw text stays in the report and status prints
173
+ `attention: <reason>`.
174
+ - **Milestones.** `plan_ready`, `running`, `aggregating`, and `settled` are
175
+ recorded with timestamps and shown in `superagent_status`; nothing is pushed.
176
+ - **Report file.** A terminal report is written atomically to
177
+ `<stateDir>/reports/<runId>.md` (directory carries `.gitignore: *`), recorded
178
+ in `run.artifacts`, and shown in status. `keepRuns` pruning removes it together
179
+ with the run record.
180
+ - **Quiet by default.** Only a delivered, failed, or partially finished run may
181
+ wake the session; a cancelled run never does, and progress is never pushed.
182
+ `maxNotificationsPerHour` (default 3) buffers extra runs into one summary.
183
+ - **Notification outbox.** A refused wake-up is retried with backoff
184
+ (`notifyRetries`, `notifyRetryDelayMs`) and messages for one session stay in
185
+ order. A buffered batch is put back into `pending` when the send fails, so a
186
+ later message still carries those runs; it is dropped only after three failed
187
+ deliveries.
188
+ - **Self-heal before reporting.** A subtask failure that looks transient
189
+ (quota, rate limit, timeout, 5xx) gets `autoResumeRounds` (default 1) more
190
+ rounds, optionally on `childModelFallback`. The failure message now says what
191
+ was tried, and `self-heal:` appears in `superagent_status`.
192
+ - **`memoryMaxEntries` is a compaction trigger.** Exceeding it, 400 lines, or
193
+ 128 KB compacts the notebook on the next write.
194
+ - New config: `memory`, `memoryScope`, `memoryMaxEntries`, `memoryMaxAgeDays`,
195
+ `memoryDigestEntries`, `memoryDigestChars`, `maxNotificationsPerHour`,
196
+ `notifyRetries`, `notifyRetryDelayMs`, `autoResumeRounds`,
197
+ `childModelFallback`.
198
+
199
+ ### Changed
200
+
201
+ - **A resume is never refused by the concurrency quota.** A `superagent_resume`
202
+ only finishes work that already exists, so it is not counted against
203
+ `maxActiveRuns` and works even when the cap is full; only `superagent_start`
204
+ creates new spend and is subject to the cap. The resume is still
205
+ session-scoped: it may only be issued by the session named in the run's
206
+ `parentSessionId`. `force` (`force` or `override_quota` over HTTP) is still
207
+ accepted so an existing caller keeps working, but it no longer changes
208
+ anything.
209
+ - `superagent_status` gained the milestone line, the attention line, and the
210
+ report file path; `superagent_start` gained `allow_duplicate`; the control
211
+ `start` body gained `allow_duplicate`, and `resume` still accepts `force`.
212
+
213
+ ### Fixed
214
+
215
+ - Memory, notification, and report-artifact writes are fail-open or retried, so
216
+ a transient filesystem error cannot turn a finished run into a failed one; a
217
+ report that is already written stays on disk and is listed in status.
218
+ - Test suite: 168 tests, 0 failures; `npm test` and `node --test` discovery
219
+ agree.
220
+
98
221
  ## 0.9.3 — 2026-11-14
99
222
 
100
223
  Documentation only; no code change.