dsh-legion

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.