dsh-role-config

---

description: "Role presets and a model pool for dsh: the model delegates to a role, the operator's rules pick the model, and a failure walks the role's chain."

@snnh/dsh-role-config

English | 中文

A dsh bundle that gives delegation two ways in and one decision layer:

• Role presets. The model delegates to a role (role: "premium") and never learns which model serves it. Each role carries a description the model reads, a priority chain, and the operator's own routing rules.
• Model pool. Models the model may name directly, each with the description the operator wrote for it. A direct route is used as given and never fails over.
• Routing rules. Before a role's chain head serves, its conditions run in order: prompt substrings, a regular expression, required input modalities, a minimum context window, or the operator's own capability tags. Nothing matched and AI routing is on, one bounded router call decides; if it fails, the chain head serves.
• Priority failover. A delegated child whose request fails terminally retries the same request on the next member of its role's chain, and the original failure stands once the chain is exhausted.
• Function bindings. Context compaction and session titles can follow a role instead of the session's route, or keep the harness default.

Install

dsh plugin --profile <profile> add @snnh/dsh-role-config

The package is published to npm, so the line above needs no build step. A git install (github:snnh/dsh-role-config) works too: the built halves (lib/index.js, lib/client.js, and their declarations) are committed, so it needs no build script and no allowBuilds permission. Rebuild them with npm run build after changing src/.

Nothing is on until you turn it on

A fresh mount registers no tool and changes no agent: exposure.delegateTool and exposure.listTool both default to false, so the official delegation tool keeps serving until an operator asks for the routed one. Turning both on is the whole opt-in:

- id: role-config
  config:
    exposure:
      delegateTool: true
      listTool: true
    pool:
      - provider: deepseek-official
        model: deepseek-chat

The one prerequisite

With exposure.delegateTool: true this plugin registers its delegation tool under the official subagent name. While the plugin is enabled that routed tool is what the agent sees; disable the plugin and the official tool serves again. Shadowing needs the official tool one scope further out than the agent, so the official tool-subagent row must carry modelSelectionSettings: false:

- id: tool-subagent
  config:
    provider: spawn
    toolName: subagent
    modelSelectionSettings: false

Leave that row ENABLED. Disabling it to free the name is a one-way trade: with this plugin switched off afterwards, the deployment has no delegation tool at all. Nothing needs it: the routed registration is nearer than the preset scope, so it wins the name while the official tool stays mounted and serves. Switching the takeover off (delegateTool: false, or the settings page's Restore the official delegation tool button, which stages that switch and saves in one click) hands the name back, and the plugin removes a leftover disabled: true from the official row while it is at it.

A profile patch reaches the rows the profile declares. The shipped presets declare their own, nested inside a cordis:group, and a patch replaces a row's whole config — so restate the preset row with that one field flipped, the way the harness's own overlays do. packages/bundle/web-app/presets/standard.patch.yml lists the shipped plugins; refresh your copy when it changes:

- id: preset-standard
  config:
    id: standard
    order: 1
    plugins:
      # …the shipped plugin list, unchanged…
      - id: delegation
        name: cordis:group
        group: true
        isolate: { workflowEngine: true }
        config:
          - id: tool-subagent
            name: '@deepseek-ai/dsh-tool-subagent'
            config:
              provider: spawn
              toolName: subagent
              modelSelectionSettings: false

With model selection on, the official tool registers inside every agent's own scope, where a same-named tool cannot exist. The plugin then names the row to fix and leaves the official tool in place, so the session still opens; delegate.toolName renames this plugin's tool instead, if you would rather keep the official configuration.

Configuring over a LAN address

Settings documents are confined to a loopback page by default, so a deployment reached at http://<lan-ip>:<port> shows the model pages and every plugin page as unavailable. To configure this plugin from the address you actually use, restate the client-connection row with its operator surface opened:

- id: connection
  config:
    trustedHosts: !!js ctx.webRuntime.trustedHosts
    operatorSurface: trusted

A patch replaces a row's whole config, so keep trustedHosts in the row. The page is served only after the access token is validated and every request it makes still passes the Host/Origin fence and the session check; what changes is that the settings and plugin pages render at all.

Configure

Open Plugins in the Web sidebar and select Role Config. The page edits one role-config settings section: the pool with its descriptions, the role presets with their chains and rules, the switches (which surfaces exist, failover, AI routing), the function bindings, and the delegation wiring.

What the model sees

A role's members, rules, and the router's answer never reach the model.

Limits

• A role never fails over for a directly named route, and the main agent's own requests never fail over.
• Agent-team members inherit the lead's route; this plugin can only fail them over, not choose their model.
• Function bindings write the target row's configuration and have no failover of their own.