@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/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.12.1
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 opt-in workspace panel is a loopback page) and patches
41
- no host code: the eleven `superagent_*` tools are the surface, plus six optional
42
- operator utilities (a terminal panel, an HTML report, an install doctor, a run
43
- archive, git sync, and the workspace panel) that read the same run files.
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.12.1
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 `<stateDir>/workspaces/<runId>/w<n>`; that
304
- directory carries its own `.gitignore`, so a state directory inside a repository
305
- does not leak worker checkouts into the user's next commit.
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 <stateDir>/workspaces/20261115T101500-ab12/w2; the main checkout was restored, so nothing
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 ten other tools keep their
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
- - `superagent_inject(run_id, message, subtask_index?, wait_seconds?)` delivers
562
- one instruction into the workers that are running right now. It uses the
563
- host's live steering channel (`subagents.sendMessage`, the same inbox the
564
- agent loop drains at its next pre-step), so the message is part of the child's
565
- next model request. It does not interrupt a model call already in flight: the
566
- delay is the remainder of the step that is running (that model response plus
567
- its tool batch). A live child that had already decided to stop runs one more
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
  ![Run report preview](https://github.com/LittleChenLiya/dsh-superagent/blob/main/docs/report-preview.jpg?raw=true)
@@ -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 eleven registered tools — each
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
- | `workspaces/<runId>/w<n>/` | A worker's git worktree when `workspaceIsolation` is on. Removed once its branch is merged or it produced no change; kept when a conflict left it for the user to merge. |
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.12.1` and read the host log for `[dsh-superagent]` lines. |
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 twenty-two `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. |
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. |