Introduction

DSH uses a plugin-based architecture. When an agent needs to interact deeply with the Maestro-Flow runtime, the Maestro-Flow runtime surface needs to be adapted into a DSH session. dsh-maestro-runtime is designed to solve this adaptation problem by providing safety guard, context injection, background KG synchronization, and other features, covering P0 + P1 scenarios.

Plugin Overview

This is a DSH host plugin maintained by zhao-wuyan. It adapts the Maestro-Flow runtime surface into DSH sessions. The plugin is mounted via cordis.patch.yml and runs without modifying DSH source code.

Core Features

Guard

  • Blocks dangerous bash / pwsh commands (such as recursive deletion, hard git reset, forced push, disk formatting, etc.).
  • Prevents direct model writes to protected Maestro state files (.workflow/state.json, .workflow/config.json, .workflow/sessions/**, .workflow/runs/**, .workflow/.maestro/**).
  • Enforces the PathGuard boundaries defined in .workflow/config.json.
  • Validates the <spec-entry> format in .workflow/specs/*.md.

Context

  • Injects a deduplicated <maestro-context> snapshot during user prompts and /maestro* skill invocations.
  • The snapshot includes workflow state, active sessions, project title, specs index, knowhow index, and delegate notifications.

Onboarding

  • When a /maestro* skill is invoked in a project without a valid configured Maestro workspace, it injects one-time guidance for /maestro-init / /maestro "<intent>".
  • Remains silent for normal non-Maestro prompts.

KG

  • Runs maestro kg init in the background when maestro.db is missing (5-minute cooldown).
  • Runs maestro kg sync --incremental in the background when maestro.db exists (30-second cooldown).
  • Launches directly via node maestro.js, without using a cmd shell and without displaying a console window.

Delegate

  • Scans maestro-notify-*.jsonl files in the host tmpdir and first-level dsh-* session temp directories.
  • Injects unread completion notifications and marks them as read.

Team

  • When the local git identity matches a joined member, appends deduplicated heartbeats (60-second interval) to .workflow/collab/activity.jsonl.

Coordinator

  • Writes the maestro-coord-<dsh_session>.json bridge file on step/end and turn/end events.

Installation and Enablement

Environment Requirements

  • DSH 0.1.0-rc.6 profile (dsh web available).
  • Node.js >= 20.
  • pnpm >= 10.
  • maestro-flow CLI installed and callable from the command line.

Installation Steps

DSH plugins are installed via pnpm and mounted using cordis.patch.yml. You can use the officially recommended direct installation command:

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

After installation, DSH automatically activates its bundle layer. Restart DSH and verify:

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

Configuration

The default configuration usually meets requirements, but it can be overridden by modifying ~/.dsh/profiles/web/cordis.patch.yml. The following configurable items and their default values are shown:

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

Typical Usage

  • Safety guard: When a user attempts to run rm -rf / or git reset --hard HEAD~10, Guard intercepts and blocks execution.
  • Context enhancement: When a user sends a normal prompt, the plugin automatically injects the current <maestro-context> snapshot, enabling the agent to access workflow state and project information.
  • Automatic initialization: The first time the /maestro command is used in a project directory, the plugin guides the user to initialize the workspace.
  • Background synchronization: Without manual intervention, KG data is automatically initialized or incrementally synchronized in the background based on file presence.
  • Collaboration synchronization: After team members commit code locally, heartbeat data is automatically written to the collaboration log.

Applicable Scenarios and Notes

Applicable Scenarios

  • Developers using Maestro-Flow for workflow orchestration.
  • Scenarios requiring deep integration of Maestro context and state into DSH sessions.
  • Scenarios requiring automated KG synchronization and team collaboration logging.

Notes

  • Permissions and processes: The plugin runs with the permissions of the current DSH process. Ensure that installed dependency versions are compatible.
  • Dependency check: Before installation, verify that the local environment meets Node.js >= 20, pnpm >= 10, and the availability of the maestro-flow CLI.
  • Source code review: Although it is under the MIT license, it is recommended to review the source code implementation before introducing it into production.

Ecosystem Background

The DSH philosophy is “everything is a plugin.” The community catalog is an independent site and has no official subordination relationship with DeepSeek / Huanfang. This plugin achieves seamless integration with the main framework by following DSH plugin publishing conventions (such as dsh-* naming, dsh.bundle declaration, and cordis.patch.yml mounting).