@xmoon76/dsh-subagent-router

English | 中文

A model-facing DSH plugin that starts a subagent on a model-selected LLM provider and model. The model picks the route (provider/model); the deployment owns the subagent backend (subagentProvider, default spawn), the lifecycle mode (executionMode), and the route allowlist (allowedProviders). Later turns reuse the official send_message / list_agents / interrupt_agent tools from @deepseek-ai/dsh-tool-subagent-control.

Installation (as a DSH profile bundle)

This package ships as a DSH profile bundle: its cordis.patch.yml (dsh.bundle.patch) inserts TWO router rows into the profile composition automatically — tool-subagent-router (spawn + continuable, subagent_route) and tool-subagent-router-fork (fork + one-shot, subagent_fork_route). Requires a profile whose bundles include @deepseek-ai/dsh-base (every shipped web/headless template does) — the subagents registry and its spawn/fork backends come from that base layer.

dsh plugin --profile <name> add @xmoon76/dsh-subagent-router

The command installs the package into the profile and adds it to the profile's dsh.profile.bundles layer list; on the next boot its patch inserts both rows with the defaults below. To override defaults, patch the same row ids in the profile's own cordis.patch.yml (a patch replaces the row's whole config):

- id: tool-subagent-router
  config:
    allowedProviders:
      - deepseek-official

Usage walkthrough

The following flow is a practical model-facing invocation. Confirm that the profile has registered the router tools (subagent_route / subagent_fork_route) and that the selected provider/model route is configured before dispatching.

Start a continuable child

subagent_route requires all four fields. The model chooses only the LLM route; deployment configuration still owns the backend and lifecycle:

{
  "description": "say hi",
  "prompt": "Say hello briefly, then state which model you are using.",
  "provider": "codex",
  "model": "gpt-5.6-luna"
}
// continuable result: started continuable subagent <id>

A continuable result acknowledges inbox acceptance and returns a durable id; it does not contain the child reply. Wait for the DSH settlement notice or inspect the child transcript by id.

Continue for more turns

Use the official send_message control tool to queue the next FIFO turn after the child has been accepted:

{
  "subagent_id": "<id>",
  "message": "What kinds of engineering tasks are you best at?"
}
// message queued as the next turn for subagent <id>

The child keeps its creation-time provider/model across later turns and cold resume. There is no mid-session route switch.

Companion controls

Continuation controls are separate from this package and must be mounted from the official @deepseek-ai/dsh-tool-subagent-control plugin:

Official delegation tools (subagent, subagent_fork) are separate: they are instances of @deepseek-ai/dsh-tool-subagent bound to one fixed deployment route. This router never replaces them — see Official tool coexistence below.

Start a dynamic fork (one-shot)

subagent_fork_route is mounted by the bundle by default (fork + one-shot), so a forked child that inherits the parent's completed turns is available out of the box. The instance uses a non-conflicting name (never the official subagent_fork):

# what the bundle inserts (defaults; override by row id in your profile)
- id: tool-subagent-router-fork
  config:
    subagentProvider: fork
    executionMode: one-shot
    toolName: subagent_fork_route
    maxDepth: 3

Model call:

{
  "description": "review prior design",
  "prompt": "Review the design discussed above and identify correctness or maintainability risks.",
  "provider": "openai",
  "model": "gpt-5.6"
}
// one-shot result: the child's final output

Fork prompt semantics: the child already sees the parent's completed turns, so the prompt only needs to state the new task; the current in-flight parent turn is not part of the fork seed.

Best practices

• Make a fresh-child (spawn) prompt self-contained: it does not see the parent conversation.
• Make a forked-child (fork) prompt a delta only: the child inherits the parent's completed turns, so state only the new task; the current in-flight turn is not in the fork seed.
• Verify provider/model availability before dispatch. There is no model-discovery tool, and route errors may surface only when the child's first request resolves the route.
• Treat a continuable start result as an acknowledgement, not as the child answer; use settlement notices and the transcript for the actual result.
• Configure allowedProviders when deployment policy restricts routes; do not rely on prompt wording for enforcement.
• Keep credentials, endpoints, and headers out of prompts and tool arguments. Use a unique toolName for each loaded instance.
• Remember that maxTokens is not durable across activations.

Why this package

The official @deepseek-ai/dsh-tool-subagent binds one instance to one fixed child agentOptions (deployment-fixed provider/model). This plugin moves the LLM route choice into the model's hands while keeping every capability owned by the DSH seam: it is a thin Consumer over ctx.subagents.startContinuable() / ctx.subagents.start() and does not re-implement continuation, sessions, persistence, authority, or queues.

Contract

The model-facing tools subagent_route / subagent_fork_route take the same four parameters:

Success returns { kind: 'continuable', subagentId } (durable id, resolved at inbox acceptance) or { kind: 'one-shot', runId, output } (final child output), depending on the instance's executionMode. Credentials, endpoints, headers, maxTokens, outputSchema, and backend selection are never exposed to the model.

Config

Routing policy

• The model selects only the LLM route: provider must name a registered DSH LLM adapter route and model a model id on it.
• allowedProviders is executor-level enforcement, not a prompt hint. provider/model validity is ultimately resolved by the DSH LLM/Agent resolution at the child's first request (no listModels() hard whitelist, preserving dynamic model routes).
• The subagent backend and lifecycle mode are deployment configuration; the model never selects them.

Continuation behavior

• A continuable child is a durable conversation: send_message (official control tool) delivers later FIFO turns, list_agents lists it, interrupt_agent interrupts it — all through ctx.subagents authority paths.
• Cold resume keeps the same agentProvider/agentModel: the durable descriptor persists them, so a resumed Activation still uses the creation-time route.
• provider/model are fixed at creation; there is no mid-session model switching.

Official tool coexistence

This plugin does not replace the official subagent / subagent_fork tools. The bundle mounts BOTH router instances by default, and when the official tools are present the final tool set is:

subagent            -> official fresh child,  fixed route,   continuable
subagent_route      -> router  fresh child,  dynamic route, continuable
subagent_fork       -> official inherited context, fixed route,   one-shot
subagent_fork_route -> router  inherited context, dynamic route, one-shot
send_message        -> official (@deepseek-ai/dsh-tool-subagent-control)
interrupt_agent     -> official (@deepseek-ai/dsh-tool-subagent-control)
list_agents         -> official (@deepseek-ai/dsh-tool-subagent-control)

The two router tools differ from their official counterparts ONLY in the child route: the official instances use a deployment-fixed provider/model, while the router lets the model select provider/model on every call. Everything else is identical:

The router never shadows, replaces, or mutates official tool definitions: it registers only its own tool names and leaves every official schema and behavior intact (locked by the coexistence test suite).

Support matrix

The router is a generic provider Consumer, so fork + continuable is not hard rejected when a provider exposes prepareContinuable() — but the product documentation recommends fork + one-shot.

Tool name collision rules

• Each loaded router instance needs a unique toolName. A name already registered in the tool registry fails the mount loud, before anything is registered.
• DSH official subagent/control names (subagent, subagent_fork, send_message, interrupt_agent, list_agents) get a dedicated diagnostic when configured as a router toolName.
• Never configure the router's toolName as subagent or subagent_fork. The shipped bundle uses subagent_route (spawn + continuable) and subagent_fork_route (fork + one-shot); further instances must pick their own unique names.

Model Experience

Tool schema

What the model sees

The registered router schemas (subagent_route / subagent_fork_route): description, prompt, provider, model, all required. The description/prompt wording follows the backend provider's inheritsParentContext: a fresh child is told to provide a complete standalone prompt; a forked child is told it already sees completed turns. No api_key, base_url, max_tokens, run_in_background, or backend/mode parameters exist.

Token effect

Fixed schema cost per request where the tool is visible; no system-prompt section is contributed by this package.

KV Cache effect

Prefix-stable while the registered tool schema is unchanged; provider registration lifecycle may invalidate reuse from the first changed tool definition.

Tool result

What the model sees

started continuable subagent <id> (continuable mode) or the child's final text (one-shot mode). Continuable results carry no child reply; the child's transcript by its id is the source of what it did, and its settlement notice arrives independently.

Token effect

One short result appended per accepted creation (continuable) or the child's output (one-shot).

KV Cache effect

Append-only after the reusable request prefix.

Known Limitations and Deferred Work

• No mid-session model switching — provider/model are fixed at creation; the durable descriptor persists them, so a resumed Activation still uses the creation-time route.
• No model discovery tool — the model must already know the configured provider/model ids; a read-only discovery tool is deferred.
• No synchronous collection of a continuable child result — subagent_route resolves at inbox acceptance; the child's settlement arrives via the DSH notice mechanism, and its transcript by id is the detailed source.
• maxTokens is not durable — per-activation budgets are not persisted in the DSH continuable descriptor, so the tool does not expose them.
• Only configured LLM adapters/routes can be used — the child route must resolve at request time; provider/model validity may fail only when the child's route is resolved (no listModels() hard whitelist by design).
• Continuation controls require the official control tool — send_message / list_agents / interrupt_agent come from @deepseek-ai/dsh-tool-subagent-control, mounted separately.
• One-shot output is not streamed — the run's final output is returned once the child settles; intermediate steps stay in the child's transcript.
• Output schema uses the DSH tools value-schema dialect — the canonical one-shot output is { type: 'array', items: { type: 'json' } }, where 'json' is @deepseek-ai/dsh-tools's Schemastery-based value type (the same dialect the official tool-subagent uses), not a bare JSON-Schema keyword; only DSH's tool registry consumes it.

Development

Prerequisites

Node.js ≥ 22 and npm. All DSH peer dependencies resolve from the npm registry (@deepseek-ai/dsh-* 0.1.0-rc.x), so no deepseek-harness checkout is required.

Gates

npm run typecheck   # tsc over src + tests
npm run lint        # oxlint
npm run test        # vitest (package integration + Loader composition)
npm run test:coverage  # per-file 100% on src/
npm run build       # tsc emit to lib/