@lvy-jsd/dsh-tool-manager 0.0.0-stage → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lvy-jsd and contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,303 @@
-# Temporary Holding Version
+# @lvy-jsd/dsh-tool-manager
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Browse every DeepSeek Harness tool as a directory and load tools on demand.
+
+A DSH host with many plugins and MCP connectors sends every tool schema to the
+model on every request. This plugin hides everything except a small always-on
+set and gives the model three entry tools to find and load the rest:
+
+```
+tools_ls("/")                       # categories
+tools_ls("/code")                   # groups (a connector or plugin)
+tools_ls("/code/github")            # tools, with a one-line summary and schema size
+tools_ls({ query: "pull request" }) # search the whole tree in one step
+tools_load(["/code/github"])        # callable from the next step, for the rest of the session
+tools_load(["mcp__github__get_me"]) # or one tool by exact name
+tools_unload(["/code/github"])
+tools_find("send an email")         # ranked matches by intent (BM25), no loading
+tools_route("send an email")        # retrieve, re-rank with the model, then load
+```
+
+Loaded tools are **native**: the model receives their full parameter schema
+and calls them directly. Nothing is proxied.
+
+The core ships **no placement rules**. Without an extension every group is
+listed under `uncategorized/` — still fully browsable and loadable. Install
+[`dsh-tool-manager-classifier-rules`](../dsh-tool-manager-classifier-rules) for
+built-in rules and config overrides, or write your own classifier.
+
+## How it works
+
+- Visibility is a per-agent allowlist installed with the host's
+  `agent.ctx.tools.restrict({ allow })`:
+  `allow = (pinned ∪ loaded tools ∪ tools of loaded groups) ∩ registered tools`,
+  then narrowed by any registered visibility filters.
+  Tools that appear later (an MCP server reconnecting, a new plugin, a renamed
+  tool) stay hidden until loaded.
+- Loading a group subscribes to it: tools the group gains later become visible
+  too.
+- Restrictions from other plugins intersect with this one, so a hard deny (for
+  example the MCP connector's governance policy) always wins. A pinned or
+  loaded tool that another layer still hides is marked `[denied]` in
+  `tools_ls`, and `tools_load` reports it as not callable instead of listing it
+  (with one log warning per tool, pointing at connector governance rules and
+  per-session injection).
+- DSH's PTC mode (`DSH_TOOLS_MODE=ptc`) works unchanged: the model gets only
+  `run_code`, and the SDK the host declares for it is built from the same
+  narrowed view, so loads show up there from the next step. `run_code` itself
+  is a host transport and never enters the directory.
+- Every agent is restricted separately. A subagent starts from the pinned set
+  plus whatever the parent loaded with `forSubagents: true`.
+- Loaded state is in memory. Install
+  [`dsh-tool-manager-persist`](../dsh-tool-manager-persist) to save it per
+  session and restore it when the session resumes.
+- If the plugin is unloaded, all its restrictions are lifted (fail open to
+  "every tool visible", never to "no tools").
+
+## Finding and routing by intent
+
+The directory above is browsable, but the model still has to guess the right
+keywords and spend turns searching. The core now ships a retrieval + routing
+layer that makes an unbounded catalog usable without that guesswork:
+
+```
+tools_find("send an email")     # ranked matches (BM25), no loading
+tools_route("send an email")    # retrieve, re-rank with the model, then load
+skills_find("write a PR")       # ranked skills, no loading
+skills_route("write a PR")      # retrieve, re-rank, then load the top skill's body
+```
+
+Retrieval is BM25 by default: no model, no network, works offline, and scales
+to a large catalog. The BM25 index lives in a Rust sidecar process
+(`sidecar/`, tantivy over a Unix socket) for headroom — the hot path is native
+and the TypeScript here is a thin client. A dependency-free JS BM25 index is
+kept as the always-available fallback, so retrieval never breaks if the sidecar
+binary is missing or the process dies.
+
+When a model is configured (`config.model { provider, model }`), `tools_route`
+and `skills_route` re-rank the BM25 candidates with the model, so a
+natural-language intent that shares no words with a tool name still finds it —
+the RAG-MCP pattern: retrieve a small candidate set, then rank it. Any model
+failure falls back to the BM25 order, so the router never breaks on a model
+hiccup.
+
+The router reuses the core's `toolCatalog` service: it indexes the same
+catalog, loads through the same path, and reports the same token budget. The
+sidecar is spawned by the plugin and exits with it (a parent-process monitor
+kills it on a DSH restart).
+
+## Configuration
+
+```yaml
+- id: tool-manager
+  name: '@lvy-jsd/dsh-tool-manager'
+  config:
+    pinned: []      # extra always-on tools (core DSH tools are built in)
+    unpin: []       # built-in always-on tools to move into the directory
+    exemptProviders: [claude-code]  # routes never narrowed (tool list fixed at session start)
+    highRisk: []    # never included in group loads; load individually
+```
+
+### Override files
+
+Three files under `$DSH_HOME/tool-manager/` override the config above. Each is
+read at startup and re-read when the settings panel saves through the API (or
+`reload*` is called); write them from the panel, or by hand and then reload.
+
+| File | Config key it replaces | What it holds |
+|---|---|---|
+| `settings.json` | `pinned`, `unpin`, `highRisk` | the lists an operator edits most often |
+| `metadata.json` | `annotate()` for the same tool | `{ "<tool>": { "group", "category", "risk", "summary" } }` |
+| `exempt.json` | `exemptProviders` | `{ "providers": [...], "sessions": [...] }` |
+
+### The tool manifest
+
+A client that receives its tool list once per session — Claude Code, driven by
+`dsh-oh-my-claude` — cannot discover the directory by asking, because nothing
+tells it the directory exists. So the catalog is also written out as text, to
+`~/.claude/dsh-tool-catalog.md`, after every rebuild:
+
+```
+## device (14 tools, Devices)
+
+### adb — load with `tools_load({ targets: ["/device/adb"] })`
+- adb_install — Install an APK on a device.
+- adb_shell ! — Run a shell command on a device.
+```
+
+The file opens by saying the listed tools are **not callable yet**, then gives
+the two calls that change that (`tools_ls`, `tools_load`) and the rule to load
+the smallest thing that covers the task. A `!` marks a high-risk tool. Reading
+it runs nothing.
+
+Add one line to `~/.claude/CLAUDE.md` so every Claude session reads it:
+
+```
+@~/.claude/dsh-tool-catalog.md
+```
+
+The write is skipped when the text did not change, so a rebuild that moves
+nothing does not cost a prompt re-read. `manifestFile` points it elsewhere, and
+`''` turns it off.
+
+The files win as a whole, not key by key: once `exempt.json` exists, the config
+list is ignored rather than merged, so what the file shows is what is in force.
+A missing file means "no opinion, use the config"; a corrupt file is reported as
+a warning and treated as empty rather than silently restoring the config.
+`sessions` exempts one session by id for its remaining lifetime, for checking
+whether a client handles late loading without de-exempting the whole route.
+
+A tool's `metadata.json` entry replaces the previous entry as a whole:
+submitting the form with a field blank drops that override, and the package
+declaration (or a classifier) applies again. `parameters` are deliberately not
+part of it — the host owns the schema sent to the model.
+
+## Extending: the `toolCatalog` service
+
+Declare `inject: ['toolCatalog']` (or use `ctx.inject(['toolCatalog'], …)` for
+an optional dependency) and register inside an effect so that unloading your
+plugin undoes the registration.
+
+### Classifiers
+
+A classifier may place tools into groups and/or groups into categories.
+Return `undefined` to pass.
+
+```js
+export const name = 'my-classifier'
+export const inject = ['toolCatalog']
+export function apply(ctx) {
+  ctx.effect(() => ctx.toolCatalog.registerClassifier({
+    name: 'my-classifier',
+    priority: 200,
+    group: (tool) => (tool.name.startsWith('lingshu_') ? 'lingshu' : undefined),
+    categorize: (group) => (group.name === 'lingshu' ? 'system' : undefined),
+  }))
+}
+```
+
+Resolution order: classifiers with `priority >= 1000` (user overrides) →
+plugin declarations → other classifiers, highest priority first → structural
+fallback (`mcp__server__…` → `server`, shared `prefix_` → `prefix`, else
+`misc`; category `uncategorized`). A classifier that throws is skipped.
+
+### Declaring your own tools
+
+Plugin authors know their tools best. Declare them in your `package.json`:
+
+```json
+{
+  "dsh": {
+    "toolCatalog": {
+      "match": "^adb_",
+      "group": "adb",
+      "category": "device",
+      "tools": { "adb_install": { "risk": "high", "summary": "Install an APK." } }
+    }
+  }
+}
+```
+
+or at runtime:
+
+```js
+ctx.effect(() => ctx.toolCatalog.annotate('^adb_', { category: 'device' }))
+ctx.effect(() => ctx.toolCatalog.annotate('adb_install', { risk: 'high' }))
+```
+
+Fields: `group`, `category`, `risk` (`"high"`), `summary`. Exact-name entries
+win over `match`; runtime annotations win over `package.json`.
+
+### New categories
+
+```js
+ctx.effect(() => ctx.toolCatalog.defineCategory('games', 'Game servers and bots'))
+```
+
+### High-risk gates
+
+A gate declares that a plugin confirms high-risk loads (normally by returning
+`{ kind: 'ask' }` from `tools/pre-execute` for `tools_load`). **With no gate
+registered, high-risk tools cannot be loaded at all** — they are skipped in
+group loads and refused individually. That is deliberate: a deployment without
+an approval path should not be able to arm them.
+
+```js
+ctx.effect(() => ctx.toolCatalog.registerRiskGate({ name: 'my-policy' }))
+ctx.effect(() => ctx.on('tools/pre-execute', async (exec, next) => {
+  if (exec.name !== 'tools_load' || !needsConfirmation(exec.arguments)) return next()
+  return { kind: 'ask', reason: 'Loading a high-risk tool' }
+}))
+```
+
+See [`dsh-tool-manager-risk-gate`](../dsh-tool-manager-risk-gate).
+
+### Persistence
+
+Loaded state lives in memory; a state provider makes it outlive the process.
+
+```js
+ctx.effect(() => ctx.toolCatalog.registerStateProvider({
+  name: 'my-store',
+  load: (agent) => readFromMyStore(agent.id),      // serialized state or null
+  save: (agent, state) => writeToMyStore(agent.id, state),
+}))
+```
+
+Providers are consulted in registration order (first non-null wins) and all
+receive every save. `exportState(agent)` / `importState(agent, state)` are the
+plain-JSON equivalents. See
+[`dsh-tool-manager-persist`](../dsh-tool-manager-persist).
+
+### Hooks
+
+Plain Cordis events on the host context:
+
+| Event | Kind | Payload |
+|---|---|---|
+| `tool-catalog/before-load` | serial; throw to veto | `{ agent, targets, names }` |
+| `tool-catalog/after-load` | emit | `{ agent, targets, added }` |
+| `tool-catalog/before-unload` | serial; throw to veto | `{ agent, targets }` |
+| `tool-catalog/after-unload` | emit | `{ agent, targets, removed }` |
+| `tool-catalog/before-rebuild` | emit | `{}` |
+| `tool-catalog/after-rebuild` | emit | `{ catalog }` |
+| `tool-catalog/state-changed` | emit | `{ agent, state }` (plain JSON, after every load/unload) |
+
+```js
+// A per-session quota: at most 60 visible tools.
+ctx.on('tool-catalog/before-load', ({ agent, names }) => {
+  const now = ctx.toolCatalog.allowFor(agent)?.length ?? 0
+  if (now + names.length > 60) throw new Error('tool quota reached; unload something first')
+})
+```
+
+### Visibility filters
+
+A filter receives the agent and the computed allowlist and returns the names
+to keep. It can only narrow; it can never add tools or hide the entry tools.
+
+```js
+// Keep GitHub write tools away from bot sessions.
+ctx.effect(() => ctx.toolCatalog.registerVisibilityFilter({
+  name: 'no-github-writes-for-bots',
+  filter: (agent, names) => (agent.id.startsWith('bot-')
+    ? names.filter((n) => !/^mcp__github__(create|delete|merge|push|update)/.test(n))
+    : names),
+}))
+```
+
+### Reading the catalog
+
+`ctx.toolCatalog.get()` returns `{ tools, groups, categories }`;
+`resolve(target)`, `stateOf(agent)`, `allowFor(agent)`, `deniedFor(agent)`
+(allowed here but hidden by another layer), `isExempt(agent)`,
+`packages()` (enabled plugin packages: `{ name, dir, manifest }`) and
+`refresh()` are also available.
+
+## Tests
+
+See the repository root.
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,29 @@
+# @lvy-jsd/dsh-tool-manager bundle patch: one loader entry.
+- insert:
+    - id: tool-manager
+      name: '@lvy-jsd/dsh-tool-manager'
+      config:
+        # Extra always-visible tools on top of the built-in core list.
+        pinned: []
+        # Built-in always-visible tools to move into the directory instead.
+        unpin: []
+        # Model routes never narrowed: their tool list is handed to an external
+        # client once per session and not refreshed (Claude Code's MCP bridge).
+        exemptProviders: [claude-code]
+        # Tools excluded from group loads; must be loaded on their own.
+        # Loading high-risk tools also needs a risk gate plugin
+        # (@lvy-jsd/dsh-tool-manager-risk-gate) to confirm them.
+        highRisk: []
+        # The catalog as text, for a client that cannot lazy-load (Claude Code
+        # reads it through a ~/.claude/CLAUDE.md `@` line). '' turns it off.
+        # manifestFile: ~/.claude/dsh-tool-catalog.md
+        # --- retrieval + routing (tools_find / tools_route / skills_find / skills_route) ---
+        # Model used to re-rank tools_route / skills_route candidates. Leave
+        # unset for pure BM25 (no model, works offline).
+        # model: { provider: deepseek, model: deepseek-chat }
+        # maxTokens: 24
+        # topK: 8
+        # maxBudget: 20000
+        # k1: 1.5
+        # b: 0.75
+        # sidecar: { bin: '', socket: '', timeoutMs: 2000 }

package/lib/catalog.d.ts

@@ -0,0 +1,35 @@
+import type { Annotation, Catalog, CatalogNode, Classifier, RegisteredResolver, ToolEntry, ToolSchema } from './types.js';
+export declare const UNCATEGORIZED = "uncategorized";
+export declare const MISC_GROUP = "misc";
+export declare const OVERRIDE_PRIORITY = 1000;
+export declare const DEFAULT_CATEGORIES: Record<string, string>;
+/**
+ * Structural group for a tool name, used when nothing else places it:
+ * `mcp__server__tool` -> server, `mcp__server__sub__tool` -> server-sub,
+ * `prefix_rest` -> prefix when at least two tools share a non-verb prefix, else misc.
+ */
+export declare function structuralGroup(name: string, prefixCounts: Map<string, number>): string;
+/** Short form of a tool name inside its group (drops the MCP routing prefix). */
+export declare function shortName(name: string): string;
+/** First sentence of a description, capped for one-line listings. */
+export declare function summary(text: string | undefined, max?: number): string;
+/** Rough token cost of one schema as the model receives it. */
+export declare function estimateTokens(schema: unknown): number;
+export interface BuildOptions {
+    /** Placement rules; priority >= OVERRIDE_PRIORITY beats plugin declarations. */
+    classifiers?: readonly Classifier[];
+    annotations?: readonly Annotation[];
+    /** Category vocabulary (name -> description). */
+    categories?: Record<string, string>;
+    /** Tool names configured as high risk. */
+    highRisk?: readonly string[];
+}
+/**
+ * Build the directory index.
+ * @param schemas - catalog tools (pinned already removed)
+ */
+export declare function buildCatalog(schemas: readonly ToolSchema[], { classifiers, annotations, categories, highRisk }?: BuildOptions): Catalog;
+export declare function resolveTarget(catalog: Catalog, raw: unknown, resolvers?: readonly Pick<RegisteredResolver, 'prefix' | 'resolve'>[]): CatalogNode;
+/** Tools under a node (whole tree for root). */
+export declare function toolsUnder(catalog: Catalog, node: CatalogNode): ToolEntry[];
+//# sourceMappingURL=catalog.d.ts.map

package/lib/catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,WAAW,EAAY,UAAU,EAAqB,kBAAkB,EAAE,SAAS,EAAuB,UAAU,EAAE,MAAM,YAAY,CAAA;AAE3K,eAAO,MAAM,aAAa,kBAAkB,CAAA;AAC5C,eAAO,MAAM,UAAU,SAAS,CAAA;AAChC,eAAO,MAAM,iBAAiB,OAAO,CAAA;AAGrC,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAarD,CAAA;AAUD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CASvF;AAED,iFAAiF;AACjF,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAI9C;AAED,qEAAqE;AACrE,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,SAAK,GAAG,MAAM,CAIlE;AAED,+DAA+D;AAC/D,wBAAgB,cAAc,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAMtD;AAqDD,MAAM,WAAW,YAAY;IAC3B,gFAAgF;IAChF,WAAW,CAAC,EAAE,SAAS,UAAU,EAAE,CAAA;IACnC,WAAW,CAAC,EAAE,SAAS,UAAU,EAAE,CAAA;IACnC,iDAAiD;IACjD,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACnC,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAC7B;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,SAAS,UAAU,EAAE,EAAE,EAAE,WAAgB,EAAE,WAAgB,EAAE,UAA+B,EAAE,QAAa,EAAE,GAAE,YAAiB,GAAG,OAAO,CA+D/K;AAqBD,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,SAAS,GAAE,SAAS,IAAI,CAAC,kBAAkB,EAAE,QAAQ,GAAG,SAAS,CAAC,EAAO,GAAG,WAAW,CAiDpJ;AAmBD,gDAAgD;AAChD,wBAAgB,UAAU,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,SAAS,EAAE,CAM3E"}