dsh-tool-manager
On-demand tool loading for DeepSeek Harness — every tool as a directory, loaded only when an agent asks.

English · 中文

---

What It Is

On-demand tool loading for DeepSeek Harness: every tool is browsable as a directory (category → group → tool) and only what an agent loads reaches the model's context. Built as a small core plus replaceable extension plugins.

Quick start

# 1. install the core plus the rule-based classifier (optional but recommended)
dsh plugin --profile web add @lvy-jsd/dsh-tool-manager @lvy-jsd/dsh-tool-manager-classifier-rules

# 2. restart DSH, then ask the agent: "what tools do you have?"
#    it answers with tools_ls("/") — a directory, not 200 tool schemas

# 3. want the UI? add the panel, then open Settings → "Tool manager"
dsh plugin --profile web add @lvy-jsd/dsh-tool-manager-panel

Install the scoped @lvy-jsd/… packages. The unscoped dsh-tool-manager on npm is a different project. Do not install both: each one narrows which tools an agent can see, so together they hide tools from each other.

On a fresh install every group is uncategorized until a classifier is installed — the tools are still browsable and loadable, only the categories are missing. See Extending to write your own classifier.

Packages

Package	What it does
@lvy-jsd/dsh-tool-manager	Core: directory, tools_ls / tools_load / tools_unload, per-agent allowlist, the toolCatalog extension service, plus intent retrieval + routing (tools_find / tools_route / skills_find / skills_route, BM25 with a Rust sidecar). Without extensions every group is uncategorized.
@lvy-jsd/dsh-tool-manager-classifier-rules	Places groups into categories from built-in rules and your config overrides.
@lvy-jsd/dsh-tool-manager-risk-gate	Confirms loading high-risk tools through the DSH approval channel, with a per-session allowlist.
@lvy-jsd/dsh-tool-manager-persist	Keeps loaded tools across a DSH restart, one state file per session.
@lvy-jsd/dsh-tool-manager-panel	Web panel: browse the tree, see each live session's loaded tools and token cost, load/unload from the UI, edit the always-on and high-risk lists, edit one tool's metadata, exempt one session.
@lvy-jsd/dsh-tool-manager-classifier-llm	Places groups with a small model, one request per group, cached by a hash of the group and its tool descriptions.
@lvy-jsd/dsh-tool-manager-capability-bridge	Load a named bundle of tools in one call: tools_load(["cap:android-debug"]).
@lvy-jsd/dsh-tool-manager-attribution-scan	Group tools by the plugin package whose source defines them.
@lvy-jsd/dsh-tool-manager-dsbot-entry	A "Tool manager" row in the ds-bot settings dialog that opens the panel.
@lvy-jsd/create-tool-manager-plugin	Scaffold your own extension: npm create @lvy-jsd/tool-manager-plugin@latest my-ext -- --type classifier.

See docs/DESIGN.md for the design.

Extending

Every feature beyond the core is an ordinary plugin using the toolCatalog service, and the bundled classifier-rules package is written exactly as a third party would write it. Four extension points:

Point	For
registerClassifier({ name, priority, group?, categorize? })	placing tools into groups and groups into categories
annotate(match, { group?, category?, risk?, summary? })	runtime metadata; package.json dsh.toolCatalog does the same without code
registerVisibilityFilter({ name, filter(agent, names) })	narrowing what one agent may see — can only remove names
registerTargetResolver({ name, prefix, resolve })	owning a target prefix, e.g. cap:<name>
registerRiskGate / registerStateProvider	confirming high-risk loads / keeping state across a restart

Hooks are plain events: tool-catalog/before-load (throw to veto), after-load, before-unload, after-unload, before-rebuild, after-rebuild, state-changed.

Start from a generated package — it comes with a passing test:

npm create @lvy-jsd/tool-manager-plugin@latest my-ext -- --type classifier
cd my-ext && npm test

Two worked examples live in examples/, and the full interface list is in the core README and docs/DESIGN.md §11.

Development

Every package is written in TypeScript (src/) and compiled to lib/ (JavaScript plus .d.ts type declarations); lib/ is build output and not committed. The root tsconfig.json lists the packages (project references); the two browser halves (client.ts) have their own tsconfig.client.json, because DSH loads them as classic scripts, not modules.

npm install                        # also links your local DSH host packages (scripts/link-host.mjs)
npm run build                      # src/*.ts -> lib/*.js + lib/*.d.ts
npm run typecheck                  # strict type check (tsc -b; writes lib/ too, references need it)
node --test test/unit/*.test.mjs   # pure catalog and registry tests (needs a build)
node test/e2e.mjs                  # boots throwaway DSH instances; never touches your profile

Host packages (@deepseek-ai/*) are peers and are never installed from the registry (.npmrc sets legacy-peer-deps): a registry copy next to the plugin would shadow the DSH you actually run. npm install links them from $DSH_APP (default ~/.local/share/deepseek-harness/app) instead.

License

MIT — see LICENSE.