dsh-swarm-panel (dsh-swarm-plugin)

dsh-swarm-panel

English · 中文 · 한국어 · 日本語 · Español · Português

Conversation Flow observability for DeepSeek Harness: watch an Orchestrator coordinate child agents, inspect routed messages, follow topology changes, and open any child session from the web UI.

This repository is the standalone dsh-swarm-panel plugin. It is not the same package as the historical dsh-agent-swarm plugin that lived inside a Harness checkout.

What it adds

• A durable swarm runtime with parent-child, peer-to-peer, and mixed routing.
• Checkpoints and cold-resume recovery from the session event log.
• Group chat turns, shared context, lightweight memory, and human-in-the-loop pauses.
• A host-composed Conversation Flow tab with topology, swimlanes, route filters, message inspection, Live follow, and child-session navigation.

UI gallery

The gallery uses a deterministic populated fixture so the screenshots show every important visual state without exposing a real workspace or API credential.

Desktop overview	Message inspector

Responsive layout	Topology and Human input

The screenshots intentionally show a pending Human input card, Error role status, parent-child and peer routes, a selected message, and the host shell around the plugin-owned panel.

Short tour

The tour moves through the desktop overview, selected-message inspector, and 390×844 responsive layout. It is assembled from the same deterministic replay fixture used by the keyless UI checks; no model output or credential is embedded.

Quick start

The plugin runs inside a compatible DeepSeek Harness installation.

Using the desktop app? Its CLI is not on PATH by default, and the reserved desktop profile must not receive third-party plugins (see the changelog). Install into an isolated profile with the app's bundled launcher instead:

# Download the released asset first: adding the URL directly fails pnpm's
# tarball-integrity check (ERR_PNPM_MISSING_TARBALL_INTEGRITY).
curl -sSL -o /tmp/dsh-swarm-panel-1.0.1.tgz \
  https://github.com/stephenlzc/dsh-swarm-panel/releases/download/v1.0.1/dsh-swarm-panel-1.0.1.tgz
DSH="/Applications/DeepSeek Harness.app/Contents/Resources/runtime/cli/bin/dsh"
"$DSH" plugin --profile dswarm add /tmp/dsh-swarm-panel-1.0.1.tgz
"$DSH" --profile dswarm --dump-config | grep -A2 swarm
"$DSH" --profile dswarm

Remove it again with rm -rf ~/.dsh/profiles/dswarm. Everything below assumes a CLI Harness install with dsh on your PATH.

Install Harness first, then install this package into the web profile.

After npm publication

dsh plugin --profile web add dsh-swarm-panel
dsh web

The GitHub repository is the current distribution source until the npm package is published; use the release tarball or the checkout instructions below today.

Create or open a session, ask the Orchestrator to create a swarm, and open the Conversation Flow tab next to Chat and Trajectory.

From a GitHub Release (works today, no npm needed)

Each release publishes the packed plugin as a tarball asset:

curl -sSL -o /tmp/dsh-swarm-panel-1.0.1.tgz \
  https://github.com/stephenlzc/dsh-swarm-panel/releases/download/v1.0.1/dsh-swarm-panel-1.0.1.tgz
dsh plugin --profile web add /tmp/dsh-swarm-panel-1.0.1.tgz
dsh web

Adding a release URL directly (dsh plugin … add https://…tgz) fails pnpm's integrity check; download the asset first, or use the GitHub spec below.

Directly from GitHub

The package currently lives in the dsh-swarm-plugin/ subdirectory of this repository. Install that package directly from GitHub with pnpm's Git subdirectory syntax:

dsh plugin --profile web add 'github:stephenlzc/dsh-swarm-panel#path:dsh-swarm-plugin'
dsh web

For a reproducible install, pin the GitHub reference to a commit:

dsh plugin --profile web add \
  'github:stephenlzc/dsh-swarm-panel#path:dsh-swarm-plugin&<commit-sha>'

GitHub installs use the repository's committed build artifacts and are best suited to development snapshots. For the stable registry release, use the npm command above after publication. Git-hosted dependencies can run install-time code; inspect and trust the source before installing.

From this checkout

git clone https://github.com/stephenlzc/dsh-swarm-panel.git
dsh plugin --profile web add file:./dsh-swarm-panel/dsh-swarm-plugin
dsh web

The source checkout's typecheck and tests require a matching DeepSeek Harness source checkout because the plugin's development dependencies use the Harness workspace packages.

The package manifest is publishable independently: runtime peers use the public Harness release ranges, while the source workspace keeps workspace:* only in development dependencies.

Runnable code-review example

The repository includes a real Harness overlay at dsh-swarm-plugin/examples/coding-squad/cordis.yml. From a DeepSeek Harness checkout with this repository available at ../dsh-swarm-panel:

export DEEPSEEK_API_KEY=... # keep credentials in the environment or DSH credential store
pnpm dsh --profile headless \
  --patch ../dsh-swarm-panel/dsh-swarm-plugin/examples/coding-squad/cordis.yml \
  "review the pending PR"

The example asks one Orchestrator to spawn planner, security, and correctness roles, exchange findings, record a verdict, and checkpoint the swarm. The web profile shows the same durable events in Conversation Flow.

Supported environment

Component	Release target
DeepSeek Harness	0.2.0-rc.2 workspace API and compatible releases
Node.js	22.19+ or Node 24+
Browser	DeepSeek Harness web profile
Package	dsh-swarm-panel@1.0.1

The package targets the Harness 0.2.x release line (0.2.0-rc.2 desktop/web runtime). Keep the plugin and Harness versions aligned when upgrading; the marketplace/Harness desktop 1.0 label currently ships the 0.2.0-rc.2 runtime.

Release 1.0.1 — DeepSeek Harness 0.2.0-rc.2 compatibility plus 16 robustness fixes from the adversarial audit. See the changelog for the full list and the upgrade notes.

Verification status

Harness 0.2.0-rc.2 upgrade checks

This release line has been checked against the published Harness 0.2.0-rc.2 packages — the runtime shipped by the current desktop app:

• TypeScript host and client checks passed (tsc --noEmit and the client project check) with zero errors.
• 93 keyless plugin tests passed (unit, projection, checkpoint/cold-resume fixtures, client rendering, lifecycle-robustness regressions, and a real-AgentLoop group-chat integration run); the two skipped tests are the key-gated real-API cold-resume and the intentionally deferred G4-07 assertion.
• tsdown produced the publishable host and client bundles; both were smoke-loaded against the 0.2.0 runtime — the host bundle exposes the Loader-safe name/inject/apply shape and the client bundle registers both slots and routes child-session navigation through uiWorkspace.openSession.
• The host-composed browser E2E (tests/host/conversation-flow.e2e.ts) passed in the real web shell against a Harness checkout at tag dsh-v0.2.0-rc.2. The test itself needed four compatibility fixes — the moved fixture path, scaffold profile package wiring, the v4 fixture envelope, and the authenticated shell URL — all recorded in the compatibility note.

See docs/harness-0.2-compatibility.md for the complete breakage/repair list, the reinstall guidance, and the remaining upstream risks.

Earlier (0.1.0-rc.7) release evidence

• Host-composed browser E2E passed in the real web shell; manual in-app browser interaction covered details, route and Agent filters, search empty state, Clear filters, Live pause/resume, Human input, child-session navigation, keyboard coexistence, and a 390×844 viewport.
• npm pack --dry-run contains the built runtime, declarations, client bundle, patch, README, license, and canonical screenshot; the final tarball installed through dsh plugin add into temporary compatible tarball, web, and headless profiles.
• The repository includes a redacted, deterministic UI tour GIF and a fresh in-app-browser audit set under docs/screenshots/.

That evidence is version-specific and needs repeating for a 0.2.0 release. npm publication and a tagged GitHub release are still maintainer actions; the current repository is the download source until those are authorized.

Scope and known limitations

• Export is not implemented because the current projection has no export data source.
• A2A / ACP external protocol bridging is not included.
• Nested sub-swarms are intentionally not included; the current model has one Orchestrator level.
• Memory is Orchestrator-owned lexical retrieval; it is not automatically injected into every turn prompt and is not shown as a separate panel.
• The panel copy is currently English-only.
• Source-level development still depends on a matching Harness workspace; the published package is the consumer installation path.
• The bundled example makes a real model call; it is intentionally not run by keyless CI.

See the detailed plugin README, Chinese plugin README, and release checklist for configuration, tool reference, development commands, and the evidence behind this status.

Repository layout

dsh-swarm-panel/
├── dsh-swarm-plugin/       # package source, built artifacts, tests, example, and gallery assets
├── docs/                   # release checklist and design/research history
└── .github/workflows/      # package and source verification gates

License

MIT. See dsh-swarm-plugin/LICENSE.

Call for Issues and Pull Requests

Found a bug, have an idea, or want to improve the plugin? Please open an issue or submit a pull request.

Forks are welcome. Feel free to build your own extensions, UI improvements, integrations, and workflow experiments on top of dsh-swarm-panel.