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

Field	Default	Description
guardEnabled	true	Enable tool guard
contextEnabled	true	Enable workflow context injection
maxContextChars	8000	Context injection byte budget
kgEnabled	true	Background maestro kg init / sync
delegateMonitorEnabled	true	Delegate notification injection
teamMonitorEnabled	true	Team heartbeat writes
coordinatorEnabled	true	Coordinator bridge writes

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