dsh-maestro-runtime

English | 中文

Repository: https://github.com/zhao-wuyan/dsh-maestro-runtime

Related projects:

• Maestro Flow (GitHub)
• Maestro Flow 中文文档

DSH (DeepSeek Harness) host plugin that adapts the Maestro-Flow runtime surface to DSH sessions.

P0 + P1 coverage: guard, workflow context injection, new-workspace onboarding, background KG sync, delegate notifications, team heartbeat, and coordinator bridge.

Features

• guard
  • blocks dangerous bash / pwsh commands (recursive delete, hard git reset, forced push, disk format, ...)
  • blocks direct model writes to protected Maestro state (.workflow/state.json, .workflow/config.json, .workflow/sessions/**, .workflow/runs/**, .workflow/.maestro/**)
  • enforces .workflow/config.json PathGuard boundaries
  • validates .workflow/specs/*.md <spec-entry> format
• context
  • injects a deduplicated <maestro-context> snapshot on user prompts and /maestro* skill invocations
  • includes workflow state, active session, project title, specs index, knowhow index, delegate notifications
• onboarding
  • when a /maestro* skill is invoked in a project without a valid Maestro workspace, injects one-time /maestro-init / /maestro "<intent>" guidance
  • stays silent for ordinary non-Maestro prompts
• kg
  • background maestro kg init when maestro.db is missing (5 min cooldown)
  • background maestro kg sync --incremental when it exists (30 s cooldown)
  • direct node maestro.js spawn, no cmd shell, no console window
• delegate
  • scans host tmpdir and first-level dsh-* session temp dirs for maestro-notify-*.jsonl
  • injects unread completion notifications and marks them read
• team
  • appends a 60 s deduplicated heartbeat to .workflow/collab/activity.jsonl when the local git identity matches a joined member
• coordinator
  • writes maestro-coord-<dsh_session>.json bridge files on step/end and turn/end

Requirements

• DSH 0.1.0-rc.6 profile (dsh web works)
• Node.js >= 20
• pnpm >= 10
• maestro-flow CLI installed and available as maestro (used by KG background sync)

Install

DSH plugins are installed into a profile with pnpm and mounted with a cordis.patch.yml entry. This plugin can be installed directly from GitHub.

Method 1: install directly from GitHub (recommended)

This package declares dsh.bundle, so dsh plugin add installs the dependency and activates its bundle layer automatically:

dsh plugin --profile web add "github:zhao-wuyan/dsh-maestro-runtime#v0.1.2"

Equivalent manual pnpm command:

cd ~/.dsh/profiles/web
pnpm add "github:zhao-wuyan/dsh-maestro-runtime#v0.1.2"

No manual cordis.patch.yml edit is required. Restart DSH and verify the bundle layer is active:

dsh --profile web --dump-config | grep maestro-runtime

To override a default, add this entry to ~/.dsh/profiles/web/cordis.patch.yml (user layer wins):

- id: maestro-runtime
  name: 'dsh-maestro-runtime'
  config:
    guardEnabled: true
    contextEnabled: true
    maxContextChars: 8000
    kgEnabled: true
    delegateMonitorEnabled: true
    teamMonitorEnabled: true
    coordinatorEnabled: true

Pin a tag or commit

Replace the fragment in the GitHub shorthand to pin the exact source:

# stable tag
pnpm add "github:zhao-wuyan/dsh-maestro-runtime#v0.1.2"

# exact commit
pnpm add "github:zhao-wuyan/dsh-maestro-runtime#<commit-sha>"

Method 2: clone and link locally (development)

git clone https://github.com/zhao-wuyan/dsh-maestro-runtime.git
cd ~/.dsh/profiles/web
dsh plugin --profile web add "<absolute-path-to>/dsh-maestro-runtime"

Because the checkout also declares dsh.bundle, the profile bundles list is updated automatically. Restart DSH afterwards.

On Windows use a forward-slash absolute path, for example pnpm add "link:C:/Users/<you>/projects/dsh-maestro-runtime".

Method 3: npm registry

If the package is available in your configured npm registry:

dsh plugin --profile web add "dsh-maestro-runtime@0.1.2"

Then add the same mount entry and restart DSH.

Configuration

DSH plugin publishing conventions followed

• package name uses the dsh-* convention
• type: module, main and exports point to the built entry
• plugin entry exports name and apply (Cordis plugin contract)
• inject: ['tools'] declares the required service
• shared DSH modules consumed at runtime (dsh-agent, dsh-llm, dsh-tools) are peer dependencies, not bundled dependencies, so the host installation keeps a single version
• @deepseek-ai/cordis@^4.0.1 and DSH host peers are aligned with 0.1.0-rc.6
• mount happens through profile cordis.patch.yml; no DSH source modification
• exports a Schemastery Config schema so invalid config fails loudly at load
• declares dsh.bundle so dsh plugin add activates the layer automatically

Development

Edit lib/index.js while DSH is running. The profile HMR plugin (root: ['.']) reloads the plugin entry after the change settles.

After changing package.json dependencies or cordis.patch.yml, restart DSH.

License

MIT