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.
Badge for your README
Markdown
[](/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
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
- # dsh-supervisor — an Always-On Supervisor Agent for DeepSeek Harness
- A 24/7 **Main Agent** that records a reviewable goal, then loops unattended: spawn a dev
- subagent → sleep → wake on settle / report / timer / your message → inspect → steer,
- kill, or continue. Built **native-first** on [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)
- (dsh): the core is one agent preset, a persona, and one schedule-service row — zero custom
- loop machinery. This repo **is an installable dsh plugin bundle**: one command puts the
- whole setup on any machine running dsh.
- Tested end-to-end on `glm-5.3` (Z.AI): goal setup, grounded delegation, mid-flight
- steering, a mid-turn kill + tighter respawn, the silent-question → recorded-assumption
- flow, deliverable verification (it caught its own buggy link-checker and re-ran it),
- and full process-restart resume. Grader scores: m0–m5 and m7 at 100%.
- ## Run the local course on a new PC
- Install Git and Python 3, clone this repository, then run its course launcher:
- ```sh
- mkdir -p "$HOME/src"
- git clone https://github.com/dat-lequoc/dsh-supervisor.git "$HOME/src/dsh-supervisor"
- cd "$HOME/src/dsh-supervisor"
- ./tutorial/setup.sh
- ```
- The launcher keeps its environment under `tutorial/.venv`, installs the grader-only Python dependencies, selects
- an unused `127.0.0.1` port, and prints the tutorial URL. Its local server powers the grade
- buttons embedded in each milestone. It intentionally does not install dsh, clone DeepSeek Harness,
- configure a model, or create workspaces; the setup chapter teaches those steps explicitly.
- ## Install the supervisor (chapter 6)
- 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`).
- ```sh
- # 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:
- ```sh
- 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>
- ## Run
- Open http://127.0.0.1:3080 → new session → workspace `~/agi-lab` → preset
- **Main Agent (Supervisor)** → give it a mission, e.g.:
- > Goal: produce SUMMARY.md describing the layout of `<some docs dir>` — delegate the
- > work, supervise, deliver.
- What you should see, in order: it **grounds** by reading the durable mission state
- and relevant workspace runbooks/scripts, calls `start_goal` to write `.agi/GOAL.md`
- and arm the native goal immediately, then continues in the same turn. No generated
- confirmation phrase or second human reply is required. It then calls the guarded
- `subagent` tool with a complete structured task and an explicit Settings-approved model route,
- arms a recurring check-in reminder, and sleeps. It wakes on the worker's settle
- notice, **verifies the deliverable with its own reads**, logs everything to
- `.agi/CHANGELOG.jsonl`, and continues or finishes. You steer at any time by chatting;
- workers are ordinary sessions in the sidebar — click one to watch it live.
- ### Reviewable, non-blocking goal frontend
- The preset deliberately disables Harness's native model-facing
- `@deepseek-ai/dsh-tool-goal` row. That frontend permits `create_goal` to infer
- long-running intent without first checking durable mission state or workspace
- runbooks. `dsh-supervisor/goal` replaces only that
- frontend; the native `ctx.goals` service, session projection and race-fenced
- goal-round driver remain installed on the host.
- The replacement exposes `get_goal`, `start_goal`, and `update_goal`. `start_goal`
- is available only to the root agent in a direct human turn and only after that
- turn calls `get_goal`. It captures objective, constraints, milestones,
- out-of-scope and the autonomous round cap in canonical `GOAL.md`, calls the native
- goal service immediately, and returns to the same model turn so work continues.
- The generated document is for visibility and steering, not an approval gate: the
- human can inspect it and redirect, pause, or stop through ordinary chat.
- `update_goal` deliberately omits `edit`; pause, resume, completion, blocking
- thresholds, native revisions, projections and automatic continuation retain their
- Harness behavior.
- Worker failures are reported only when the native continuable child has actually
- settled. The supervisor preserves that single wake and enriches it from the child's
- durable final `turn/end`, for example `Terminal failure [QUOTA]: …`. Intermediate
- `RATE_LIMIT`, `SERVER`, `TIMEOUT`, `TRANSPORT`, and empty-response hiccups stay silent
- while Harness's retry policy owns them; a successful retry produces an ordinary
- completion notice, while exhausted retries expose only their final cause. The stopped
- child remains resumable through `send_message`.
- Blocked workers likewise cannot strand a question inside their own session. The
- guarded spawn frontend applies a native per-child tool restriction that removes
- `ask_user_question` from both the worker's advertised schema and execution path.
- The child-scoped `report` tool deliberately survives that restriction, so a question
- arrives at the parent as a `subagent-report` message, wakes the supervisor, and can be
- answered with `send_message`. A periodic reminder therefore remains a recovery check,
- not the first place the supervisor discovers that a worker has been waiting for input.
- The live prompt also forbids treating `list_agents: running` as evidence of progress.
- Every check-in must compare a concrete report, artifact/log change, or completed step
- with its prior `NOTES.md` checkpoint. The first unchanged check triggers a status probe;
- the next unchanged check interrupts and recovers or respawns the worker. This policy is
- rendered into every request, so the supervisor cannot legally loop on “still running.”
- User-owned knobs in `<workspace>/.agi/config.json` (the agent may propose changes but
- never edits it): `wakeMinutes` (check-in cadence, ≥ 5 — the schedule floor) and
- `questionWaitMinutes` (patience before it records an assumption and moves on).
- The preset treats recovery and continuity as explicit invariants. Before it
- escalates a blocker, the supervisor must inspect repository-local runbooks and
- scripts and try a bounded set of distinct safe recoveries; repeated hammering
- and bypassing security or approval boundaries are forbidden. A human-only
- dependency blocks only its branch: independent preparation and verification
- continue. Every unfinished long-running turn must leave a durable wake-up path
- (a running worker, an active native goal round, or a reminder), so a plain chat
- promise to wait cannot silently strand the mission. A legacy `GOAL.md` remains
- useful context but does not impersonate an armed native goal:
- every direct request to start, resume, or continue long-running work must first
- check `get_goal`; when no active native goal exists, the supervisor must inspect
- the workspace's relevant runbooks/scripts and call `start_goal`. Reminders are
- recovery aids, not a substitute for the goal driver.
- This boundary is enforced by a plugin-owned pre-execution guard, not only by
- persona text: an explicit long-running continuation may inspect durable state,
- but operational tools remain closed until the current turn checks native goal
- state and arms a reviewable goal. Once `start_goal` succeeds, the same turn may
- immediately use the workspace's existing automation. If the workspace contains
- a runbook, automation script, or source entry, `start_goal` is additionally
- denied until the current turn successfully opens one outside `.agi`; a broad
- listing or reading only GOAL.md/NOTES.md does not satisfy grounding.
- ## Meta-config (Settings → Plugins → Supervisor)
- The supervisor's user-owned knobs live in one settings namespace,
- **`dsh-supervisor`**, editable two ways with the same effect:
- - **Web UI:** Settings → Plugins → *Supervisor* — the card has an
- add-from-catalog dropdown. A synthetic **Current runtime model** choice is
- enabled by default; fixed models are tagged with native input modalities and
- their model-advertised reasoning efforts. Every allowed model row owns its
- own effort selector, and the add flow asks for both route and effort.
- - **File:** the `dsh-supervisor:` block in `~/.dsh/settings.yaml`.
- | Key | Meaning | Applies |
- |---|---|---|
- | `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) |
- | `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) |
- | `maxParallelWorkers` | max simultaneously open workers, **enforced** at spawn time; 0 = unlimited | next tool call (live) |
- | `wakeMinutes` | how often the supervisor wakes to inspect workers (minutes; recurring schedule, ≥ 5) | next turn (live) |
- | `questionWaitMinutes` | how long it waits for an answer to a question before recording an assumption and continuing | next turn (live) |
- Changes are **live** — no restart, no new session: the plugin re-resolves the
- allowlist and remounts `subagent` so its `model` enum and capability labels show
- only the current approved choices. Execution re-reads settings as well, closing
- the race where a model is removed after a request receives its tool schema. A
- `SUPERVISOR META-CONFIG` system-prompt section re-renders the same policy into
- every request alongside the enforced cap and timing defaults.
- Effort is a property of each settings-owned model row, not a tool-call choice.
- The main agent receives a required model enum but no effort parameter. It also
- cannot inherit effort from its own request: a missing legacy map entry becomes
- `provider/default`. A fixed effort that the exact resolved worker route does
- not advertise is refused before provider I/O; it is never clamped or silently
- downgraded. For dynamic `runtime/current`, only the provider/model route follows
- the calling turn; its effort still comes from `workerEfforts.runtime/current`.
- The plugin reserves the continuable child's exact id (or
- captures a foreground child's creation edge) and applies a one-use,
- id-filtered request override before its first model call, making the choice part
- of the child's durable `request/header`. Later warm steps and cold resumes both
- recover the logged explicit effort. No Harness patch or custom continuation
- descriptor is needed.
- There is deliberately no preset model list and no implicit parent/default
- inheritance. A fresh installation explicitly allows `runtime/current`: choosing
- it reads the provider/model captured in the calling turn's durable request
- header, resolves its capabilities, and forwards that exact route to the child.
- It never reads the parent's creation-time options, so switching the main model
- before a turn also switches what `runtime/current` means without reviving the
- stale-route bug. Remove this entry in Settings if every child must use a pinned
- route; remove every entry to disable spawning.
- The shipped native spawn and fork frontends are absent from the preset because
- they have no settings-guarded `model` argument and can inherit the main
- session's route/effort. The plugin-owned `subagent` is the sole delegation
- frontend. Every successful tool result names the selected
- route, native modalities, and effective effort policy, e.g.
- `antigravity/gemini-3.7-flash [text,image] effort=high`, so the hierarchy makes
- the settings-owned choice visible. Vision routing: give
- a `[text,image]` model and the supervisor sends image work (screenshots, UI
- checks, figures) there; workers read files with `read_image`, which the harness
- only allows on image-capable routes.
- ## The Feed tab
- Every session's view ring (the tabs holding **Chat** and **Trajectory**) gains a
- **Feed** entry: for a workspace with `.agi/` state it shows the whole run at a
- glance — live goal card, workers (with `outcome.md`), progress timeline, question
- stack, action changelog, notes, and the mission report, refreshing every ~5 s.
- Ships in this bundle as a durable client plugin (`lib/client.js`, served via the
- harness's client-modules scan) plus one host route (`GET /supervisor/feed?ws=…`)
- reading the `.agi/` tree. No frontend rebuild, no dynamic-plugin approval.
- ### Full stop (the button in the Feed header)
- The native stop square only aborts the current turn — the supervisor's recurring
- check-in reminder (`wakeMinutes`, floor 5 min) is a durable schedule event, so
- the agent re-runs by itself minutes later. The Feed header's **■ Full stop**
- button ends that for real. From a worker's Feed it resolves the lineage back to
- the root `main-agent`; if that supervisor is cold, the browser first resumes it
- through Harness's existing-id `session.create` path without starting a turn.
- `POST /supervisor/stop?session=…` then aborts the active turn, waits for idle,
- releases every resident continuable worker branch recursively, flushes before
- folding, and deletes **every** active schedule reminder from inside the agent's
- exclusive maintenance window, followed by a second persistence flush. `GET` on
- the same route verifies the turn, reminders, and workers, so a successful stop
- replaces the button with its stopped status even after a page refresh. A later
- manual prompt explicitly resumes the supervisor; stopped worker sessions remain
- in history, but do not keep running or wake it.
- Looking for the **Shots** tab (the screenshot player over a browser daemon's
- `<workspace>/shots/` feed)? That is its own standalone plugin, **`dsh-shots`** —
- generic browser-daemon tooling, deliberately not part of the supervisor.
- ## What's in this repo
- | Path | What |
- |---|---|
- | `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) |
- | `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 |
- | `agi-template/` | The `.agi/config.json` template for a new workspace |
- | `tutorial/` | The self-contained 15-step course app: HTML/CSS/JS, setup/server, private requirements, grading UI/CLI, milestone grader, and optional headless driver |
- | `scripts/install-manual.sh` | Non-bundle fallback installer |
- | `DESIGN.md` / `IMPLEMENTATION_PLAN.md` | The design record (Q1–Q23, A1–A6, S1–S4, N1–N7, G1) and the v2 plan |
- ## Grade it
- ```sh
- ./tutorial/grade.sh all --ws ~/agi-lab # m0–m6 report with bar chart
- ./tutorial/grade.sh m7 --ws ~/agi-acceptance # acceptance + restart evidence
- ./tutorial/grade.sh doctor # what the grader can see
- ```
- Graders read only durable artifacts (preset files, patch/bundle rows, `.agi/`, session
- event logs) — nothing is executed in your agents. `tutorial/GRADING.md` documents every
- check.
- ## Drive it headlessly (optional)
- ```sh
- S=$(python3 tutorial/drive.py create --cwd ~/agi-lab) # new supervisor session
- python3 tutorial/drive.py send "$S" "your mission here" # prompt + wait + tail
- python3 tutorial/drive.py tail "$S" # readable event tail
- ```
- ## Learn it from scratch
- Run `./tutorial/setup.sh` and open the URL it prints. Part I teaches Cordis and the harness from zero (no
- TypeScript assumed); Part II builds everything in this repo milestone by milestone,
- each with a live test and a grader; Part III covers packaged-plugin extensions —
- the very pattern this repo uses — and troubleshooting.
- ## Publishing & the plugin ecosystem
- How this package reaches other people, in ascending order of effort:
- 1. **GitHub + the `dsh-plugin` topic.** Tag the repo with the
- [`dsh-plugin`](https://github.com/topics/dsh-plugin) topic (the harness README's
- official discoverability channel) and write a crisp one-line repo description — the
- community indexes scrape exactly that line. Users then install straight from git:
- `dsh plugin --profile web add "github:you/dsh-supervisor"`.
- 2. **The aggregators pick it up automatically**: the awesome-lists
- (e.g. `vvlife/awesome-deepseek-harness-plugins` regenerates its `PLUGINS.md` daily
- from the topic) and topic-driven marketplaces (e.g. WhaleHub, a visual market with
- one-click install commands). A PR to a curated list adds human placement.
- 3. **npm publish** (optional): `dsh plugin` forwards to pnpm, so a published package
- installs by name. The `files` list in `package.json` already scopes the payload
- (`lib`, `cordis.patch.yml`, `agent-presets`, `agi-template`).
- Packaging notes for preset-shipping plugins, learned from the ecosystem
- (`dsh-minimal-msys2` ships presets with this same copy-at-boot pattern;
- `dsh-preset-qa-mode` ships script-only; `dsh-preset-scaffold` additionally registers
- its packaged `skills/` as a skill root via `dsh-skill-filesystem`):
- - Copy-at-boot into `${DSH_HOME}/.agent-presets/` is the established pattern — preset
- discovery re-reads roots on every call, so no restart is needed after the copy, and
- removing the plugin deliberately does not delete installed presets.
- - The roster also supports deployment-configured extra preset `roots` (see
- `dsh-agent-presets` Config), but a bundle cannot append to the shipped row's config
- without restating it wholesale — which is why the copy pattern won in practice.
- ## Safety notes
- - Most supervisor protocol remains prose plus audit, but goal creation and worker-model
- routing are hard-enforced by plugin-owned frontends. Read `.agi/CHANGELOG.jsonl` —
- it is the diary of every spawn/steer/kill/assumption.
- - Decide the sandbox/approval posture deliberately before unattended missions with
- real credentials (this lab runs `danger-full-access`).
- - One dsh per `$DSH_HOME`, ever. Never edit shipped presets or the harness checkout.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.