Skip to content
Back to search

dsh-supervisor

Always-on supervisor agent bundle for DeepSeek Harness: main-agent preset + schedule overlay, one dsh plugin add away

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/dat-lequoc--dsh-supervisor/badge.svg)](/listings/dat-lequoc--dsh-supervisor)

HTML

<a href="/listings/dat-lequoc--dsh-supervisor"><img src="/api/listings/dat-lequoc--dsh-supervisor/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites: Node.js 22.19+ in the 22.x line, or Node.js 24+, and dsh (`npm i -g @deepseek-ai/dsh`), with a model configured (web UI → Settings → Models; tested with Z.AI `glm-5.3`).

# When chapter 6 tells you to install the already-cloned package:
cd "$HOME/src/dsh-supervisor"
dsh plugin --profile web add "file:$PWD"

# restart dsh once (bundle layers compose at boot):
dsh web

That's the whole install. The one command registers the package as a **profile bundle** (dependency + `dsh.profile.bundles` entry), and at boot the bundle:

1. mounts the schedule service (`dsh-schedule`) the supervisor's timers need (no `dsh-time-context` — it would inject a timestamp block into every request, and Schedule does not depend on it), and 2. runs this package's setup plugin (`lib/index.js`), which installs the bundled **`main-agent` preset** into `${DSH_HOME:-~/.dsh}/.agent-presets/` — only if absent, never clobbering your edits (row config `syncPreset: always | if-absent | never`).

Then create a workspace for the supervisor's state:

mkdir -p "$HOME/agi-lab/.agi/subagents"
cp "$HOME/src/dsh-supervisor/agi-template/config.json" "$HOME/agi-lab/.agi/config.json"

<details> <summary>Alternative: manual install without the plugin manager</summary>

`./scripts/install-manual.sh ~/agi-lab` copies the preset into the user preset root and writes the schedule rows into your profile's `cordis.patch.yml` instead. Use ONE path, not both — the schedule service registers once per process, so the bundle rows and manual patch rows must not coexist. If your profile already mounts `dsh-schedule` from elsewhere, disable this bundle's copy with an id-targeted `disabled: true` patch on `agi-schedule`. </details>

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 325 lines
  1. # dsh-supervisor — an Always-On Supervisor Agent for DeepSeek Harness
  2. A 24/7 **Main Agent** that records a reviewable goal, then loops unattended: spawn a dev
  3. subagent → sleep → wake on settle / report / timer / your message → inspect → steer,
  4. kill, or continue. Built **native-first** on [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)
  5. (dsh): the core is one agent preset, a persona, and one schedule-service row — zero custom
  6. loop machinery. This repo **is an installable dsh plugin bundle**: one command puts the
  7. whole setup on any machine running dsh.
  8. Tested end-to-end on `glm-5.3` (Z.AI): goal setup, grounded delegation, mid-flight
  9. steering, a mid-turn kill + tighter respawn, the silent-question → recorded-assumption
  10. flow, deliverable verification (it caught its own buggy link-checker and re-ran it),
  11. and full process-restart resume. Grader scores: m0–m5 and m7 at 100%.
  12. ## Run the local course on a new PC
  13. Install Git and Python 3, clone this repository, then run its course launcher:
  14. ```sh
  15. mkdir -p "$HOME/src"
  16. git clone https://github.com/dat-lequoc/dsh-supervisor.git "$HOME/src/dsh-supervisor"
  17. cd "$HOME/src/dsh-supervisor"
  18. ./tutorial/setup.sh
  19. ```
  20. The launcher keeps its environment under `tutorial/.venv`, installs the grader-only Python dependencies, selects
  21. an unused `127.0.0.1` port, and prints the tutorial URL. Its local server powers the grade
  22. buttons embedded in each milestone. It intentionally does not install dsh, clone DeepSeek Harness,
  23. configure a model, or create workspaces; the setup chapter teaches those steps explicitly.
  24. ## Install the supervisor (chapter 6)
  25. Prerequisites: Node.js 22.19+ in the 22.x line, or Node.js 24+, and dsh
  26. (`npm i -g @deepseek-ai/dsh`), with a model configured (web UI → Settings → Models;
  27. tested with Z.AI `glm-5.3`).
  28. ```sh
  29. # When chapter 6 tells you to install the already-cloned package:
  30. cd "$HOME/src/dsh-supervisor"
  31. dsh plugin --profile web add "file:$PWD"
  32. # restart dsh once (bundle layers compose at boot):
  33. dsh web
  34. ```
  35. That's the whole install. The one command registers the package as a **profile bundle**
  36. (dependency + `dsh.profile.bundles` entry), and at boot the bundle:
  37. 1. mounts the schedule service (`dsh-schedule`) the supervisor's timers need
  38. (no `dsh-time-context` — it would inject a timestamp block into every request,
  39. and Schedule does not depend on it), and
  40. 2. runs this package's setup plugin (`lib/index.js`), which installs the bundled
  41. **`main-agent` preset** into `${DSH_HOME:-~/.dsh}/.agent-presets/` — only if absent,
  42. never clobbering your edits (row config `syncPreset: always | if-absent | never`).
  43. Then create a workspace for the supervisor's state:
  44. ```sh
  45. mkdir -p "$HOME/agi-lab/.agi/subagents"
  46. cp "$HOME/src/dsh-supervisor/agi-template/config.json" "$HOME/agi-lab/.agi/config.json"
  47. ```
  48. <details>
  49. <summary>Alternative: manual install without the plugin manager</summary>
  50. `./scripts/install-manual.sh ~/agi-lab` copies the preset into the user preset root
  51. and writes the schedule rows into your profile's `cordis.patch.yml` instead. Use ONE
  52. path, not both — the schedule service registers once per process, so the bundle rows
  53. and manual patch rows must not coexist. If your profile already mounts
  54. `dsh-schedule` from elsewhere, disable this bundle's copy with an id-targeted
  55. `disabled: true` patch on `agi-schedule`.
  56. </details>
  57. ## Run
  58. Open http://127.0.0.1:3080 → new session → workspace `~/agi-lab` → preset
  59. **Main Agent (Supervisor)** → give it a mission, e.g.:
  60. > Goal: produce SUMMARY.md describing the layout of `<some docs dir>` — delegate the
  61. > work, supervise, deliver.
  62. What you should see, in order: it **grounds** by reading the durable mission state
  63. and relevant workspace runbooks/scripts, calls `start_goal` to write `.agi/GOAL.md`
  64. and arm the native goal immediately, then continues in the same turn. No generated
  65. confirmation phrase or second human reply is required. It then calls the guarded
  66. `subagent` tool with a complete structured task and an explicit Settings-approved model route,
  67. arms a recurring check-in reminder, and sleeps. It wakes on the worker's settle
  68. notice, **verifies the deliverable with its own reads**, logs everything to
  69. `.agi/CHANGELOG.jsonl`, and continues or finishes. You steer at any time by chatting;
  70. workers are ordinary sessions in the sidebar — click one to watch it live.
  71. ### Reviewable, non-blocking goal frontend
  72. The preset deliberately disables Harness's native model-facing
  73. `@deepseek-ai/dsh-tool-goal` row. That frontend permits `create_goal` to infer
  74. long-running intent without first checking durable mission state or workspace
  75. runbooks. `dsh-supervisor/goal` replaces only that
  76. frontend; the native `ctx.goals` service, session projection and race-fenced
  77. goal-round driver remain installed on the host.
  78. The replacement exposes `get_goal`, `start_goal`, and `update_goal`. `start_goal`
  79. is available only to the root agent in a direct human turn and only after that
  80. turn calls `get_goal`. It captures objective, constraints, milestones,
  81. out-of-scope and the autonomous round cap in canonical `GOAL.md`, calls the native
  82. goal service immediately, and returns to the same model turn so work continues.
  83. The generated document is for visibility and steering, not an approval gate: the
  84. human can inspect it and redirect, pause, or stop through ordinary chat.
  85. `update_goal` deliberately omits `edit`; pause, resume, completion, blocking
  86. thresholds, native revisions, projections and automatic continuation retain their
  87. Harness behavior.
  88. Worker failures are reported only when the native continuable child has actually
  89. settled. The supervisor preserves that single wake and enriches it from the child's
  90. durable final `turn/end`, for example `Terminal failure [QUOTA]: …`. Intermediate
  91. `RATE_LIMIT`, `SERVER`, `TIMEOUT`, `TRANSPORT`, and empty-response hiccups stay silent
  92. while Harness's retry policy owns them; a successful retry produces an ordinary
  93. completion notice, while exhausted retries expose only their final cause. The stopped
  94. child remains resumable through `send_message`.
  95. Blocked workers likewise cannot strand a question inside their own session. The
  96. guarded spawn frontend applies a native per-child tool restriction that removes
  97. `ask_user_question` from both the worker's advertised schema and execution path.
  98. The child-scoped `report` tool deliberately survives that restriction, so a question
  99. arrives at the parent as a `subagent-report` message, wakes the supervisor, and can be
  100. answered with `send_message`. A periodic reminder therefore remains a recovery check,
  101. not the first place the supervisor discovers that a worker has been waiting for input.
  102. The live prompt also forbids treating `list_agents: running` as evidence of progress.
  103. Every check-in must compare a concrete report, artifact/log change, or completed step
  104. with its prior `NOTES.md` checkpoint. The first unchanged check triggers a status probe;
  105. the next unchanged check interrupts and recovers or respawns the worker. This policy is
  106. rendered into every request, so the supervisor cannot legally loop on “still running.”
  107. User-owned knobs in `<workspace>/.agi/config.json` (the agent may propose changes but
  108. never edits it): `wakeMinutes` (check-in cadence, ≥ 5 — the schedule floor) and
  109. `questionWaitMinutes` (patience before it records an assumption and moves on).
  110. The preset treats recovery and continuity as explicit invariants. Before it
  111. escalates a blocker, the supervisor must inspect repository-local runbooks and
  112. scripts and try a bounded set of distinct safe recoveries; repeated hammering
  113. and bypassing security or approval boundaries are forbidden. A human-only
  114. dependency blocks only its branch: independent preparation and verification
  115. continue. Every unfinished long-running turn must leave a durable wake-up path
  116. (a running worker, an active native goal round, or a reminder), so a plain chat
  117. promise to wait cannot silently strand the mission. A legacy `GOAL.md` remains
  118. useful context but does not impersonate an armed native goal:
  119. every direct request to start, resume, or continue long-running work must first
  120. check `get_goal`; when no active native goal exists, the supervisor must inspect
  121. the workspace's relevant runbooks/scripts and call `start_goal`. Reminders are
  122. recovery aids, not a substitute for the goal driver.
  123. This boundary is enforced by a plugin-owned pre-execution guard, not only by
  124. persona text: an explicit long-running continuation may inspect durable state,
  125. but operational tools remain closed until the current turn checks native goal
  126. state and arms a reviewable goal. Once `start_goal` succeeds, the same turn may
  127. immediately use the workspace's existing automation. If the workspace contains
  128. a runbook, automation script, or source entry, `start_goal` is additionally
  129. denied until the current turn successfully opens one outside `.agi`; a broad
  130. listing or reading only GOAL.md/NOTES.md does not satisfy grounding.
  131. ## Meta-config (Settings → Plugins → Supervisor)
  132. The supervisor's user-owned knobs live in one settings namespace,
  133. **`dsh-supervisor`**, editable two ways with the same effect:
  134. - **Web UI:** Settings → Plugins → *Supervisor* — the card has an
  135. add-from-catalog dropdown. A synthetic **Current runtime model** choice is
  136. enabled by default; fixed models are tagged with native input modalities and
  137. their model-advertised reasoning efforts. Every allowed model row owns its
  138. own effort selector, and the add flow asks for both route and effort.
  139. - **File:** the `dsh-supervisor:` block in `~/.dsh/settings.yaml`.
  140. | Key | Meaning | Applies |
  141. |---|---|---|
  142. | `workerModels` | complete allowlist for required `subagent.model`: `runtime/current` and/or exact `provider/model-id` routes; fresh install = `runtime/current`; empty = spawning disabled | next tool call and next tool schema (live) |
  143. | `workerEfforts` | map from each allowed route to its user-selected effort; `provider/default` sends no explicit effort (fresh-install and missing-entry default), while fixed ids such as `high` come from the route's native catalog | next spawn and next tool description (live) |
  144. | `maxParallelWorkers` | max simultaneously open workers, **enforced** at spawn time; 0 = unlimited | next tool call (live) |
  145. | `wakeMinutes` | how often the supervisor wakes to inspect workers (minutes; recurring schedule, ≥ 5) | next turn (live) |
  146. | `questionWaitMinutes` | how long it waits for an answer to a question before recording an assumption and continuing | next turn (live) |
  147. Changes are **live** — no restart, no new session: the plugin re-resolves the
  148. allowlist and remounts `subagent` so its `model` enum and capability labels show
  149. only the current approved choices. Execution re-reads settings as well, closing
  150. the race where a model is removed after a request receives its tool schema. A
  151. `SUPERVISOR META-CONFIG` system-prompt section re-renders the same policy into
  152. every request alongside the enforced cap and timing defaults.
  153. Effort is a property of each settings-owned model row, not a tool-call choice.
  154. The main agent receives a required model enum but no effort parameter. It also
  155. cannot inherit effort from its own request: a missing legacy map entry becomes
  156. `provider/default`. A fixed effort that the exact resolved worker route does
  157. not advertise is refused before provider I/O; it is never clamped or silently
  158. downgraded. For dynamic `runtime/current`, only the provider/model route follows
  159. the calling turn; its effort still comes from `workerEfforts.runtime/current`.
  160. The plugin reserves the continuable child's exact id (or
  161. captures a foreground child's creation edge) and applies a one-use,
  162. id-filtered request override before its first model call, making the choice part
  163. of the child's durable `request/header`. Later warm steps and cold resumes both
  164. recover the logged explicit effort. No Harness patch or custom continuation
  165. descriptor is needed.
  166. There is deliberately no preset model list and no implicit parent/default
  167. inheritance. A fresh installation explicitly allows `runtime/current`: choosing
  168. it reads the provider/model captured in the calling turn's durable request
  169. header, resolves its capabilities, and forwards that exact route to the child.
  170. It never reads the parent's creation-time options, so switching the main model
  171. before a turn also switches what `runtime/current` means without reviving the
  172. stale-route bug. Remove this entry in Settings if every child must use a pinned
  173. route; remove every entry to disable spawning.
  174. The shipped native spawn and fork frontends are absent from the preset because
  175. they have no settings-guarded `model` argument and can inherit the main
  176. session's route/effort. The plugin-owned `subagent` is the sole delegation
  177. frontend. Every successful tool result names the selected
  178. route, native modalities, and effective effort policy, e.g.
  179. `antigravity/gemini-3.7-flash [text,image] effort=high`, so the hierarchy makes
  180. the settings-owned choice visible. Vision routing: give
  181. a `[text,image]` model and the supervisor sends image work (screenshots, UI
  182. checks, figures) there; workers read files with `read_image`, which the harness
  183. only allows on image-capable routes.
  184. ## The Feed tab
  185. Every session's view ring (the tabs holding **Chat** and **Trajectory**) gains a
  186. **Feed** entry: for a workspace with `.agi/` state it shows the whole run at a
  187. glance — live goal card, workers (with `outcome.md`), progress timeline, question
  188. stack, action changelog, notes, and the mission report, refreshing every ~5 s.
  189. Ships in this bundle as a durable client plugin (`lib/client.js`, served via the
  190. harness's client-modules scan) plus one host route (`GET /supervisor/feed?ws=…`)
  191. reading the `.agi/` tree. No frontend rebuild, no dynamic-plugin approval.
  192. ### Full stop (the button in the Feed header)
  193. The native stop square only aborts the current turn — the supervisor's recurring
  194. check-in reminder (`wakeMinutes`, floor 5 min) is a durable schedule event, so
  195. the agent re-runs by itself minutes later. The Feed header's **■ Full stop**
  196. button ends that for real. From a worker's Feed it resolves the lineage back to
  197. the root `main-agent`; if that supervisor is cold, the browser first resumes it
  198. through Harness's existing-id `session.create` path without starting a turn.
  199. `POST /supervisor/stop?session=…` then aborts the active turn, waits for idle,
  200. releases every resident continuable worker branch recursively, flushes before
  201. folding, and deletes **every** active schedule reminder from inside the agent's
  202. exclusive maintenance window, followed by a second persistence flush. `GET` on
  203. the same route verifies the turn, reminders, and workers, so a successful stop
  204. replaces the button with its stopped status even after a page refresh. A later
  205. manual prompt explicitly resumes the supervisor; stopped worker sessions remain
  206. in history, but do not keep running or wake it.
  207. Looking for the **Shots** tab (the screenshot player over a browser daemon's
  208. `<workspace>/shots/` feed)? That is its own standalone plugin, **`dsh-shots`** —
  209. generic browser-daemon tooling, deliberately not part of the supervisor.
  210. ## What's in this repo
  211. | Path | What |
  212. |---|---|
  213. | `package.json` + `cordis.patch.yml` + `lib/` | The dsh bundle: manifest (`dsh.bundle.patch` + `dsh.client`), the inserted rows, setup/routes, non-blocking native-goal frontend, final-settlement diagnostics, and the browser half (`lib/client.js`: Feed tab, Full stop, settings card) |
  214. | `agent-presets/main-agent/` | The supervisor preset: persona (grounding, non-blocking goal setup, loop, questions), plugin-owned goal frontend, and the sole settings-guarded `subagent` worker row |
  215. | `agi-template/` | The `.agi/config.json` template for a new workspace |
  216. | `tutorial/` | The self-contained 15-step course app: HTML/CSS/JS, setup/server, private requirements, grading UI/CLI, milestone grader, and optional headless driver |
  217. | `scripts/install-manual.sh` | Non-bundle fallback installer |
  218. | `DESIGN.md` / `IMPLEMENTATION_PLAN.md` | The design record (Q1–Q23, A1–A6, S1–S4, N1–N7, G1) and the v2 plan |
  219. ## Grade it
  220. ```sh
  221. ./tutorial/grade.sh all --ws ~/agi-lab # m0–m6 report with bar chart
  222. ./tutorial/grade.sh m7 --ws ~/agi-acceptance # acceptance + restart evidence
  223. ./tutorial/grade.sh doctor # what the grader can see
  224. ```
  225. Graders read only durable artifacts (preset files, patch/bundle rows, `.agi/`, session
  226. event logs) — nothing is executed in your agents. `tutorial/GRADING.md` documents every
  227. check.
  228. ## Drive it headlessly (optional)
  229. ```sh
  230. S=$(python3 tutorial/drive.py create --cwd ~/agi-lab) # new supervisor session
  231. python3 tutorial/drive.py send "$S" "your mission here" # prompt + wait + tail
  232. python3 tutorial/drive.py tail "$S" # readable event tail
  233. ```
  234. ## Learn it from scratch
  235. Run `./tutorial/setup.sh` and open the URL it prints. Part I teaches Cordis and the harness from zero (no
  236. TypeScript assumed); Part II builds everything in this repo milestone by milestone,
  237. each with a live test and a grader; Part III covers packaged-plugin extensions —
  238. the very pattern this repo uses — and troubleshooting.
  239. ## Publishing & the plugin ecosystem
  240. How this package reaches other people, in ascending order of effort:
  241. 1. **GitHub + the `dsh-plugin` topic.** Tag the repo with the
  242. [`dsh-plugin`](https://github.com/topics/dsh-plugin) topic (the harness README's
  243. official discoverability channel) and write a crisp one-line repo description — the
  244. community indexes scrape exactly that line. Users then install straight from git:
  245. `dsh plugin --profile web add "github:you/dsh-supervisor"`.
  246. 2. **The aggregators pick it up automatically**: the awesome-lists
  247. (e.g. `vvlife/awesome-deepseek-harness-plugins` regenerates its `PLUGINS.md` daily
  248. from the topic) and topic-driven marketplaces (e.g. WhaleHub, a visual market with
  249. one-click install commands). A PR to a curated list adds human placement.
  250. 3. **npm publish** (optional): `dsh plugin` forwards to pnpm, so a published package
  251. installs by name. The `files` list in `package.json` already scopes the payload
  252. (`lib`, `cordis.patch.yml`, `agent-presets`, `agi-template`).
  253. Packaging notes for preset-shipping plugins, learned from the ecosystem
  254. (`dsh-minimal-msys2` ships presets with this same copy-at-boot pattern;
  255. `dsh-preset-qa-mode` ships script-only; `dsh-preset-scaffold` additionally registers
  256. its packaged `skills/` as a skill root via `dsh-skill-filesystem`):
  257. - Copy-at-boot into `${DSH_HOME}/.agent-presets/` is the established pattern — preset
  258. discovery re-reads roots on every call, so no restart is needed after the copy, and
  259. removing the plugin deliberately does not delete installed presets.
  260. - The roster also supports deployment-configured extra preset `roots` (see
  261. `dsh-agent-presets` Config), but a bundle cannot append to the shipped row's config
  262. without restating it wholesale — which is why the copy pattern won in practice.
  263. ## Safety notes
  264. - Most supervisor protocol remains prose plus audit, but goal creation and worker-model
  265. routing are hard-enforced by plugin-owned frontends. Read `.agi/CHANGELOG.jsonl` —
  266. it is the diary of every spawn/steer/kill/assumption.
  267. - Decide the sandbox/approval posture deliberately before unattended missions with
  268. real credentials (this lab runs `danger-full-access`).
  269. - One dsh per `$DSH_HOME`, ever. Never edit shipped presets or the harness checkout.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.