dsh-plugin-product-subagents

English | 简体中文

Role-based Codex / Claude Code / ACP subagent providers for the DeepSeek Harness. Turns external agent CLIs into durable, continuable subagents with a declarative role library, per-role product permissions, delegation with a permission ceiling, and cross-platform process launching.

Features

• Continuable children — one-shot sync or async continuable (control with send_message, list_agents, interrupt_agent; attach synchronously with product_wait).
• Session continuity — a child's remote product session survives idle disposal and process restarts (durable registry + log markers; claude/codex resume by id, ACP reconnects).
• Declarative roles (roles/*.json) — general (default), code-review, explore (never delegates), debug. Delegation defaults ON; a role can ban it. Unknown roles fall back to general.
• Two-layer permission model — the relay model is always a read-only pipe; permissionMode (readonly / default / full) applies to the remote product and is mapped to each product's own CLI flags.
• Permission ceiling — a child can never spawn a descendant with more permission than it has.
• Any ACP agent — add Cursor (agent acp), CodeBuddy (cbc --acp), Gemini (gemini --acp) and more via config.providers; no code needed.
• Resource management — idle disposal, configurable timeouts, concurrency cap.
• Cross-platform — Windows .cmd shims, Windows-safe path escaping; CI runs macOS / Ubuntu / Windows.

Requirements

• A DeepSeek Harness deployment (web profile).
• At least one product CLI on PATH and authenticated: claude, codex, or an ACP CLI (opencode, agent, cbc, …).
• Node ≥ 18.

Install

Recommended — dsh plugin add

dsh plugin --profile web add dsh-plugin-product-subagents

That single command installs the package and wires the host-plane row automatically: the plugin ships a cordis.patch.yml declared via dsh.bundle in its package.json, so dsh plugin add registers it as a profile layer (no manual cordis.patch.yml editing needed). Restart the harness afterwards so the plugin loads.

To customise the plugin (e.g. add ACP providers), target the product-subagents id in your profile's own cordis.patch.yml (~/.dsh/profiles/web/cordis.patch.yml):

- id: product-subagents
  config:
    idleTimeoutMs: 600000
    providers:
      cursor:    { type: acp, command: agent, args: [acp] }
      codebuddy: { type: acp, command: cbc, args: [--acp] }

Note: a config override replaces the row's whole config object, so restate any keys you wish to keep (like idleTimeoutMs above).

Install via your agent (one line)

Paste this to your DeepSeek Harness agent (or any coding agent with shell access to the harness home) — it performs every step itself:

Install the dsh-plugin-product-subagents plugin into my DeepSeek Harness web profile: run dsh plugin --profile web add dsh-plugin-product-subagents, then tell me to restart the harness so the plugin loads.

Manual (advanced)

If you prefer to manage the profile yourself, use pnpm (not npm) inside the profile directory so peer dependencies are not auto-installed:

cd ~/.dsh/profiles/web
pnpm add dsh-plugin-product-subagents

Then add a host-plane row to your profile's cordis.patch.yml:

- insert:
    - id: product-subagents
      name: 'dsh-plugin-product-subagents'
      config:
        idleTimeoutMs: 600000
        providers:
          cursor:    { type: acp, command: agent, args: [acp] }
          codebuddy: { type: acp, command: cbc, args: [--acp] }

Quick start

In a session, the model has six tools:

product_delegate role=general task="Refactor demo-project/calc.js and run its tests"
product_wait subagent_id=<childId>

Configuration

config:
  providers: { cursor: { type: acp, command: agent, args: [acp] } }
  idleTimeoutMs: 600000       # settled children release their remote session
                              # after this idle period (0 disables)
  maxConcurrentChildren: 8    # cap on simultaneous continuable children
  rolesDir: <path>            # declarative role library (default: roles/)
  registryPath: <path>        # durable remote-session registry

Roles and permissions

Each role file:

{
  "id": "code-review",
  "description": "Review code for bugs, security, maintainability (read-only).",
  "provider": "claude-code",
  "permissionMode": "readonly",
  "allowDelegation": true,
  "instructions": "You are a code reviewer. READ-ONLY: never modify files. …"
}

• permissionMode maps to product flags: readonly (claude --permission-mode plan / codex --sandbox read-only), full (claude --dangerously-skip-permissions / codex --dangerously-bypass-approvals-and-sandbox).
• The relay model never gets write-capable tools, in every role.
• Delegation is capped: readonly < default < full; a child cannot spawn a descendant with a higher mode.

Custom ACP providers

config.providers accepts any ACP-capable CLI — the generic bridge handles a persistent process, session/load resume, and dead-process reconnect:

providers:
  cursor:    { type: acp, command: agent, args: [acp] }    # Cursor CLI
  codebuddy: { type: acp, command: cbc, args: [--acp] }    # CodeBuddy
  gemini:    { type: acp, command: gemini, args: [--acp] } # Gemini CLI
  opencode:  { type: acp, command: opencode, args: [acp] } # opencode

Providers appear in the delegation enum only when their command is detected on PATH. Built-ins (claude-code, codex, acp) can be overridden with the same keys.

Development

npm install
npm test        # node:test — pure logic + fake bridge, no CLIs or keys
npm run lint    # syntax-check every module

See docs/ARCHITECTURE.md for the bridge contract, the permission model, and how to add products. CI runs the suite on macOS / Ubuntu / Windows × Node 18/20/22.

Security

This is a configuration-as-trust-boundary tool: it spawns whatever CLIs you configure, and full passes the products' own "bypass all permission checks" flags. See SECURITY.md.

License

MIT