dsh-meta-orchestrator

A DeepSeek Harness plugin that teaches the agent to synthesize a task-specific workflow at runtime — instead of hard-coding pipelines or fixed agent topologies. For anyone running multi-step work in DSH who wants the plan the agent follows to be explicit, versioned, and durable rather than implicit.

🧭 How it works

Normally an agent just starts working on your request. With this plugin, it plans first, then works the plan — and the workflow is dynamic: written by the model itself, per request:

1. Analyze — the agent reads the request; if it is genuinely ambiguous, it asks before doing anything.
2. Pick a pattern — it chooses one of five proven ways to organize the work: ⛓️ steps in order (prompt-chaining), ⚡ fan out independent parts (parallel-workers), 🔀 classify, then dispatch (router), 🎯 delegate and review (supervisor), 🔁 draft → score → improve (evaluation-loop). Each pattern's detailed playbook is loaded only when picked.
3. Write the plan down — it calls orchestrate with the stages, the roles it will delegate, and verifiable success criteria. The plugin validates the structure and saves it durably. That is all the plugin ever does: it records plans, it never executes them.
4. Do the work with DSH's own tools — subagents, todos, workflow scripts, plan mode. The plugin adds no runtime of its own.
5. Adapt or close — if reality diverges, adapt_workflow revises the plan (every revision is versioned); when the work is done, complete_workflow records how each success criterion turned out.

Simple requests skip all of this — the agent is explicitly told not to orchestrate for orchestration's sake.

flowchart LR
    A["1 · Analyze"] --> P["2 · Pick a pattern"] --> W["3 · Write the plan<br/><sub>orchestrate</sub>"] --> E["4 · Do the work<br/><sub>DSH primitives</sub>"] --> M["watch progress"]
    M -- "reality diverged" --> AD["revise the plan<br/><sub>adapt_workflow</sub>"] --> E
    M -- "work finished" --> D["5 · close it out<br/><sub>complete_workflow</sub>"]

All of this behavior comes from one short instruction block the plugin adds to the agent's system prompt — no extra model calls, no background processes.

What gets installed

🧩 Why it's built this way

• The model is the planner — no hard-coded pipeline and no fixed agent topology decides how your task runs; the model picks and composes per request, and may deviate when the task demands it.
• Recording, not executing — the plugin holds no runtime, no scheduler, no message bus. Execution stays on the harness's battle-tested primitives, so there is nothing extra to break.
• Plans survive restarts — every plan lives in DSH's storage domain as an append-only create → adapt* → complete chain, fenced per session lifecycle. No custom session event types, so orchestrated sessions always resume cleanly.
• Built to track a fast-moving harness — only stable public plugin surfaces are used; nothing is pinned to harness internals.

flowchart TB
    subgraph P["🧭 dsh-meta-orchestrator"]
        direction LR
        PS["policy section"]
        SK["5 pattern skills"]
        TL["orchestrate · adapt_workflow · complete_workflow"]
    end
    subgraph H["🐋 DeepSeek Harness"]
        direction LR
        SYS["system prompt"]
        CAT["skill catalog"]
        REG["tool registry"]
        DOM[("storage domain")]
    end
    PS --> SYS
    SK --> CAT
    TL --> REG
    TL --> DOM
    H --> EX["subagent · workflow · todo · goals · plan mode"]

✅ Compatibility

Only public plugin surfaces are used — systemPrompt, skills, tools, storageDomain, agent/pre-step — so ordinary harness churn rarely bites. But the harness is pre-1.0, and a semver caret does not span prerelease lines: ^0.1.0-rc.5 matches 0.1.0-rc.6, not a future 0.1.1-rc.1. When a new rc line lands, the peer range here needs a bump — open an issue if you get there first.

📦 Install

Requires a profile with the storage stack — the standard web profile (dsh-web-app bundle) ships it (see Compatibility).

dsh plugin --profile web add dsh-meta-orchestrator                           # from npm
dsh plugin --profile web add github:jiruidai/dsh-meta-orchestrator#v0.2.0    # from git, pinned

dsh plugin forwards to pnpm inside the profile directory, so every pnpm verb works. Restart dsh after an add or remove — the bundle layer list is read at boot; only the cordis.patch.yml layers hot-reload.

A git install builds via the package's prepare script, so pnpm asks you to allowlist it once in the profile's pnpm-workspace.yaml (allowBuilds: { dsh-meta-orchestrator: true }).

Upgrade

dsh plugin --profile web update dsh-meta-orchestrator                        # within the installed range
dsh plugin --profile web add dsh-meta-orchestrator@latest                    # across ranges
dsh plugin --profile web add github:jiruidai/dsh-meta-orchestrator#v0.3.0    # git installs: re-add the new ref

Disable without removing

The profile's own patch layer applies after every bundle layer and hot-reloads — this takes effect on the next request, no restart, no reinstall. In $DSH_HOME/profiles/web/cordis.patch.yml ($DSH_HOME defaults to ~/.dsh):

- id: meta-orchestrator
  disabled: true

Delete those two lines to switch it back on. Recorded workflows are untouched either way.

Uninstall

dsh plugin --profile web remove dsh-meta-orchestrator   # drops the dependency and the bundle layer

Restart dsh. For a complete removal, the leftovers the CLI does not touch:

- insert:
    - id: meta-orchestrator
      name: file:///<path-to-checkout>/lib/index.js
      config:
        autoTrigger: false

🚀 Quick start

No configuration needed — the defaults are the intended setup. Install into the web profile, restart dsh, and hand the agent something genuinely multi-part:

Audit this repo's error handling, then write a short report with concrete fixes ranked by risk.

What you should see, in order:

1. The agent names its pattern in a sentence — "this is a chain: audit → rank → write."

2. A skill call loading that pattern's playbook.

3. An orchestrate call whose result reads back:

   workflow "wf-3f2a91c4" recorded (v1)
   pattern: prompt-chaining
   stages: 4
   success criteria: 3
   Execute it with the harness's native primitives and report the final result against the success criteria.

4. Then ordinary DSH work — todos, subagents, tools. The plugin runs none of it: it recorded the plan and got out of the way.

5. At the end, a complete_workflow call — workflow "wf-3f2a91c4" completed (achieved, v1).

Proof it was persisted, not just narrated (the file appears with the first recorded workflow):

cat $DSH_HOME/storages/meta_orchestrator.json   # $DSH_HOME defaults to ~/.dsh

One entry per session id, holding the append-only create → adapt* → complete chain with a full spec snapshot at every step.

Ask something simple instead — "what's in this folder?" — and the agent skips orchestrate entirely. That is the protocol working, not failing.

⚙️ Configuration

One key, no environment variables, nothing sensitive:

🔐 Permissions & data

Worth knowing what lands in that file: every mutation stores a full spec snapshot — the model's written analysis of your request, stage names and details, the briefs it would hand to subagents, success criteria, and the completion report. That is a paraphrase of your task, in plaintext, per session, on your machine. It never leaves the machine, and deleting the file is the entire erase story.

Scope note: this is a host-plane plugin. The ~330-word policy section and the three tools register globally, so every session in the profile carries them — that is the design (see What gets installed), not a leak. With autoTrigger: true, one reminder message is appended to the first request of each session, once.

🩺 Troubleshooting

Boot fails: meta-orchestrator: pending (waiting for services: storageDomain) The profile has no storage stack. Only the dsh-web-app bundle ships storage / storage-json / storage-domain; the stock headless profile does not. Install into the web profile — or insert those three rows into your profile's patch layer above this plugin.

No orchestrate tool — the plugin seems absent Check whether the row actually composed: dsh --profile web --dump-config and look for the dsh-meta-orchestrator layer. Missing → the package isn't installed (re-run dsh plugin … add, then restart dsh). Present but disabled: true → a patch layer turned it off.

First add from git fails on a blocked build script pnpm ≥ 10 refuses a git dependency's prepare script until allowlisted. Copy the exact key pnpm prints into $DSH_HOME/profiles/web/pnpm-workspace.yaml under allowBuilds: and re-run. That allowance means running package code at install time — pin a tag or sha.

The model answers without orchestrating Intended for simple requests. If you want a nudge at the start of every session, set autoTrigger: true.

orchestrate rejected the spec: … A structurally invalid spec (no stages, no success criteria, unknown pattern). The error lists every problem and the model normally fixes it on the next call. Nothing is persisted from a rejected call.

… could not record the spec (storage write failed) The backend rejected the write — check that $DSH_HOME/storages/ is writable. A failed write leaves the recorded chain exactly as it was; it never half-records.

Where to look

Rollback, fastest first: disabled: true in the profile patch layer (live on the next request), or dsh plugin --profile web remove dsh-meta-orchestrator plus a restart. Neither deletes recorded workflows.

🛠️ Development

pnpm install      # normal checkout: installs the published @deepseek-ai/* packages
pnpm build        # clean + tsc → lib/
pnpm typecheck    # src + tests
pnpm test         # vitest — 46 unit + mount-integration tests

Issues and PRs are welcome — pnpm typecheck && pnpm test must be green. CI runs install → build → typecheck → test on Node 22 and 24, --frozen-lockfile against the committed pnpm-lock.yaml (generated against registry.npmjs.org).

The maintainer's local checkout instead resolves @deepseek-ai/* from a sibling harness checkout through a hand-built junction tree (see the comments in pnpm-workspace.yaml) — in that setup pnpm install is never run.

🚧 Limitations

• Prompt discipline is the primary enforcement — a model may skip orchestrate entirely.
• Specs are per session lifecycle by design; a reused session id never inherits a stale workflow.
• No client UI yet — workflow state is visible in conversation, tool results, and the storage domain.

📄 License & security

MIT.

Reporting a vulnerability — please don't open a public issue. Use GitHub's private vulnerability reporting for this repo; see SECURITY.md. Surface-wise there is little to hold: the plugin executes nothing, opens no sockets, and reads no credentials — the realistic concerns are the policy text it injects and the task paraphrases it stores locally (see Permissions & data).