@xiangyixie/dsh-superagent 0.14.2 → 0.14.3
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 +226 -82
- package/README.en.md +120 -25
- package/README.md +1223 -1167
- package/README.zh.md +1223 -1167
- package/cordis.patch.yml +32 -9
- package/docs/DETAIL.md +1 -0
- package/docs/DETAIL.zh.md +1 -0
- package/lib/board-messages.js +327 -0
- package/lib/board.js +891 -0
- package/lib/client.js +210 -0
- package/lib/console.js +375 -3
- package/lib/entry.js +65 -0
- package/lib/index.js +697 -6
- package/lib/orchestrator.js +425 -15
- package/lib/schedule.js +2 -1
- package/lib/wizard.js +1498 -0
- package/lib/workspace.js +10 -3
- package/package.json +15 -5
- package/public/board.html +1110 -0
- package/public/console.html +1427 -187
package/CHANGELOG.md
CHANGED
|
@@ -8,88 +8,232 @@ 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.14.
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
`
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
`
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
11
|
+
## 0.14.3 — 2026-11-15
|
|
12
|
+
|
|
13
|
+
The release is about the three things a run could not answer for itself: which
|
|
14
|
+
directory it is allowed to work in, whether its files actually reached that
|
|
15
|
+
directory, and whether the session mounts the plugin at all.
|
|
16
|
+
|
|
17
|
+
### Added
|
|
18
|
+
|
|
19
|
+
- **Sidebar entry and approval card.** The package now publishes
|
|
20
|
+
`exports["./client"]` → `lib/client.js` and declares `dsh.client.platform:
|
|
21
|
+
"web"`, so a web host shows a Superagent entry next to its own sidebar items
|
|
22
|
+
instead of leaving the console reachable only by port. The entry discovers the
|
|
23
|
+
console through `GET /superagent/console-address` (the route answers with the
|
|
24
|
+
address the host actually serves, not the port from the patch file), and
|
|
25
|
+
`approval/request` is bridged to the console session with `prepend` so the
|
|
26
|
+
approval card appears where the console is open and an unanswered request
|
|
27
|
+
counts as a refusal. A client bundle that does not compile is reported on the
|
|
28
|
+
entry itself (`client.js.broken`) instead of silently disappearing from the
|
|
29
|
+
sidebar.
|
|
30
|
+
- **First-use wizard.** `lib/wizard.js` plus `GET|POST /api/console/wizard/*`
|
|
31
|
+
(`status`, `preview`, `save`, `rollback`, `trial`) walk a user who has never
|
|
32
|
+
opened a terminal from "nothing configured" to "a real run finished": the
|
|
33
|
+
environment check explains each item, an API key is verified against the real
|
|
34
|
+
endpoint before anything is written, and the key itself goes to the host's
|
|
35
|
+
credential store with only its reference left in the profile patch. The patch
|
|
36
|
+
editor understands exactly the two entries it owns (`llm-pi-ai`,
|
|
37
|
+
`agent-default-model`), leaves every other line and comment untouched, and
|
|
38
|
+
keeps the last 10 backups restorable from the page. The last step is a real
|
|
39
|
+
trial run in a temporary directory, not a simulated success. Without the
|
|
40
|
+
wizard hooks on the host the console answers `501 wizard-unavailable` and says
|
|
41
|
+
why instead of drawing a dead form.
|
|
42
|
+
- **Task board.** `boardPort` serves one Chinese page where a run is a column
|
|
43
|
+
of subtask cards (status, steps, elapsed time, tokens, cost, dependencies,
|
|
44
|
+
and the dependency that skipped it). Cards can be cancelled or rerun one at a
|
|
45
|
+
time: `cancelSubtask` aborts only that child and the rest of the run
|
|
46
|
+
continues; `rerunSubtask` resets that subtask and any dependents skipped only
|
|
47
|
+
because of it, then resumes without touching completed siblings. A run whose
|
|
48
|
+
remaining work was all cancelled now ends as `cancelled`.
|
|
49
|
+
- **Human inbox.** Planner `needsInput`, deliverable reviews, missing
|
|
50
|
+
capabilities, policy confirmations, browser checks that need a person, and
|
|
51
|
+
interrupted runs are collected in one list with what happened, why a person
|
|
52
|
+
is needed, the options, and the effect of answering. Answers use the same
|
|
53
|
+
`orchestrator.answer` path as `superagent_answer`, with the run owner as the
|
|
54
|
+
actor and an audit line naming the answer. An empty inbox says so.
|
|
55
|
+
- **Plain-language failures.** `lib/board-messages.js` maps capability blocks,
|
|
56
|
+
unusable plans, missing deliverables, sandbox writes, `spawn EPERM`,
|
|
57
|
+
unavailable models, budget/deadline exhaustion, and a dead scheduler owner to
|
|
58
|
+
one Chinese sentence plus one action; the raw error is folded away.
|
|
59
|
+
- **Template forms.** The four built-in templates show their purpose,
|
|
60
|
+
parameters, and expected subtask count; submitting starts a run from the
|
|
61
|
+
board's own persisted Host Session and jumps to its board.
|
|
62
|
+
- **Reconnect-safe stream.** `/api/board/events` opens with a full snapshot and
|
|
63
|
+
polls durable run records, so a refresh or a dropped connection restores the
|
|
64
|
+
board instead of leaving it blank.
|
|
65
|
+
- **A stated policy for multi-step goals.** A session that mounts
|
|
66
|
+
`superagent_start` next to the host's `subagent` tool can hand-orchestrate the
|
|
67
|
+
work with the latter and never create a run — no plan, no timing, no merged
|
|
68
|
+
report, nothing in the run list. `lib/index.js` now registers an
|
|
69
|
+
`agent/pre-step` hook that prepends one system-reminder at the first step of a
|
|
70
|
+
**top-level** turn only (`delegationDepth === 0` and no `origin: "subagent"`),
|
|
71
|
+
never twice in the same turn, and passes a rejected step through untouched.
|
|
72
|
+
The text defines multi-step (two or more independently deliverable artifacts,
|
|
73
|
+
or a prerequisite step), names `superagent_start(mode="planned")` /
|
|
74
|
+
`superagent_followup` / `superagent_status`, says to call the tool first rather
|
|
75
|
+
than audit its own tool list, and keeps single actions (one lookup, one edit,
|
|
76
|
+
one command, one short piece of writing) out of a run. Guidance only: no new
|
|
77
|
+
tool, no new spend. `superagent_start`'s description says the same in one
|
|
78
|
+
sentence.
|
|
79
|
+
- **`workspaceBase`.** New config (`session` by default, `config` for the old
|
|
80
|
+
behaviour) decides what per-worker isolation is based on. See “Changed” for
|
|
81
|
+
what it fixes; the README table documents both values.
|
|
82
|
+
- **The planner preset has a card of its own.** `cordis.patch.yml` now declares
|
|
83
|
+
the tool-less `planner` preset with the Chinese name
|
|
84
|
+
“插件内部:规划器(请勿选择)”, a description saying that picking it leaves the
|
|
85
|
+
session with no tools, and `order: 9999`. A fresh install used to show a bare
|
|
86
|
+
`planner` row with an empty description at the top of the mode picker. The
|
|
87
|
+
host preset schema has no hidden/internal field, so this is the closest the
|
|
88
|
+
schema allows.
|
|
89
|
+
|
|
90
|
+
### Changed
|
|
91
|
+
|
|
92
|
+
- **Four workers per layer by default.** `maxParallel` now defaults to 4 (hard
|
|
93
|
+
max 8) instead of 3, so a plan whose layer has three independent subtasks
|
|
94
|
+
starts all three instead of queueing the third. Dependency order is unchanged —
|
|
95
|
+
a subtask still starts only after its `dependsOn` finish — and two subtasks
|
|
96
|
+
that declare the same deliverable path are never in flight together, so a wider
|
|
97
|
+
layer cannot turn a same-file race into a lost file.
|
|
98
|
+
- **A budget stop is a notice, not an error.** Hitting `maxModelCallsPerRun` or
|
|
99
|
+
`maxTokensPerRun` no longer writes `model-call budget reached (86/80 calls)`
|
|
100
|
+
into the run's `error`. It is recorded as `budgetStop` (detail, time, calls,
|
|
101
|
+
tokens), the status text prints it as `note: stopped starting new workers — …`,
|
|
102
|
+
and a run that still finished every subtask stays `completed` with `error`
|
|
103
|
+
null. A run that did not finish keeps the detail in `error` so the reason is
|
|
104
|
+
not lost, and the scheduler still pauses a plan on it.
|
|
105
|
+
- **A run whose files never reached the target is `partial`, not `completed`.**
|
|
106
|
+
A skipped merge (uncommitted changes in the main checkout) and a conflict both
|
|
107
|
+
leave the worker's work only inside its branch. Such a run now drops to
|
|
108
|
+
`partial` and records one attention item naming: the branches, the worktree
|
|
109
|
+
each is kept in, why the merge was refused, the two options, and the exact
|
|
110
|
+
`git stash push -u` plus `git merge --no-ff <branch>` commands that finish it
|
|
111
|
+
by hand. Nothing is deleted, so a manual merge stays possible.
|
|
112
|
+
- **The package entry point is `lib/entry.js`.** `main` and `exports["."]` point
|
|
113
|
+
at a file whose only job is to import `lib/index.js`; a missing sibling
|
|
114
|
+
(`wizard.js`, `board.js`, …) is caught there and reported as the missing file
|
|
115
|
+
plus the fix (`Copy-Item lib\* -Force`, or reinstall) instead of the plugin
|
|
116
|
+
vanishing with no explanation.
|
|
117
|
+
- **`superagent_status` reports a version mismatch.** When `package.json` on
|
|
118
|
+
disk differs from the version the host loaded, the status text ends with
|
|
119
|
+
`note: ... restart DSH`. Code is read once at startup, so replacing files
|
|
120
|
+
changes nothing until a restart; the README's install section now says so.
|
|
121
|
+
- **Child activations carry the delegation fields twice.** `startActivation` is
|
|
122
|
+
given both `request` and the same fields at the top level of the spec, because
|
|
123
|
+
dsh 0.2.2-rc.1 reads the former and the desktop host (0.2.2-rc.3) reads the
|
|
124
|
+
latter and otherwise throws `Cannot read properties of undefined (reading
|
|
125
|
+
'id')` before any child exists.
|
|
126
|
+
- **The planner failure log keeps the host stack.** A planner attempt that fails
|
|
127
|
+
inside the host now logs the stack alongside the message that goes into the
|
|
128
|
+
run file.
|
|
129
|
+
- **Docs.** `README.md` / `README.en.md` / `README.zh.md` gained the restart
|
|
130
|
+
requirement and the `workspaceBase` row; `docs/DETAIL.md` and
|
|
131
|
+
`docs/DETAIL.zh.md` open “What it solves” with the dispatch-desk case (work
|
|
132
|
+
spread across domains costs more to manage than to do). `docs/host-compat.md`
|
|
133
|
+
lists every rc.1/rc.3 shape difference the plugin papers over — start-request
|
|
134
|
+
field placement, child handle, host service probes, preset schema — with the
|
|
135
|
+
file and line to re-check when the host changes.
|
|
136
|
+
|
|
137
|
+
### Fixed
|
|
138
|
+
|
|
139
|
+
- **Isolation followed `workspaceRoot` even when it named another project.**
|
|
140
|
+
The base was taken from the profile, while the sandbox boundary, the declared
|
|
141
|
+
deliverables, and the merge target all came from the session — so merges
|
|
142
|
+
landed where nobody looked, or were refused because that checkout had
|
|
143
|
+
unrelated local edits. The default (`workspaceBase: "session"`) now uses the
|
|
144
|
+
session's cwd (or the repository root git resolves from it) and honours
|
|
145
|
+
`workspaceRoot` only when it names that same directory, comparing paths
|
|
146
|
+
case-insensitively on Windows. A mismatch is recorded on the run as
|
|
147
|
+
`workspace.baseNote` and printed by status as `workspace warning: ...` instead
|
|
148
|
+
of being silently applied; when isolation is impossible, the shared directory
|
|
149
|
+
reported as `base` is the session's too.
|
|
150
|
+
- **A merge that never happened used to print `completed`.** The user opened the
|
|
151
|
+
target directory and found it empty. Covered by the `partial` change above.
|
|
152
|
+
- **An incomplete install no longer looks like a plugin with no tools.**
|
|
153
|
+
Covered by the entry-point change above.
|
|
154
|
+
|
|
155
|
+
## 0.14.2 — 2026-11-15
|
|
156
|
+
|
|
157
|
+
### Fixed
|
|
158
|
+
|
|
159
|
+
- **The detail page carries the language switch.** `docs/DETAIL.zh.md` and
|
|
160
|
+
`docs/DETAIL.md` now open with `中文 | English`, pointing at the other
|
|
161
|
+
document on GitHub. The plugin detail page previously rendered a Chinese body
|
|
162
|
+
with no way to reach the English one, even though both READMEs had the switch.
|
|
163
|
+
|
|
164
|
+
## 0.14.1 — 2026-11-15
|
|
165
|
+
|
|
166
|
+
### Added
|
|
167
|
+
|
|
168
|
+
- **Plugin card metadata.** `icon.svg` is declared by the package manifest and
|
|
169
|
+
exported as `./icon`; `locale/en.json` and `locale/zh.json` carry the title,
|
|
170
|
+
description, and a `meta.detail` document. In a Chinese UI the card reads
|
|
171
|
+
“超级智能体” with a Chinese one-line description, and the detail page renders
|
|
172
|
+
`docs/DETAIL.zh.md` instead of the English README.
|
|
173
|
+
- **A format-1 plugin index** at `plugin-index.json`, with the package name, a
|
|
174
|
+
Chinese title, and a `git` source pinned to a full 40-hex commit, so the
|
|
175
|
+
Discover page can add the index and install or update the plugin in one step.
|
|
176
|
+
The public URL and the two-step instructions are in the README.
|
|
177
|
+
|
|
178
|
+
### Changed
|
|
179
|
+
|
|
180
|
+
- `README.md` is now Simplified Chinese-first; `README.en.md` keeps the English
|
|
181
|
+
text and both open with a language switch. `README.zh.md` mirrors the Chinese
|
|
182
|
+
page, and `package.json`'s `description` is Chinese.
|
|
183
|
+
|
|
184
|
+
## 0.14.0 — 2026-11-15
|
|
185
|
+
|
|
186
|
+
### Added
|
|
187
|
+
|
|
188
|
+
- **Attach mode is complete.** With `runtime.browser.attachPort` set, every
|
|
189
|
+
browser tool — listing, clicking, typing, screenshots, scripts — runs on the
|
|
190
|
+
browser the user started with `--remote-debugging-port`, on the tab that is
|
|
191
|
+
already open. The tab keeps its own window size (no viewport override), and
|
|
192
|
+
`browser_close` detaches instead of terminating the user's browser (a blank tab
|
|
193
|
+
created only because no page existed is closed). A port that is not listening
|
|
194
|
+
now fails with the port, a Chrome/Edge start command, and an explicit
|
|
195
|
+
statement that no profile was launched in its place; attach never falls back
|
|
196
|
+
to a fresh profile.
|
|
197
|
+
- **Persistent profile option.** `runtime.browser.userDataDir` points a launched
|
|
198
|
+
browser at one dedicated profile, so a sign-in done once is reused on later
|
|
199
|
+
runs. The default is still a fresh temporary profile, which cannot see the
|
|
200
|
+
user's daily cookies; the README spells out the trade-off and ignores
|
|
201
|
+
`userDataDir` while `attachPort` is set.
|
|
202
|
+
- **Human checks hand back instead of failing.** `lib/browser.js` classifies
|
|
203
|
+
page text for a sign-in wall, CAPTCHA / "confirm you are human", SMS or
|
|
204
|
+
one-time code, two-factor, and QR login. `browser_open`, `browser_click`, and a
|
|
205
|
+
submitting `browser_type` stop at such a page and return `[attention]` with
|
|
206
|
+
the page, the check, where the person finishes it, and the next call — never a
|
|
207
|
+
failure. New `browser_await_human` polls until the check is gone and reports
|
|
208
|
+
ok, or hands back again at its timeout. It never solves, types, or scans the
|
|
209
|
+
check. A headless launch explains that it has no window and points at
|
|
210
|
+
`headless: false` or attach.
|
|
211
|
+
- **Audit distinguishes the connection.** Every browser audit line carries
|
|
212
|
+
`meta.session: "attach" | "launch"`, plus `meta.port` and the reused tab for
|
|
213
|
+
attach, or `meta.profile` / `meta.persistentProfile` / `meta.headless` for a
|
|
214
|
+
launch. Human hand-offs are recorded as `kind: "attention"`,
|
|
215
|
+
`decision: "attention"`, `result: "needs-human"`; attach failures record
|
|
216
|
+
`rule: "runtime/attach-failed"` with the actionable message rather than being
|
|
217
|
+
mistaken for a provider error.
|
|
218
|
+
|
|
219
|
+
### Changed
|
|
220
|
+
|
|
221
|
+
- The domain allow-list, irreversible-action confirmation, file-upload refusal,
|
|
222
|
+
stop switch, and worker-tool guard all sit in the same call path as before, so
|
|
223
|
+
they apply unchanged on an attach connection; tests cover each one there.
|
|
224
|
+
- `browser_type` masks the read-back value for a password field.
|
|
225
|
+
|
|
226
|
+
### Fixed
|
|
227
|
+
|
|
228
|
+
- **Costs are grouped by currency.** A run that used a USD-priced route and a
|
|
229
|
+
CNY-priced route used to add their micro-units and label the sum with the
|
|
230
|
+
first model's currency. It now keeps one subtotal per currency and prints
|
|
231
|
+
them separately (`¥0.0952 + $0.0248`) in the run line, `superagent_list`'s
|
|
232
|
+
ledger line, the `watch` footer, the exported `README.md`, and the HTML
|
|
233
|
+
report; a mixed window gets one cost curve per currency. Single-currency runs
|
|
234
|
+
keep the existing `¥0.3600` format, and an unpriced model stays `unpriced`
|
|
235
|
+
rather than becoming zero.
|
|
236
|
+
|
|
93
237
|
## 0.13.0 — 2026-11-15
|
|
94
238
|
|
|
95
239
|
### Added
|
package/README.en.md
CHANGED
|
@@ -27,7 +27,7 @@ filesystem; this is not a sandbox.
|
|
|
27
27
|
in the environment:
|
|
28
28
|
|
|
29
29
|
```bash
|
|
30
|
-
dsh plugin --profile web add @xiangyixie/dsh-superagent@0.14.
|
|
30
|
+
dsh plugin --profile web add @xiangyixie/dsh-superagent@0.14.3
|
|
31
31
|
```
|
|
32
32
|
|
|
33
33
|
Then ask the session for a run — a real call, not a sketch:
|
|
@@ -80,29 +80,29 @@ your `PATH`, use `npx @deepseek-ai/dsh@0.2.2-rc.1` instead.
|
|
|
80
80
|
|
|
81
81
|
```bash
|
|
82
82
|
# 1. install the plugin into a profile (web, headless, ... whatever you run)
|
|
83
|
-
dsh plugin --profile web add @xiangyixie/dsh-superagent@0.14.
|
|
83
|
+
dsh plugin --profile web add @xiangyixie/dsh-superagent@0.14.3
|
|
84
84
|
|
|
85
85
|
# 2. confirm the bundle row exists in the merged config
|
|
86
86
|
dsh --profile web --dump-config
|
|
87
87
|
```
|
|
88
88
|
|
|
89
|
-
### Install from the plugin index (optional)
|
|
90
|
-
|
|
91
|
-
The plugin index pins the package name, the release version, and the exact commit
|
|
92
|
-
in one JSON file, which the desktop app's **Discover** page can read directly:
|
|
93
|
-
|
|
94
|
-
1. Open **Discover**, choose **Add index**, and enter `https://raw.githubusercontent.com/LittleChenLiya/dsh-superagent/main/plugin-index.json`.
|
|
95
|
-
2. Find "Superagent" in the list and install it; later releases update from the same entry.
|
|
96
|
-
|
|
97
|
-
Every version entry points at a full 40-hex commit, so a one-click update lands on
|
|
98
|
-
a known revision instead of a moving branch head.
|
|
99
|
-
|
|
89
|
+
### Install from the plugin index (optional)
|
|
90
|
+
|
|
91
|
+
The plugin index pins the package name, the release version, and the exact commit
|
|
92
|
+
in one JSON file, which the desktop app's **Discover** page can read directly:
|
|
93
|
+
|
|
94
|
+
1. Open **Discover**, choose **Add index**, and enter `https://raw.githubusercontent.com/LittleChenLiya/dsh-superagent/main/plugin-index.json`.
|
|
95
|
+
2. Find "Superagent" in the list and install it; later releases update from the same entry.
|
|
96
|
+
|
|
97
|
+
Every version entry points at a full 40-hex commit, so a one-click update lands on
|
|
98
|
+
a known revision instead of a moving branch head.
|
|
99
|
+
|
|
100
100
|
The desktop app's **Add plugin** dialog accepts the same three forms:
|
|
101
101
|
|
|
102
102
|
| Dialog input | Value | What it does |
|
|
103
103
|
| --- | --- | --- |
|
|
104
|
-
| Package name | `@xiangyixie/dsh-superagent@0.14.
|
|
105
|
-
| GitHub repository | `https://github.com/LittleChenLiya/dsh-superagent` | Installs from the repository. Add `#v0.14.
|
|
104
|
+
| Package name | `@xiangyixie/dsh-superagent@0.14.3` | Installs from npm. Name the version (see below). |
|
|
105
|
+
| GitHub repository | `https://github.com/LittleChenLiya/dsh-superagent` | Installs from the repository. Add `#v0.14.3` if you need a fixed release. |
|
|
106
106
|
| Local directory | `file:/absolute/path/to/dsh-superagent` | Copies the checkout. Re-add after changing the source. |
|
|
107
107
|
|
|
108
108
|
Upgrading is remove-then-add, not in-place: remove the old copy
|
|
@@ -121,6 +121,14 @@ actually landed with:
|
|
|
121
121
|
npm ls --prefix <DSH_HOME>/profiles/web @xiangyixie/dsh-superagent
|
|
122
122
|
```
|
|
123
123
|
|
|
124
|
+
A new or updated plugin takes effect only after **restarting DSH**: quit the
|
|
125
|
+
desktop app completely and reopen it, or stop and start the `dsh web` host.
|
|
126
|
+
Code is loaded once at host startup, so replacing files on disk does not change
|
|
127
|
+
the process that is already running. `superagent_status` appends a
|
|
128
|
+
`note: ... restart DSH` line when the version on disk differs from the one the
|
|
129
|
+
host loaded; that check itself only exists in the newer code, so after an
|
|
130
|
+
upgrade the restart is still what makes it real.
|
|
131
|
+
|
|
124
132
|
For an offline machine or a pinned artifact, install a packed tarball instead —
|
|
125
133
|
it is byte-identical to what the registry serves:
|
|
126
134
|
|
|
@@ -212,7 +220,7 @@ Row config in `<profile>/cordis.patch.yml`:
|
|
|
212
220
|
- id: superagent
|
|
213
221
|
config:
|
|
214
222
|
maxSubtasks: 8
|
|
215
|
-
maxParallel:
|
|
223
|
+
maxParallel: 4
|
|
216
224
|
maxActiveRuns: 2
|
|
217
225
|
```
|
|
218
226
|
|
|
@@ -231,7 +239,7 @@ Row config in `<profile>/cordis.patch.yml`:
|
|
|
231
239
|
| `maxSubagentDepth` | `1` | How deep children may delegate. `1` forbids grandchildren; `provider-managed` leaves it to the backend. |
|
|
232
240
|
| `commandWorkerPermission` | `inherit` | Sandbox mode for workers whose plan entry declares a command capability (`shell`, `bash`, `pwsh`, …). `danger-full-access` lets those workers actually run commands on a `workspace-write` host; every other child keeps inheritance. See [Per-worker command permissions](#per-worker-command-permissions). |
|
|
233
241
|
| `maxSubtasks` | `8` | Cap on planned subtasks. A tool argument can only lower it, never raise it; hard max 16. |
|
|
234
|
-
| `maxParallel` | `
|
|
242
|
+
| `maxParallel` | `4` | Subtasks executing at once. A tool argument can only lower it; hard max 8. |
|
|
235
243
|
| `maxActiveRuns` | `2` | Active runs per state directory, across profiles and hosts that share it. A further `superagent_start` is rejected unless it passes `queue: true`, in which case it waits for a slot instead. `superagent_resume` is not counted and works when the cap is full, because it only finishes work that already exists. |
|
|
236
244
|
| `maxQueuedRuns` | `5` | Runs allowed to wait for a free slot at once; hard max 32. `0` turns queueing off, so every start over `maxActiveRuns` is rejected again. |
|
|
237
245
|
| `queueTimeoutMinutes` | `30` | How long a queued run waits before it fails without ever starting; nothing is spent. |
|
|
@@ -262,12 +270,15 @@ Row config in `<profile>/cordis.patch.yml`:
|
|
|
262
270
|
| `auditDir` | `<stateDir>/audit` | Where `audit.jsonl` and its exports live. |
|
|
263
271
|
| `controlPort` | off | Loopback port for the embedding surface; `0` picks a free one. See [docs/embedding.md](https://github.com/LittleChenLiya/dsh-superagent/blob/main/docs/embedding.md). |
|
|
264
272
|
| `workspaceIsolation` | `false` | Give every worker its own git worktree so parallel workers cannot overwrite each other. See [Per-worker workspace isolation](#per-worker-workspace-isolation). |
|
|
265
|
-
| `workspaceRoot` |
|
|
273
|
+
| `workspaceRoot` | session directory (see `workspaceBase`) | Repository the workers are isolated in when `workspaceIsolation` is on. Must be a git working tree with at least one commit. |
|
|
274
|
+
| `workspaceBase` | `session` | What isolation is based on. `session` uses the current session's directory (or the repository root git resolves from it) and honours `workspaceRoot` only when it names the same directory; `config` restores the old behaviour of always using `workspaceRoot`. A mismatch prints `workspace warning` in status and in the log instead of silently isolating in another project. |
|
|
266
275
|
| `workbenchPort` | off | Loopback port for the local workspace panel; `0` picks a free one. The panel reads and edits files itself, without a host API. |
|
|
267
276
|
| `workbenchRoot` | `process.cwd()` | Directory the panel may browse and edit. Every path outside it is refused. |
|
|
268
277
|
| `consolePort` | off | Loopback port for the conversation console; `0` picks a free one. Requires the host `sessionController` service. |
|
|
269
278
|
| `consoleRoot` | `workbenchRoot`, then host cwd | Directory the console's conversation session joins. |
|
|
270
279
|
| `consolePreset` | host default | Agent preset id the console session mounts. Tools follow this preset, not this plugin. |
|
|
280
|
+
| `boardPort` | off | Loopback port for the task board; `0` picks a free one. One page with subtask cards, the human inbox, and the built-in templates. See [Task board](#task-board). |
|
|
281
|
+
| `boardRoot` | `consoleRoot`, then `workbenchRoot` | Directory the board's own conversation session joins, and where template-started runs work. |
|
|
271
282
|
| `schedulerTickSeconds` | `30` | How often a live plan is checked for a due window, in seconds (1–3600). Nothing is armed until a plan exists, so this has no effect on an install with no schedules. |
|
|
272
283
|
| `schedulerHumanPriority` | `true` | Default for a plan's `human_priority`: a scheduled run may not take the last free concurrency slot. |
|
|
273
284
|
| `schedulerMaxConsecutiveFailures` | `3` | Consecutive failed executions before a plan pauses itself and says so once (1–20). |
|
|
@@ -408,10 +419,13 @@ kept at <repository>/.superagent/worktrees/20261115T101500-ab12/w2; the main che
|
|
|
408
419
|
was lost. Resolve with: git -C "/home/me/projects/api" merge superagent/20261115T101500-ab12-w2
|
|
409
420
|
```
|
|
410
421
|
|
|
411
|
-
The wake-up message for the run says the same in one line
|
|
412
|
-
the
|
|
413
|
-
|
|
414
|
-
|
|
422
|
+
The wake-up message for the run says the same in one line. As soon as one branch
|
|
423
|
+
has not reached the main checkout — a conflict, or a dirty checkout at merge time
|
|
424
|
+
— the run is not reported as `completed`: it drops to `partial` and writes one
|
|
425
|
+
attention item naming the branch, where its worktree still is, why the merge was
|
|
426
|
+
refused, and the commands that finish it by hand. Nothing is discarded: the
|
|
427
|
+
branch and its checkout are kept until you merge or delete them. Two more cases
|
|
428
|
+
are reported the same way rather than silently dropped:
|
|
415
429
|
|
|
416
430
|
- the main checkout has uncommitted changes when the merge is due — every
|
|
417
431
|
branch is left unmerged, since merging into a dirty tree would mix your edits
|
|
@@ -419,7 +433,15 @@ them. Two more cases are reported the same way rather than silently dropped:
|
|
|
419
433
|
- the run was cancelled or hit its deadline before merging — the branches are
|
|
420
434
|
kept and a resume reuses the same worktrees.
|
|
421
435
|
|
|
422
|
-
**
|
|
436
|
+
**What isolation is based on.** The default is the session's own directory
|
|
437
|
+
(`workspaceBase: "session"`) — the same directory the sandbox boundary, the
|
|
438
|
+
declared deliverables, and the merge target already use. `workspaceRoot` is
|
|
439
|
+
honoured only when it names that directory; when it does not,
|
|
440
|
+
`superagent_status` prints `workspace warning` and names the directory actually
|
|
441
|
+
used instead of isolating inside another project. `workspaceBase: "config"`
|
|
442
|
+
restores the old behaviour of always using `workspaceRoot`.
|
|
443
|
+
|
|
444
|
+
**When isolation is not possible.** If the base directory is not a git working tree,
|
|
423
445
|
git is not on `PATH`, or the repository has no commit yet, the run does not fail.
|
|
424
446
|
It falls back to the shared directory (the previous behaviour) and both
|
|
425
447
|
`superagent_status` and the notification say so:
|
|
@@ -708,6 +730,13 @@ and captures the window.
|
|
|
708
730
|
|
|
709
731
|
## Tools
|
|
710
732
|
|
|
733
|
+
When a goal has two or more independently deliverable artifacts, or a step that
|
|
734
|
+
must precede another, use `superagent_start` rather than hand-orchestrating the
|
|
735
|
+
host's own `subagent` tool: only a run keeps the plan, the parallel timing, and
|
|
736
|
+
one merged report. A top-level session gets a short reminder saying the same at
|
|
737
|
+
its first step; child sessions are not given it again. A single action — one
|
|
738
|
+
lookup, one edit, one command, one short piece of writing — does not need a run.
|
|
739
|
+
|
|
711
740
|
- `superagent_start(goal, mode?, queue?, max_subtasks?, max_parallel?, deadline_minutes?, allow_duplicate?, wait_seconds?)`
|
|
712
741
|
starts a run and returns immediately with a run id. `mode: "direct"` runs the
|
|
713
742
|
goal on one worker with no planner and no aggregator, and returns that worker's
|
|
@@ -1421,6 +1450,16 @@ The bound URL and a fresh per-process token are written to
|
|
|
1421
1450
|
the event stream, answers `401` without it, and every request with a non-loopback
|
|
1422
1451
|
`Host` header answers `403`.
|
|
1423
1452
|
|
|
1453
|
+
On a fresh install the page opens with 首次使用向导 (first-use wizard): an
|
|
1454
|
+
environment check, an API key verified against the real endpoint before anything
|
|
1455
|
+
is written, a preview and save of the profile patch, and one real trial run in a
|
|
1456
|
+
temporary directory. Every save leaves a restorable backup (the last 10), the key
|
|
1457
|
+
goes only to the host's credential store while the patch keeps its reference, and
|
|
1458
|
+
the editor touches just the two entries it owns (`llm-pi-ai`,
|
|
1459
|
+
`agent-default-model`). A host without the wizard hooks answers
|
|
1460
|
+
`501 wizard-unavailable`, so the button says that rather than opening a form that
|
|
1461
|
+
cannot work.
|
|
1462
|
+
|
|
1424
1463
|
If the host does not mount `sessionController` (for example a headless profile
|
|
1425
1464
|
without the web session API), the page says so and refuses to create a session.
|
|
1426
1465
|
It does **not** pretend to be a chat. The console also keeps one active
|
|
@@ -1489,6 +1528,62 @@ When `workbenchPort` is on, the plugin records the files each run changed into
|
|
|
1489
1528
|
that run's JSON record (`run.changes`), so the Runs view can show those files and
|
|
1490
1529
|
their diff against `git HEAD` later.
|
|
1491
1530
|
|
|
1531
|
+
## Task board
|
|
1532
|
+
|
|
1533
|
+
`boardPort` adds the page to open when you do not want to read a run record.
|
|
1534
|
+
It is written for someone who has never seen the plugin: every subtask is a
|
|
1535
|
+
card, everything that waits for a person is in one inbox, and the four built-in
|
|
1536
|
+
templates start with a form instead of a prompt.
|
|
1537
|
+
|
|
1538
|
+
```yaml
|
|
1539
|
+
- id: superagent
|
|
1540
|
+
config:
|
|
1541
|
+
boardPort: 0 # off by default; 0 = OS picks a free loopback port
|
|
1542
|
+
boardRoot: /path/to/project
|
|
1543
|
+
```
|
|
1544
|
+
|
|
1545
|
+
Open the URL in `<stateDir>/board.json` (mode `0600`), or use
|
|
1546
|
+
`http://127.0.0.1:<port>/?token=<token>`; the token is stored in the browser and
|
|
1547
|
+
removed from the address bar. Every route and the event stream answer `401`
|
|
1548
|
+
without it, and a non-loopback `Host` answers `403`. The stream opens with a
|
|
1549
|
+
full snapshot, so a reconnect or a page refresh restores the board from durable
|
|
1550
|
+
run records instead of a blank page.
|
|
1551
|
+
|
|
1552
|
+
**Board.** One card per subtask with its status, attempts, elapsed time, tokens,
|
|
1553
|
+
cost, dependencies, and — when it did not run — the dependency that stopped it.
|
|
1554
|
+
Each card can be cancelled on its own or rerun on its own. `cancelSubtask`
|
|
1555
|
+
aborts only that child; the rest of the run keeps going, and dependents are
|
|
1556
|
+
skipped with `not started because w2 was cancelled`. `rerunSubtask` resets that
|
|
1557
|
+
one subtask (plus dependents that were skipped only because of it) and resumes
|
|
1558
|
+
the run; completed siblings are not touched. A run whose entire remaining work
|
|
1559
|
+
was cancelled reports `cancelled`, not `failed`.
|
|
1560
|
+
|
|
1561
|
+
**Inbox.** Planner `needsInput` questions, deliverable reviews (`unverified`),
|
|
1562
|
+
missing capabilities, policy confirmations, browser checks that need a person,
|
|
1563
|
+
and interrupted runs. Each item says what happened, why a person is needed, the
|
|
1564
|
+
options, and what answering will do. Answers go through the same
|
|
1565
|
+
`orchestrator.answer` path as `superagent_answer`, with the run's owning session
|
|
1566
|
+
as the actor, and the audit trail records who answered what. When nothing is
|
|
1567
|
+
waiting, the page says "当前没有需要你处理的事" instead of showing an empty
|
|
1568
|
+
column.
|
|
1569
|
+
|
|
1570
|
+
**Templates.** `bugfix-verify`, `review-fix`, `docs-examples`, and
|
|
1571
|
+
`research-report` are forms: purpose, parameters, and the expected subtask
|
|
1572
|
+
count. Submitting expands the template, starts one run from the board's own
|
|
1573
|
+
persisted Host Session, and jumps to its board.
|
|
1574
|
+
|
|
1575
|
+
**Plain-language failures.** Capability preflight blocks, unparsable plans,
|
|
1576
|
+
missing or wrong-type deliverables, sandbox write denial, `spawn EPERM`,
|
|
1577
|
+
unavailable models/endpoints, budget or deadline exhaustion, and a dead
|
|
1578
|
+
scheduler owner session each map to one Chinese sentence plus one action
|
|
1579
|
+
(retry, rerun, open configuration, or copy diagnostics). The raw stack stays
|
|
1580
|
+
folded under "原始错误(给技术同学看)".
|
|
1581
|
+
|
|
1582
|
+
The board never owns a run. It resolves the run's `parentSessionId` through the
|
|
1583
|
+
host and calls the same orchestrator methods the tools call. Without
|
|
1584
|
+
`sessionController` it still shows every run and explains, in Chinese, why the
|
|
1585
|
+
action buttons are unavailable; it does not fake a chat or an agent.
|
|
1586
|
+
|
|
1492
1587
|
## State and recovery
|
|
1493
1588
|
|
|
1494
1589
|
One file per run: `$DSH_HOME/state/superagent/runs/<runId>.json`, written with a
|
|
@@ -1683,8 +1778,8 @@ appears to "hang" until the ignored-abort child returns.
|
|
|
1683
1778
|
|
|
1684
1779
|
| What you see | What it means | What to do |
|
|
1685
1780
|
| --- | --- | --- |
|
|
1686
|
-
| `superagent_*` tools do not exist | The bundle row is not mounted, or the host refused to load the plugin. | Run `--dump-config` and check for the `@xiangyixie/dsh-superagent` block; reinstall with `dsh plugin --profile <p> add @xiangyixie/dsh-superagent@0.14.
|
|
1687
|
-
| `Cannot find module .../lib/control.js` (or `watch.js` / `report.js`)
|
|
1781
|
+
| `superagent_*` tools do not exist | The bundle row is not mounted, or the host refused to load the plugin. | Run `--dump-config` and check for the `@xiangyixie/dsh-superagent` block; reinstall with `dsh plugin --profile <p> add @xiangyixie/dsh-superagent@0.14.3` and read the host log for `[dsh-superagent]` lines. |
|
|
1782
|
+
| `Cannot find module .../lib/control.js` (or `watch.js` / `report.js` / `wizard.js`), or `[dsh-superagent] dsh-superagent failed to load because a file it imports is missing: ...` in the host log | The copy in that profile is incomplete — an `add` that was interrupted leaves a partial extraction. From 0.14.3 the entry point names the missing file itself. The published package is not the cause: every version ships all thirty-four `lib/` files. | Delete the plugin's directory under the profile's `node_modules` (scoped `@xiangyixie/dsh-superagent`, or unscoped `dsh-superagent` from an older tarball install) and run the same `add` command again, with the version number. Do not copy files in by hand. |
|
|
1688
1783
|
| `[error] the model provider rejected the API key` | The key env var is missing in the process that started the host. | Export `DEEPSEEK_API_KEY` (the default route) or the variable your route names, then restart `dsh`. |
|
|
1689
1784
|
| `MISSING_CREDENTIAL ... no API key for provider route "..."` | The profile's route has no credential in the environment. | Set the env var named for that route and restart. The error line names the route, so use that, not this page. |
|
|
1690
1785
|
| `[error] the subagent service is unavailable` | The profile has no `subagents` service, so the plugin has nothing to spawn. | Use a profile built on the base bundle (`web` or `headless` from the stock image), or add the subagent plugin to the profile. |
|