dsh-swarm

Readme

# dsh-swarm

BSP coding swarm plugin for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) — nested, barrier-synchronized coding swarms of **100+ concurrent agents** tiered across DeepSeek V4 models.

- **1 root planner** (`deepseek-v4-pro`) → **2–16 squad leads** (`deepseek-v4-pro`) → **4–16 workers each** (`deepseek-v4-flash`, default fan-out 10×10 = 100 workers)
- **Five BSP phases** (partition → planning → execution → synthesis → integration), each closed by a barrier with a straggler deadline — no agent reads another agent's mid-phase output
- **Write isolation**: one git worktree per squad + a tiered region-ownership map enforced by the sandbox policy
- **Guardrail permissions**: in-grant actions auto-approve; out-of-grant escalate to the root planner; dangerous/budget actions escalate to you
- **Budget discipline**: per-tier pricing (pro $1.32/M in, flash $0.0826/M in), 90% pre-escalation, hard mission cap
- **Cache-stable prefixes**: byte-identical worker prefixes per squad ride one DeepSeek prefix-cache entry — a 100-worker mission lands at roughly $10–30
- **Checkpoint/resume** at every barrier

## Install

```bash
dsh plugin add github:Makoveli89/dsh-swarm
```

This runs pnpm in your DSH profile and reconciles the bundle layer: the five
swarm rows (engine, context, worktree, guard, tool) join your profile's
composition. It needs a profile whose base bundles provide the subagent spawn
backend, the LLM route, and the token meter (the default DSH profile does).

### Mount the mode

Copy the preset into your agent-presets directory:

```bash
mkdir -p "${DSH_HOME:-$HOME/.dsh}/.agent-presets/swarm"
cp preset.yml agent.cordis.yml "${DSH_HOME:-$HOME/.dsh}/.agent-presets/swarm/"
```

Then select the **DeepSeek Coding Swarm** preset for a session (or mount it as
your standing preset). The session agent gains the `swarm` tool.

## Use

```
swarm launch — repo: /absolute/path/to/repo, brief: "implement the TODOs in src/queue"
swarm status — missionId: <id>
swarm pause | resume | cancel | continue — missionId: <id>
swarm answer — escalationId: <id>, decision: <allow | reject | raise-cap>
```

Missions run asynchronously: after launch, monitor with `swarm status` and
react to `swarm/*` events. Defaults: 10×10 fan-out, $30 hard budget cap, per-
phase deadlines 5m/5m/20m/5m/5m — all overridable per launch or in the row
config.

## Packages

| Package | Role | ctx key |
|---|---|---|
| `@deepseek-ai/dsh-swarm` | Service definition + engine (BSP barriers, region ownership, budget, checkpoints, `swarm/*` events) | `ctx.swarmEngine` |
| `@deepseek-ai/dsh-swarm-context` | Cache-stable prefix compositor + role personas | `ctx.swarmContext` |
| `@deepseek-ai/dsh-swarm-worktree` | Per-squad git worktree leases | `ctx.swarmWorktree` |
| `@deepseek-ai/dsh-swarm-guard` | Capability grants + escalation verdicts | `ctx.swarmGuard` |
| `@deepseek-ai/dsh-tool-swarm` | Model-facing mission tool | registers on `ctx.tools` |

## Verification

Developed in the harness monorepo (PR: [deepseek-ai/deepseek-harness](https://github.com/deepseek-ai/deepseek-harness)): 117 tests, 100%
per-file coverage, host typecheck and oxlint clean, and a 100-concurrent-worker
load run over the barrier. Live-mission acceptance (real-model cache-hit ratio
and spend) is documented in the subsystem doc there.

## License

MIT. The cache-stable-prefix doctrine and planner/executor tiering are adopted
from [DeepSeek-Reasonix](https://github.com/esengine/DeepSeek-Reasonix) (MIT);
no code was imported.