# dsh-orchestrate

> **One prompt. A team of agents.**

[中文](./README.md) ｜ English

![dsh-orchestrate concept](./docs/concept.png)

A third-party plugin for [DeepSeek Harness](https://github.com/deepseek-ai/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

```sh
# 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

| Tool | Purpose |
| --- | --- |
| `orchestrate_delegate` | Parallel split: `tasks` (array of task briefs) / `task` (single task) / `template` (`delegations/<id>.yml` + `templateArgs` placeholder fill). Concurrency 4, timeout 10 min by default. Supports `run_in_background`, `converge.mode: all/any`, `retryFailed`, `role`, `model` (per-run), `maxTokens` (soft budget). Returns a structured digest with per-child provenance. |
| `orchestrate_review` | Adversarial review: spawn read-only reviewer sub-agents to pick holes; returns a mechanical digest of risks / challenged assumptions / edge cases / suggestions for the parent to judge. Supports `aspects`, `reviewers` (1-5), `model`, `maxTokens`. |
| `orchestrate_explore` | Diverse exploration: spawn read-only researcher sub-agents along independent directions; returns confidence-tagged findings. Supports `directions` (max 6, truncates with a note), `model`, `maxTokens`. |
| `orchestrate_converge` | Converge a background run: blocks on the run's sub-agent results and returns the full digest (re-readable). |
| `orchestrate_status` | Query orchestration runs and child states (incl. background progress). |
| `orchestrate_stop` | Abort a running orchestration (children settle as `aborted`). |

> 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):

| role | lens | structured output |
| --- | --- | --- |
| `executor` (default) | complete the task and report | `{ summary, findings[], open_questions[] }` |
| `reviewer` | adversarial review: risks / assumptions / edges / suggestions | `{ verdict, risks[], assumptions_challenged[], edge_cases[], suggestions[] }` |
| `researcher` | directional exploration with confidence | `{ summary, findings[], confidence, evidence[] }` |
| `devil` | adversarial pressure test: counterpoints and what-ifs | `{ challenge, counterpoints[], what_if[] }` |

### 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

| key | default | meaning |
| --- | --- | --- |
| `provider` | `spawn` | in-process spawn provider name |
| `auto` | `true` | inject the `orchestration:policy` decision prompt (`false` = passive only) |
| `denyTools` | `orchestrate_*` | tool names hidden from children |
| `maxDepth` | `1` | child recursion depth cap |
| `templatesDir` | bundled `delegations/` | task-template directory (mount external template libraries) |
| `registryCapacity` | `100` | max orchestration records kept (oldest evicted) |

## 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

```sh
pnpm install
pnpm test       # 55 tests
pnpm typecheck
pnpm build
```

## License

MIT