dsh-legion: Multi-Agent Teams and Model Routing for DeepSeek Harness

English · 简体中文

dsh-legion is a TypeScript multi-agent orchestration plugin for DeepSeek Harness (DSH). It adds configurable AI agent Profiles, exact model routing, declarative Teams and Strategies, structured results, and bounded subagent delegation without replacing the DSH runtime.

Give one DSH agent a small, meaningful delegation interface—such as quick, deep, and review—while the deployment owner controls the model, backend, tools, persona, limits, and output contract behind each choice.

Important: Legion is a DSH plugin, not a standalone agent framework or application. DeepSeek Harness supplies the Agent, Session, model adapters, subagent runtime, sandbox, approvals, and Web GUI.

Contents

• What is dsh-legion used for?
• Capabilities
• How it works
• Install
• Set up a Legion agent preset
• Upgrade
• Uninstall
• Usage
• Configuration
• Doctor and explain
• Status and limitations
• FAQ

What is dsh-legion used for?

Legion is useful when one AI coding agent should delegate different kinds of work under explicit, reusable policy.

• Route work by task type. Send extraction or summaries to a fast model and architecture or debugging to a deeper model.
• Run independent reviews. Give a reviewer read-only tools, a separate persona, and a structured review-v1 result.
• Build multi-agent workflows. Define bounded Teams and declarative plan/execute/review or research fanout Strategies.
• Bound workload and risk. Limit depth, concurrency, participants, deadlines, output size, tools, and eligible routes. These bounds constrain cost drivers, but Legion does not provide aggregate token or monetary-cost admission.
• Standardize delegation. Keep semantic Profile names stable when the underlying model or backend changes.
• Validate policy before runtime. Diagnose configuration against explicit provider capability fixtures.
• Customize without forking. Add, replace, disable, or revive Profiles, Teams, and Strategies through Catalog Layers.

Legion is for developers and deployment owners who already use DSH and want configurable multi-agent delegation without adopting another scheduler, session store, or agent runtime.

Capabilities

Capability	What it provides
Semantic Profiles	Named policies such as quick, deep, and review instead of raw model choices in every prompt.
Exact model routing	Up to eight ordered provider/model candidates with static context and output-budget constraints.
Multiple backends	Use spawn, fork, codex, claude-code, or another DSH-registered subagent provider per Profile.
Tool and persona policy	Restrict child tools, add Profile instructions, set depth, and choose foreground/background defaults.
Structured results	Versioned text, findings-v1, and review-v1 foreground result contracts.
Custom Teams	Declare bounded Member Slots that reference existing Profiles.
Declarative Strategies	Compile typed artifact graphs to frozen DSH delegation primitives.
Hard limits	Bound agents, concurrency, deadline, and accepted output size for each Team Run.
Catalog customization	Layer, replace, disable, and restore user or third-party catalog entries.
Prompt Fragments	Load confined, immutable UTF-8 prompt resources from deployment-owned roots.
Explainable policy	Stable digests, deterministic diagnostics, route evidence, and JSON explain output.
Live reconfiguration	Optional: when the Host mounts a settings provider, edit the same config through the legion namespace and republish without a restart.
Native DSH lifecycle	Continuations, cancellation, settlement, providers, and HMR-safe registration remain DSH-owned.

How it works

Catalog Layers
  ├─ Profiles   -> model routes, backend, persona, tools, result contract
  ├─ Teams      -> bounded Member Slots referencing Profiles
  └─ Strategies -> typed artifact graph + hard limits
                         │
                         ▼
                frozen DSH primitive IR
                         │
                         ▼
                 native DSH subagents

A typical model-facing Profile call is small:

{
  "profile": "quick",
  "description": "summarize findings",
  "prompt": "Summarize the investigation and preserve source paths.",
  "run_in_background": true
}

The coordinator chooses a semantic Profile; the prompt cannot change that Profile's deployment-owned model, tools, persona, depth, or result policy.

Legion intentionally does not own the agent loop, sessions, persistence, model adapters, credentials, sandbox, approvals, subagent registry, or Web GUI. It uses DSH's public ctx.subagents, ctx.tools, and ctx.systemPrompt seams so there is only one runtime and lifecycle owner.

Install

Prerequisites

• A compatible DeepSeek Harness installation.
• pnpm on PATH; dsh plugin forwards package operations to pnpm.
• A DSH host profile, such as the default web profile.
• A configured DSH subagent provider and the LLM provider/model routes referenced by your Profiles.
• For local development: Node.js ^22.19.0 || >=24.0.0 and pnpm 11.21.0.

Install from GitHub

Install an immutable commit SHA into the web profile:

dsh plugin --profile web add github:wxxb789/dsh-legion#<commit-sha>

Replace web if Legion should be available in another DSH host profile. No release tag is published yet, so use a commit SHA rather than a moving branch. After a version appears on GitHub Releases, that release's tag is also an immutable installation spec.

Git dependencies run Legion's prepare build. pnpm 10+ may reject the first install until the package is explicitly allowed. Add the exact key printed by pnpm to $DSH_HOME/profiles/web/pnpm-workspace.yaml, then repeat the install:

allowBuilds:
  dsh-legion: true

If pnpm prints a source-qualified key, use that exact key instead of the short name.

Install from a local checkout

git clone https://github.com/wxxb789/dsh-legion.git
cd dsh-legion
pnpm install --frozen-lockfile
pnpm run build
dsh plugin --profile web add .

A local checkout needs built lib/ artifacts. The bundle patch is intentionally empty: installation makes dsh-legion resolvable from user-owned agent presets but does not inject a process-global model tool.

Set up a Legion agent preset

Installing the package is only the first step. Legion must also be loaded by an agent preset.

Recommended: extend your existing preset

1. Open the DSH Web GUI.
2. Copy the shipped standard preset to a user-owned preset named legion.
3. Append the Legion row from the example fragment.
4. Adjust provider names, model IDs, tools, and limits for your deployment.
5. Start a new session with the legion preset.

Do not edit DSH's shipped standard preset directly.

Alternative: copy the bundled preset

Copy presets/legion to $DSH_HOME/.agent-presets/legion. It contains a focused coding tool set and example deep, quick, and review Profiles.

A copied preset is a versioned template. It does not automatically inherit later DSH or Legion changes. Existing nonblank sessions also cannot change their recorded preset, so start a new session after changing composition.

Upgrade

GitHub installation

Re-add the package with the new exact commit SHA. After releases exist, a newer published release tag may be used instead:

dsh plugin --profile web add github:wxxb789/dsh-legion#<new-commit-sha>

For a registry or moving-ref installation, DSH also forwards pnpm's update command:

dsh plugin --profile web update dsh-legion

After upgrading:

1. Review CHANGELOG.md.
2. Compare your user-owned preset with the current example; Legion never overwrites presets automatically.
3. Restart the affected DSH process. If the preset composition changed, start a new session.

Local checkout

cd dsh-legion
git pull --ff-only
pnpm install --frozen-lockfile
pnpm run build
dsh plugin --profile web add .

Uninstall

Remove Legion from every DSH host profile where it was installed:

1. Remove or disable the name: dsh-legion row in user-owned agent presets.

2. Remove the package:

   dsh plugin --profile web remove dsh-legion
   

3. Optionally delete $DSH_HOME/.agent-presets/legion if that copied preset is no longer needed.

4. Restart the affected DSH process.

Package removal does not delete user-owned presets or configuration.

Usage

Delegate through a Profile

The coordinator sees one legion tool plus active Profile descriptions:

{
  "profile": "review",
  "description": "review the authentication change",
  "prompt": "Inspect the diff for correctness and security issues. Cite files and lines.",
  "run_in_background": false
}

If defaultProfile is configured, profile may be omitted. Concurrent sibling calls use DSH's normal parallel tool execution.

Run a Strategy

Strategies are hidden by default. A deployment must explicitly set enableStrategies: true. The same tool then accepts a strict Strategy request:

{
  "kind": "strategy",
  "strategy": "independent-review",
  "objective": "Review the implementation and return evidence-backed findings.",
  "limits": { "deadlineMs": 60000 }
}

Profile and Strategy fields cannot be mixed. Invocation limits may only narrow compiled Strategy limits.

Configuration

A minimal agent-preset row:

- id: tool-legion
  name: dsh-legion
  config:
    configVersion: 2
    toolName: legion
    defaultProfile: quick
    profiles:
      quick:
        description: Fast exploration, extraction, and summaries.
        subagentProvider: spawn
        agentOptions:
          provider: your-llm-provider
          model: your-fast-model
          maxTokens: 8192
        maxDepth: 2
        defaultRunInBackground: true

      review:
        description: Independent correctness and security review.
        subagentProvider: spawn
        agentOptions:
          provider: your-llm-provider
          model: your-review-model
        toolFilter:
          deny: [write, edit]
        maxDepth: 2
        defaultRunInBackground: false
        result: review-v1

Use valid provider and model IDs for your deployment. See the complete preset fragment and standalone configuration example.

When the Host mounts a settings provider (DSH 0.1.0-rc.7 serves every registered namespace), Legion also registers this same schema as the legion settings namespace: the preset row above becomes the base layer, a stored user section overrides individual fields, and a commit republishes the tool without restarting DSH. Nothing changes in a composition without a settings provider. See live reconfiguration.

Top-level fields

Field	Default	Meaning
configVersion	2	Current configuration contract; legacy v1 input migrates to v2.
toolName	legion	Model-facing tool name.
profiles	required	Semantic Profile map.
defaultProfile	none	Profile used when a call omits profile.
enableRunInBackground	true	Expose background delegation.
enableStrategies	false	Explicitly expose active Strategies to the model.
guidance	none	Extra coordinator guidance.
resourceRoots	{}	Relative deployment roots for Prompt Fragments.
maxResourceBytes	65536	Prompt Fragment bytes per Profile; hard ceiling 4 MiB.
catalogLayers	[]	Ordered third-party or project policy layers.
teams	{}	Final deployment-layer Teams.
strategies	{}	Final deployment-layer Strategies.

Profile names must match ^[a-z][a-z0-9-]*$.

Profile fields

Field	Default	Meaning
description	required	Task-fit guidance shown to the coordinator.
subagentProvider	spawn	DSH subagent backend, not an LLM provider.
agentOptions	inherited	Fixed provider, model, and maxTokens; cannot be combined with routes.
routes	none	Up to eight ordered exact Route Candidates.
persona	inherited	Child persona/system-policy override.
toolFilter.allow / deny	none	Child tool visibility restriction.
maxDepth	3	Child depth or provider-managed for external one-shot products.
defaultRunInBackground	true	Default to a continuable child.
result	text	text, findings-v1, or review-v1.
promptFiles	none	Ordered Prompt Fragments loaded after validation.

For codex and claude-code, model selection belongs to the external product. Normally use maxDepth: provider-managed and defaultRunInBackground: false.

Exact Route Candidates

routes:
  - id: primary
    provider: your-llm-provider
    model: your-deep-model
    maxTokens: 16384
    constraints:
      minContextTokens: 65536
      minEffectiveOutputTokens: 8192
  - id: fast-static
    provider: your-llm-provider
    model: your-fast-model
    constraints:
      minContextTokens: 32768

Immediately before child start, Legion observes registered DSH adapters and exact-model metadata. It selects the first candidate without a known static contradiction. Missing metadata remains unknown and admissible; Legion never turns absent metadata into a health claim.

Legion starts at most one child and never retries another route after provider, authentication, quota, network, or child failure.

Catalog Layers, Teams, and Strategies

Config v2 layers Profiles, Teams, and Strategies. A later definition replaces the same name; a tombstone disables it; a later definition may revive it. Root maps are the final deployment layer.

configVersion: 2
teams:
  coding:
    description: One executor and one reviewer.
    members:
      executor: { profile: deep }
      reviewer: { profile: review }
strategies:
  reviewed:
    description: Execute and review.
    team: coding
    stages:
      - kind: delegate
        id: execute
        member: executor
        inputs: [{ artifact: objective, contract: objective-v1 }]
        output: { artifact: execution, contract: text }
        prompt: Execute and return evidence.
      - kind: delegate
        id: review
        member: reviewer
        inputs: [{ artifact: execution, contract: text }]
        output: { artifact: review, contract: review-v1 }
        prompt: Review the evidence independently.
    completion: { artifact: review, contract: review-v1 }
    limits:
      maxAgents: 2
      maxConcurrent: 1
      deadlineMs: 900000
      maxOutputBytes: 524288
    memberFailure: fail

Legion validates the artifact graph and lowers accepted stages to detached, deep-frozen DSH primitive IR. It is an adapter over DSH one-shot subagents, not a persistent scheduler. The Default Catalog includes independent-review, research-panel, and plan-execute-review as ordinary replaceable data, with model exposure off by default.

See benchmarks/README.md for deterministic protocol gates and separate real-model evidence requirements.

Prompt Fragments, structured results, and trust

Prompt Fragments are explicit deployment resources, not arbitrary workspace reads. Legion confines relative paths below configured roots and rejects links, malformed UTF-8, NUL bytes, missing files, and byte-budget violations. Edits require plugin or preset reactivation.

Structured foreground contracts are deliberately narrow:

• findings-v1: summary, evidence-backed findings, decisions, verification, and open risks;
• review-v1: verdict, severity findings, recommendations, and verification;
• background continuations remain text/session oriented.

Presets, Catalog Layers, plugin packages, resource roots, and Prompt Fragments are trusted deployment configuration. Tool filters and path confinement enforce policy and integrity for that trusted deployment; they are not a sandbox for hostile presets or untrusted plugins. See SECURITY.md.

Doctor and explain

Validate a standalone Legion config against an explicit provider fixture:

dsh-legion doctor examples/legion.config.yml --providers examples/providers.fixture.yml
dsh-legion explain examples/legion.config.yml --providers examples/providers.fixture.yml --json

doctor prints a compact summary; explain adds Profiles, execution modes, model routes, result contracts, and diagnostic codes. --json emits the versioned legion-explain view.

The fixture proves only supplied static facts. The CLI does not inspect a live DSH process, credentials, reachability, health, quota, billing, latency, or actual model availability.

Exit codes: 0 for no error diagnostic, 1 for capability errors, and 2 for usage, I/O, resource, parse, or schema failures.

Status and limitations

The source tree declares version 1.1.0 and config contract v2. Check CHANGELOG.md, the roadmap, and GitHub Releases before selecting or upgrading an install revision.

Known limitations:

• Curated Strategies are not automatically model-exposed; deployment owners may opt in with enableStrategies: true.
• Legion does not retry or switch models after a selected child fails.
• In-process children inherit the parent's named DSH agent preset; Profiles can still vary model, persona, tools, backend, and limits.
• There is no Legion GUI settings card; configure it in a user-owned agent preset.
• A bare package without compatible DSH peers is unsupported.

FAQ

Is dsh-legion a standalone multi-agent framework?

No. It is a DeepSeek Harness plugin for multi-agent policy and delegation. DSH remains the runtime and lifecycle owner.

Does Legion automatically choose the cheapest or healthiest model?

No. It checks ordered routes against known static facts. It does not claim live health, price, authentication, quota, or latency, and does not replay after failure.

Can I create custom Profiles, Teams, and Strategies?

Yes. The Default Catalog uses the same public, replaceable contracts as user and third-party entries.

Why does the Legion tool disappear?

Only Profiles whose subagent provider is registered are published. If none are active, the tool and guidance disappear and return with the provider. Also verify that Legion is installed into the host profile and that a new session uses the preset containing its row.

Can I edit DSH's shipped standard preset?

Do not. Copy it to a user-owned preset so upgrades cannot overwrite your changes.

Compatibility, development, and releases

The package requires Node.js ^22.19.0 || >=24.0.0 and DSH peers in >=0.1.0-rc.6 <0.2.0. CI covers Windows, Ubuntu, packed DSH consumers, public contracts, protocol benchmarks, and reproducible packages.

pnpm install --frozen-lockfile
pnpm run check

Useful references:

• Implementation roadmap
• Public contract v1
• Durable Strategy Runs
• Journal contract v1
• Run replay
• Versioned configuration and rollback
• Declarative Team and Strategy IR
• Explicit Strategy exposure authority
• Reproducible releases
• All architecture decisions

Issues and contributions are welcome through the GitHub issue tracker.

License

MIT

Durable Strategy Runs (v1.1, opt-in)

Durable runs are disabled by default and preserve v1.0 ephemeral behavior. When enabled by deployment, a Strategy caller explicitly selects journal mode with execution: { durability: 'journal' }; omission remains ephemeral. They use eight typed events in the invoking DSH Session journal and projection key legion-run at state version 6. Run control supports bounded read-only inspect, one-activation resume, flushed cancel, and validated proposal-only steer. Task delivery is at least once; matching fence and generation permit exactly one accepted commit, not exactly-once external effects. Mail is reserved, incorporated, durably flushed when required, then acknowledged; expired reservations are reclaimable.

This package does not ship DSH persistence, projection, atomic coordination, global admission, or child-receipt Host services. Published DSH 0.1.0-rc.6 lacks the projection and coordination services required for production durable mutation. Enabling durable runs there produces stable capability diagnostics and fails closed before mutation; pure contracts, validation, replay, and inspection remain usable. See Durable Strategy Runs and Journal Contract v1.