dsh-preset-run

English | 中文

DeepSeek Harness plugin that turns "web session + agent preset" into a programmable interface.

Registers a host-plane tool preset_run(preset, task) — create a fresh, independent agent session composed from any agent preset (router-spec / router-standard / standard / minimal / cordis), send task as its first user message, wait for it to finish, and return the final answer text. This is the headless equivalent of the Web UI's New Session → pick preset → send message flow.

Requirements

• DeepSeek Harness >= 0.1.0-rc.6 installed (dsh CLI, Web or headless profile)
• Node.js >= 18 (20+ recommended — the plugin and its verify script use modern Node features)
• A configured model service (agent-default-model in settings.yaml)
• The agent presets you want to call must exist in the deployment's roster (e.g. router-spec, minimal)

This is a dsh plugin, not a standalone npm package: it must be installed through dsh plugin add into a dsh profile. It does not bundle the dsh runtime.

Install

# From GitHub (recommended)
dsh plugin --profile web add "github:YiGeSama/dsh-preset-run"

# Alternative: git+https URL
dsh plugin --profile web add "git+https://github.com/YiGeSama/dsh-preset-run.git"

# Alternative: local clone / source directory
dsh plugin --profile web add "file:C:/path/to/dsh-preset-run"

> Windows caveat: a file: local path containing spaces may be split by the > pnpm bridge (ERR_PNPM_LINKED_PKG_DIR_NOT_FOUND, tested with E:/BaiduSyncdisk/SD Manager/...). > In that case use the GitHub install above, clone to a path without spaces, or use the > 8.3 short path.

Restart the web process after installing: preset_run is a host-plane tool and becomes available to every session on the next boot.

dsh plugin add performs: pnpm dependency resolution → detects the dsh.bundle.patch declaration in package.json → appends preset-run to the profile's dsh.profile.bundles list → the cordis.patch.yml plugin row is loaded with the bundle layer on the next start.

Dependency handling

The plugin imports @deepseek-ai/dsh-tools, dsh-agent, dsh-llm, dsh-session at runtime. They are declared only as peerDependencies, never dependencies:

• These packages are provided by the dsh harness installation that hosts the profile;
• Declaring them as dependencies would let pnpm hoist another copy into

profiles/web/node_modules/@deepseek-ai/, so the tools service instance and the dsh-agent-loop TOOL_RUNTIME_SCHEDULER symbol would come from two different module instances — every tool dispatch would crash (Cannot read properties of undefined (reading 'prepare'));

• Hence the repository ships no node_modules and no machine-specific paths/junctions.

Usage

Ask the model to call the tool in any session:

preset_run("router-spec", "请调用 dev_router_status 工具并输出结果")
preset_run("minimal", "1+1=?")
preset_run("standard", "把 README.md 里的 TODO 列表整理成表格")

Optional parameter timeoutMs caps a single child run (default 600000 ms).

Supported presets

preset_run uses whatever preset ids the deployment's agentPresets roster provides; it does not hardcode a list.

Out of the box it supports the 4 default dsh presets (shipped with dsh, no extra install):

The other 2 routing presets come from a third-party plugin (yjh051108/dsh-router-standard — not part of this plugin; install it separately for them to appear in the roster):

The exact roster depends on the deployment (agentPreset.list).

How it works

• Preset application follows the official path: agentPresets.mount(agentCtx, presetId)

runs inside the agent factory's setup(agentCtx) hook (before the agent is published — a mount failure rolls the whole creation back), and the preset id is recorded in the session header (meta.agentPreset). This matches the Web backend (dsh-host-apiproxy's composeAgent/ensureSession); it is not a loader --patch hack.

• Model routing: reads agentDefaultModel.currentSelection() (i.e.

agent-default-model in settings.yaml) and installs it on the child agent via installModelSelection — provider/model/effort all apply.

• Task execution: agent.followup(createUserMessage(task)) drives the child,

agent.whenIdle() waits for it to settle, then the final assistant text and the turn/end reason are aggregated from the session event log. A run that never emitted turn/end is reported as failed (strict), even if it produced partial text.

• Cleanup: after returning, dispose() tears the child agent down; the session is

removed from the registry and leaves no UI residue. Abort/timeout first call agent.cancel() so the child stops burning tokens. Cleanup failures are logged and never mask the child's own result.

Security notes

• preset_run lets any session that can call it spawn child sessions that run tasks

with the deployment's default permission preset. In multi-user or untrusted deployments, make sure only authorized callers reach it.

• Child sessions inherit the deployment's default permission preset (new-session

sandbox + approval). In a workspace-write + ask deployment, a child that requests elevation enters an approval flow nobody answers and may block until timeout — configure danger-full-access (in settings.yaml or DSH_PERMISSION_MODE=danger-full-access) when unattended runs are required.

• Child sessions are one-shot: destroyed after returning, no history is kept.

Verification

Tested end-to-end on @deepseek-ai/dsh 0.1.0-rc.6 + tokenrythm/deepseek-v4-flash-0731.

# 1. Start a verification instance (same profile, separate port)
dsh web --port 3083

# 2. Run the acceptance script (drives the web JSON-RPC: create session → send → wait → check catalog/log)
node verify-preset-run.mjs http://127.0.0.1:3083

Expected highlights:

• The roster contains router-spec / minimal;
• A router-spec child session's escalated catalog includes dev_router_status and

actually calls it (returns router-mode=spec / mode=1.00 (band=react) / core=[read, write, edit] / override=no);

• A minimal child session answers 1+1=2;
• Two preset_run calls from one standard parent session relay both child answers.

Notes

• The router-spec preset intentionally exposes only core tools on the first turn

(read/edit/glob/grep + shell); the full catalog opens after the first tool call. If your task text asks for a post-escalation tool such as dev_router_status, guide the child to run one shell command first (e.g. pwd).

Credits

• Idea & requirements: YiGeSama (repository owner)
• Implementation: built collaboratively by two AI agents — the assistant inside

dsh (DeepSeek Harness) handled core implementation; the Hermes assistant handled coordination, review and engineering.

License

MIT — see [LICENSE](LICENSE).