dsh-orchestrate

> One prompt. A team of agents.

中文 ｜ English


A third-party plugin for DeepSeek Harness that makes the main agent proactively orchestrate sub-agents: orchestrate_delegate (parallel decomposition), orchestrate_review (adversarial review), orchestrate_explore (diverse exploration), plus orchestrate_status / orchestrate_stop / orchestrate_converge to track, abort, and converge runs. Ships with an orchestration:policy decision prompt (root-agent only) that teaches the model when to delegate and when not to.

> ⚠️ Third-party plugin, not an official DeepSeek product. Built on the official subagent capability family (ctx.subagents) — this plugin only adds the decision layer, orchestration patterns, and convergence layer.

Why

• The official harness has a complete sub-agent substrate (spawn / continuable / toolFilter / structured output), but the model only has the ability to delegate — not the judgment of when to delegate, how to split, how to wait, and how to converge.
• A single agent has limits: long tasks run serially, plans lack a second perspective, and multiple directions are decided by gut feel.
• This plugin turns Proma's agent-collaboration methodology (parallel split / adversarial review / diverse exploration) into engineering.

Real-API validation (Spike C, 2026-08-16): 10 should-orchestrate tasks triggered orchestration 100%; 10 control tasks 0% false positives (deepseek-v4-flash). Triggering depends on the task brief being self-contained — consistent with the plugin's design.

Install

# install from this checkout; the provider version must match the DSH host
# 0.1.0-rc.6 is the combination verified by this repository
dsh plugin --profile demo add \
  @deepseek-ai/dsh-subagent-spawn-in-process@0.1.0-rc.6 .

# install the same combination from npm
dsh plugin --profile demo add \
  @deepseek-ai/dsh-subagent-spawn-in-process@0.1.0-rc.6 \
  dsh-orchestrate@0.3.1

Uses the spawn provider by default. The official provider must be installed in the DSH profile separately and must match the DSH host version. This repository verifies 0.1.0-rc.6; fork and acp require separate provider installation and validation.

Usage

In the dsh Web UI, say:

Research these three directions in parallel: ① SQLite vs DuckDB storage, ② RAG chunk strategy, ③ index design.

The agent calls orchestrate_delegate, which returns:

🧩 编排完成（run run-8ca117bf，3/3 成功）
  [0] ✅ SQLite 更适合小规模…
  [1] ✅ 512-token 重叠 10%…
  [2] ✅ HNSW 优于 IVF…

Long tasks can run in the background: pass run_in_background: true to get a runId immediately, then collect with orchestrate_converge.

Tools

> In background mode (run_in_background: true) converge.mode=any and retryFailed are ignored (semantics require synchronous waiting); the returned note states this.

Personas

Sub-agents accept role (an orchestrate_delegate parameter; review/explore fix their roles):

Behavior details

• Structured child output: the schema for the chosen role is enforced via the official structured_output mechanism.
• Recursion guard: every child auto-hides orchestrate_* tools (one visibility, verified in Spike B) and requests carry maxDepth=1; the depth cap still applies if toolFilter is downgraded.
• Decision prompt (plan C): the orchestration:policy section is filtered by delegationDepth — visible only to the root agent; children never see it (landed 2026-08-16).
• Read-only: relies on the official deployment sandbox default (read-only); if the deployment is workspace-write, children inherit write access.
• Failure semantics: child failures (error/refusal/max-tokens) are marked failed with partial output preserved; retryFailed retries only non-abort failures; mode=any returns a failed digest when all tasks settle without enough successes instead of waiting forever.
• Cost control: converge.timeoutMs aborts in-flight children on timeout; maxTokens is a soft budget (output-length estimate; over-limit aborts remaining children, estimate returned in costTokens); up to 20 tasks.
• Cancellation: cancelling the parent turn aborts in-flight children (parent signal wired in).

Limitations

• The task path does not auto-split (equivalent to a single task); write the array of task briefs yourself.
• Orchestration state lives in-process; a restart requires re-orchestration (cross-restart recovery not implemented).
• costTokens is an estimate (output-length approximation), not an official token count.
• Background runs are bounded by timeoutMs; convergence relies on official one-shot sub-agents (not the continuable background API).

Configuration

Template library

delegations/ ships 10 task-brief templates (research-compare / code-review / competitor-analysis / bug-hunt …), referenceable via the template parameter (pattern plug-in):

Call orchestrate_delegate with template=code-review-multi, templateArgs={ module: ['src/a', 'src/b'] }

templateArgs values that are string arrays (e.g. module / items / competitor) expand one task per element; scalar values are injected as shared context. PRs welcome (mirror dsh-bench datasets/).

Benchmark (collab suite)

Collab real extension set (2026-08-17): development-time runs over 27 tasks and batched retests measured 11/12 (91.7%) on explicit should-orchestrate tasks, 1/5 (20.0%) on implicit autonomous tasks, 12/17 (70.6%) overall, and 0/10 false positives on controls. These benchmark results came from the host project's development environment and are not included in this standalone repository or npm package.

Roadmap

• [x] M1: delegate / status / stop + decision prompt + template library (16 tests)
• [x] M2: review / explore / personas / per-run model (30 tests)
• [x] M3: template parameterization, backgrounding (converge), decision prompt plan C, collab suite, Spike C (54 + 37 tests)
• [x] 0.3.0: first public npm release; named entry exports and release builds without workspace path aliases
• [x] 0.3.1: fix mode=any zero-success convergence hangs; synchronize standalone docs, CI, LICENSE, and package metadata
• [ ] UI cards

Development

pnpm install
pnpm test       # 55 tests
pnpm typecheck
pnpm build

License

MIT