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

Install via your agent (one line)

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

Install the dsh-plugin-product-subagents plugin into my DeepSeek Harness web profile: run npm i dsh-plugin-product-subagents in ~/.dsh/profiles/web, then append this row to ~/.dsh/profiles/web/cordis.patch.yml — - insert: [{id: product-subagents, name: 'dsh-plugin-product-subagents', config: {idleTimeoutMs: 600000}}] — then tell me to restart the harness so the plugin loads.

That one prompt covers: installing the package into the profile, wiring the host-plane row, and flagging the required restart. (Before the package is published, use the local variant: point the row's name at this repo's lib/index.js instead of the package name.)

Manual

npm i 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

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