@xiangyixie/dsh-superagent 0.11.0 → 0.12.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -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,91 @@ 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.1 — 2026-11-15
12
+
13
+ ### Fixed
14
+
15
+ - **Line endings in `bin/` and `lib/`.** Added `.gitattributes` with
16
+ `*.js text eol=lf` for both directories and normalized the tracked files to
17
+ LF. npm rewrites the shebang line of bin scripts during install (CRLF → LF,
18
+ one byte per file), which made `doctor`'s registry checksum comparison report
19
+ a false `Registry match` failure for `bin/*.js` on npm-installed copies. With
20
+ the tarball now shipping LF, installed files match the published package
21
+ byte-for-byte.
22
+
23
+ ## 0.12.0 — 2026-11-15
24
+
25
+ ### Added
26
+
27
+ - **Worker safety guard.** Child tool calls are now checked on the host's
28
+ `tools/pre-execute` / `ctx.tools.guard` pipeline. Writes are limited to the
29
+ child's workspace and the OS temp directory; credential stores and
30
+ `.git/config` / `.git/hooks` are refused for reading and writing; system
31
+ directories are refused for writing. Default command rules block disk
32
+ formatting, system scheduler and registry changes, writes into system
33
+ directories, destructive recursive deletes whose target is `/`, `~`, `.`,
34
+ `..`, a wildcard, or outside the workspace, permission nukes, and commands
35
+ that name a credential store. `guard.allowCommands` is an explicit,
36
+ audited override. Blocked calls surface in `superagent_status` and in a
37
+ `## Safety guard` report section. See “Worker safety guard” in the README
38
+ for the full defaults and their rationale.
39
+ - **Permission policy.** `<stateDir>/policy.json` (or `policyFile`) lets a person
40
+ say which paths may be written, which commands may run, which action classes
41
+ need a human, and what the default level is per run. The file accepts `//`,
42
+ `#`, and `/* */` comments, validates against a schema, and reports every
43
+ problem with file, line, and column. It only tightens: deny wins, explicit
44
+ allow entries record what they relaxed, and an invalid policy fails closed. A
45
+ start the policy denies is refused before any run record exists; a start held
46
+ for confirmation needs `approve_policy: true`, which is logged.
47
+ - **Audit trail.** Append-only JSONL at `<stateDir>/audit/audit.jsonl`: tool
48
+ calls, path writes, commands, blocks, approvals, attention decisions, and run
49
+ lifecycle, each with run id, subtask id, actor, timestamp, decision, result,
50
+ and duration. Appends are serialized in-process and locked across processes;
51
+ a torn tail or a damaged line is reported and skipped instead of hiding the
52
+ log. `audit: false` turns the trail off without changing run behaviour.
53
+ - **`superagent_audit`** queries by run, subtask, kind, decision, result, target,
54
+ and time window, and exports the matching events as one JSONL or CSV file.
55
+ - `createAuditor(...).attachGuard(fn)` is the seam for a separate path/command
56
+ guard: it can tighten a decision, never relax one.
57
+ - `superagent_inject(run_id, message, subtask_index?, wait_seconds?)` steers a
58
+ running child instead of waiting for the next prompt. It calls the host's
59
+ documented live channel (`subagents.sendMessage`, which lands in the same
60
+ `Agent` inbox that `steer`/`inject` expose), so the message is claimed at the
61
+ child's next pre-step and becomes part of its next model request. A child
62
+ that had already decided to stop runs one more turn to read it. Receipts
63
+ record `latencyMs` from acceptance to the claim, or a `missedReason` when the
64
+ child is cancelled, disposed, or finishes before another boundary. On a real
65
+ `dsh@0.2.2-rc.1` host the measured delay was 2986 ms with a 4 s child step
66
+ and 6978 ms with an 8 s step, i.e. bounded by the remainder of the running
67
+ step, not by the plugin. A host without that channel degrades to the followup
68
+ queue and the reply labels it as such.
69
+ - **Multi-device sync over git.** `dsh-superagent-sync` turns the state
70
+ directory into a repository and carries it between machines through any git
71
+ remote — no server, no account, no dependency. `init <remote>` writes a
72
+ managed `.gitignore` block (credentials, locks, cancel markers, quarantine
73
+ files, temp files, logs, machine identity) and makes the first commit;
74
+ `pull` fetches and merges, stashing uncommitted local work first and saying
75
+ so; `push` commits local state and pushes, reporting a rejection instead of
76
+ forcing; `status` reports ahead/behind counts, uncommitted files, stashes,
77
+ and conflicted paths. A conflict stops the merge with both sides kept and the
78
+ paths listed — nothing is resolved automatically. Run records were already
79
+ one file per run, so ordinary concurrent work on two machines does not
80
+ collide; the remaining shared surface is an append-only memory scope. The
81
+ README documents the limits: no realtime channel, no cross-machine lock, no
82
+ key distribution.
83
+ - **Local workspace panel.** `workbenchPort` (off by default, loopback only)
84
+ serves an IDE-shaped page from `public/workbench.html`: file tree, text editor,
85
+ diff preview before save, and a run view that lists the files a run changed.
86
+ The plugin reads and edits the filesystem itself, so no host API is involved.
87
+ Every request needs the per-process bearer token in `workbench.json`; absolute
88
+ paths, traversal, symlinks out of the root, the state directory, binaries, and
89
+ files above 512 KB are refused with a reason. Saving requires the hash and
90
+ mtime the editor read, so an external edit is never overwritten.
91
+ - `dsh-superagent-workbench` runs the same panel standalone, with `--root`,
92
+ `--port`, and `--state-dir`; no host is required.
93
+ - Run records now carry `changes` (recorded when the panel is on), which is what
94
+ the panel's run view reads and diffs against `git HEAD`.
95
+
11
96
  ## 0.11.0 — 2026-11-15
12
97
 
13
98
  Runs became something you can talk back to and shape: instructions and answers
@@ -40,15 +125,13 @@ still ships one file per module from `lib/`.
40
125
  one with the same key, and the planner digest now ranks notes against the run's
41
126
  goal instead of only taking the newest ones.
42
127
  - `superagent_followup(run_id, message)` appends an instruction to an active
43
- run. There is no host interface for appending a message to a running child
44
- activation, so delivery is boundary-scoped and the reply says so: the next
45
- worker spawn or the aggregation carries it, whichever comes first, and
46
- subtasks already running or finished keep their results. Each instruction
47
- records `appliedAt` / `appliedAtStage`, or `missedAt` with a reason when the
48
- run settled before another boundary ran. A paused run keeps the instruction
49
- for its next resume; a completed run refuses it. A run owned by another
50
- process is refused rather than written, because that owner's next save would
51
- erase it.
128
+ run. It stays next-prompt by design: the next worker spawn or the aggregation
129
+ carries it, whichever comes first, and subtasks already running or finished
130
+ keep their results. Each instruction records `appliedAt` / `appliedAtStage`,
131
+ or `missedAt` with a reason when the run settled before another boundary ran.
132
+ A paused run keeps the instruction for its next resume; a completed run
133
+ refuses it. A run owned by another process is refused rather than written,
134
+ because that owner's next save would erase it.
52
135
  - `superagent_answer(run_id, attention_id?, answer, wait_seconds?)` answers one
53
136
  structured attention item. Attention items now carry stable ids (`q1`, `q2`, …)
54
137
  from a per-run counter; the answer is recorded on that item and the run
@@ -131,6 +214,10 @@ still ships one file per module from `lib/`.
131
214
  were applied, are waiting, or never took effect; notifications lead with the
132
215
  question id so `superagent_answer` can be called directly.
133
216
 
217
+
218
+
219
+
220
+
134
221
  ## 0.10.0 — 2026-11-15
135
222
 
136
223
  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 — this adds no UI, only nine tools. Children run
21
- with the host's credentials and filesystem; this is not a sandbox.
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.11.0
28
+ dsh plugin --profile web add @xiangyixie/dsh-superagent@0.12.1
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 and patches no host code: the nine `superagent_*` tools are
40
- the surface, plus four optional operator utilities (a terminal panel, an HTML
41
- report, an install doctor, and a run archive) that read the same run files.
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.11.0
78
+ dsh plugin --profile web add @xiangyixie/dsh-superagent@0.12.1
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. It is **not** a live
440
- channel to the children: the host has no way to append a message to a running
441
- child activation, so the instruction is queued on the run and the next prompt
442
- built for it carries it — the next worker spawn or the aggregation, whichever
443
- comes first. Subtasks that are already running or finished keep their results
444
- and never see it. The reply names that boundary, and status shows the same
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 eight other tools keep their
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.** `superagent_followup` appends to the same log.
501
- The dialog is boundary-delivered by design: running children cannot be reached,
502
- so each instruction records `appliedAt` / `appliedAtStage` when a prompt first
503
- carries it, or `missedAt` when the run settled first. Status prints both, so
504
- "delivered" and "waiting" are never confused.
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
- Four operator utilities ship with the package, need no session, and add no
602
- runtime dependency. `watch`, `report`, and `archive` read the same durable run
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 nine registered tools — each
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.11.0` and read the host log for `[dsh-superagent]` lines. |
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 twelve `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. |
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. |
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