dsh-swarm-orchestrator

dsh-swarm-orchestrator

English · 简体中文

Role-based AI swarms for DeepSeek Harness. Give it a goal, get a team: an architect breaks the work into a task graph, parallel builders execute it, reviewers hold the line, and an integrator ships the result — while you watch the whole thing move on a live kanban board.

It runs inside your dsh web host. No daemon, no second process, no glue scripts. Task agents are ordinary DSH subagents with your tool access and your models; the orchestrator is just a well-behaved Cordis plugin.

It has already shipped real work: the first production run reverse-engineered a biotech research dashboard and rebuilt it as a six-indication suite (680 curated clinical trials across six cancers) in a single afternoon — five data-curation agents working in parallel, every deliverable machine-verified.

---

At a glance

dsh-swarm-orchestrator turns one goal into a supervised agent team inside DeepSeek Harness: an architect reviews your plan into PLAN.md, parallel builders execute it as a task DAG, reviewers gate quality, an integrator ships. Every role runs a model you pin from your live catalog, every deliverable can be machine-verified, and the whole pipeline is visible on a live kanban + flow chart.

        you ── "spawn a swarm: ⟨goal⟩"
         │
         ▼
   your chat agent            (free to plan/research on its own —
         │  swarm_dispatch     its plan becomes the proposal)
         ▼
  ┌─────────────────┐
  │ architect-review │  deep-reviews the proposal against the repo,
  │  → PLAN.md       │  consolidates parallel workstreams (evidence-checked)
  └────────┬────────┘
    ┌──────┼──────┐
    ▼      ▼      ▼
 builder builder builder    ▸ parallel wave — one model per role,
    │      │      │           fallback chains, exclusive write scopes
    ▼      ▼      ▼
 reviewer reviewer (human)   ▸ rejections loop back with feedback;
    └──────┼──────┘            `reviewGate: "human"` parks it on you
           ▼
       integrator             ▸ merges, verifies, ships
           ▼
       📄 run report          ▸ per-task summaries · models used · stats

Example Kanban View (real-time workflow)

Optional hybrid workteam

Why not just ask one agent?

Because one agent serializes. Long research tasks queue behind quick edits, context fills up, quality drifts, and nothing checks the output but the same model that wrote it.

This plugin takes the coordination seriously so you don't have to:

• Parallel by construction. Tasks declare dependencies (blockedBy); everything independent runs at once, bounded by a concurrency cap that adapts when the provider struggles.
• Every role gets its own model. Pin DeepSeek, GLM, Kimi, Claude — any model configured in DSH — to any role, with an ordered fallback chain and a per-role reasoning-effort ladder. The picker reads your live model catalog, so new providers show up automatically.
• Review before "done" means done. Tasks tagged reviewBy are judged by a reviewer agent against the task brief; a rejection loops back to the builder with the feedback attached. Want the last word yourself? Set reviewGate: "human" and approve from the dashboard.
• Failure is a state, not a mystery. Provider timeouts, quota exhaustion, bad evidence — each is detected, reported plainly, and handled: retries with resume hints, run pause/resume instead of burn-down, automatic model rotation after repeated failures.
• Scoped to where you are. Each chat's Swarm tab shows the runs for that chat's workspace; a persisted switch reveals everything on the machine when you want the full picture.
• One run per goal, reviewed before built. Dispatching into a workspace with an active run raises a warning (or a block, your choice); and unless you opt out, an architect agent reviews the dispatcher's plan into PLAN.md before any builder starts.
• Shared concurrency budget. Swarm agents run in-process on the DSH host, sharing its Node.js heap. A global cap (maxTotalConcurrentAgents, default 100) shares the budget across runs and counts cancelling holders until cleanup. Choose a much lower cap on memory-constrained hosts; no fixed cap guarantees memory safety.
• Every agent stays on the board. Task agents cannot spawn hidden sub-agents of their own (maxSubagentDepth, default 1). Without that bound an agent could delegate to helpers the dispatcher cannot see or account for — not counted by the global cap, not tracked by the watchdog, not shown on the board, yet all sharing the host heap. Measured on a real machine: one task spawned 12 such hidden helpers while the board showed a single task.
• Work outlives its agent. Every task agent writes a small completion report as its final action. If the host restarts and kills an agent between finishing the work and being recorded, the dispatcher adopts the on-disk report instead of throwing the finished work away and re-running the task. A task can also never sit dispatching forever: spawnTimeoutSeconds arms a sliding no-progress window — it runs from creation, then every heartbeat re-arms it, so a working child is never killed for elapsed time while a child that never starts or goes silent is reclaimed (per-role override in the Roster).
• The right effort for the right model. Before a child is spawned, the pinned reasoning effort is validated against the deployment's declared model capabilities: a model whose declared levels exclude the pin has it stripped, and the candidate chain is never filtered. A model that declares no levels at all is left alone — absence is unknown, and the adapter may resolve such a model through its installed catalog — so since 2026-09-26 the trade-off is the visible way round: no silent downgrade. A pin that is genuinely refused dies fast with no output, and the dispatcher retries the same model at the next rung of the effort ladder (max → high → … → no pin) before any model rotation — without spending the task's retry budget. Reviewer pins are validated the same way, and the preflight's once-only log line reports how many models rest on that uncertainty.

⚠️ Running multiple swarms from different workspaces in parallel: this is supported and safe with the global cap. However, be mindful that each swarm agent is an in-process session on the host. We recommend max 2 concurrent runs unless your host has headroom for more - the global cap defaults to 100 in-process agents, which suits a large machine. If you experience ERR_CONNECTION_REFUSED (host crash), lower maxTotalConcurrentAgents in the Runtime settings.

Notices reach the running chat (0.6.32)

Swarm notices — the run result and the "waiting on a human" attention ping — now reach the dispatching chat while its turn is still running, instead of sitting in the input queue until that turn ends.

• The plugin reads the dispatching session's live status and picks the channel: idle → one ordinary turn, busy → steer, which the running turn consumes at its next step. A mid-turn followup is claimed only after the running turn fully ends, and a turn that ends by abort replays only a latched wake — production left a completed-run notice parked behind the dispatch turn until a human clicked Steer.
• A host without steer gets the no-wake inject fallback, and a host that cannot report status keeps followup, so older DSH versions still receive every notice.
• Notices are attributed as plugin notices, not user messages: they render as a collapsed dsh-swarm-orchestrator row with a one-line summary, and they are no longer mistaken for human authorization by goal, skill-scan or wake-budget policy. Their producer-owned source kind is plugin:dsh-swarm-orchestrator, matching migrated historical notices; the retired { kind: 'plugin', plugin: 'dsh-swarm-orchestrator' } wrapper is rejected by native V4 session persistence.
• The same routing covers the human-attention ping, so a decision that needs you surfaces during the run rather than after it.

Hardening and Flow updates (0.6.31)

This release adds lifecycle, admission and persistence safeguards, plus a readable, left-aligned Flow view.

• HTTP reads and actions share host admission checks; JSON and SSE have explicit resource bounds.
• Children inherit a captured sandbox ceiling with noninteractive approvals; command evidence uses the DSH Shell under that same authority, never an unrestricted host subprocess.
• Cancellation keeps capacity reserved until child/evidence cleanup actually finishes. A cleanup failure remains visible and retains its reservation.
• Attempt-bound reports are recovery hints, not approval: recovered work passes the same command-evidence and human/agent review gates as normal completion.
• Reviewer unavailability or exhausted retries are recorded separately from approval. Builder and reviewer identities, fallback models and actual effort pins remain distinct.
• Each owner receives only their own waits. The shared SSE transport fences stale responses; settings drafts survive progress and show observed conflicts. Saves are not server-side compare-and-swap.
• Flow waves, scheduler and report start at the same left edge. Nodes start at readable 100% size; use the zoom controls or Fit for a full-chart overview. The scaled footprint stays left-aligned; resizing, zooming or opening the task drawer returns the view to the left edge, while live progress preserves zoom and pan.
• Isolated headless Chrome checks previously covered Flow sizing, zoom, Fit, resizing, task clicks and progress. The subsequent left-alignment change has geometry and rendering regressions. These automated checks do not exercise the existing authenticated GUI.

Reliability notes (v0.5.8 – v0.6.17)

Diagnosed from 47 recorded runs / 184 task failures plus the incidents below, then fixed and regression-tested:

• Evidence commands run under PowerShell (bash elsewhere) from the workspace root, and the evidence.commands schema says so. Previously they were handed to cmd.exe, so a perfectly normal PowerShell gate (if (Test-Path …) { exit 0 }) failed the task — 32% of all recorded task failures. Commands are mandatory gates; evidence.files checks expected artifacts without a shell and produces advisory warnings, not a completion gate.
• modlens is denied to swarm roles by default in the shipped roster guidance: it is an interactive tool that asks the user a question, and swarm children run non-interactively. Add it back per-role from the Roster if your deployment has a headless vision provider.
• A task report that does not claim "status": "completed" is never adopted — adoption cannot mask unfinished work.
• An adopted report must belong to the exact live attempt. New reports use hashed run/attempt/task namespaces and carry matching identities; missing, wrong or revoked identities are rejected. Only legacy reports use the old task-id path and timestamp compatibility check. Adoption still runs evidence and review gates.
• Recovery is scoped to running runs. Orphan recovery only requeues tasks whose run is still running, so a terminal run's tasks stay frozen instead of being re-failed on every host restart.
• Review verdicts are parsed from the complete final message — the parser used to read a 2,000-character summary and fail every thorough review open. A reviewer that omits the verdict line now gets one explicit re-ask before failing open.
• Watchdog reclaims adopt finished work and arm the retry backoff. A child that wrote its report moments before being reclaimed is credited, not failed — the old path stranded a run in retrying for seven hours. Orphan recovery re-arms stranded retrying tasks, and every fresh attempt starts with a clean silence clock.
• Liveness is progress-based, not elapsed-time. The spawn ceiling is a sliding no-progress window re-armed by every heartbeat, with a per-role spawnTimeoutSeconds override in the Roster — a healthy child is never killed for running long.
• The web client holds exactly one /swarm/events connection, reference-counted and shared by the tab, the badge, the header popover and every dispatch card. It previously opened one stream per rendered dispatch card, exhausting the browser's ~6-connections-per-origin budget and freezing the whole UI while the host stayed healthy.
• An evidence-only failure no longer re-runs the work. One command-only recheck, then the task parks for a human (blocked + human review). The recorded outcome carries the exit code, the timeout state, the elapsed time and an output tail — a green-but-nonzero suite is diagnosable from the event log.

The dashboard

A Swarm tab lives next to Chat in the web GUI, in three views:

• Board — runs on the left, task columns (Queued / Running / Done / Failed) front and center. Click a task for its full brief, model, attempt count, interim agent notes, reviewer feedback, and retry. Completed runs fold into a report with per-task summaries and fallback/retry/review stats.
• Flow — the task DAG as a living flow chart: the scheduler at the top, tasks fanned out into parallel waves (same wave = runs concurrently), dependency arrows turning green as blockers complete, reviewer and write-scope hints on each node, all converging into the run report. You can see at a glance what ran in parallel, what ran in sequence, and exactly how far the run has gotten.
• Roster — the duty-table editor: per-role model pickers fed by your live catalog, fallback-chain ordering, effort ladder, concurrency caps, per-role spawn timeouts, tool filters, personas, custom roles, and an override lock for "hands off my table". The pickers list only providers you have configured in DSH (with API keys) and follow changes automatically — DSH 0.1.6+ required.
• Everywhere else — a 🐝 status button in every session header, a small badge for active runs, and a live progress card right in chat where the run was dispatched.
• Workspace-aware — each chat's Swarm tab shows the runs for that chat's workspace; an All switch reveals every run on the machine. The roster stays global (one table, all workspaces).
• Language — the Swarm UI follows the DSH language preference (Settings → General → Language) automatically: English and 简体中文 ship in the box, switching re-renders in place.

How a run works

1. Dispatch — tell your agent what you want; it calls swarm_dispatch with a task graph. Runs start gated: planning, zero agents spawned.
2. Execute — the architect reviews the proposal and produces PLAN.md; then parallel builders start.
3. Watch — Board shows the kanban; Flow shows the workflow chart; click any task for its drawer.

Getting started (~5 minutes)

1 · Install

From this GitHub repo (pnpm will run the package's prepare script to build from source):

dsh plugin --profile web add github:linkbag/dsh-swarm-orchestrator

pnpm ≥ 10 asks you to allow that build first — add the exact key it prints to the profile's pnpm-workspace.yaml:

allowBuilds:
  dsh-swarm-orchestrator: true

and re-run the add. (That allowance executes this package's code on your machine at install time — the usual trust rule applies; pin a commit if you prefer: github:linkbag/dsh-swarm-orchestrator#<sha>.)

Or install prebuilt from npm — no build allowance needed:

dsh plugin --profile web add dsh-swarm-orchestrator

Then restart dsh web (or reload the profile). You should see the Swarm tab next to Chat, a 🐝 button in every session header, and Settings → AI Swarm (the title shows the running version — a quick way to confirm the install).

2 · Assign models to roles

Open the Swarm tab in any chat and switch to Roster — or open Settings → AI Swarm, the same editor reachable from anywhere. The four built-in roles:

For each role, pick a model from the dropdown. It lists every provider configured in DSH (DeepSeek, GLM, Kimi, Claude, …), grouped by provider — the same live catalog as the Models settings page. Leave a role on inherit deployment default to use whatever model the dispatching chat runs on.

Optional, per role (all have sane defaults):

• Fallback chain — models tried in order if the primary is unavailable.
• Effort + effort ladder — the role's pinned reasoning effort; rungs advance per attempt and always end unpinned, and a level a model's declared map excludes is stripped before spawning.
• Concurrency cap — limit simultaneous agents of this role.
• Spawn timeout — per-role override of the no-progress window that reclaims a silent child.
• Tool filter — deny specific tools to this role's agents (e.g. a read-only reviewer).
• Persona — the role's standing instructions.

Missing a model? Add the provider in DSH Settings → Models first, then hit refresh catalog in the Roster.

3 · Dispatch your first swarm

In any chat, just ask:

"Spawn a swarm: audit every package.json in this repo for stale deps, one task per package, then an integrator compiles a summary table. Review the integrator's output."

or the one-shot form:

/swarm build a landing page for this project

Your agent will call swarm_dispatch with a task DAG. (It may plan first itself — that's fine: an architect agent reviews and refines whatever plan it sends.)

4 · Watch the run

• Board shows the kanban; Flow shows the same run as a workflow chart (scheduler → parallel waves → report); click any task for its drawer — brief, model, interim notes, reviewer feedback, retry.
• Tasks with reviewGate: "human" park on the board for your Approve/Reject.
• The dispatching chat gets a live progress card; the 🐝 header button and the bottom-right badge track active runs from anywhere.

5 · Read the report

When the run finishes it folds into a report: per-task summaries, models used, fallback/retry/review stats. The whole history is an append-only event log you can replay.

Defaults worth knowing: every run starts with an architect review of the plan (skip per dispatch with architectReview: false); dispatching into a workspace that already has an active run raises a warning — parallel workstreams belong in one DAG; the roster, badge, and header button are global across workspaces.

Talking to it

Everything is driven from normal chat — no config files to hand-edit:

"Spawn a swarm: audit every package.json in this repo for stale deps, one task per package, then an integrator compiles a summary table. Review the integrator's output."

or the one-shot form: /swarm build a landing page for this project (plans it, then executes it).

Tasks also accept an evidence contract — evidence: { files: [...], commands: [...] } — that is machine-checked before a task may close; a write scope — writes: [files] — that keeps concurrent builders out of each other's files (the dispatcher warns on overlap); and a human review gate that parks the verdict on the dashboard. A failing evidence command no longer re-runs the finished work: it gets one command-only recheck, and if the command still fails — non-zero exit or timeout (evidenceTimeoutMs, default 120 s) — the task parks on the board for a human verdict, with the exit code and an output tail recorded in the event log.

Configuration

Everything has a default; override in your profile's cordis.patch.yml:

- id: swarm
  require: dsh-swarm-orchestrator
  config:
    storageDir: !!js dshHomePath("storages/swarm")   # event log + duty table
    maxConcurrent: 50           # simultaneous task agents per run
    maxTotalConcurrentAgents: 100 # global cap across ALL runs (they share the budget)
    adaptiveConcurrency: true   # shrink on provider pain, recover on success
    spawnStaggerMs: 750         # pace launches within a wave
    nudgeAfterMinutes: 20       # board marker for long-silent tasks (0 = off)
    workspaceRunPolicy: warn      # one-run-per-goal guard: warn | block | off
    requireArchitectReview: true  # architect reviews the dispatcher's plan into PLAN.md first
    staleTimeoutSeconds: 14400  # watchdog: silent agents get reclaimed
    maxRetries: 2               # per task
    evidenceTimeoutMs: 120000   # per evidence command (1 s – 10 min)
    reviewLoops: 3              # review rejections per task
    notifyDispatchSession: true  # push completion notification to the dispatching chat
    retryBackoffBaseMs: 5000    # retry backoff: base × 2^attempt before retrying
    circuitBreakerThreshold: 3  # failures in 30s before pausing all retries (0 = off)
    circuitBreakerCooldownMs: 60000  # circuit breaker pause duration
    spawnTimeoutSeconds: 3600   # sliding no-progress window per child, re-armed by heartbeats (0 = off)
    maxSubagentDepth: 1         # delegation-depth cap for task agents (1 = no delegation)
    bootGraceSeconds: 3         # wait after plugin load before orphan recovery

Runtime control

All concurrency, hardening, and watchdog parameters are tunable from the dashboard — no YAML editing or restart needed. Open Settings → AI Swarm → Runtime tuning (or the Roster tab → Runtime tuning) and adjust: