DSH-Tool-Router

DSH Tool Router

Lazy tool discovery for DSH: hides every tool schema from the model's prefill and reveals exactly one tool on demand through a decision model API.

• Prefill cost: one small find_tool schema instead of every mounted tool (26 schemas on a default Standard profile — see Why?).
• Stage 0 — full-surface send: every mounted tool (≤ 24) carries a 160-char criterion, ordered by a stopword-filtered lexical rank (the rank only bounds pathological mounts — d1-omni does not saturate as the choice count grows; see Why?).
• Stage 1 — one POST /v1/systemone to the decision model API: a bestTool choice plus a usable question kept as telemetry only (~235–500 tokens, ~6–7 s on-device).
• Stage 2 — accept iff confidence >= 0.70: return the winner's JSON Schema and reveal exactly that one tool; otherwise return a probability-ordered shortlist whose reason names the closest match, so the model can retry with that exact tool name (or send an empty request to get the whole catalog). Exact tool-name requests skip the decision call and reveal instantly.

Why?

Fresh session, first message, server-reported usage.prompt_tokens — the DSH Standard preset (the platform default) versus this plugin's no-prefill preset:

Cost before the first word	Standard	no-prefill
Prefill tokens	6,559	283
System prompt	5,816 chars	372 chars
Tool schemas shipped up front	26 schemas (21,417 B)	1 schema (697 B)

Standard makes the model ingest a 5.8k-character system prompt plus every mounted tool schema — 6,559 tokens — before it emits a single word, and pays it again on every subsequent turn. no-prefill ingests 283 tokens (23× less, 96% smaller prefill): a slim persona plus the single find_tool schema. On the measured backend that difference was ~40 s versus ~14 min of prompt evaluation for the first reply.

What that buys you:

• Latency — time-to-first-word scales with the whole tool shelf today. Reveal-on-demand makes it scale with the tool you actually call.
• Context budget — 6.5k tokens of standing preamble is 6.5k tokens you don't have for code, conversation, and results. On a 32k window that's ~20% of the model's world spent before work starts.
• Reliability on small models — a model reading 26 schemas behaves like a model reading 26 instructions it must never violate. One schema at a time is one schema to follow; the rest of the shelf doesn't exist for it.
• Pay for what you use — a turn that calls no tool costs 283 tokens instead of 6,559. A turn that calls one tool reveals that one schema once; the other 25 are never sent.

If a session ends up using most tools anyway, the gap narrows — but the unused half of the shelf is exactly what a default profile charges for from word one.

What the bundle patch declares

cordis.patch.yml (applied when the bundle is selected):

1. preset-no-prefill — an agent preset whose composition is only persona + dsh-tool-router. The persona tells the model: no tools are declared; call find_tool first — and if a result carries no schema, retry with an exact tool name or an empty request instead of giving up.
2. Host tool rows enabled — tool-bash, tool-fs, tool-fs-search, tool-todo, tool-web flipped to disabled: false, plus a present row inserted. Discovery needs the tools to exist somewhere; preset-scoped registrations shadow host ones, so other presets keep their own behavior. The slim preset keeps the Agent Presets page showing only find_tool.

Prerequisites

• DSH 0.2.0-rc.2 (bundles mechanism with dsh.bundle.patch).
• A running decision model API that speaks POST /v1/systemone (the router defaults to http://127.0.0.1:8081/v1/systemone; edit ROUTER_BASE in index.js to point at another host or port).
• pnpm on PATH of the host running DSH (the plugin manager installs through pnpm; the CLI forwards pnpm arguments).

Install

From GitHub (recommended): Plugins → install → spec

git+https://github.com/residenthiago2011/DSH-Tool-Router.git

or via the CLI:

dsh plugin --profile <profile> add git+https://github.com/residenthiago2011/DSH-Tool-Router.git

From a prebuilt tarball: download dsh-tool-router.tgz from Releases, then install from the local path (also accepted: absolute path, git URL, or an npm registry name after publishing):

dsh plugin --profile <profile> add /path/to/dsh-tool-router.tgz

Then select the bundle on the Plugins page (installation enables it by default) and restart DSH if the profile runs without HMR.

Uninstall

Deselect/remove the bundle on the Plugins page. The preset row and the host tool flips vanish with the bundle patch; other presets are untouched.

Files

File	Purpose
index.js	The router plugin: registers find_tool, masks every other tool per agent, runs the 3-stage decision.
cordis.patch.yml	The bundle patch: preset declaration + host tool enablement.
tool-registry.json	Stage-0 labels and Stage-1 criteria (25 tools, both shells incl. bash).

Tests

node router-import-test.mjs   # module shape (no dependencies)
node rank-sim.mjs             # Stage-0 ranking on sample queries (needs tool-registry.json)
node router-e2e-test.mjs      # full flow: arm/deny-set/live reveal — requires the decision endpoint at 127.0.0.1:8081

router-e2e-test.mjs uses a stub DSH context that emits tools/change synchronously (the worst case that once caused a ~970x feedback loop), then drives the real find_tool against a live decision endpoint: armed-once, deny-set dedup, late registration, reveal re-arm, empty-request catalog hint, and the exact-name fast path. ALL_PASS is expected.

Notes

• find_tool registers with a standard JSON Schema (type/properties/required/additionalProperties). A raw register with author-style parameters reaches the LLM unconstrained — the model then calls with {}. Always compile.
• The empty-request catalog hint and the exact-name fast path exist for small models; see execute() in index.js.