@xiangyixie/dsh-superagent 0.14.2 → 0.14.4

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,88 +8,266 @@ 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.2 — 2026-11-15
11
+ ## 0.14.4 — 2026-11-16
12
12
 
13
- ### Fixed
14
-
15
- - **The detail page carries the language switch.** `docs/DETAIL.zh.md` and
16
- `docs/DETAIL.md` now open with `中文 | English`, pointing at the other
17
- document on GitHub. The plugin detail page previously rendered a Chinese body
18
- with no way to reach the English one, even though both READMEs had the switch.
19
-
20
- ## 0.14.1 — 2026-11-15
13
+ This release gives a goal a life longer than one run, and fixes a check that
14
+ could not see a file that was already on disk.
21
15
 
22
16
  ### Added
23
17
 
24
- - **Plugin card metadata.** `icon.svg` is declared by the package manifest and
25
- exported as `./icon`; `locale/en.json` and `locale/zh.json` carry the title,
26
- description, and a `meta.detail` document. In a Chinese UI the card reads
27
- “超级智能体” with a Chinese one-line description, and the detail page renders
28
- `docs/DETAIL.zh.md` instead of the English README.
29
- - **A format-1 plugin index** at `plugin-index.json`, with the package name, a
30
- Chinese title, and a `git` source pinned to a full 40-hex commit, so the
31
- Discover page can add the index and install or update the plugin in one step.
32
- The public URL and the two-step instructions are in the README.
33
-
34
- ### Changed
35
-
36
- - `README.md` is now Simplified Chinese-first; `README.en.md` keeps the English
37
- text and both open with a language switch. `README.zh.md` mirrors the Chinese
38
- page, and `package.json`'s `description` is Chinese.
39
-
40
- ## 0.14.0 — 2026-11-15
41
-
42
- ### Added
43
-
44
- - **Attach mode is complete.** With `runtime.browser.attachPort` set, every
45
- browser tool — listing, clicking, typing, screenshots, scripts — runs on the
46
- browser the user started with `--remote-debugging-port`, on the tab that is
47
- already open. The tab keeps its own window size (no viewport override), and
48
- `browser_close` detaches instead of terminating the user's browser (a blank tab
49
- created only because no page existed is closed). A port that is not listening
50
- now fails with the port, a Chrome/Edge start command, and an explicit
51
- statement that no profile was launched in its place; attach never falls back
52
- to a fresh profile.
53
- - **Persistent profile option.** `runtime.browser.userDataDir` points a launched
54
- browser at one dedicated profile, so a sign-in done once is reused on later
55
- runs. The default is still a fresh temporary profile, which cannot see the
56
- user's daily cookies; the README spells out the trade-off and ignores
57
- `userDataDir` while `attachPort` is set.
58
- - **Human checks hand back instead of failing.** `lib/browser.js` classifies
59
- page text for a sign-in wall, CAPTCHA / "confirm you are human", SMS or
60
- one-time code, two-factor, and QR login. `browser_open`, `browser_click`, and a
61
- submitting `browser_type` stop at such a page and return `[attention]` with
62
- the page, the check, where the person finishes it, and the next call — never a
63
- failure. New `browser_await_human` polls until the check is gone and reports
64
- ok, or hands back again at its timeout. It never solves, types, or scans the
65
- check. A headless launch explains that it has no window and points at
66
- `headless: false` or attach.
67
- - **Audit distinguishes the connection.** Every browser audit line carries
68
- `meta.session: "attach" | "launch"`, plus `meta.port` and the reused tab for
69
- attach, or `meta.profile` / `meta.persistentProfile` / `meta.headless` for a
70
- launch. Human hand-offs are recorded as `kind: "attention"`,
71
- `decision: "attention"`, `result: "needs-human"`; attach failures record
72
- `rule: "runtime/attach-failed"` with the actionable message rather than being
73
- mistaken for a provider error.
74
-
75
- ### Changed
76
-
77
- - The domain allow-list, irreversible-action confirmation, file-upload refusal,
78
- stop switch, and worker-tool guard all sit in the same call path as before, so
79
- they apply unchanged on an attach connection; tests cover each one there.
80
- - `browser_type` masks the read-back value for a password field.
18
+ - **Long-term goals.** `superagent_goal` takes one goal and splits it into
19
+ ordered phases; each phase is still an ordinary run, so planning, parallel
20
+ subtasks, budgets, attention items, reports and resume keep working the way
21
+ they already did. Phases run in dependency order, retry within a budget, and
22
+ survive a host restart: a phase already finished is not planned again, and a
23
+ goal picks up from where the disk says it stopped. When a phase runs out of
24
+ budget, keeps failing without progress, or its worker and the machine check
25
+ disagree about the result, the goal stops and asks the person to decide —
26
+ `superagent_status` shows both sides of the evidence and the options (accept,
27
+ retry, stop) instead of guessing. The design is in `docs/LONG-GOAL.md`, now
28
+ shipped with the package.
29
+ - The plugin mounts thirteen tools; the new one is listed in the README.
81
30
 
82
31
  ### Fixed
83
32
 
84
- - **Costs are grouped by currency.** A run that used a USD-priced route and a
85
- CNY-priced route used to add their micro-units and label the sum with the
86
- first model's currency. It now keeps one subtotal per currency and prints
87
- them separately (`¥0.0952 + $0.0248`) in the run line, `superagent_list`'s
88
- ledger line, the `watch` footer, the exported `README.md`, and the HTML
89
- report; a mixed window gets one cost curve per currency. Single-currency runs
90
- keep the existing `¥0.3600` format, and an unpriced model stays `unpriced`
91
- rather than becoming zero.
33
+ - **A deliverable that is on disk is no longer reported as missing.** In goal
34
+ mode the deliverable check resolved declared paths against the directory the
35
+ host was launched from, while the worker wrote into the goal's workspace. The
36
+ file existed, the check looked elsewhere, and the subtask failed with
37
+ `declared deliverable missing` — then retried with a fresh worker until the
38
+ attempts ran out. The check now uses the same base directory as the goal's
39
+ own acceptance step. Relative and absolute declarations, either separator,
40
+ and a different case on Windows all name the same file, and an absolute path
41
+ outside the workspace is still refused. A write that becomes visible only
42
+ just after the check starts is re-read inside a bounded 150 ms window; a file
43
+ that is never written still fails as missing.
92
44
 
45
+ ## 0.14.3 — 2026-11-15
46
+
47
+ The release is about the three things a run could not answer for itself: which
48
+ directory it is allowed to work in, whether its files actually reached that
49
+ directory, and whether the session mounts the plugin at all.
50
+
51
+ ### Added
52
+
53
+ - **Sidebar entry and approval card.** The package now publishes
54
+ `exports["./client"]` → `lib/client.js` and declares `dsh.client.platform:
55
+ "web"`, so a web host shows a Superagent entry next to its own sidebar items
56
+ instead of leaving the console reachable only by port. The entry discovers the
57
+ console through `GET /superagent/console-address` (the route answers with the
58
+ address the host actually serves, not the port from the patch file), and
59
+ `approval/request` is bridged to the console session with `prepend` so the
60
+ approval card appears where the console is open and an unanswered request
61
+ counts as a refusal. A client bundle that does not compile is reported on the
62
+ entry itself (`client.js.broken`) instead of silently disappearing from the
63
+ sidebar.
64
+ - **First-use wizard.** `lib/wizard.js` plus `GET|POST /api/console/wizard/*`
65
+ (`status`, `preview`, `save`, `rollback`, `trial`) walk a user who has never
66
+ opened a terminal from "nothing configured" to "a real run finished": the
67
+ environment check explains each item, an API key is verified against the real
68
+ endpoint before anything is written, and the key itself goes to the host's
69
+ credential store with only its reference left in the profile patch. The patch
70
+ editor understands exactly the two entries it owns (`llm-pi-ai`,
71
+ `agent-default-model`), leaves every other line and comment untouched, and
72
+ keeps the last 10 backups restorable from the page. The last step is a real
73
+ trial run in a temporary directory, not a simulated success. Without the
74
+ wizard hooks on the host the console answers `501 wizard-unavailable` and says
75
+ why instead of drawing a dead form.
76
+ - **Task board.** `boardPort` serves one Chinese page where a run is a column
77
+ of subtask cards (status, steps, elapsed time, tokens, cost, dependencies,
78
+ and the dependency that skipped it). Cards can be cancelled or rerun one at a
79
+ time: `cancelSubtask` aborts only that child and the rest of the run
80
+ continues; `rerunSubtask` resets that subtask and any dependents skipped only
81
+ because of it, then resumes without touching completed siblings. A run whose
82
+ remaining work was all cancelled now ends as `cancelled`.
83
+ - **Human inbox.** Planner `needsInput`, deliverable reviews, missing
84
+ capabilities, policy confirmations, browser checks that need a person, and
85
+ interrupted runs are collected in one list with what happened, why a person
86
+ is needed, the options, and the effect of answering. Answers use the same
87
+ `orchestrator.answer` path as `superagent_answer`, with the run owner as the
88
+ actor and an audit line naming the answer. An empty inbox says so.
89
+ - **Plain-language failures.** `lib/board-messages.js` maps capability blocks,
90
+ unusable plans, missing deliverables, sandbox writes, `spawn EPERM`,
91
+ unavailable models, budget/deadline exhaustion, and a dead scheduler owner to
92
+ one Chinese sentence plus one action; the raw error is folded away.
93
+ - **Template forms.** The four built-in templates show their purpose,
94
+ parameters, and expected subtask count; submitting starts a run from the
95
+ board's own persisted Host Session and jumps to its board.
96
+ - **Reconnect-safe stream.** `/api/board/events` opens with a full snapshot and
97
+ polls durable run records, so a refresh or a dropped connection restores the
98
+ board instead of leaving it blank.
99
+ - **A stated policy for multi-step goals.** A session that mounts
100
+ `superagent_start` next to the host's `subagent` tool can hand-orchestrate the
101
+ work with the latter and never create a run — no plan, no timing, no merged
102
+ report, nothing in the run list. `lib/index.js` now registers an
103
+ `agent/pre-step` hook that prepends one system-reminder at the first step of a
104
+ **top-level** turn only (`delegationDepth === 0` and no `origin: "subagent"`),
105
+ never twice in the same turn, and passes a rejected step through untouched.
106
+ The text defines multi-step (two or more independently deliverable artifacts,
107
+ or a prerequisite step), names `superagent_start(mode="planned")` /
108
+ `superagent_followup` / `superagent_status`, says to call the tool first rather
109
+ than audit its own tool list, and keeps single actions (one lookup, one edit,
110
+ one command, one short piece of writing) out of a run. Guidance only: no new
111
+ tool, no new spend. `superagent_start`'s description says the same in one
112
+ sentence.
113
+ - **`workspaceBase`.** New config (`session` by default, `config` for the old
114
+ behaviour) decides what per-worker isolation is based on. See “Changed” for
115
+ what it fixes; the README table documents both values.
116
+ - **The planner preset has a card of its own.** `cordis.patch.yml` now declares
117
+ the tool-less `planner` preset with the Chinese name
118
+ “插件内部:规划器(请勿选择)”, a description saying that picking it leaves the
119
+ session with no tools, and `order: 9999`. A fresh install used to show a bare
120
+ `planner` row with an empty description at the top of the mode picker. The
121
+ host preset schema has no hidden/internal field, so this is the closest the
122
+ schema allows.
123
+
124
+ ### Changed
125
+
126
+ - **Four workers per layer by default.** `maxParallel` now defaults to 4 (hard
127
+ max 8) instead of 3, so a plan whose layer has three independent subtasks
128
+ starts all three instead of queueing the third. Dependency order is unchanged —
129
+ a subtask still starts only after its `dependsOn` finish — and two subtasks
130
+ that declare the same deliverable path are never in flight together, so a wider
131
+ layer cannot turn a same-file race into a lost file.
132
+ - **A budget stop is a notice, not an error.** Hitting `maxModelCallsPerRun` or
133
+ `maxTokensPerRun` no longer writes `model-call budget reached (86/80 calls)`
134
+ into the run's `error`. It is recorded as `budgetStop` (detail, time, calls,
135
+ tokens), the status text prints it as `note: stopped starting new workers — …`,
136
+ and a run that still finished every subtask stays `completed` with `error`
137
+ null. A run that did not finish keeps the detail in `error` so the reason is
138
+ not lost, and the scheduler still pauses a plan on it.
139
+ - **A run whose files never reached the target is `partial`, not `completed`.**
140
+ A skipped merge (uncommitted changes in the main checkout) and a conflict both
141
+ leave the worker's work only inside its branch. Such a run now drops to
142
+ `partial` and records one attention item naming: the branches, the worktree
143
+ each is kept in, why the merge was refused, the two options, and the exact
144
+ `git stash push -u` plus `git merge --no-ff <branch>` commands that finish it
145
+ by hand. Nothing is deleted, so a manual merge stays possible.
146
+ - **The package entry point is `lib/entry.js`.** `main` and `exports["."]` point
147
+ at a file whose only job is to import `lib/index.js`; a missing sibling
148
+ (`wizard.js`, `board.js`, …) is caught there and reported as the missing file
149
+ plus the fix (`Copy-Item lib\* -Force`, or reinstall) instead of the plugin
150
+ vanishing with no explanation.
151
+ - **`superagent_status` reports a version mismatch.** When `package.json` on
152
+ disk differs from the version the host loaded, the status text ends with
153
+ `note: ... restart DSH`. Code is read once at startup, so replacing files
154
+ changes nothing until a restart; the README's install section now says so.
155
+ - **Child activations carry the delegation fields twice.** `startActivation` is
156
+ given both `request` and the same fields at the top level of the spec, because
157
+ dsh 0.2.2-rc.1 reads the former and the desktop host (0.2.2-rc.3) reads the
158
+ latter and otherwise throws `Cannot read properties of undefined (reading
159
+ 'id')` before any child exists.
160
+ - **The planner failure log keeps the host stack.** A planner attempt that fails
161
+ inside the host now logs the stack alongside the message that goes into the
162
+ run file.
163
+ - **Docs.** `README.md` / `README.en.md` / `README.zh.md` gained the restart
164
+ requirement and the `workspaceBase` row; `docs/DETAIL.md` and
165
+ `docs/DETAIL.zh.md` open “What it solves” with the dispatch-desk case (work
166
+ spread across domains costs more to manage than to do). `docs/host-compat.md`
167
+ lists every rc.1/rc.3 shape difference the plugin papers over — start-request
168
+ field placement, child handle, host service probes, preset schema — with the
169
+ file and line to re-check when the host changes.
170
+
171
+ ### Fixed
172
+
173
+ - **Isolation followed `workspaceRoot` even when it named another project.**
174
+ The base was taken from the profile, while the sandbox boundary, the declared
175
+ deliverables, and the merge target all came from the session — so merges
176
+ landed where nobody looked, or were refused because that checkout had
177
+ unrelated local edits. The default (`workspaceBase: "session"`) now uses the
178
+ session's cwd (or the repository root git resolves from it) and honours
179
+ `workspaceRoot` only when it names that same directory, comparing paths
180
+ case-insensitively on Windows. A mismatch is recorded on the run as
181
+ `workspace.baseNote` and printed by status as `workspace warning: ...` instead
182
+ of being silently applied; when isolation is impossible, the shared directory
183
+ reported as `base` is the session's too.
184
+ - **A merge that never happened used to print `completed`.** The user opened the
185
+ target directory and found it empty. Covered by the `partial` change above.
186
+ - **An incomplete install no longer looks like a plugin with no tools.**
187
+ Covered by the entry-point change above.
188
+
189
+ ## 0.14.2 — 2026-11-15
190
+
191
+ ### Fixed
192
+
193
+ - **The detail page carries the language switch.** `docs/DETAIL.zh.md` and
194
+ `docs/DETAIL.md` now open with `中文 | English`, pointing at the other
195
+ document on GitHub. The plugin detail page previously rendered a Chinese body
196
+ with no way to reach the English one, even though both READMEs had the switch.
197
+
198
+ ## 0.14.1 — 2026-11-15
199
+
200
+ ### Added
201
+
202
+ - **Plugin card metadata.** `icon.svg` is declared by the package manifest and
203
+ exported as `./icon`; `locale/en.json` and `locale/zh.json` carry the title,
204
+ description, and a `meta.detail` document. In a Chinese UI the card reads
205
+ “超级智能体” with a Chinese one-line description, and the detail page renders
206
+ `docs/DETAIL.zh.md` instead of the English README.
207
+ - **A format-1 plugin index** at `plugin-index.json`, with the package name, a
208
+ Chinese title, and a `git` source pinned to a full 40-hex commit, so the
209
+ Discover page can add the index and install or update the plugin in one step.
210
+ The public URL and the two-step instructions are in the README.
211
+
212
+ ### Changed
213
+
214
+ - `README.md` is now Simplified Chinese-first; `README.en.md` keeps the English
215
+ text and both open with a language switch. `README.zh.md` mirrors the Chinese
216
+ page, and `package.json`'s `description` is Chinese.
217
+
218
+ ## 0.14.0 — 2026-11-15
219
+
220
+ ### Added
221
+
222
+ - **Attach mode is complete.** With `runtime.browser.attachPort` set, every
223
+ browser tool — listing, clicking, typing, screenshots, scripts — runs on the
224
+ browser the user started with `--remote-debugging-port`, on the tab that is
225
+ already open. The tab keeps its own window size (no viewport override), and
226
+ `browser_close` detaches instead of terminating the user's browser (a blank tab
227
+ created only because no page existed is closed). A port that is not listening
228
+ now fails with the port, a Chrome/Edge start command, and an explicit
229
+ statement that no profile was launched in its place; attach never falls back
230
+ to a fresh profile.
231
+ - **Persistent profile option.** `runtime.browser.userDataDir` points a launched
232
+ browser at one dedicated profile, so a sign-in done once is reused on later
233
+ runs. The default is still a fresh temporary profile, which cannot see the
234
+ user's daily cookies; the README spells out the trade-off and ignores
235
+ `userDataDir` while `attachPort` is set.
236
+ - **Human checks hand back instead of failing.** `lib/browser.js` classifies
237
+ page text for a sign-in wall, CAPTCHA / "confirm you are human", SMS or
238
+ one-time code, two-factor, and QR login. `browser_open`, `browser_click`, and a
239
+ submitting `browser_type` stop at such a page and return `[attention]` with
240
+ the page, the check, where the person finishes it, and the next call — never a
241
+ failure. New `browser_await_human` polls until the check is gone and reports
242
+ ok, or hands back again at its timeout. It never solves, types, or scans the
243
+ check. A headless launch explains that it has no window and points at
244
+ `headless: false` or attach.
245
+ - **Audit distinguishes the connection.** Every browser audit line carries
246
+ `meta.session: "attach" | "launch"`, plus `meta.port` and the reused tab for
247
+ attach, or `meta.profile` / `meta.persistentProfile` / `meta.headless` for a
248
+ launch. Human hand-offs are recorded as `kind: "attention"`,
249
+ `decision: "attention"`, `result: "needs-human"`; attach failures record
250
+ `rule: "runtime/attach-failed"` with the actionable message rather than being
251
+ mistaken for a provider error.
252
+
253
+ ### Changed
254
+
255
+ - The domain allow-list, irreversible-action confirmation, file-upload refusal,
256
+ stop switch, and worker-tool guard all sit in the same call path as before, so
257
+ they apply unchanged on an attach connection; tests cover each one there.
258
+ - `browser_type` masks the read-back value for a password field.
259
+
260
+ ### Fixed
261
+
262
+ - **Costs are grouped by currency.** A run that used a USD-priced route and a
263
+ CNY-priced route used to add their micro-units and label the sum with the
264
+ first model's currency. It now keeps one subtotal per currency and prints
265
+ them separately (`¥0.0952 + $0.0248`) in the run line, `superagent_list`'s
266
+ ledger line, the `watch` footer, the exported `README.md`, and the HTML
267
+ report; a mixed window gets one cost curve per currency. Single-currency runs
268
+ keep the existing `¥0.3600` format, and an unpriced model stays `unpriced`
269
+ rather than becoming zero.
270
+
93
271
  ## 0.13.0 — 2026-11-15
94
272
 
95
273
  ### 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.2
30
+ dsh plugin --profile web add @xiangyixie/dsh-superagent@0.14.4
31
31
  ```
32
32
 
33
33
  Then ask the session for a run — a real call, not a sketch:
@@ -40,7 +40,7 @@ covers the path from an empty machine, including the reason not to install npm's
40
40
  unrelated `dsh` package by name.
41
41
 
42
42
  It adds no in-host UI (the workspace panel and the conversation console are
43
- loopback pages) and patches no host code: the twelve `superagent_*` tools are the
43
+ loopback pages) and patches no host code: the thirteen `superagent_*` tools are the
44
44
  surface, plus six optional operator utilities (a terminal panel, an HTML report,
45
45
  an install doctor, a run archive, git sync, and the workspace panel) that read the
46
46
  same run files. Browser and desktop control is a separate layer: with
@@ -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.2
83
+ dsh plugin --profile web add @xiangyixie/dsh-superagent@0.14.4
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.2` | Installs from npm. Name the version (see below). |
105
- | GitHub repository | `https://github.com/LittleChenLiya/dsh-superagent` | Installs from the repository. Add `#v0.14.2` if you need a fixed release. |
104
+ | Package name | `@xiangyixie/dsh-superagent@0.14.4` | Installs from npm. Name the version (see below). |
105
+ | GitHub repository | `https://github.com/LittleChenLiya/dsh-superagent` | Installs from the repository. Add `#v0.14.4` 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: 3
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` | `3` | Subtasks executing at once. A tool argument can only lower it; hard max 8. |
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` | host cwd | Repository the workers are isolated in when `workspaceIsolation` is on. Must be a git working tree with at least one commit. |
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, because a conflict is
412
- the one outcome that needs the user even when the run itself "completed". Nothing
413
- is discarded: the branch and its checkout are kept until you merge or delete
414
- them. Two more cases are reported the same way rather than silently dropped:
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
- **When isolation is not possible.** If `workspaceRoot` is not a git working tree,
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
@@ -794,7 +823,7 @@ and captures the window.
794
823
  (project rules), `profile` (user preferences), or the run scope. `search`
795
824
  ranks notes against `query` (the current goal works well) and/or exact `tags`,
796
825
  so a relevant old note is found instead of only the newest ones; notes can
797
- carry `tags` when set. The tool is additive: the eleven other tools keep their
826
+ carry `tags` when set. The tool is additive: the twelve other tools keep their
798
827
  arguments and output.
799
828
  - `superagent_template(action, id?, params?, template?, limit?)` lists, shows,
800
829
  expands, saves, or deletes a workflow template: a fixed goal skeleton with
@@ -812,6 +841,18 @@ and captures the window.
812
841
  goal (or an expanded template), a clock, and its own limits; it survives a host
813
842
  restart and starts runs nobody asked for. Nothing is armed until a plan exists.
814
843
  See [Scheduled runs](#scheduled-runs).
844
+ - `superagent_goal(action, goal_id?, goal?, phases?, cwd?, budget?, phase_budget?,
845
+ max_parallel_phases?, max_attempts_per_phase?, auto_resume?, decision_id?, answer?,
846
+ note?, limit?)` turns one natural-language goal into dependent phases, each phase
847
+ an ordinary run, advancing up to `max_parallel_phases` at once and surviving a host
848
+ restart. `create` decomposes with one direct run when `phases` is omitted;
849
+ `status`/`list` report phase state, run ids, usage, and open decisions; `answer`
850
+ settles phase-exhausted, verification-conflict, and stalled decisions;
851
+ `pause`/`resume`/`cancel` govern the whole goal. A phase budget is clamped to what
852
+ the goal has left, and the goal budget sums every phase, retry, and decompose run.
853
+ It extends the run engine rather than replacing it: planner, dependency graph,
854
+ budgets, attention, persistence, and resume are the same code. See
855
+ [docs/LONG-GOAL.md](docs/LONG-GOAL.md).
815
856
  - `superagent_audit(run_id?, subtask_id?, kind?, decision?, result?, target?,
816
857
  since?, until?, limit?, order?, format?, out_path?)` reads the audit trail, or
817
858
  exports the matching events as one JSONL or CSV file. See
@@ -1265,7 +1306,7 @@ records the command plus a zero-external-reference audit.
1265
1306
  does. It reads only: no install, no mount, no edit to the profile. One block per
1266
1307
  check — imported files against the `files` whitelist, declared files against
1267
1308
  what is on disk, the installed copy against the published tarball for its
1268
- version, the profile's bundle registration, and the twelve registered tools — each
1309
+ version, the profile's bundle registration, and the thirteen registered tools — each
1269
1310
  failure followed by the command that fixes it.
1270
1311
 
1271
1312
  ```bash
@@ -1421,6 +1462,16 @@ The bound URL and a fresh per-process token are written to
1421
1462
  the event stream, answers `401` without it, and every request with a non-loopback
1422
1463
  `Host` header answers `403`.
1423
1464
 
1465
+ On a fresh install the page opens with 首次使用向导 (first-use wizard): an
1466
+ environment check, an API key verified against the real endpoint before anything
1467
+ is written, a preview and save of the profile patch, and one real trial run in a
1468
+ temporary directory. Every save leaves a restorable backup (the last 10), the key
1469
+ goes only to the host's credential store while the patch keeps its reference, and
1470
+ the editor touches just the two entries it owns (`llm-pi-ai`,
1471
+ `agent-default-model`). A host without the wizard hooks answers
1472
+ `501 wizard-unavailable`, so the button says that rather than opening a form that
1473
+ cannot work.
1474
+
1424
1475
  If the host does not mount `sessionController` (for example a headless profile
1425
1476
  without the web session API), the page says so and refuses to create a session.
1426
1477
  It does **not** pretend to be a chat. The console also keeps one active
@@ -1489,6 +1540,62 @@ When `workbenchPort` is on, the plugin records the files each run changed into
1489
1540
  that run's JSON record (`run.changes`), so the Runs view can show those files and
1490
1541
  their diff against `git HEAD` later.
1491
1542
 
1543
+ ## Task board
1544
+
1545
+ `boardPort` adds the page to open when you do not want to read a run record.
1546
+ It is written for someone who has never seen the plugin: every subtask is a
1547
+ card, everything that waits for a person is in one inbox, and the four built-in
1548
+ templates start with a form instead of a prompt.
1549
+
1550
+ ```yaml
1551
+ - id: superagent
1552
+ config:
1553
+ boardPort: 0 # off by default; 0 = OS picks a free loopback port
1554
+ boardRoot: /path/to/project
1555
+ ```
1556
+
1557
+ Open the URL in `<stateDir>/board.json` (mode `0600`), or use
1558
+ `http://127.0.0.1:<port>/?token=<token>`; the token is stored in the browser and
1559
+ removed from the address bar. Every route and the event stream answer `401`
1560
+ without it, and a non-loopback `Host` answers `403`. The stream opens with a
1561
+ full snapshot, so a reconnect or a page refresh restores the board from durable
1562
+ run records instead of a blank page.
1563
+
1564
+ **Board.** One card per subtask with its status, attempts, elapsed time, tokens,
1565
+ cost, dependencies, and — when it did not run — the dependency that stopped it.
1566
+ Each card can be cancelled on its own or rerun on its own. `cancelSubtask`
1567
+ aborts only that child; the rest of the run keeps going, and dependents are
1568
+ skipped with `not started because w2 was cancelled`. `rerunSubtask` resets that
1569
+ one subtask (plus dependents that were skipped only because of it) and resumes
1570
+ the run; completed siblings are not touched. A run whose entire remaining work
1571
+ was cancelled reports `cancelled`, not `failed`.
1572
+
1573
+ **Inbox.** Planner `needsInput` questions, deliverable reviews (`unverified`),
1574
+ missing capabilities, policy confirmations, browser checks that need a person,
1575
+ and interrupted runs. Each item says what happened, why a person is needed, the
1576
+ options, and what answering will do. Answers go through the same
1577
+ `orchestrator.answer` path as `superagent_answer`, with the run's owning session
1578
+ as the actor, and the audit trail records who answered what. When nothing is
1579
+ waiting, the page says "当前没有需要你处理的事" instead of showing an empty
1580
+ column.
1581
+
1582
+ **Templates.** `bugfix-verify`, `review-fix`, `docs-examples`, and
1583
+ `research-report` are forms: purpose, parameters, and the expected subtask
1584
+ count. Submitting expands the template, starts one run from the board's own
1585
+ persisted Host Session, and jumps to its board.
1586
+
1587
+ **Plain-language failures.** Capability preflight blocks, unparsable plans,
1588
+ missing or wrong-type deliverables, sandbox write denial, `spawn EPERM`,
1589
+ unavailable models/endpoints, budget or deadline exhaustion, and a dead
1590
+ scheduler owner session each map to one Chinese sentence plus one action
1591
+ (retry, rerun, open configuration, or copy diagnostics). The raw stack stays
1592
+ folded under "原始错误(给技术同学看)".
1593
+
1594
+ The board never owns a run. It resolves the run's `parentSessionId` through the
1595
+ host and calls the same orchestrator methods the tools call. Without
1596
+ `sessionController` it still shows every run and explains, in Chinese, why the
1597
+ action buttons are unavailable; it does not fake a chat or an agent.
1598
+
1492
1599
  ## State and recovery
1493
1600
 
1494
1601
  One file per run: `$DSH_HOME/state/superagent/runs/<runId>.json`, written with a
@@ -1683,8 +1790,8 @@ appears to "hang" until the ignored-abort child returns.
1683
1790
 
1684
1791
  | What you see | What it means | What to do |
1685
1792
  | --- | --- | --- |
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.2` and read the host log for `[dsh-superagent]` lines. |
1687
- | `Cannot find module .../lib/control.js` (or `watch.js` / `report.js`) and the plugin never activates | The copy in that profile is incomplete — an `add` that was interrupted leaves a partial extraction. The published package is not the cause: every version ships all thirty `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. |
1793
+ | `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.4` and read the host log for `[dsh-superagent]` lines. |
1794
+ | `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
1795
  | `[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
1796
  | `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
1797
  | `[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. |