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). Every installable
  @deepseek-ai/dsh release from 0.0.1-rc.5 through the current 0.1.5-rc.1
  is verified — see Compatibility.
• 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:

Tool	Purpose
product_delegate	delegate a task under a role (sync or continuable)
product_roles	list the role library
product_submit	per-child bridge (continuable children only)
subagent_progress	status + internal trace of one child
product_wait	block until a child settles, return its answer
product_agents	provider availability + live children

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
  providerNamespace: product-subagents
                              # namespace for the ids registered on
                              # ctx.subagents; '' registers the bare keys

Provider ids

claude-code, codex, acp (and any config.providers key) stay the names
you use in roles and in product_delegate — but they are also the ids the
official @deepseek-ai/dsh-subagent-claude-code / -codex / -acp plugins
register under, and the harness rejects a duplicate provider id hard enough to
fail the whole profile's plugin tree at boot.

So on ctx.subagents this plugin registers namespaced, plugin-owned ids —
product-subagents:claude-code and friends — and both plugins can live in one
profile. This only changes the harness-wide subagent tool's provider names;
nothing in this plugin's own surface moved. Set providerNamespace: '' to
register the bare keys again (safe only where no official product subagent
plugin is loaded).

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.

Compatibility

package.json declares the supported DSH range under dsh.compatibility, plus
dshReleases — a per-release compatible / incompatible / unknown verdict.
Every compatible verdict is backed by an acceptance run in a disposable
profile, not by the range alone:

node scripts/verify-dsh-profile.mjs --dsh 0.1.5-alpha.2

For one DSH release that creates a throwaway $DSH_HOME, installs the packed
tarball with the real dsh plugin add, checks the composed profile tree, boots
the profile and asserts from inside the running harness that all six tools are
registered, the providers reached the real SubagentRuntime, and the tools
execute and schema-validate — then uninstalls and checks the bundle layer is
gone. It needs no API key, and it is not part of npm test.

The recorded matrix and what a verdict does (and does not) prove are in
docs/COMPATIBILITY.md.

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