@xiangyixie/dsh-superagent 0.12.1 → 0.14.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 +171 -8
- package/LICENSE +21 -21
- package/README.md +522 -40
- package/bin/doctor.js +1 -1
- package/cordis.patch.yml +9 -9
- package/lib/audit.js +8 -1
- package/lib/browser.js +795 -0
- package/lib/console.js +763 -0
- package/lib/cost.js +71 -11
- package/lib/cron.js +387 -0
- package/lib/desktop.js +507 -0
- package/lib/doctor.js +1 -0
- package/lib/goal.js +649 -0
- package/lib/guard.js +15 -0
- package/lib/index.js +1296 -42
- package/lib/ledger.js +26 -12
- package/lib/orchestrator.js +1765 -136
- package/lib/report.js +59 -29
- package/lib/runtime-control.js +1151 -0
- package/lib/schedule.js +1030 -0
- package/lib/store.js +6 -2
- package/lib/user-memory.js +587 -0
- package/lib/watch.js +25 -17
- package/lib/workbench.js +7 -7
- package/lib/workspace.js +88 -27
- package/package.json +101 -92
- package/public/console.html +1618 -0
package/README.md
CHANGED
|
@@ -25,7 +25,7 @@ filesystem; this is not a sandbox.
|
|
|
25
25
|
in the environment:
|
|
26
26
|
|
|
27
27
|
```bash
|
|
28
|
-
dsh plugin --profile web add @xiangyixie/dsh-superagent@0.
|
|
28
|
+
dsh plugin --profile web add @xiangyixie/dsh-superagent@0.14.0
|
|
29
29
|
```
|
|
30
30
|
|
|
31
31
|
Then ask the session for a run — a real call, not a sketch:
|
|
@@ -37,10 +37,13 @@ The reply ends `completed` with the merged report, or with
|
|
|
37
37
|
covers the path from an empty machine, including the reason not to install npm's
|
|
38
38
|
unrelated `dsh` package by name.
|
|
39
39
|
|
|
40
|
-
It adds no in-host UI (the
|
|
41
|
-
no host code: the
|
|
42
|
-
operator utilities (a terminal panel, an HTML report,
|
|
43
|
-
archive, git sync, and the workspace panel) that read the
|
|
40
|
+
It adds no in-host UI (the workspace panel and the conversation console are
|
|
41
|
+
loopback pages) and patches no host code: the twelve `superagent_*` tools are the
|
|
42
|
+
surface, plus six optional operator utilities (a terminal panel, an HTML report,
|
|
43
|
+
an install doctor, a run archive, git sync, and the workspace panel) that read the
|
|
44
|
+
same run files. Browser and desktop control is a separate layer: with
|
|
45
|
+
`runtime.enabled` set, fourteen more tools are registered, and with the default
|
|
46
|
+
`false` none of them exist.
|
|
44
47
|
|
|
45
48
|
Personal project, not affiliated with DeepSeek or the harness maintainers. MIT
|
|
46
49
|
licensed, © 2026 Admire (LittleChenLiya); details in [License](#license).
|
|
@@ -75,12 +78,25 @@ your `PATH`, use `npx @deepseek-ai/dsh@0.2.2-rc.1` instead.
|
|
|
75
78
|
|
|
76
79
|
```bash
|
|
77
80
|
# 1. install the plugin into a profile (web, headless, ... whatever you run)
|
|
78
|
-
dsh plugin --profile web add @xiangyixie/dsh-superagent@0.
|
|
81
|
+
dsh plugin --profile web add @xiangyixie/dsh-superagent@0.14.0
|
|
79
82
|
|
|
80
83
|
# 2. confirm the bundle row exists in the merged config
|
|
81
84
|
dsh --profile web --dump-config
|
|
82
85
|
```
|
|
83
86
|
|
|
87
|
+
The desktop app's **Add plugin** dialog accepts the same three forms:
|
|
88
|
+
|
|
89
|
+
| Dialog input | Value | What it does |
|
|
90
|
+
| --- | --- | --- |
|
|
91
|
+
| Package name | `@xiangyixie/dsh-superagent@0.14.0` | Installs from npm. Name the version (see below). |
|
|
92
|
+
| GitHub repository | `https://github.com/LittleChenLiya/dsh-superagent` | Installs from the repository. Add `#v0.14.0` if you need a fixed release. |
|
|
93
|
+
| Local directory | `file:/absolute/path/to/dsh-superagent` | Copies the checkout. Re-add after changing the source. |
|
|
94
|
+
|
|
95
|
+
Upgrading is remove-then-add, not in-place: remove the old copy
|
|
96
|
+
(`dsh plugin --profile web remove @xiangyixie/dsh-superagent`) before adding
|
|
97
|
+
the new version. The same applies to any other plugin already in that profile —
|
|
98
|
+
remove and re-add it rather than expecting the dialog or `add` to replace it.
|
|
99
|
+
|
|
84
100
|
Name the version. Without one, pnpm's minimum release age policy skips releases
|
|
85
101
|
published in the last few hours and installs the newest older one, so a bare
|
|
86
102
|
`add` succeeds while giving you a version that is not current. If you would
|
|
@@ -100,15 +116,6 @@ npm pack # writes xiangyixie-dsh-superagent-<ve
|
|
|
100
116
|
dsh plugin --profile web add ./xiangyixie-dsh-superagent-<version>.tgz
|
|
101
117
|
```
|
|
102
118
|
|
|
103
|
-
If you are working on the plugin itself, install the checkout instead:
|
|
104
|
-
|
|
105
|
-
```bash
|
|
106
|
-
dsh plugin --profile web add file:/absolute/path/to/dsh-superagent
|
|
107
|
-
```
|
|
108
|
-
|
|
109
|
-
`file:` installs copy the package; re-run the `add` after changing the source,
|
|
110
|
-
or the profile keeps running the old copy.
|
|
111
|
-
|
|
112
119
|
Look for this block in the dump. If it is missing, the plugin is installed but
|
|
113
120
|
not mounted, and no `superagent_*` tool will exist:
|
|
114
121
|
|
|
@@ -203,7 +210,13 @@ Row config in `<profile>/cordis.patch.yml`:
|
|
|
203
210
|
| `childProvider` | parent's | Optional provider route override for child agents. |
|
|
204
211
|
| `childModel` | parent's | Optional model override for child agents. |
|
|
205
212
|
| `childPreset` | none | Agent preset for child agents. A preset owns the child's tool set; this host has no per-run tool filter. |
|
|
213
|
+
| `plannerPreset` | none | Agent preset for the planner child only. Use a tool-less preset: a planner only reads its prompt and returns JSON, and inherited tools invite a tool loop instead of a plan. Requires the host to compose an `agentPresets` registry. |
|
|
214
|
+
| `plannerProvider` | parent's | Optional provider route override for the planner child. |
|
|
215
|
+
| `plannerModel` | parent's | Optional model override for the planner child. Planning is a single JSON turn, so a stronger model here is usually cheaper than fixing plans after workers ran. |
|
|
216
|
+
| `plannerTimeoutSeconds` | `120` | Wall-clock bound per planner attempt. On expiry the attempt is stopped and recorded; no fallback worker is started. |
|
|
217
|
+
| `plannerMaxModelCalls` | `20` | Model calls the planning phase may spend across attempts; `0` disables. Once spent, the run fails as unplannable instead of draining the run budget. |
|
|
206
218
|
| `maxSubagentDepth` | `1` | How deep children may delegate. `1` forbids grandchildren; `provider-managed` leaves it to the backend. |
|
|
219
|
+
| `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). |
|
|
207
220
|
| `maxSubtasks` | `8` | Cap on planned subtasks. A tool argument can only lower it, never raise it; hard max 16. |
|
|
208
221
|
| `maxParallel` | `3` | Subtasks executing at once. A tool argument can only lower it; hard max 8. |
|
|
209
222
|
| `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. |
|
|
@@ -228,6 +241,7 @@ Row config in `<profile>/cordis.patch.yml`:
|
|
|
228
241
|
| `memoryMaxAgeDays` | `30` | Notes older than this are ignored, then compacted away. |
|
|
229
242
|
| `memoryDigestEntries` | `12` | Notes injected into a prompt. |
|
|
230
243
|
| `memoryDigestChars` | `1600` | Character budget for the note part of that prompt. |
|
|
244
|
+
| `memoryUserProfile` | `false` | Cross-task user profile (facts, preferences, decisions) under `<stateDir>/user-memory`. Off means nothing is constructed and no directory is created. See [User profile](#user-profile). |
|
|
231
245
|
| `keepRuns` | `0` | Delete terminal runs older than this many days at mount; `0` keeps everything. |
|
|
232
246
|
| `guard` | on | Worker path and command policy. See [Worker safety guard](#worker-safety-guard) for every default and the reason behind it. |
|
|
233
247
|
| `audit` | `true` | Append-only audit trail. It only observes; turning it off removes the trail, never the run behaviour. |
|
|
@@ -238,6 +252,12 @@ Row config in `<profile>/cordis.patch.yml`:
|
|
|
238
252
|
| `workspaceRoot` | host cwd | Repository the workers are isolated in when `workspaceIsolation` is on. Must be a git working tree with at least one commit. |
|
|
239
253
|
| `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. |
|
|
240
254
|
| `workbenchRoot` | `process.cwd()` | Directory the panel may browse and edit. Every path outside it is refused. |
|
|
255
|
+
| `consolePort` | off | Loopback port for the conversation console; `0` picks a free one. Requires the host `sessionController` service. |
|
|
256
|
+
| `consoleRoot` | `workbenchRoot`, then host cwd | Directory the console's conversation session joins. |
|
|
257
|
+
| `consolePreset` | host default | Agent preset id the console session mounts. Tools follow this preset, not this plugin. |
|
|
258
|
+
| `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. |
|
|
259
|
+
| `schedulerHumanPriority` | `true` | Default for a plan's `human_priority`: a scheduled run may not take the last free concurrency slot. |
|
|
260
|
+
| `schedulerMaxConsecutiveFailures` | `3` | Consecutive failed executions before a plan pauses itself and says so once (1–20). |
|
|
241
261
|
|
|
242
262
|
### Switching models
|
|
243
263
|
|
|
@@ -279,6 +299,54 @@ list, but the run tools (`superagent_start`, `superagent_resume`, `superagent_ca
|
|
|
279
299
|
`superagent_followup`, `superagent_inject`, `superagent_answer`) refuse to run from a worker session;
|
|
280
300
|
only the top-level agent manages runs.
|
|
281
301
|
|
|
302
|
+
### Per-worker command permissions
|
|
303
|
+
|
|
304
|
+
A `workspace-write` host sandbox refuses a child process spawned with piped
|
|
305
|
+
stdio (`EPERM`). A worker that needs to run `npm test` therefore cannot do so
|
|
306
|
+
under the inherited policy, and this plugin will not turn the sandbox off for
|
|
307
|
+
the whole machine. `commandWorkerPermission` raises it only for the workers that
|
|
308
|
+
declare it:
|
|
309
|
+
|
|
310
|
+
```yaml
|
|
311
|
+
- id: superagent
|
|
312
|
+
config:
|
|
313
|
+
commandWorkerPermission: danger-full-access
|
|
314
|
+
```
|
|
315
|
+
|
|
316
|
+
With that setting, a worker whose plan entry has `requires` containing a command
|
|
317
|
+
capability (`shell`, `bash`, `sh`, `zsh`, `fish`, `terminal`, `pwsh`,
|
|
318
|
+
`powershell`, `cmd`, `run_command`, `exec_command`) gets full access. Planner,
|
|
319
|
+
aggregator, acceptance judges, and workers without such a capability keep the
|
|
320
|
+
inherited mode.
|
|
321
|
+
|
|
322
|
+
How it works, and why it is a delegation trick rather than a host feature:
|
|
323
|
+
|
|
324
|
+
- The host has no per-subagent permission field. What it does have is
|
|
325
|
+
inheritance: `subagents.startActivation` captures the parent session's last
|
|
326
|
+
`sandbox/mode` event **synchronously, before its first `await`**, and seeds
|
|
327
|
+
that mode into the child.
|
|
328
|
+
- For one qualifying worker, the plugin appends `sandbox/mode:
|
|
329
|
+
danger-full-access` to the parent session, calls `startActivation`, and
|
|
330
|
+
appends the previous mode back in a `finally` — all in the same synchronous
|
|
331
|
+
tick, with no `await` between those steps. A concurrent call can therefore
|
|
332
|
+
never observe the temporary override, and the child still captures it.
|
|
333
|
+
- Both steps append one `sandbox/mode` event; the plugin never uses
|
|
334
|
+
`permissionPresets.set()`, whose `custom` state cannot be restored by name.
|
|
335
|
+
- The approval policy is pinned to `never` for that child by the host's own
|
|
336
|
+
delegation capture, not by this plugin.
|
|
337
|
+
- Each step is written to the audit trail as `worker.escalate` and
|
|
338
|
+
`worker.restore` with `runId`, `subtaskId`, and the reason (the declared
|
|
339
|
+
capability). When `audit` is off, no audit line is written; the escalation
|
|
340
|
+
still behaves the same.
|
|
341
|
+
|
|
342
|
+
Limits: this only applies to in-process providers whose child is created from
|
|
343
|
+
the parent session in the same host process (`provider: spawn`). An upstream
|
|
344
|
+
change to when the override is captured — or to delegation inheritance itself —
|
|
345
|
+
makes this silently fall back to inheritance rather than fail the run. The
|
|
346
|
+
temporary event also pins the previous mode in the parent log when the parent
|
|
347
|
+
had no explicit override: it records the deployment default, which is
|
|
348
|
+
behaviourally identical until that default changes.
|
|
349
|
+
|
|
282
350
|
### Per-worker workspace isolation
|
|
283
351
|
|
|
284
352
|
Parallel workers are independent agents, but by default they share one working
|
|
@@ -300,9 +368,13 @@ user can run to finish by hand. A recursive copy would either need a diff3
|
|
|
300
368
|
engine (a dependency this package does not have) or overwrite the main checkout,
|
|
301
369
|
which is the bug the feature exists to prevent. A worktree also shares the object
|
|
302
370
|
database and ignore rules, so a worker sees the real repository without a full
|
|
303
|
-
copy of it. Worktrees live under
|
|
304
|
-
directory
|
|
305
|
-
|
|
371
|
+
copy of it. Worktrees live under `.superagent/worktrees/<runId>/w<n>` inside the
|
|
372
|
+
directory the host was started in — the repository itself when that is the
|
|
373
|
+
starting directory. The host's `workspace-write` sandbox takes its writable
|
|
374
|
+
boundary from the session cwd, so a checkout under the state directory, or
|
|
375
|
+
inside a repository the host was not started in, would be denied every write.
|
|
376
|
+
The pool carries its own `.gitignore`, so worker checkouts never leak into the
|
|
377
|
+
user's next commit or make the main checkout look dirty.
|
|
306
378
|
|
|
307
379
|
**What happens during a run.** Each worker is given
|
|
308
380
|
`superagent/<runId>-w<n>`, a branch created from the main checkout's `HEAD`. Its
|
|
@@ -319,7 +391,7 @@ The outcome is recorded on the run and printed by `superagent_status`:
|
|
|
319
391
|
|
|
320
392
|
```
|
|
321
393
|
workspace conflict: [2] src/routes.js, src/index.js — branch superagent/20261115T101500-ab12-w2
|
|
322
|
-
kept at <
|
|
394
|
+
kept at <repository>/.superagent/worktrees/20261115T101500-ab12/w2; the main checkout was restored, so nothing
|
|
323
395
|
was lost. Resolve with: git -C "/home/me/projects/api" merge superagent/20261115T101500-ab12-w2
|
|
324
396
|
```
|
|
325
397
|
|
|
@@ -460,6 +532,167 @@ number you see is always a lower bound:
|
|
|
460
532
|
cost: at least ¥0.0041 (estimate; no price for haoduo/gpt-6.1-sol)
|
|
461
533
|
```
|
|
462
534
|
|
|
535
|
+
Amounts are kept per currency and never added across currencies. A run that
|
|
536
|
+
used both a CNY route and a USD route prints one subtotal per currency:
|
|
537
|
+
|
|
538
|
+
```
|
|
539
|
+
cost: ¥0.0952 + $0.0248 (estimate; all models priced)
|
|
540
|
+
```
|
|
541
|
+
|
|
542
|
+
The same rule holds for `superagent_list`'s ledger line, the live `watch`
|
|
543
|
+
footer, the exported `README.md`, and the HTML report — a mixed window gets one
|
|
544
|
+
figure per currency instead of a single number whose unit would be undefined.
|
|
545
|
+
|
|
546
|
+
## Runtime control
|
|
547
|
+
|
|
548
|
+
The plugin can drive a browser and, on Windows, the desktop. Both halves are
|
|
549
|
+
**off by default**: with `runtime.enabled` false not one of these tools is
|
|
550
|
+
registered, so an existing profile sees exactly the same tool list as before.
|
|
551
|
+
Nothing here needs an npm dependency — the browser is spoken to over the
|
|
552
|
+
DevTools protocol with Node's own `WebSocket`, and the desktop is reached
|
|
553
|
+
through `powershell.exe` and `user32.dll`.
|
|
554
|
+
|
|
555
|
+
```json
|
|
556
|
+
{
|
|
557
|
+
"@xiangyixie/dsh-superagent": {
|
|
558
|
+
"runtime": {
|
|
559
|
+
"enabled": true,
|
|
560
|
+
"browser": {
|
|
561
|
+
"headless": true,
|
|
562
|
+
"allowedHosts": ["localhost", "127.0.0.1"],
|
|
563
|
+
"executablePath": null,
|
|
564
|
+
"attachPort": null,
|
|
565
|
+
"userDataDir": null
|
|
566
|
+
},
|
|
567
|
+
"desktop": { "enabled": false, "allowActivation": false }
|
|
568
|
+
}
|
|
569
|
+
}
|
|
570
|
+
}
|
|
571
|
+
```
|
|
572
|
+
|
|
573
|
+
`enabled` turns the layer on. `browser.enabled` and `desktop.enabled` decide
|
|
574
|
+
which halves register; desktop is separately gated because it can touch any
|
|
575
|
+
application on the machine. `allowedHosts` replaces the loopback default — a
|
|
576
|
+
leading `*.` matches any subdomain. `stopFile` and `shotDir` default to
|
|
577
|
+
`<stateDir>/runtime/STOP` and `<stateDir>/runtime/shots`.
|
|
578
|
+
|
|
579
|
+
`attachPort` and `userDataDir` are the two ways to reach a page that needs a
|
|
580
|
+
sign-in, and they trade differently:
|
|
581
|
+
|
|
582
|
+
- **`attachPort`** (for example `9222`) borrows the browser you started
|
|
583
|
+
yourself with `--remote-debugging-port`. Element listing, clicks, typing, and
|
|
584
|
+
screenshots all run on that connection, the tab keeps its own window size, and
|
|
585
|
+
`browser_close` only detaches — it never terminates your browser. If the port
|
|
586
|
+
is not listening the call fails with the port and a start command; it never
|
|
587
|
+
falls back to a fresh profile behind your back. Because that profile is
|
|
588
|
+
already signed in to whatever you use, every action inherits that access.
|
|
589
|
+
- **`userDataDir`** keeps one dedicated profile for a browser this plugin
|
|
590
|
+
launches: sign in once (QR code, SMS, whatever the site asks), and later runs
|
|
591
|
+
reuse the same cookie jar. The directory is a real credential store on disk —
|
|
592
|
+
keep it somewhere you would keep a password file, and do not point it at your
|
|
593
|
+
daily browser's profile. It is ignored while `attachPort` is set.
|
|
594
|
+
|
|
595
|
+
The default remains a fresh temporary profile under
|
|
596
|
+
`%TEMP%/dsh-runtime-profile-*`, so an ordinary run cannot see your daily
|
|
597
|
+
browser's cookies.
|
|
598
|
+
|
|
599
|
+
### What it registers
|
|
600
|
+
|
|
601
|
+
| Tool | What it does |
|
|
602
|
+
| --- | --- |
|
|
603
|
+
| `browser_open(url, headless?, width?, height?)` | Launches a browser with its own fresh or persistent profile, or attaches to yours when `attachPort` is set; opens the URL, returns URL, title, viewport, and a screenshot path. A sign-in, CAPTCHA, SMS, or QR page comes back as `[attention]`. |
|
|
604
|
+
| `browser_elements(text?, role?, limit?)` | Lists actionable elements with a stable index, accessible name, role, bounding box, and whether it is in the viewport. Matching is by visible text, ARIA name, or role — not only CSS. |
|
|
605
|
+
| `browser_click(index?, css?, text?, role?, confirm?, screenshot?)` | Scrolls the element into view, dispatches a real mouse press/release at its centre, and screenshots afterwards. |
|
|
606
|
+
| `browser_type(index?, css?, text?, value, submit?, screenshot?)` | Focuses the field, inserts text through the browser input pipeline, optionally presses Enter, and reports the value the page now holds (a password field is masked). |
|
|
607
|
+
| `browser_screenshot(path?, full_page?)` | PNG of the page, with path, pixel size, and byte size. |
|
|
608
|
+
| `browser_script(expression, await_promise?)` | Evaluates one expression and returns its JSON value; for reads, not for clicking. |
|
|
609
|
+
| `browser_wait(text?, css?, url_contains?, milliseconds?, timeout_ms?)` | Waits for a condition or a fixed delay. |
|
|
610
|
+
| `browser_await_human(timeout_ms?, poll_ms?, screenshot?)` | Waits for the person to clear a sign-in, CAPTCHA, SMS, two-factor, or QR check; returns ok when automation may continue, or `[attention]` if it is still pending. It never solves the check itself. |
|
|
611
|
+
| `browser_close()` | Closes a browser this plugin launched. On an attach connection it only detaches and leaves your browser running. |
|
|
612
|
+
| `desktop_screenshot(window?, path?)` | Whole desktop, or one window by title captured with `PrintWindow` (a covered window still yields its own pixels). |
|
|
613
|
+
| `desktop_windows(filter?, limit?)` | Visible top-level windows: handle, title, pid, screen rectangle. |
|
|
614
|
+
| `desktop_click(x, y, window?, activate?, right?, confirm?)` | Click at screen coordinates. Background by default; `activate` is required for a foreground click. |
|
|
615
|
+
| `desktop_type(text, window?, activate?)` | Types into a window, background `WM_CHAR` by default. |
|
|
616
|
+
| `desktop_keys(keys, window?, activate?)` | Presses named keys (`enter`, `tab`, `f5`, `a`, `1` …) in order. |
|
|
617
|
+
| `runtime_status()` | Stop state, registered halves, allowed hosts, browser executable, attach/launch mode, session. |
|
|
618
|
+
|
|
619
|
+
Every browser and desktop call writes one line to the existing audit trail
|
|
620
|
+
(`lib/audit.js`) with `source: "runtime"`, the action, the target, the decision,
|
|
621
|
+
the result, and the duration. A gate that refuses an action writes
|
|
622
|
+
`decision: "deny"` or `"confirm"` and `result: "blocked"`, so the log can never
|
|
623
|
+
claim that a refused click succeeded. Browser lines also carry `meta.session` —
|
|
624
|
+
`"attach"` when the action ran on the browser you started (with `meta.port` and
|
|
625
|
+
the tab it reused), `"launch"` when it ran on one this plugin started (with
|
|
626
|
+
`meta.profile` and `meta.persistentProfile`) — so the trail can never confuse
|
|
627
|
+
your session with a throwaway profile. A page that asks for a person writes
|
|
628
|
+
`kind: "attention"`, `decision: "attention"`, and `result: "needs-human"`.
|
|
629
|
+
|
|
630
|
+
### Gates
|
|
631
|
+
|
|
632
|
+
- **Emergency stop.** While the stop file exists — or `DSH_RUNTIME_STOP=1` is
|
|
633
|
+
set — every action is refused and the refusal is audited. Create the file and
|
|
634
|
+
the layer stops at the next call; delete it to re-enable.
|
|
635
|
+
- **Navigation.** Only `http:` and `https:` on the allowed hosts. `file://` is
|
|
636
|
+
refused because a page that could read local files would walk around the
|
|
637
|
+
workspace guard; `javascript:`, `data:`, and `chrome:` are refused too.
|
|
638
|
+
- **Uploads.** `browser_click` refuses an `<input type="file">`, because the
|
|
639
|
+
native file picker that follows cannot be driven and would fall through to the
|
|
640
|
+
user's own file system.
|
|
641
|
+
- **Irreversible actions.** A target whose label reads submit, delete, pay,
|
|
642
|
+
publish, transfer, 提交, 删除, 支付 … needs `confirm: true`. Without it the
|
|
643
|
+
click does not happen and the audit line records `decision: "confirm"`.
|
|
644
|
+
- **Human checks.** A page asking for a sign-in, CAPTCHA, SMS code, two-factor
|
|
645
|
+
confirmation, or QR scan stops the action at that point and returns
|
|
646
|
+
`[attention]` with what the page wants and how to hand over. The check is read
|
|
647
|
+
from the page text, so an ordinary settings page with a password field but no
|
|
648
|
+
sign-in wording is not flagged; nothing here solves or types the check. In a
|
|
649
|
+
launched window or an attached tab the person finishes it in the browser, then
|
|
650
|
+
`browser_await_human` polls until it is gone and the run continues. A pending
|
|
651
|
+
check is a hand-off, not a failed run.
|
|
652
|
+
- **Focus.** A background click or keystroke never brings a window forward. A
|
|
653
|
+
foreground action requires `activate: true` **and**
|
|
654
|
+
`runtime.desktop.allowActivation: true`, and each activation is recorded in
|
|
655
|
+
`meta.activated`.
|
|
656
|
+
- **Worker agents.** `browser_*` and `desktop_*` belong to the session that
|
|
657
|
+
mounted the plugin. The guard blocks them for bound child agents with rule
|
|
658
|
+
`guard/runtime-tool` unless `guard.allowRuntimeTools` is true.
|
|
659
|
+
|
|
660
|
+
### What it deliberately cannot do
|
|
661
|
+
|
|
662
|
+
- **Borrow your logins by accident.** A launched browser gets a fresh profile
|
|
663
|
+
under `%TEMP%/dsh-runtime-profile-*`, so your cookies, saved passwords, and
|
|
664
|
+
signed-in sessions are simply not there. Reaching an authenticated page is an
|
|
665
|
+
explicit choice: attach to a browser you started with
|
|
666
|
+
`--remote-debugging-port` and set `browser.attachPort`, or point
|
|
667
|
+
`browser.userDataDir` at one dedicated profile and sign in there once. Both
|
|
668
|
+
make that access available to every later action, and both are visible in
|
|
669
|
+
`meta.session` in the audit log; a wrong attach port fails with instructions
|
|
670
|
+
instead of silently starting a profile.
|
|
671
|
+
- **Solve human verification for you.** CAPTCHAs, SMS codes, "confirm you are
|
|
672
|
+
human" interstitials, and QR logins stop the action and hand it back. It never
|
|
673
|
+
types a code or scans a code for you; it waits for you to do it and then
|
|
674
|
+
reports that the run may continue.
|
|
675
|
+
- **Evade bot detection.** A launched Chromium is detectable through CDP
|
|
676
|
+
artefacts, and sites that block automation will block this. Nothing here
|
|
677
|
+
patches `navigator.webdriver` or spoofs fingerprints.
|
|
678
|
+
- **Type into every application.** Background `WM_CHAR` reaches classic Win32
|
|
679
|
+
controls; Chromium, Electron, Qt, and most games ignore posted messages. For
|
|
680
|
+
those, either `activate: true` and accept the focus change, or drive the page
|
|
681
|
+
through `browser_*` instead.
|
|
682
|
+
- **Guess coordinates.** `desktop_*` takes physical screen pixels. With mixed
|
|
683
|
+
DPI scaling, take a `desktop_screenshot` first and read the rectangle from
|
|
684
|
+
`desktop_windows` rather than computing it.
|
|
685
|
+
- **Control macOS or Linux desktops.** The desktop half is Windows-only. The
|
|
686
|
+
browser half works anywhere a Chromium-family binary exists.
|
|
687
|
+
|
|
688
|
+
Two runnable proofs ship with the repository. `node scripts/runtime-demo.mjs`
|
|
689
|
+
starts a local page, clicks a button, reads the counter back out of the DOM,
|
|
690
|
+
types into a field, is refused on an irreversible button and on a file input,
|
|
691
|
+
flips the stop switch, and prints the audit lines and screenshot paths.
|
|
692
|
+
`node scripts/runtime-desktop-demo.mjs` opens a no-activate test window, posts a
|
|
693
|
+
click and text into it, verifies both from the target process's own state file,
|
|
694
|
+
and captures the window.
|
|
695
|
+
|
|
463
696
|
## Tools
|
|
464
697
|
|
|
465
698
|
- `superagent_start(goal, mode?, queue?, max_subtasks?, max_parallel?, deadline_minutes?, allow_duplicate?, wait_seconds?)`
|
|
@@ -473,7 +706,8 @@ cost: at least ¥0.0041 (estimate; no price for haoduo/gpt-6.1-sol)
|
|
|
473
706
|
independent subtasks still run in parallel. A dependency cycle rejects the
|
|
474
707
|
plan before any work starts, and a dependency on a task the plan never
|
|
475
708
|
declared is skipped with the reason. Both modes produce the same run record,
|
|
476
|
-
quota, deadline, cancel, and usage accounting.
|
|
709
|
+
quota, deadline, cancel, and usage accounting. `goal_mode: true` adds an
|
|
710
|
+
acceptance step and re-plans a failed round; see [Goal mode](#goal-mode).
|
|
477
711
|
`queue: true` makes a start wait for a free slot when `maxActiveRuns` is in use
|
|
478
712
|
instead of failing: it returns `status: "queued"` with `queue.position` /
|
|
479
713
|
`queue.of`, starts automatically when an active run finishes, and fails after
|
|
@@ -547,7 +781,7 @@ cost: at least ¥0.0041 (estimate; no price for haoduo/gpt-6.1-sol)
|
|
|
547
781
|
(project rules), `profile` (user preferences), or the run scope. `search`
|
|
548
782
|
ranks notes against `query` (the current goal works well) and/or exact `tags`,
|
|
549
783
|
so a relevant old note is found instead of only the newest ones; notes can
|
|
550
|
-
carry `tags` when set. The tool is additive: the
|
|
784
|
+
carry `tags` when set. The tool is additive: the eleven other tools keep their
|
|
551
785
|
arguments and output.
|
|
552
786
|
- `superagent_template(action, id?, params?, template?, limit?)` lists, shows,
|
|
553
787
|
expands, saves, or deletes a workflow template: a fixed goal skeleton with
|
|
@@ -558,29 +792,191 @@ cost: at least ¥0.0041 (estimate; no price for haoduo/gpt-6.1-sol)
|
|
|
558
792
|
widens what a run may do. Built-in ids are read-only; custom ones live under
|
|
559
793
|
the template directory in the state directory, and a failure there is logged
|
|
560
794
|
without disabling the run tools.
|
|
561
|
-
- `
|
|
562
|
-
|
|
563
|
-
|
|
564
|
-
|
|
565
|
-
|
|
566
|
-
|
|
567
|
-
|
|
568
|
-
turn to read it, so an uncancelled child consumes it. The reply reports the
|
|
569
|
-
measured delay from acceptance to the child's next request, and marks a
|
|
570
|
-
message as `missed` — never as delivered — when the child is cancelled,
|
|
571
|
-
disposed, or finishes before another boundary. Worst case measured on a real
|
|
572
|
-
`dsh@0.2.2-rc.1` host: **6978 ms** with an 8 s child step and **2986 ms** with
|
|
573
|
-
a 4 s step, i.e. the bound tracks the step, not the plugin. With a host that
|
|
574
|
-
exposes no live channel, the tool degrades to the followup queue and says so
|
|
575
|
-
in the reply; it never calls that live.
|
|
795
|
+
- `superagent_schedule(action, id?, name?, goal?, template_id?, params?, cron?,
|
|
796
|
+
every_minutes?, timezone?, miss_policy?, goal_mode?, acceptance?, max_rounds?,
|
|
797
|
+
max_wall_clock_minutes?, no_progress_rounds?, budget?, human_priority?)` creates,
|
|
798
|
+
lists, pauses, resumes, deletes, or runs a scheduled plan now. A plan stores a
|
|
799
|
+
goal (or an expanded template), a clock, and its own limits; it survives a host
|
|
800
|
+
restart and starts runs nobody asked for. Nothing is armed until a plan exists.
|
|
801
|
+
See [Scheduled runs](#scheduled-runs).
|
|
576
802
|
- `superagent_audit(run_id?, subtask_id?, kind?, decision?, result?, target?,
|
|
577
803
|
since?, until?, limit?, order?, format?, out_path?)` reads the audit trail, or
|
|
578
804
|
exports the matching events as one JSONL or CSV file. See
|
|
579
805
|
[Permissions and audit](#permissions-and-audit).
|
|
580
806
|
|
|
581
807
|
|
|
808
|
+
## Goal mode
|
|
809
|
+
|
|
810
|
+
A normal run finishes when its subtasks finish. That is not the same as the goal
|
|
811
|
+
being met, and a plan can report success over a broken build. Goal mode is an
|
|
812
|
+
opt-in (`goal_mode: true` on `superagent_start` or `superagent_schedule`) that
|
|
813
|
+
adds an independent acceptance step and keeps the run going until every
|
|
814
|
+
condition passes or a hard stop says a person has to decide.
|
|
815
|
+
|
|
816
|
+
- **Acceptance conditions.** `acceptance` is required and is a list of
|
|
817
|
+
`{id?, text, check?}`. A `check` of `{"type":"command","command":"npm test"}`
|
|
818
|
+
or `{"type":"file","path":"dist/app.js"}` is run by the plugin itself, so that
|
|
819
|
+
verdict rests on a real exit code or a real file, never on a model's claim. A
|
|
820
|
+
condition without a check is judged by a separate acceptance model, and
|
|
821
|
+
`superagent_status` names the source of every verdict. At most 12 conditions
|
|
822
|
+
are accepted; a longer list is a badly framed goal, not a checklist.
|
|
823
|
+
- **Rounds.** A failed round does not repeat the same work: the next round's
|
|
824
|
+
plan receives what failed and why. `max_rounds` (default 5, max 20),
|
|
825
|
+
`max_wall_clock_minutes` (default 60), and `no_progress_rounds` (default 2)
|
|
826
|
+
bound it. When the acceptance has a machine check, a round that changed no
|
|
827
|
+
file stops immediately instead of paying for another one.
|
|
828
|
+
- **Hard stops.** The loop stops with a reason instead of looping forever: the
|
|
829
|
+
round cap, the wall clock, the run deadline, a budget stop, an open attention
|
|
830
|
+
item, two identical failing rounds, or a round that cannot make progress.
|
|
831
|
+
The stop report lists every condition with its last result and what was tried.
|
|
832
|
+
- **Notifications.** One notification when the goal is met or the loop stops —
|
|
833
|
+
none between rounds. The run record, status line, and report all carry the
|
|
834
|
+
round count and each condition's verdict.
|
|
835
|
+
|
|
836
|
+
Goal mode is off by default, adds no tool of its own, and changes nothing about
|
|
837
|
+
a run that does not pass `goal_mode: true`.
|
|
838
|
+
|
|
839
|
+
## Scheduled runs
|
|
840
|
+
|
|
841
|
+
`superagent_schedule` stores a plan — a goal plus a clock — and starts it
|
|
842
|
+
without anyone calling `superagent_start`. A scheduled run is an ordinary run:
|
|
843
|
+
same planner, same quota, same budgets, cancel, usage accounting, report, and
|
|
844
|
+
status. The scheduler is only a timer-shaped caller of the orchestrator, not a
|
|
845
|
+
second run engine.
|
|
846
|
+
|
|
847
|
+
```text
|
|
848
|
+
superagent_schedule(action: "create", name: "nightly audit",
|
|
849
|
+
goal: "Audit yesterday's error logs and list anything new",
|
|
850
|
+
cron: "0 3 * * *", timezone: "Asia/Shanghai",
|
|
851
|
+
budget: { max_total_runs: 30, max_total_tokens: 5000000 })
|
|
852
|
+
```
|
|
853
|
+
|
|
854
|
+
Actions are `create`, `list`, `pause`, `resume`, `delete`, and `run-now`.
|
|
855
|
+
`run-now` starts one execution immediately without moving the next planned
|
|
856
|
+
window. A plan may name a `template_id` and `params` instead of a literal
|
|
857
|
+
`goal`; the template is expanded at create time, so editing the template later
|
|
858
|
+
does not silently change an existing plan.
|
|
859
|
+
|
|
860
|
+
A plan stores its clock (`cron` or `every_minutes`, plus `timezone`), the goal,
|
|
861
|
+
an optional `mode` / `goal_mode` with acceptance, its own `budget`, and its
|
|
862
|
+
`human_priority`. Plans persist to `schedules.json` in the state directory and
|
|
863
|
+
are reloaded at mount, so a host restart keeps them. The timer starts only when
|
|
864
|
+
at least one plan exists; the state file is not created by `init()` on an empty
|
|
865
|
+
state directory.
|
|
866
|
+
|
|
867
|
+
### Missed windows
|
|
868
|
+
|
|
869
|
+
A window that comes due while the host is down is **not** replayed in full. The
|
|
870
|
+
default policy, `miss_policy: "latest"`, runs only the newest missed window and
|
|
871
|
+
records every other due window as `missed` with its scheduled time and the
|
|
872
|
+
reason (the host was not running at that time); the plan then advances to its
|
|
873
|
+
next window on the normal grid. The run that executes that newest window is a
|
|
874
|
+
catch-up, and the plan says so: `totalRuns` counts it, `catchUpRuns` counts how
|
|
875
|
+
many runs were catch-ups, and the `started` history entry names the window and
|
|
876
|
+
the number of missed windows it stands in for. `miss_policy: "none"` skips all
|
|
877
|
+
due windows while the host was down, records the count, and resumes at the next
|
|
878
|
+
scheduled window. Catch-up work is bounded, so a laptop that was off for a month
|
|
879
|
+
does not queue thousands of runs.
|
|
880
|
+
|
|
881
|
+
The counters are separate on purpose: `missedRuns` is how many windows never
|
|
882
|
+
ran, `catchUpRuns` is how many ran late, and `skippedRuns` is how many were
|
|
883
|
+
passed over because the previous run was still active. `list` prints all three.
|
|
884
|
+
|
|
885
|
+
A plan also never overlaps itself: if the previous execution is still active
|
|
886
|
+
when a new window comes due, that window is not started and is recorded as
|
|
887
|
+
`skipped: previous run still active`. The next window is evaluated normally.
|
|
888
|
+
|
|
889
|
+
### Completion requires an artifact
|
|
890
|
+
|
|
891
|
+
A worker ending its turn with `completed` is not, by itself, a completed
|
|
892
|
+
subtask. When a subtask declares `deliverables` (file paths, relative to its
|
|
893
|
+
working directory), every listed file must exist, be a file, and be non-empty
|
|
894
|
+
before the subtask counts. With no file declared, the reply text is the
|
|
895
|
+
artifact, so an empty or whitespace-only reply is rejected with
|
|
896
|
+
`empty deliverable: ...` and the subtask is retried or failed like any other
|
|
897
|
+
incomplete attempt. A run whose report strips down to nothing is recorded as
|
|
898
|
+
`partial`, never `completed`, so a schedule cannot report success for an empty
|
|
899
|
+
result.
|
|
900
|
+
|
|
901
|
+
### Quota and manual priority
|
|
902
|
+
|
|
903
|
+
Scheduled runs share `maxActiveRuns` with manual runs. With
|
|
904
|
+
`human_priority: true` (the default, also configurable with
|
|
905
|
+
`schedulerHumanPriority`), a scheduled run may not occupy the last free slot:
|
|
906
|
+
when only one slot is free it waits for the next tick instead of blocking a
|
|
907
|
+
`superagent_start`. A scheduled run also never enters the queue, so a person's
|
|
908
|
+
`superagent_start(..., queue: true)` is never pushed back by a timer. When the
|
|
909
|
+
cap is reached, the due window stays due and is retried on a later tick,
|
|
910
|
+
without spending anything.
|
|
911
|
+
|
|
912
|
+
### Budget and failures
|
|
913
|
+
|
|
914
|
+
`budget.max_model_calls` / `max_tokens` cap one execution;
|
|
915
|
+
`budget.max_total_model_calls` / `max_total_tokens` / `max_total_runs` cap the
|
|
916
|
+
plan across executions. Reaching a plan total pauses the plan and records the
|
|
917
|
+
reason on the plan and in its run report; reaching a per-run cap ends that
|
|
918
|
+
execution the same way a manual run ends.
|
|
919
|
+
|
|
920
|
+
A failed execution does not notify on every retry. The first failure is
|
|
921
|
+
reported once, and `schedulerMaxConsecutiveFailures` (default 3) consecutive
|
|
922
|
+
failures pause the plan and report that once. A success resets the counter.
|
|
923
|
+
Notifications are otherwise limited to: the goal was achieved, the budget was
|
|
924
|
+
reached, or a run needs a decision. Milestones and ordinary progress stay in
|
|
925
|
+
`list` / `status` and never wake the session.
|
|
926
|
+
|
|
927
|
+
### Cron support
|
|
928
|
+
|
|
929
|
+
Cron parsing is built in and has no dependency. Supported: the standard five
|
|
930
|
+
fields (minute hour day-of-month month day-of-week), `*`, `*/n`, ranges
|
|
931
|
+
(`1-5`), lists (`1,15,30`), month and weekday names (`JAN`, `MON-FRI`), and `0`
|
|
932
|
+
or `7` for Sunday. Day-of-month and day-of-week together are OR-ed, as in
|
|
933
|
+
classic cron.
|
|
934
|
+
|
|
935
|
+
Not supported, and refused at create time with the offending field number:
|
|
936
|
+
seconds, a year field, `@daily`-style macros, and the `L`, `W`, `#`, and `?`
|
|
937
|
+
extensions. An expression with six fields is rejected as “field 1 is not a
|
|
938
|
+
minute” rather than being reinterpreted. Time zones use IANA names and are
|
|
939
|
+
evaluated in the zone the expression was written in, never the host's zone; a
|
|
940
|
+
time that does not exist at the spring DST jump is skipped, and an ambiguous
|
|
941
|
+
autumn time uses the earlier offset.
|
|
942
|
+
|
|
943
|
+
### What a plan needs from the host
|
|
944
|
+
|
|
945
|
+
Each plan is owned by the session that created it (or an explicit
|
|
946
|
+
`session_id`), and that owner is resolved **on every window**, not captured once.
|
|
947
|
+
If the session is live, it is used as is. After a host restart the plugin asks
|
|
948
|
+
the host to resume the persisted session (`agents.resume`, or the Host Session
|
|
949
|
+
API where that is the available surface); if the session was deleted, it creates
|
|
950
|
+
a replacement and the plan adopts the new id (recorded as `owner-recovered`). A
|
|
951
|
+
plan therefore survives a restart without depending on the original process or
|
|
952
|
+
conversation staying open.
|
|
953
|
+
|
|
954
|
+
When the host exposes no way to resume or create a session at all, that limit is
|
|
955
|
+
recorded at `create` time instead of being discovered as a pause. The response
|
|
956
|
+
carries a warning and the plan is marked `requires a resident session`; when a
|
|
957
|
+
window finds no live owner it is recorded as `blocked`, announced once, and the
|
|
958
|
+
plan stays enabled. It is not silently paused after three windows.
|
|
959
|
+
|
|
960
|
+
Nothing runs and nothing is written until the first `create`. An installation
|
|
961
|
+
with no plans behaves exactly as it did before this tool existed.
|
|
962
|
+
|
|
582
963
|
## Progress, decisions, and artifacts
|
|
583
964
|
|
|
965
|
+
- **Plan honesty.** Before a worker starts, the planner names what it cannot map
|
|
966
|
+
to a concrete object: an ambiguous phrase goes into `ambiguities`, and a
|
|
967
|
+
question only the user can answer goes into `needsInput`, so the run stops and
|
|
968
|
+
asks instead of inventing a name that looks plausible. Each assumption the
|
|
969
|
+
planner does make is recorded on that subtask (`assumptions`) and printed in
|
|
970
|
+
status and in the report, so a guess is visible instead of silent. A plan
|
|
971
|
+
whose questions arrive together is one decision point, not a drip of prompts.
|
|
972
|
+
- **Capability preflight.** A subtask may declare `requires` (`shell`,
|
|
973
|
+
`net.http`, `browser`, `gui`, `desktop`, `git`, `gh`). The host compares that
|
|
974
|
+
list with the tools this session actually has before any worker is spawned.
|
|
975
|
+
A subtask whose capability is missing is `blocked`, with the capability and
|
|
976
|
+
what would enable it named; it never starts and is never counted as success,
|
|
977
|
+
and everything downstream of it is skipped for that reason. When the host
|
|
978
|
+
cannot list its tools, preflight records `unavailable` and blocks nothing
|
|
979
|
+
rather than guessing an inventory.
|
|
584
980
|
- **Milestones.** Every run records `plan_ready`, `running`, `aggregating`, and
|
|
585
981
|
`settled` with a timestamp, shown in `superagent_status`. They never produce a
|
|
586
982
|
proactive message; progress stays visible without becoming noisy.
|
|
@@ -768,6 +1164,36 @@ itself. A `stateDir` inside the installed package disables memory rather than
|
|
|
768
1164
|
risk shipping it. If you point `stateDir` at a repository, the nested
|
|
769
1165
|
`.gitignore` still keeps the files out of a default `git add`.
|
|
770
1166
|
|
|
1167
|
+
### User profile
|
|
1168
|
+
|
|
1169
|
+
The notebook above answers "what did the last run learn about this task". A
|
|
1170
|
+
second, optional store answers a different question — "who is this person, what
|
|
1171
|
+
do they want, and why did we choose that before" — and it has to outlive
|
|
1172
|
+
unrelated tasks, so it is kept apart and read apart. It is off by default
|
|
1173
|
+
(`memoryUserProfile: false`): nothing is constructed, no directory is created,
|
|
1174
|
+
and the run notebook behaves exactly as before.
|
|
1175
|
+
|
|
1176
|
+
- **Three categories, three files.** `fact` (durable technical context such as
|
|
1177
|
+
the stack or the environment), `preference` (how the user wants work done),
|
|
1178
|
+
and `decision` (the choice, what was rejected, why, and how to undo it).
|
|
1179
|
+
A search opens one category file, so a fact can never come back as a
|
|
1180
|
+
preference just because the words match.
|
|
1181
|
+
- **A decision needs its reason.** A decision without a rationale teaches the
|
|
1182
|
+
next run nothing, so the reason is part of the record and part of every digest
|
|
1183
|
+
line; a bare "chose X" is refused.
|
|
1184
|
+
- **Reading and writing.** `superagent_memory` with `layer: "user"` and a
|
|
1185
|
+
`category` lists, searches, adds, corrects, or forgets profile records. The
|
|
1186
|
+
planner prompt gets a short digest of the matching records, labelled by
|
|
1187
|
+
category, under the same character budget as the notebook.
|
|
1188
|
+
- **Forgetting is deletion.** The matching lines are removed under a lock and the
|
|
1189
|
+
file is replaced, with no tombstone that a later search could leak the value
|
|
1190
|
+
back through. A forget must name a key, a run id, or a time range, so a bare
|
|
1191
|
+
"forget everything" cannot wipe the profile by accident.
|
|
1192
|
+
- **Privacy.** Every record is redacted before it is written: credentials,
|
|
1193
|
+
emails, phone numbers, and usernames inside home paths. The profile lives
|
|
1194
|
+
under `<stateDir>/user-memory` with the same nested `.gitignore` as the
|
|
1195
|
+
notebook, and is never in the package `files` whitelist.
|
|
1196
|
+
|
|
771
1197
|
## Watch and report
|
|
772
1198
|
|
|
773
1199
|

|
|
@@ -826,7 +1252,7 @@ records the command plus a zero-external-reference audit.
|
|
|
826
1252
|
does. It reads only: no install, no mount, no edit to the profile. One block per
|
|
827
1253
|
check — imported files against the `files` whitelist, declared files against
|
|
828
1254
|
what is on disk, the installed copy against the published tarball for its
|
|
829
|
-
version, the profile's bundle registration, and the
|
|
1255
|
+
version, the profile's bundle registration, and the twelve registered tools — each
|
|
830
1256
|
failure followed by the command that fixes it.
|
|
831
1257
|
|
|
832
1258
|
```bash
|
|
@@ -954,6 +1380,62 @@ The full contract — routes, error ids, security model, lifecycle, client
|
|
|
954
1380
|
examples — is [docs/embedding.md](https://github.com/LittleChenLiya/dsh-superagent/blob/main/docs/embedding.md). It is opt-in, loopback
|
|
955
1381
|
only, and there is no remote or unauthenticated mode.
|
|
956
1382
|
|
|
1383
|
+
## Conversation console
|
|
1384
|
+
|
|
1385
|
+
`consolePort` adds a local page where you talk to a **real Host Session**, not a
|
|
1386
|
+
mock chat and not a re-skinned `superagent_start(goal)` form:
|
|
1387
|
+
|
|
1388
|
+
```yaml
|
|
1389
|
+
- id: superagent
|
|
1390
|
+
config:
|
|
1391
|
+
consolePort: 0 # off by default; 0 = OS picks a free loopback port
|
|
1392
|
+
consoleRoot: /path/to/project
|
|
1393
|
+
```
|
|
1394
|
+
|
|
1395
|
+
The plugin creates the session with the host's `sessionController.create()`,
|
|
1396
|
+
sends each message with `prompt({ mode: 'queue' | 'steer' })`, and forwards
|
|
1397
|
+
`follow({ assistantStream: true })` plus `observeState()` to the page. Follow-up
|
|
1398
|
+
messages therefore continue the same conversation; they are not a new session.
|
|
1399
|
+
The right-hand column lists the runs whose `parentSessionId` is that session, so
|
|
1400
|
+
the page shows exactly the subtasks the conversation derived. An attention card
|
|
1401
|
+
answers through `orchestrator.answer`, the same path as the
|
|
1402
|
+
`superagent_answer` tool, with the conversation agent as the run owner.
|
|
1403
|
+
|
|
1404
|
+
The bound URL and a fresh per-process token are written to
|
|
1405
|
+
`<stateDir>/console.json` (mode `0600`). Open
|
|
1406
|
+
`http://127.0.0.1:<port>/?token=<token>` once; the page stores the token in
|
|
1407
|
+
`sessionStorage` and removes it from the address bar. Every route, including
|
|
1408
|
+
the event stream, answers `401` without it, and every request with a non-loopback
|
|
1409
|
+
`Host` header answers `403`.
|
|
1410
|
+
|
|
1411
|
+
If the host does not mount `sessionController` (for example a headless profile
|
|
1412
|
+
without the web session API), the page says so and refuses to create a session.
|
|
1413
|
+
It does **not** pretend to be a chat. The console also keeps one active
|
|
1414
|
+
conversation per process; "新对话" creates a new Host Session and leaves the old
|
|
1415
|
+
one intact. Approval prompts that appear as host `pendingInput` are surfaced in
|
|
1416
|
+
the status line but are not answered by this page; only run attention questions
|
|
1417
|
+
are.
|
|
1418
|
+
|
|
1419
|
+
### Tools the conversation gets
|
|
1420
|
+
|
|
1421
|
+
The console session is created with no tool list of its own: it mounts whatever
|
|
1422
|
+
the host's agent preset mounts, which is the same set the Web app's own
|
|
1423
|
+
sessions get. The plugin registers no conversation tools and filters none; the
|
|
1424
|
+
only filter it can apply is the opt-in `guard` for child agent calls. To see the
|
|
1425
|
+
real list, the page asks the host for `ctx.tools.definitions(agent)` and shows
|
|
1426
|
+
it under "这个会话挂载的工具"; when the host cannot enumerate, the page says so
|
|
1427
|
+
instead of printing a fixed list. `consolePreset` passes `agentPreset` to
|
|
1428
|
+
`sessionController.create()` when you want a preset other than the profile
|
|
1429
|
+
default.
|
|
1430
|
+
|
|
1431
|
+
Browser and desktop control are not implemented here. They come from
|
|
1432
|
+
`feat/runtime-control`, which registers host-scope `browser_*` and `desktop_*`
|
|
1433
|
+
tools; those are visible to the console session like any other host tool. On a
|
|
1434
|
+
build without that branch the page reports them as "未挂载". Neither branch ships a 3D tool; when
|
|
1435
|
+
the preset includes `bash` or `pwsh`, a headless Blender can be driven through
|
|
1436
|
+
it (`blender --background --python`), which is the scriptable path the console
|
|
1437
|
+
can already reach.
|
|
1438
|
+
|
|
957
1439
|
## Workspace panel
|
|
958
1440
|
|
|
959
1441
|
`workbenchPort` adds a local, IDE-shaped panel over one directory. It has its
|
|
@@ -1028,7 +1510,7 @@ Three side files live next to the run:
|
|
|
1028
1510
|
| `<runId>.cancel` | A cancel was requested by some process. The owner polls it once per second and stops its children. Removed when the run ends. |
|
|
1029
1511
|
| `<runId>.lock` | The process that is allowed to schedule this run. Created with `wx`, so exactly one process wins. A lock left by a dead local pid is broken immediately; a live local pid keeps it however long it has held it; a lock from another machine is broken once it is older than 10 minutes, since its pid cannot be checked. |
|
|
1030
1512
|
| `<runId>.json.corrupt-<ts>` | The state file was not valid JSON and was moved aside, not deleted. The run is skipped by `superagent_list` and reported by id with this path. |
|
|
1031
|
-
|
|
|
1513
|
+
| `<anchor>/.superagent/worktrees/<runId>/w<n>/` | A worker's git worktree when `workspaceIsolation` is on. Anchored inside the host's session directory (the repository when that is where the host started) so the sandbox allows writes, and ignored so it never shows up in `git status`. Removed once its branch is merged or it produced no change; kept when a conflict left it for the user to merge. |
|
|
1032
1514
|
|
|
1033
1515
|
If a run's file is damaged, nothing else breaks: other runs list normally, and
|
|
1034
1516
|
starting a new run works. Inspect the `.corrupt-` file, then delete it. A file
|
|
@@ -1186,8 +1668,8 @@ appears to "hang" until the ignored-abort child returns.
|
|
|
1186
1668
|
|
|
1187
1669
|
| What you see | What it means | What to do |
|
|
1188
1670
|
| --- | --- | --- |
|
|
1189
|
-
| `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.
|
|
1190
|
-
| `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
|
|
1671
|
+
| `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.0` and read the host log for `[dsh-superagent]` lines. |
|
|
1672
|
+
| `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. |
|
|
1191
1673
|
| `[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`. |
|
|
1192
1674
|
| `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. |
|
|
1193
1675
|
| `[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. |
|