@xiangyixie/dsh-superagent 0.11.0 → 0.12.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 +85 -10
- package/README.md +322 -28
- package/bin/doctor.js +1 -1
- package/bin/sync.js +187 -0
- package/bin/workbench.js +98 -0
- package/docs/policy.example.json +38 -0
- package/lib/audit.js +555 -0
- package/lib/doctor.js +2 -0
- package/lib/guard.js +841 -0
- package/lib/index.js +493 -9
- package/lib/inject.js +138 -0
- package/lib/orchestrator.js +543 -4
- package/lib/policy.js +739 -0
- package/lib/sync.js +456 -0
- package/lib/workbench.js +1119 -0
- package/package.json +92 -80
- package/public/workbench.html +836 -0
package/CHANGELOG.md
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
# Changelog
|
|
1
|
+
# Changelog
|
|
2
2
|
|
|
3
3
|
Doc-only releases: npm serves the README from the tarball, so a README edit is
|
|
4
4
|
invisible on the package page until something is published. When the edit
|
|
@@ -8,6 +8,79 @@ along with the next code release. A doc-only version leaves `lib/` and `bin/`
|
|
|
8
8
|
byte-identical to the version before it, and the pinned install line in the
|
|
9
9
|
README is updated to the version being released.
|
|
10
10
|
|
|
11
|
+
## 0.12.0 — 2026-11-15
|
|
12
|
+
|
|
13
|
+
### Added
|
|
14
|
+
|
|
15
|
+
- **Worker safety guard.** Child tool calls are now checked on the host's
|
|
16
|
+
`tools/pre-execute` / `ctx.tools.guard` pipeline. Writes are limited to the
|
|
17
|
+
child's workspace and the OS temp directory; credential stores and
|
|
18
|
+
`.git/config` / `.git/hooks` are refused for reading and writing; system
|
|
19
|
+
directories are refused for writing. Default command rules block disk
|
|
20
|
+
formatting, system scheduler and registry changes, writes into system
|
|
21
|
+
directories, destructive recursive deletes whose target is `/`, `~`, `.`,
|
|
22
|
+
`..`, a wildcard, or outside the workspace, permission nukes, and commands
|
|
23
|
+
that name a credential store. `guard.allowCommands` is an explicit,
|
|
24
|
+
audited override. Blocked calls surface in `superagent_status` and in a
|
|
25
|
+
`## Safety guard` report section. See “Worker safety guard” in the README
|
|
26
|
+
for the full defaults and their rationale.
|
|
27
|
+
- **Permission policy.** `<stateDir>/policy.json` (or `policyFile`) lets a person
|
|
28
|
+
say which paths may be written, which commands may run, which action classes
|
|
29
|
+
need a human, and what the default level is per run. The file accepts `//`,
|
|
30
|
+
`#`, and `/* */` comments, validates against a schema, and reports every
|
|
31
|
+
problem with file, line, and column. It only tightens: deny wins, explicit
|
|
32
|
+
allow entries record what they relaxed, and an invalid policy fails closed. A
|
|
33
|
+
start the policy denies is refused before any run record exists; a start held
|
|
34
|
+
for confirmation needs `approve_policy: true`, which is logged.
|
|
35
|
+
- **Audit trail.** Append-only JSONL at `<stateDir>/audit/audit.jsonl`: tool
|
|
36
|
+
calls, path writes, commands, blocks, approvals, attention decisions, and run
|
|
37
|
+
lifecycle, each with run id, subtask id, actor, timestamp, decision, result,
|
|
38
|
+
and duration. Appends are serialized in-process and locked across processes;
|
|
39
|
+
a torn tail or a damaged line is reported and skipped instead of hiding the
|
|
40
|
+
log. `audit: false` turns the trail off without changing run behaviour.
|
|
41
|
+
- **`superagent_audit`** queries by run, subtask, kind, decision, result, target,
|
|
42
|
+
and time window, and exports the matching events as one JSONL or CSV file.
|
|
43
|
+
- `createAuditor(...).attachGuard(fn)` is the seam for a separate path/command
|
|
44
|
+
guard: it can tighten a decision, never relax one.
|
|
45
|
+
- `superagent_inject(run_id, message, subtask_index?, wait_seconds?)` steers a
|
|
46
|
+
running child instead of waiting for the next prompt. It calls the host's
|
|
47
|
+
documented live channel (`subagents.sendMessage`, which lands in the same
|
|
48
|
+
`Agent` inbox that `steer`/`inject` expose), so the message is claimed at the
|
|
49
|
+
child's next pre-step and becomes part of its next model request. A child
|
|
50
|
+
that had already decided to stop runs one more turn to read it. Receipts
|
|
51
|
+
record `latencyMs` from acceptance to the claim, or a `missedReason` when the
|
|
52
|
+
child is cancelled, disposed, or finishes before another boundary. On a real
|
|
53
|
+
`dsh@0.2.2-rc.1` host the measured delay was 2986 ms with a 4 s child step
|
|
54
|
+
and 6978 ms with an 8 s step, i.e. bounded by the remainder of the running
|
|
55
|
+
step, not by the plugin. A host without that channel degrades to the followup
|
|
56
|
+
queue and the reply labels it as such.
|
|
57
|
+
- **Multi-device sync over git.** `dsh-superagent-sync` turns the state
|
|
58
|
+
directory into a repository and carries it between machines through any git
|
|
59
|
+
remote — no server, no account, no dependency. `init <remote>` writes a
|
|
60
|
+
managed `.gitignore` block (credentials, locks, cancel markers, quarantine
|
|
61
|
+
files, temp files, logs, machine identity) and makes the first commit;
|
|
62
|
+
`pull` fetches and merges, stashing uncommitted local work first and saying
|
|
63
|
+
so; `push` commits local state and pushes, reporting a rejection instead of
|
|
64
|
+
forcing; `status` reports ahead/behind counts, uncommitted files, stashes,
|
|
65
|
+
and conflicted paths. A conflict stops the merge with both sides kept and the
|
|
66
|
+
paths listed — nothing is resolved automatically. Run records were already
|
|
67
|
+
one file per run, so ordinary concurrent work on two machines does not
|
|
68
|
+
collide; the remaining shared surface is an append-only memory scope. The
|
|
69
|
+
README documents the limits: no realtime channel, no cross-machine lock, no
|
|
70
|
+
key distribution.
|
|
71
|
+
- **Local workspace panel.** `workbenchPort` (off by default, loopback only)
|
|
72
|
+
serves an IDE-shaped page from `public/workbench.html`: file tree, text editor,
|
|
73
|
+
diff preview before save, and a run view that lists the files a run changed.
|
|
74
|
+
The plugin reads and edits the filesystem itself, so no host API is involved.
|
|
75
|
+
Every request needs the per-process bearer token in `workbench.json`; absolute
|
|
76
|
+
paths, traversal, symlinks out of the root, the state directory, binaries, and
|
|
77
|
+
files above 512 KB are refused with a reason. Saving requires the hash and
|
|
78
|
+
mtime the editor read, so an external edit is never overwritten.
|
|
79
|
+
- `dsh-superagent-workbench` runs the same panel standalone, with `--root`,
|
|
80
|
+
`--port`, and `--state-dir`; no host is required.
|
|
81
|
+
- Run records now carry `changes` (recorded when the panel is on), which is what
|
|
82
|
+
the panel's run view reads and diffs against `git HEAD`.
|
|
83
|
+
|
|
11
84
|
## 0.11.0 — 2026-11-15
|
|
12
85
|
|
|
13
86
|
Runs became something you can talk back to and shape: instructions and answers
|
|
@@ -40,15 +113,13 @@ still ships one file per module from `lib/`.
|
|
|
40
113
|
one with the same key, and the planner digest now ranks notes against the run's
|
|
41
114
|
goal instead of only taking the newest ones.
|
|
42
115
|
- `superagent_followup(run_id, message)` appends an instruction to an active
|
|
43
|
-
run.
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
run
|
|
49
|
-
|
|
50
|
-
process is refused rather than written, because that owner's next save would
|
|
51
|
-
erase it.
|
|
116
|
+
run. It stays next-prompt by design: the next worker spawn or the aggregation
|
|
117
|
+
carries it, whichever comes first, and subtasks already running or finished
|
|
118
|
+
keep their results. Each instruction records `appliedAt` / `appliedAtStage`,
|
|
119
|
+
or `missedAt` with a reason when the run settled before another boundary ran.
|
|
120
|
+
A paused run keeps the instruction for its next resume; a completed run
|
|
121
|
+
refuses it. A run owned by another process is refused rather than written,
|
|
122
|
+
because that owner's next save would erase it.
|
|
52
123
|
- `superagent_answer(run_id, attention_id?, answer, wait_seconds?)` answers one
|
|
53
124
|
structured attention item. Attention items now carry stable ids (`q1`, `q2`, …)
|
|
54
125
|
from a per-run counter; the answer is recorded on that item and the run
|
|
@@ -131,6 +202,10 @@ still ships one file per module from `lib/`.
|
|
|
131
202
|
were applied, are waiting, or never took effect; notifications lead with the
|
|
132
203
|
question id so `superagent_answer` can be called directly.
|
|
133
204
|
|
|
205
|
+
|
|
206
|
+
|
|
207
|
+
|
|
208
|
+
|
|
134
209
|
## 0.10.0 — 2026-11-15
|
|
135
210
|
|
|
136
211
|
The dispatch, progress, delivery, and memory layer. No runtime dependencies were
|
package/README.md
CHANGED
|
@@ -17,14 +17,15 @@ prints the cost once you give it a price for the route.
|
|
|
17
17
|
planner and an aggregator on top. It is also the wrong tool for work that must
|
|
18
18
|
finish inside a single turn, for a step that needs human approval in the middle,
|
|
19
19
|
for anything that needs nested delegation (child depth is capped at 1), and for
|
|
20
|
-
anyone who wants an in-host panel —
|
|
21
|
-
with the host's credentials and
|
|
20
|
+
anyone who wants an in-host panel — the optional workspace panel below is a
|
|
21
|
+
loopback page, not host UI. Children run with the host's credentials and
|
|
22
|
+
filesystem; this is not a sandbox.
|
|
22
23
|
|
|
23
24
|
**Install and run.** Node `>= 24.9.0`, a tool-calling route, and that route's key
|
|
24
25
|
in the environment:
|
|
25
26
|
|
|
26
27
|
```bash
|
|
27
|
-
dsh plugin --profile web add @xiangyixie/dsh-superagent@0.
|
|
28
|
+
dsh plugin --profile web add @xiangyixie/dsh-superagent@0.12.0
|
|
28
29
|
```
|
|
29
30
|
|
|
30
31
|
Then ask the session for a run — a real call, not a sketch:
|
|
@@ -36,9 +37,10 @@ The reply ends `completed` with the merged report, or with
|
|
|
36
37
|
covers the path from an empty machine, including the reason not to install npm's
|
|
37
38
|
unrelated `dsh` package by name.
|
|
38
39
|
|
|
39
|
-
It adds no in-host UI
|
|
40
|
-
|
|
41
|
-
report, an install doctor,
|
|
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.
|
|
42
44
|
|
|
43
45
|
Personal project, not affiliated with DeepSeek or the harness maintainers. MIT
|
|
44
46
|
licensed, © 2026 Admire (LittleChenLiya); details in [License](#license).
|
|
@@ -73,7 +75,7 @@ your `PATH`, use `npx @deepseek-ai/dsh@0.2.2-rc.1` instead.
|
|
|
73
75
|
|
|
74
76
|
```bash
|
|
75
77
|
# 1. install the plugin into a profile (web, headless, ... whatever you run)
|
|
76
|
-
dsh plugin --profile web add @xiangyixie/dsh-superagent@0.
|
|
78
|
+
dsh plugin --profile web add @xiangyixie/dsh-superagent@0.12.0
|
|
77
79
|
|
|
78
80
|
# 2. confirm the bundle row exists in the merged config
|
|
79
81
|
dsh --profile web --dump-config
|
|
@@ -227,9 +229,15 @@ Row config in `<profile>/cordis.patch.yml`:
|
|
|
227
229
|
| `memoryDigestEntries` | `12` | Notes injected into a prompt. |
|
|
228
230
|
| `memoryDigestChars` | `1600` | Character budget for the note part of that prompt. |
|
|
229
231
|
| `keepRuns` | `0` | Delete terminal runs older than this many days at mount; `0` keeps everything. |
|
|
232
|
+
| `guard` | on | Worker path and command policy. See [Worker safety guard](#worker-safety-guard) for every default and the reason behind it. |
|
|
233
|
+
| `audit` | `true` | Append-only audit trail. It only observes; turning it off removes the trail, never the run behaviour. |
|
|
234
|
+
| `policyFile` | `<stateDir>/policy.json` when it exists | Permission policy. Unset and absent means no policy, i.e. the old behaviour. |
|
|
235
|
+
| `auditDir` | `<stateDir>/audit` | Where `audit.jsonl` and its exports live. |
|
|
230
236
|
| `controlPort` | off | Loopback port for the embedding surface; `0` picks a free one. See [docs/embedding.md](https://github.com/LittleChenLiya/dsh-superagent/blob/main/docs/embedding.md). |
|
|
231
237
|
| `workspaceIsolation` | `false` | Give every worker its own git worktree so parallel workers cannot overwrite each other. See [Per-worker workspace isolation](#per-worker-workspace-isolation). |
|
|
232
238
|
| `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
|
+
| `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
|
+
| `workbenchRoot` | `process.cwd()` | Directory the panel may browse and edit. Every path outside it is refused. |
|
|
233
241
|
|
|
234
242
|
### Switching models
|
|
235
243
|
|
|
@@ -268,7 +276,7 @@ subagent start request has no tool filter, and its own `subagent` tool rejects a
|
|
|
268
276
|
supported way to narrow a child's tools; without a dedicated preset, workers
|
|
269
277
|
inherit the session's tools. The `superagent_*` tools still exist in their tool
|
|
270
278
|
list, but the run tools (`superagent_start`, `superagent_resume`, `superagent_cancel`,
|
|
271
|
-
`superagent_followup`, `superagent_answer`) refuse to run from a worker session;
|
|
279
|
+
`superagent_followup`, `superagent_inject`, `superagent_answer`) refuse to run from a worker session;
|
|
272
280
|
only the top-level agent manages runs.
|
|
273
281
|
|
|
274
282
|
### Per-worker workspace isolation
|
|
@@ -344,6 +352,66 @@ edit the main checkout, but that shows up in `git status` before any merge and
|
|
|
344
352
|
cannot damage a sibling's branch. With isolation off, behaviour is exactly what
|
|
345
353
|
it was before this option existed.
|
|
346
354
|
|
|
355
|
+
### Worker safety guard
|
|
356
|
+
|
|
357
|
+
Workers inherit the session's filesystem and credentials, so every tool call a
|
|
358
|
+
superagent child makes passes through a guard mounted on the host's
|
|
359
|
+
`tools/pre-execute` path (`ctx.tools.guard` when available). The guard only
|
|
360
|
+
policies children this plugin spawned; the parent session is untouched.
|
|
361
|
+
|
|
362
|
+
```yaml
|
|
363
|
+
- id: superagent
|
|
364
|
+
config:
|
|
365
|
+
guard:
|
|
366
|
+
enabled: true
|
|
367
|
+
allowWriteRoots: [] # extra writable roots, absolute or ~-relative
|
|
368
|
+
denyPaths: [] # extra read+write denials
|
|
369
|
+
denyCommands: [] # [{ id, pattern, reason }] extra regex denials
|
|
370
|
+
allowCommands: # explicit overrides; every use is recorded
|
|
371
|
+
- id: clean-build
|
|
372
|
+
pattern: '^rm -rf build$'
|
|
373
|
+
reason: clean build output
|
|
374
|
+
maxEvents: 50
|
|
375
|
+
```
|
|
376
|
+
|
|
377
|
+
Defaults, and why they are set that way:
|
|
378
|
+
|
|
379
|
+
| Rule | Default | Why |
|
|
380
|
+
| --- | --- | --- |
|
|
381
|
+
| Write roots | The child session's working directory plus the OS temp directory | A worker needs its own workspace and a scratch area. Everything else is outside the job, so it is refused. The state directory is deliberately **not** writable: a worker must not rewrite run records or reports. |
|
|
382
|
+
| Always denied (read and write) | `~/.ssh`, `~/.aws`, `~/.gnupg`, `~/.netrc`, `~/.npmrc`, `~/.yarnrc`, `~/.pypirc`, `~/.git-credentials`, `~/.docker/config.json`, `~/.kube/config`, `~/.config/gcloud`, `~/.config/gh/hosts.yml`, `~/.azure`, any `.git/config` and `.git/hooks` | These are credentials or code-execution vectors. A broader workspace never opens them. |
|
|
383
|
+
| System directories | Writable by nobody (`C:\Windows`, `C:\Program Files`, `C:\ProgramData`, `/etc`, `/usr`, `/bin`, `/boot`, `/dev`, `/System`, `/Library`, …), except the OS temp directory | Reading them is normal (`win.ini`, `/etc/hosts`); writing them is not a development task. The temp exception exists because `%TEMP%` can live under `C:\Windows\TEMP` for service accounts, and workers must still be able to write scratch files there. |
|
|
384
|
+
| `cmd/recursive-force-delete` | Denied when the target is `/`, a drive root, `~`, `.`, `..`, `*`, outside the write roots, or contains one | `rm -rf build` and `rm -rf node_modules` are normal; `rm -rf /` and `rm -rf .` are not. Blanket-blocking every `rm -rf` would make ordinary cleanup impossible, so the target decides. |
|
|
385
|
+
| `cmd/disk-format` | `mkfs`, `diskpart`, `wipefs`, `format X:`, `dd of=/dev/sd*` | Never a development action. |
|
|
386
|
+
| `cmd/system-scheduler` | `schtasks /create`, `Register-ScheduledTask`, `crontab -r`, `systemctl enable\|disable\|mask`, `launchctl load` | Persistence outside the workspace. |
|
|
387
|
+
| `cmd/system-registry` | `reg add/delete` on `HKLM`/`HKCR`, and any `\Run` key | Machine-wide or auto-start changes. |
|
|
388
|
+
| `cmd/system-write` | A redirection or write cmdlet whose target is a system directory, including `%SystemRoot%`/`$env:SystemRoot` | Catches writes that hide behind a variable. |
|
|
389
|
+
| `cmd/permission-nuke` | `chmod -R 777 /`, recursive `chown` of `/`, `icacls … /grant Everyone /t` | Destroys the access model of the machine. |
|
|
390
|
+
| `cmd/credential-access` | A shell command that names one of the credential locations above, `id_rsa`, `id_ed25519`, … | A worker reading a key is as harmful as writing one. |
|
|
391
|
+
|
|
392
|
+
A denial is a real tool error, not a silent failure: the worker receives
|
|
393
|
+
`[guard] blocked <tool>: rule <id> — <reason>. The call did not run.`, and the
|
|
394
|
+
event is added to the run. `superagent_status` prints
|
|
395
|
+
`guard: N tool call(s) blocked; M explicit allow(s) recorded (rule ×count)`
|
|
396
|
+
plus up to three blocked commands, and the finished report gains a
|
|
397
|
+
`## Safety guard` section listing every kept event. Counters cover all events
|
|
398
|
+
even when `maxEvents` stops the list.
|
|
399
|
+
|
|
400
|
+
`allowCommands` is the only override. It wins over a denial, but every match is
|
|
401
|
+
recorded as `decision: allowed` with the rule it overrode, so an override is
|
|
402
|
+
never invisible. Credential, `.git` control, and system-directory denials are
|
|
403
|
+
not overridable; to permit a legitimate build directory outside the workspace,
|
|
404
|
+
add it to `allowWriteRoots`. The guard is lexical and realpath based, so a
|
|
405
|
+
symlink inside the workspace that points at a denied path is still caught.
|
|
406
|
+
|
|
407
|
+
The guard is a policy layer over tool arguments, not an OS sandbox. A command
|
|
408
|
+
that delegates the write to a program (`node build.js`, a compiler) can still
|
|
409
|
+
write wherever that program runs; blocking that requires a host-level sandbox,
|
|
410
|
+
which `dsh@0.2.2-rc.1` does not expose. The guard stops direct `write`/`edit`/
|
|
411
|
+
`apply_patch` targets, shell redirections, and the destructive command classes
|
|
412
|
+
above, which covers the accidental `rm` and "write into `C:\Windows`" cases a
|
|
413
|
+
wandering worker actually produces.
|
|
414
|
+
|
|
347
415
|
### Spending limits and prices
|
|
348
416
|
|
|
349
417
|
Two hard budgets stop a pathological goal before it can spend quietly. Both are
|
|
@@ -436,18 +504,33 @@ cost: at least ¥0.0041 (estimate; no price for haoduo/gpt-6.1-sol)
|
|
|
436
504
|
holds an answer that never reached a prompt — then resume reopens it, because
|
|
437
505
|
otherwise that decision would be stranded.
|
|
438
506
|
- `superagent_followup(run_id, message)` adds an instruction to a run that is
|
|
439
|
-
already executing, instead of starting a second run.
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
thing; an instruction that arrives after the last boundary is recorded as
|
|
507
|
+
already executing, instead of starting a second run. This tool is explicitly
|
|
508
|
+
next-prompt: the instruction is queued on the run and the next prompt built for
|
|
509
|
+
it carries it — the next worker spawn or the aggregation, whichever comes
|
|
510
|
+
first. Subtasks that are already running or finished keep their results and
|
|
511
|
+
never see it. The reply names that boundary, and status shows the same thing;
|
|
512
|
+
an instruction that arrives after the last boundary is recorded as
|
|
446
513
|
`never took effect` rather than looking delivered. A paused run
|
|
447
514
|
(`interrupted`, `failed`, `partial`, `cancelled`) keeps the instruction for
|
|
448
515
|
the next round, which starts when it is resumed; a `completed` run refuses it.
|
|
449
516
|
A run owned by another process is refused, because that owner's next save
|
|
450
|
-
would overwrite it. Only the session that started the run may add to it.
|
|
517
|
+
would overwrite it. Only the session that started the run may add to it. Use
|
|
518
|
+
`superagent_inject` when the running workers must read the instruction now.
|
|
519
|
+
- `superagent_inject(run_id, message, subtask_index?, wait_seconds?)` delivers
|
|
520
|
+
one instruction into the workers that are running right now. It uses the
|
|
521
|
+
host's live steering channel (`subagents.sendMessage`, the same inbox the
|
|
522
|
+
agent loop drains at its next pre-step), so the message is part of the child's
|
|
523
|
+
next model request. It does not interrupt a model call already in flight: the
|
|
524
|
+
delay is the remainder of the step that is running (that model response plus
|
|
525
|
+
its tool batch). A live child that had already decided to stop runs one more
|
|
526
|
+
turn to read it, so an uncancelled child consumes it. The reply reports the
|
|
527
|
+
measured delay from acceptance to the child's next request, and marks a
|
|
528
|
+
message as `missed` — never as delivered — when the child is cancelled,
|
|
529
|
+
disposed, or finishes before another boundary. Worst case measured on a real
|
|
530
|
+
`dsh@0.2.2-rc.1` host: **6978 ms** with an 8 s child step and **2986 ms** with
|
|
531
|
+
a 4 s step, i.e. the bound tracks the step, not the plugin. With a host that
|
|
532
|
+
exposes no live channel, the tool degrades to the followup queue and says so
|
|
533
|
+
in the reply; it never calls that live.
|
|
451
534
|
- `superagent_answer(run_id, attention_id?, answer, wait_seconds?)` answers one
|
|
452
535
|
structured attention item so that run continues with the decision. An active
|
|
453
536
|
run applies the answer at its next boundary; a finished run is reopened and
|
|
@@ -464,7 +547,7 @@ cost: at least ¥0.0041 (estimate; no price for haoduo/gpt-6.1-sol)
|
|
|
464
547
|
(project rules), `profile` (user preferences), or the run scope. `search`
|
|
465
548
|
ranks notes against `query` (the current goal works well) and/or exact `tags`,
|
|
466
549
|
so a relevant old note is found instead of only the newest ones; notes can
|
|
467
|
-
carry `tags` when set. The tool is additive: the
|
|
550
|
+
carry `tags` when set. The tool is additive: the ten other tools keep their
|
|
468
551
|
arguments and output.
|
|
469
552
|
- `superagent_template(action, id?, params?, template?, limit?)` lists, shows,
|
|
470
553
|
expands, saves, or deletes a workflow template: a fixed goal skeleton with
|
|
@@ -475,6 +558,26 @@ cost: at least ¥0.0041 (estimate; no price for haoduo/gpt-6.1-sol)
|
|
|
475
558
|
widens what a run may do. Built-in ids are read-only; custom ones live under
|
|
476
559
|
the template directory in the state directory, and a failure there is logged
|
|
477
560
|
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.
|
|
576
|
+
- `superagent_audit(run_id?, subtask_id?, kind?, decision?, result?, target?,
|
|
577
|
+
since?, until?, limit?, order?, format?, out_path?)` reads the audit trail, or
|
|
578
|
+
exports the matching events as one JSONL or CSV file. See
|
|
579
|
+
[Permissions and audit](#permissions-and-audit).
|
|
580
|
+
|
|
478
581
|
|
|
479
582
|
## Progress, decisions, and artifacts
|
|
480
583
|
|
|
@@ -497,11 +600,14 @@ cost: at least ¥0.0041 (estimate; no price for haoduo/gpt-6.1-sol)
|
|
|
497
600
|
archived (not deleted) when a resume retires it, which is what lets a late
|
|
498
601
|
answer be refused with `expired at <time>` instead of being attached to
|
|
499
602
|
whatever is open now.
|
|
500
|
-
- **Instructions during a run.**
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
carries it, or `missedAt` when the run
|
|
504
|
-
|
|
603
|
+
- **Instructions during a run.** Two boundaries, kept distinct.
|
|
604
|
+
`superagent_followup` appends to the dialog log and is carried by the next
|
|
605
|
+
prompt built for the run: each instruction records `appliedAt` /
|
|
606
|
+
`appliedAtStage` when a prompt first carries it, or `missedAt` when the run
|
|
607
|
+
settled first. `superagent_inject` instead steers a live child's inbox and is
|
|
608
|
+
claimed at its next pre-step; its receipt records `latencyMs` measured from
|
|
609
|
+
acceptance to that claim, or `missedReason` when the child left first. Status
|
|
610
|
+
prints both, so a queued instruction and a live one are never confused.
|
|
505
611
|
- **Report file.** A terminal run writes its report to
|
|
506
612
|
`<stateDir>/reports/<runId>.md` with an atomic rename, so the outcome has a
|
|
507
613
|
path that can be opened or attached. The directory carries a `.gitignore` with
|
|
@@ -514,6 +620,78 @@ cost: at least ¥0.0041 (estimate; no price for haoduo/gpt-6.1-sol)
|
|
|
514
620
|
cycle rejects the plan before any subtask starts. Status and the report show
|
|
515
621
|
waiting separately from running.
|
|
516
622
|
|
|
623
|
+
## Permissions and audit
|
|
624
|
+
|
|
625
|
+
Two independent layers sit around a run. A **policy** decides whether an action
|
|
626
|
+
may happen; an **audit trail** records what was decided and what followed. The
|
|
627
|
+
trail is on by default because it only observes. A policy changes nothing until
|
|
628
|
+
one exists, and it can only tighten what the plugin does on its own.
|
|
629
|
+
|
|
630
|
+
### Policy
|
|
631
|
+
|
|
632
|
+
Copy [docs/policy.example.json](https://github.com/LittleChenLiya/dsh-superagent/blob/main/docs/policy.example.json) to
|
|
633
|
+
`<stateDir>/policy.json`, or name another file with `policyFile`. Rules are
|
|
634
|
+
matched in this order:
|
|
635
|
+
|
|
636
|
+
1. a `paths.deny` / `commands.deny` pattern -> `deny` (deny always wins);
|
|
637
|
+
2. an explicit `paths.allow` / `commands.allow` entry -> `allow`;
|
|
638
|
+
3. the action kind listed under `confirm.actions` -> `confirm`;
|
|
639
|
+
4. the run's `runs.<id>.level`, else `defaultLevel`.
|
|
640
|
+
|
|
641
|
+
An allow entry that beats a `confirm` or a per-run `deny` is recorded with
|
|
642
|
+
`meta.relaxedFrom`, so a person can always see where the policy was opened up.
|
|
643
|
+
Relative path patterns match at any directory boundary (`src/**` covers
|
|
644
|
+
`/anywhere/repo/src/a.js`) but not a sibling that merely ends the same way
|
|
645
|
+
(`xsrc/a.js`). A command entry without `*` is a prefix on whole tokens
|
|
646
|
+
(`git status` permits `git status --short`, not `git statusx`); a composite line
|
|
647
|
+
(`git status && curl ...`) can never be lifted above `confirm` by a prefix.
|
|
648
|
+
|
|
649
|
+
`policy.json` may contain `//`, `#`, and `/* */` comments. A schema problem is
|
|
650
|
+
reported with the file, line, and column:
|
|
651
|
+
|
|
652
|
+
```
|
|
653
|
+
policy.json: 1 problem in the permission policy
|
|
654
|
+
policy.json:3:19 [defaultLevel] must be one of allow | confirm | deny
|
|
655
|
+
"defaultLevel": "maybe",
|
|
656
|
+
^
|
|
657
|
+
```
|
|
658
|
+
|
|
659
|
+
An unreadable or invalid policy **fails closed**: governed actions are denied and
|
|
660
|
+
`superagent_audit` prints the problem. A start or resume that is denied is
|
|
661
|
+
refused before any state changes; one held for `confirm` needs
|
|
662
|
+
`approve_policy: true` on the next call, and that approval is written as an
|
|
663
|
+
`approved` event naming the held event. An approval cannot release a `deny`.
|
|
664
|
+
|
|
665
|
+
### Audit
|
|
666
|
+
|
|
667
|
+
`<stateDir>/audit/audit.jsonl`, one JSON object per event:
|
|
668
|
+
|
|
669
|
+
```json
|
|
670
|
+
{"v":1,"id":"evt_...","at":"2026-11-15T10:04:11.238Z","runId":"20261115T100400-ab12cd34","subtaskId":"subtask-2","actor":"session:9f3c","kind":"path.write","action":"path.write","target":"C:/work/app/src/db.js","decision":"allow","result":"ok","durationMs":4,"rule":"paths.allow[0]","source":"policy","meta":{"relaxedFrom":"confirm","reason":"..."}}
|
|
671
|
+
```
|
|
672
|
+
|
|
673
|
+
Every event carries the run, the subtask, the actor, a timestamp, the decision,
|
|
674
|
+
the result, and how long the check took. Higher layers may add `tool.call` and
|
|
675
|
+
`command.exec` events. Triggered by the plugin itself: `run.start`, `run.resume`,
|
|
676
|
+
`run.cancel`, `run.finish`, `attention`, plus `blocked` when a policy denies and
|
|
677
|
+
`approved` when a person releases a held action.
|
|
678
|
+
|
|
679
|
+
Appends are serialized inside the process and guarded by a `wx` lock file across
|
|
680
|
+
processes, and each event is written with one append, so two workers finishing at
|
|
681
|
+
the same moment cannot splice a line. A trailing fragment left by a crash is
|
|
682
|
+
reported as `torn` and skipped; a damaged line is counted as `invalid` and does
|
|
683
|
+
not hide the rest.
|
|
684
|
+
|
|
685
|
+
`superagent_audit` reads by run, subtask, kind, decision, result, target text, and
|
|
686
|
+
time window. With `format: "jsonl"` or `format: "csv"` it writes one deliverable
|
|
687
|
+
file (default `<stateDir>/audit/audit-export-<time>.<ext>`) and returns its path.
|
|
688
|
+
|
|
689
|
+
A path/command guard can be attached without the audit layer knowing its rules:
|
|
690
|
+
`createAuditor({ dir, policyFile }).attachGuard(request => ({ decision, reason }))`.
|
|
691
|
+
The guard may only tighten the decision the policy produced; a guard that throws
|
|
692
|
+
is treated as a block. A guard that answers `{ blocked, rule, reason }` — the
|
|
693
|
+
shape a tool-call guard already produces — is understood as well.
|
|
694
|
+
|
|
517
695
|
## Cross-run memory
|
|
518
696
|
|
|
519
697
|
A run is isolated on purpose: planner and workers start empty. Without a
|
|
@@ -598,9 +776,9 @@ _Top of a report rendered from 40 real host runs. The full page — timeline,
|
|
|
598
776
|
swimlanes, call and cost curves, failure annotations, run table — is
|
|
599
777
|
[docs/report-sample.html](https://github.com/LittleChenLiya/dsh-superagent/blob/main/docs/report-sample.html)._
|
|
600
778
|
|
|
601
|
-
|
|
602
|
-
runtime dependency. `watch`, `report`, and `
|
|
603
|
-
files as the tools; `doctor` inspects the install itself.
|
|
779
|
+
Five operator utilities ship with the package, need no session, and add no
|
|
780
|
+
runtime dependency. `watch`, `report`, `archive`, and `sync` read the same
|
|
781
|
+
durable run files as the tools; `doctor` inspects the install itself.
|
|
604
782
|
|
|
605
783
|
Run them from the installed copy inside the profile:
|
|
606
784
|
|
|
@@ -648,7 +826,7 @@ records the command plus a zero-external-reference audit.
|
|
|
648
826
|
does. It reads only: no install, no mount, no edit to the profile. One block per
|
|
649
827
|
check — imported files against the `files` whitelist, declared files against
|
|
650
828
|
what is on disk, the installed copy against the published tarball for its
|
|
651
|
-
version, the profile's bundle registration, and the
|
|
829
|
+
version, the profile's bundle registration, and the eleven registered tools — each
|
|
652
830
|
failure followed by the command that fixes it.
|
|
653
831
|
|
|
654
832
|
```bash
|
|
@@ -669,6 +847,80 @@ None of these utilities is the install path: the plugin is installed with
|
|
|
669
847
|
**`archive`** is the fourth utility. It prunes terminal runs and exports or
|
|
670
848
|
imports one run as a self-contained archive; see [Retention](#retention) and
|
|
671
849
|
[Archives](#archives).
|
|
850
|
+
## Syncing one state directory across machines
|
|
851
|
+
|
|
852
|
+
There is no server and no account. The state directory is a directory of files,
|
|
853
|
+
so a git remote can carry it: `dsh-superagent-sync` makes that directory a
|
|
854
|
+
repository, keeps the machine-local files out, and gives you `pull`, `push`, and
|
|
855
|
+
`status`. `git` is the only requirement — the command has no dependency of its
|
|
856
|
+
own.
|
|
857
|
+
|
|
858
|
+
```bash
|
|
859
|
+
PKG="${DSH_HOME:-$HOME/.dsh}/profiles/web/node_modules/@xiangyixie/dsh-superagent"
|
|
860
|
+
node "$PKG/bin/sync.js" init git@github.com:me/superagent-state.git # once per machine
|
|
861
|
+
node "$PKG/bin/sync.js" push # after runs finish
|
|
862
|
+
node "$PKG/bin/sync.js" pull # before starting work
|
|
863
|
+
node "$PKG/bin/sync.js" status
|
|
864
|
+
```
|
|
865
|
+
|
|
866
|
+
Or `node_modules/.bin/dsh-superagent-sync`. All four accept `--state-dir
|
|
867
|
+
<path>` (default `$DSH_HOME/state/superagent`), and `--json` prints the raw
|
|
868
|
+
result.
|
|
869
|
+
|
|
870
|
+
**`init <remote>`** creates the repository, writes a managed block into
|
|
871
|
+
`.gitignore`, sets `origin`, and makes the first commit. Re-running it refreshes
|
|
872
|
+
the remote URL and that block without touching entries you added yourself. A
|
|
873
|
+
machine with no `~/.gitconfig` gets a repository-local commit identity, so the
|
|
874
|
+
first commit cannot fail on that alone.
|
|
875
|
+
|
|
876
|
+
**`pull`** fetches `origin`, then merges. Uncommitted local changes are stashed
|
|
877
|
+
first (`stash@{0}`, subject `dsh-sync auto-stash …`) and reapplied after the
|
|
878
|
+
merge, so a pull never silently overwrites an edit. A conflict stops the merge
|
|
879
|
+
with both sides still in the files: the paths are printed, nothing is chosen,
|
|
880
|
+
and the stash is left unapplied with a line saying so.
|
|
881
|
+
|
|
882
|
+
**`push`** commits everything and pushes the current branch, setting its
|
|
883
|
+
upstream on the first push. A rejected push is reported, not forced and not
|
|
884
|
+
auto-merged: run `pull`, resolve what it reports, then push again.
|
|
885
|
+
|
|
886
|
+
**`status`** prints ahead/behind counts, uncommitted files, stashes, and the
|
|
887
|
+
conflicted paths waiting for a decision.
|
|
888
|
+
|
|
889
|
+
### What never leaves the machine
|
|
890
|
+
|
|
891
|
+
`.owner`, `control.json` (a bearer token), `notifications.json`, `*.lock`,
|
|
892
|
+
`*.cancel`, `*.corrupt-*`, `*.tmp`, `*.log`, and `.env` / key material. The
|
|
893
|
+
notebook is the one exception worth knowing: `memory/.gitignore` normally holds
|
|
894
|
+
a bare `*`, which would keep every note local, so `init` rewrites that one
|
|
895
|
+
default to allow `<scope>.jsonl`. A file you customized is left alone.
|
|
896
|
+
|
|
897
|
+
### When it conflicts
|
|
898
|
+
|
|
899
|
+
Run records are one file per run (`runs/<runId>.json`), so ordinary concurrent
|
|
900
|
+
work on two machines — different runs — never touches the same path. A conflict
|
|
901
|
+
needs one of these:
|
|
902
|
+
|
|
903
|
+
- the same run id written on both machines: a resume or cancel on the second
|
|
904
|
+
machine before pulling the first machine's state;
|
|
905
|
+
- the same memory scope appended to on both machines (`memory/<scope>.jsonl` is
|
|
906
|
+
append-only, and two different tails collide);
|
|
907
|
+
- the same `reports/<runId>.md` regenerated with different content;
|
|
908
|
+
- `.gitignore` edited by hand on both machines.
|
|
909
|
+
|
|
910
|
+
While a run file still contains conflict markers it is not valid JSON, and the
|
|
911
|
+
plugin quarantines it at mount as `<runId>.json.corrupt-<ts>`. Resolve it before
|
|
912
|
+
starting the host: keep the side you want, `git add` it, `git commit`.
|
|
913
|
+
|
|
914
|
+
### Why this is approximate
|
|
915
|
+
|
|
916
|
+
- Two machines writing at the same moment can conflict. The merge stops and you
|
|
917
|
+
decide; nothing is merged behind your back.
|
|
918
|
+
- There is no live sync and no cross-machine lock. A machine sees another
|
|
919
|
+
machine's run only after `pull`, and `push` does not know what the other
|
|
920
|
+
machine is doing right now. Run one host per state directory at a time.
|
|
921
|
+
- Keys are not distributed: each machine still needs its own model credential.
|
|
922
|
+
- `keepRuns` pruning deletes files, and a deletion reaches the other machine
|
|
923
|
+
only on the next `pull`.
|
|
672
924
|
|
|
673
925
|
## Embedding over local HTTP
|
|
674
926
|
|
|
@@ -702,6 +954,44 @@ The full contract — routes, error ids, security model, lifecycle, client
|
|
|
702
954
|
examples — is [docs/embedding.md](https://github.com/LittleChenLiya/dsh-superagent/blob/main/docs/embedding.md). It is opt-in, loopback
|
|
703
955
|
only, and there is no remote or unauthenticated mode.
|
|
704
956
|
|
|
957
|
+
## Workspace panel
|
|
958
|
+
|
|
959
|
+
`workbenchPort` adds a local, IDE-shaped panel over one directory. It has its
|
|
960
|
+
own file tree, editor, diff preview, and run change view; nothing is proxied
|
|
961
|
+
through the host.
|
|
962
|
+
|
|
963
|
+
```bash
|
|
964
|
+
npx dsh-superagent-workbench --root /path/to/project --port 8787
|
|
965
|
+
```
|
|
966
|
+
|
|
967
|
+
The same server can run inside the host, with its Runs view wired to the plugin
|
|
968
|
+
state directory:
|
|
969
|
+
- id: superagent
|
|
970
|
+
config:
|
|
971
|
+
workbenchPort: 0 # off by default; 0 = OS picks a free loopback port
|
|
972
|
+
workbenchRoot: /path/to/project
|
|
973
|
+
```
|
|
974
|
+
|
|
975
|
+
The standalone command serves the same page and defaults its run state to
|
|
976
|
+
`<root>/.dsh-workbench`; pass `--state-dir <plugin state directory>` to read
|
|
977
|
+
existing runs. Neither form opens a socket unless you ask for it.
|
|
978
|
+
|
|
979
|
+
The bound URL and a fresh per-process token are written to
|
|
980
|
+
`<stateDir>/workbench.json` (mode `0600`). Open `http://127.0.0.1:<port>/?token=<token>`
|
|
981
|
+
once; the page keeps the token in `sessionStorage` and strips it from the
|
|
982
|
+
address bar. Without the token every route answers `401`.
|
|
983
|
+
|
|
984
|
+
The panel can list, read, and edit regular text files under `workbenchRoot`. It
|
|
985
|
+
refuses absolute paths, `..` traversal, symlinks that leave the root, the plugin
|
|
986
|
+
state directory, binary files, and files above 512 KB. Saving sends the hash and
|
|
987
|
+
mtime the editor read; if either changed on disk, the save is refused with
|
|
988
|
+
`external-change` instead of overwriting another process's work. Before a save
|
|
989
|
+
is confirmed the page shows a unified diff.
|
|
990
|
+
|
|
991
|
+
When `workbenchPort` is on, the plugin records the files each run changed into
|
|
992
|
+
that run's JSON record (`run.changes`), so the Runs view can show those files and
|
|
993
|
+
their diff against `git HEAD` later.
|
|
994
|
+
|
|
705
995
|
## State and recovery
|
|
706
996
|
|
|
707
997
|
One file per run: `$DSH_HOME/state/superagent/runs/<runId>.json`, written with a
|
|
@@ -896,8 +1186,8 @@ appears to "hang" until the ignored-abort child returns.
|
|
|
896
1186
|
|
|
897
1187
|
| What you see | What it means | What to do |
|
|
898
1188
|
| --- | --- | --- |
|
|
899
|
-
| `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.
|
|
900
|
-
| `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
|
|
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.0` 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. |
|
|
901
1191
|
| `[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`. |
|
|
902
1192
|
| `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. |
|
|
903
1193
|
| `[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. |
|
|
@@ -944,6 +1234,10 @@ A run that fails *after* it was accepted keeps its report and shows `error:`
|
|
|
944
1234
|
it cannot be exposed remotely, and there is no MCP server. A local process
|
|
945
1235
|
running as the same user can read the token, which is the same trust boundary
|
|
946
1236
|
as writing run files.
|
|
1237
|
+
- Cross-machine sync is a git repository, not a service: it is offline-first,
|
|
1238
|
+
conflict-stop rather than conflict-free, has no realtime channel, and does
|
|
1239
|
+
not move credentials between machines. Two hosts actively writing one state
|
|
1240
|
+
directory on two machines still need a `pull` between them.
|
|
947
1241
|
|
|
948
1242
|
## Naming
|
|
949
1243
|
|
package/bin/doctor.js
CHANGED
|
@@ -15,7 +15,7 @@ Check that this copy of dsh-superagent can actually run:
|
|
|
15
15
|
- every file the code imports is shipped by package.json "files" and exists
|
|
16
16
|
- the installed copy matches the version package.json claims
|
|
17
17
|
- the installed files match the published tarball (skipped when offline)
|
|
18
|
-
- the DSH profile mounts the bundle patch and the
|
|
18
|
+
- the DSH profile mounts the bundle patch and the eleven tools are registered
|
|
19
19
|
- the running Node satisfies "engines"
|
|
20
20
|
|
|
21
21
|
Nothing is installed or modified; the only network access is one public
|