dsh-maestro-runtime

Readme

# dsh-maestro-runtime

[English](README.md) | [中文](README.zh.md)

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

**Related projects**:
- [Maestro Flow (GitHub)](https://github.com/catlog22/maestro-flow)
- [Maestro Flow 中文文档](https://catlog22.github.io/maestro-flow)

[DSH (DeepSeek Harness)](https://github.com/deepseek-ai/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:

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

Equivalent manual pnpm command:

```sh
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:

```sh
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):

```yaml
- 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:

```sh
# 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)

```sh
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:

```sh
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