@xuanling-rs/xuanling-dsh-tools 0.2.10 → 0.3.1

package/README-ZH.md

@@ -6,19 +6,19 @@
 原生工具，并以 `mcp__xuanling__` 前缀增加 XuanLing 工具。
 
 ```sh
-dsh plugin --profile web add @xuanling-rs/xuanling-dsh-tools@0.2.10
+dsh plugin --profile web add @xuanling-rs/xuanling-dsh-tools@0.3.1
 ```
 
 该命令会扩展 DSH 内置的 Web profile。内置 Headless profile 应使用 `--profile headless`。
 未知 profile 名称只包含 base bundle，本身不会提供可运行的 Web 或 Headless 应用。
 
-精确版本的 `@xuanling-rs/xuanling-mcp@0.2.10` runtime 会安装在 profile 内，并通过带校验的 JS launcher
-启动；不需要也不会使用全局 npm package。只有文件系统 capability root 与 DSH 工作目录不同时，
-才需要设置 `XUANLING_WORKSPACE_ROOT`。
+精确版本的 `@xuanling-rs/xuanling-mcp@0.3.1` runtime 会安装在 profile 内，并通过带校验的 JS launcher
+启动；不需要也不会使用全局 npm package。启动 DSH 前必须把 `XUANLING_WORKSPACE_ROOT` 设置为
+已确认的绝对 workspace；缺失时 bundle 会启动失败，DSH 进程工作目录不会被当成用户授权。
 
-Bridge 会缓存 MCP 分页中的全部定义，但起初只暴露 `mcp_catalog__xuanling`。应按名称或描述检索并
-激活精确 raw name；选中的定义会在下一次模型请求中作为 `mcp__xuanling__*` 工具出现。不要预先
-激活完整目录。
+Bundle 自带的 lazy wrapper 会让官方 bridge 缓存 MCP 分页中的全部定义，但起初只暴露
+`mcp_catalog__xuanling`。应按名称或描述检索，并在每次调用中激活一个精确 raw name；选中的定义
+会在下一次模型请求中作为 `mcp__xuanling__*` 工具出现。不要预先激活完整目录。
 
 该 bundle 的 result adapter 会保留完整 Native 文本投影，只删除与 `structuredContent` 完全重复的
 意外文本块。

package/README.md

@@ -7,22 +7,24 @@ keeps all Harness-native tools enabled and adds XuanLing tools under the
 `mcp__xuanling__` prefix.
 
 ```sh
-dsh plugin --profile web add @xuanling-rs/xuanling-dsh-tools@0.2.10
+dsh plugin --profile web add @xuanling-rs/xuanling-dsh-tools@0.3.1
 ```
 
 This command augments DSH's shipped Web profile. Use `--profile headless` for
 the shipped Headless profile. Unknown profile names start with the base bundle
 only and do not provide a runnable Web or Headless application by themselves.
 
-The exact `@xuanling-rs/xuanling-mcp@0.2.10` runtime is installed in the profile and started
+The exact `@xuanling-rs/xuanling-mcp@0.3.1` runtime is installed in the profile and started
 through its verified JS launcher. A global npm package is neither required nor
-used. Set `XUANLING_WORKSPACE_ROOT` only when the filesystem capability root
-must differ from the DSH working directory.
-
-The bridge caches every paginated MCP definition but initially exposes only
-`mcp_catalog__xuanling`. Search by name or description and activate exact raw
-names; the selected definitions appear as `mcp__xuanling__*` tools on the next
-model request. Do not activate the complete catalog speculatively.
+used. Set `XUANLING_WORKSPACE_ROOT` to the confirmed absolute workspace before
+starting DSH; the bundle fails startup when it is absent and never treats the
+DSH process working directory as user authorization.
+
+The bundle-owned lazy wrapper lets the official bridge cache every paginated
+MCP definition but initially exposes only `mcp_catalog__xuanling`. Search by
+name or description and activate one exact raw name per call; the selected
+definition appears as an `mcp__xuanling__*` tool on the next model request. Do
+not activate the complete catalog speculatively.
 
 The bundle's result adapter preserves the complete Native text projection and
 removes only accidental duplicate text blocks that exactly repeat

package/cordis.patch.yml

@@ -1,27 +1,28 @@
 # XuanLing tools for DeepSeek Harness — additive variant.
 #
 # Mounts the xuanling-mcp binary through the local result adapter and the
-# official @deepseek-ai/dsh-mcp-client bridge. The bridge caches every XuanLing
-# definition and exposes mcp_catalog__xuanling first; exact activations become
-# native mcp__xuanling__<raw> tools. It owns reconnect, re-sync, and generation rollback. Built-in tools
-# (read/write/edit/glob/grep/bash/…) stay registered — this variant only ADDS.
+# official @deepseek-ai/dsh-mcp-client bridge through a bundle-owned lazy
+# wrapper. The bridge caches every XuanLing definition; the wrapper exposes
+# mcp_catalog__xuanling first and registers exact activations as native
+# mcp__xuanling__<raw> tools. The official bridge still owns reconnect,
+# re-sync, and generation rollback. Built-in tools stay registered.
 #
 # The bundle resolves its exact result adapter and xuanling-mcp dependency from
 # the DSH profile. The JS launcher then selects and verifies the matching native
 # package; the adapter preserves one complete text projection and structured value.
 #
-# The filesystem capability root defaults to the directory dsh was started
-# from; override with XUANLING_WORKSPACE_ROOT. Memory uses the shared default
+# The filesystem capability root is explicit. XUANLING_WORKSPACE_ROOT must
+# name the confirmed absolute workspace; missing configuration fails startup.
+# Memory uses the shared default
 # database (~/.xuanling/memory.db) exactly like the ZCode plugin deployment.
 # The ZCode-only object-parameter compat shim stays OFF everywhere in this
 # integration: DeepSeek forwards model arguments as verbatim JSON.
 
 - insert:
     - id: xuanling-tools
-      name: '@deepseek-ai/dsh-mcp-client'
+      name: '@xuanling-rs/xuanling-dsh-tools/lazy-mcp-client.mjs'
       config:
         serverName: xuanling
-        toolExposure: lazy
         transport: stdio
         command: !!js process.execPath
         args:
@@ -31,5 +32,5 @@
           - '--'
           - !!js process.getBuiltinModule('node:module').createRequire(baseUrl).resolve('@xuanling-rs/xuanling-mcp/bin/xuanling-mcp.js')
           - '--workspace-root'
-          - !!js process.env.XUANLING_WORKSPACE_ROOT ?? process.cwd()
+          - !!js (() => { const root = process.env.XUANLING_WORKSPACE_ROOT; if (!root) throw new Error('XUANLING_WORKSPACE_ROOT is required for the XuanLing full-tools bundle'); return root })()
         toolCallTimeoutMs: 120000

package/lazy-mcp-client.mjs

@@ -0,0 +1,234 @@
+const REQUIRED_SERVER_NAME = "xuanling";
+const CATALOG_NAME = "mcp_catalog__xuanling";
+const MAX_MATCHES = 8;
+
+export const name = "xuanling-lazy-mcp-client";
+export const inject = ["tools"];
+
+function bindMember(target, property) {
+  const value = Reflect.get(target, property, target);
+  return typeof value === "function" ? value.bind(target) : value;
+}
+
+function rawNameFromPublicName(serverName, publicName) {
+  // The release contract proves every XuanLing raw name is already valid in
+  // DSH's public-name space, so the official bridge performs no lossy rewrite.
+  const prefix = `mcp__${serverName}__`;
+  if (typeof publicName !== "string" || !publicName.startsWith(prefix)) {
+    throw new Error(
+      `[XUANLING_LAZY_NAME_MISMATCH] bridge registered ${JSON.stringify(publicName)} outside ${prefix}`,
+    );
+  }
+  const rawName = publicName.slice(prefix.length);
+  if (rawName.length === 0 || `${prefix}${rawName}` !== publicName) {
+    throw new Error(
+      `[XUANLING_LAZY_NAME_MISMATCH] bridge public name is not reversibly qualified: ${publicName}`,
+    );
+  }
+  return rawName;
+}
+
+function createCatalogDefinition(state) {
+  return {
+    name: CATALOG_NAME,
+    description:
+      "Search cached XuanLing MCP tools by raw name or description and optionally activate one exact raw name for subsequent model turns.",
+    parameters: {
+      type: "object",
+      properties: {
+        query: {
+          type: "string",
+          description: "Case-insensitive search text. Empty text lists the first bounded page.",
+        },
+        activate: {
+          type: "string",
+          description: "Optional exact raw MCP tool name to activate. Identity matching is case-sensitive.",
+        },
+      },
+      required: ["query"],
+      additionalProperties: false,
+    },
+    output: {
+      schema: {
+        type: "object",
+        properties: {
+          query: { type: "string" },
+          total_tools: { type: "integer" },
+          matched_tools: { type: "integer" },
+          matches: {
+            type: "array",
+            items: {
+              type: "object",
+              properties: {
+                raw_name: { type: "string" },
+                public_name: { type: "string" },
+                description: { type: "string" },
+                active: { type: "boolean" },
+              },
+              required: ["raw_name", "public_name", "description", "active"],
+              additionalProperties: false,
+            },
+          },
+          active_tools: { type: "array", items: { type: "string" } },
+          activated: { type: "string" },
+          truncated: { type: "boolean" },
+        },
+        required: ["query", "total_tools", "matched_tools", "matches", "active_tools", "truncated"],
+        additionalProperties: false,
+      },
+      render(_arguments, value) {
+        return [{ type: "text", text: JSON.stringify(value) }];
+      },
+    },
+    async execute(argumentsValue) {
+      if (
+        typeof argumentsValue !== "object" ||
+        argumentsValue === null ||
+        Array.isArray(argumentsValue) ||
+        typeof argumentsValue.query !== "string" ||
+        (argumentsValue.activate !== undefined && typeof argumentsValue.activate !== "string")
+      ) {
+        throw new Error("[XUANLING_CATALOG_INVALID_ARGUMENTS] query must be a string and activate must be an optional string");
+      }
+
+      let activated;
+      if (argumentsValue.activate !== undefined) {
+        activated = state.activate(argumentsValue.activate);
+      }
+
+      const normalizedQuery = argumentsValue.query.trim().toLocaleLowerCase("en-US");
+      const allMatches = [...state.definitions.entries()]
+        .map(([rawName, record]) => ({
+          raw_name: rawName,
+          public_name: record.definition.name,
+          description: typeof record.definition.description === "string"
+            ? record.definition.description
+            : "",
+          active: state.isActive(rawName),
+        }))
+        .filter((entry) =>
+          normalizedQuery.length === 0 ||
+          entry.raw_name.toLocaleLowerCase("en-US").includes(normalizedQuery) ||
+          entry.description.toLocaleLowerCase("en-US").includes(normalizedQuery)
+        )
+        .sort((left, right) => left.raw_name.localeCompare(right.raw_name, "en-US"));
+
+      return {
+        query: argumentsValue.query,
+        total_tools: state.definitions.size,
+        matched_tools: allMatches.length,
+        matches: allMatches.slice(0, MAX_MATCHES),
+        active_tools: state.activeRawNames(),
+        ...(activated === undefined ? {} : { activated }),
+        truncated: allMatches.length > MAX_MATCHES,
+      };
+    },
+  };
+}
+
+export async function applyWithOfficialBridge(ctx, config, applyOfficialBridge) {
+  if (config?.serverName !== REQUIRED_SERVER_NAME) {
+    throw new Error(
+      `[XUANLING_LAZY_INVALID_SERVER] expected serverName ${REQUIRED_SERVER_NAME}, got ${JSON.stringify(config?.serverName)}`,
+    );
+  }
+  if (typeof applyOfficialBridge !== "function") {
+    throw new Error("[XUANLING_LAZY_INVALID_BRIDGE] official bridge apply export is unavailable");
+  }
+
+  const definitions = new Map();
+  const desiredActiveNames = new Set();
+  const registeredActive = new Map();
+
+  function registerActive(rawName, record) {
+    const previous = registeredActive.get(rawName);
+    if (previous !== undefined) previous.dispose();
+    const dispose = ctx.tools.register(record.definition);
+    registeredActive.set(rawName, { record, dispose });
+  }
+
+  function captureDefinition(definition) {
+    const rawName = rawNameFromPublicName(config.serverName, definition?.name);
+    if (definitions.has(rawName)) {
+      throw new Error(`[XUANLING_LAZY_DUPLICATE_TOOL] duplicate raw tool name: ${rawName}`);
+    }
+    const record = { definition };
+    definitions.set(rawName, record);
+    if (desiredActiveNames.has(rawName)) registerActive(rawName, record);
+
+    let disposed = false;
+    return () => {
+      if (disposed) return;
+      disposed = true;
+      if (definitions.get(rawName) !== record) return;
+      definitions.delete(rawName);
+      const active = registeredActive.get(rawName);
+      if (active?.record === record) {
+        active.dispose();
+        registeredActive.delete(rawName);
+      }
+    };
+  }
+
+  const projectedTools = new Proxy(ctx.tools, {
+    get(target, property) {
+      if (property === "register") return captureDefinition;
+      return bindMember(target, property);
+    },
+  });
+  const projectedContext = new Proxy(ctx, {
+    get(target, property) {
+      if (property === "tools") return projectedTools;
+      return bindMember(target, property);
+    },
+  });
+
+  await applyOfficialBridge(projectedContext, { ...config, failOnStartupError: true });
+  if (definitions.size === 0) {
+    throw new Error("[XUANLING_LAZY_EMPTY_CATALOG] official bridge discovered no XuanLing tools");
+  }
+
+  const state = {
+    definitions,
+    activate(rawName) {
+      const record = definitions.get(rawName);
+      if (record === undefined) {
+        throw new Error(`[XUANLING_CATALOG_UNKNOWN_TOOL] exact raw tool name not found: ${JSON.stringify(rawName)}`);
+      }
+      if (!desiredActiveNames.has(rawName)) {
+        desiredActiveNames.add(rawName);
+        try {
+          registerActive(rawName, record);
+        } catch (error) {
+          desiredActiveNames.delete(rawName);
+          throw error;
+        }
+      }
+      return rawName;
+    },
+    isActive(rawName) {
+      return registeredActive.has(rawName);
+    },
+    activeRawNames() {
+      return [...registeredActive.keys()].sort((left, right) => left.localeCompare(right, "en-US"));
+    },
+  };
+
+  ctx.effect(
+    () => () => {
+      desiredActiveNames.clear();
+      for (const active of [...registeredActive.values()].reverse()) active.dispose();
+      registeredActive.clear();
+    },
+    "xuanling.lazy-mcp-active-tools",
+  );
+  ctx.effect(
+    () => ctx.tools.register(createCatalogDefinition(state)),
+    "xuanling.lazy-mcp-catalog",
+  );
+}
+
+export async function apply(ctx, config) {
+  const bridge = await import("@deepseek-ai/dsh-mcp-client");
+  return applyWithOfficialBridge(ctx, config, bridge.apply);
+}

package/package.json

@@ -1,18 +1,19 @@
 {
   "name": "@xuanling-rs/xuanling-dsh-tools",
-  "version": "0.2.10",
-  "description": "DeepSeek Harness bundle: mount the XuanLing MCP server (xuanling-mcp binary) as native mcp__xuanling__* tools through the official @deepseek-ai/dsh-mcp-client bridge. Additive variant: built-in tools stay enabled.",
+  "version": "0.3.1",
+  "description": "DeepSeek Harness bundle: lazily mount XuanLing through a bundle-owned wrapper around the official MCP bridge. Additive variant: built-in tools stay enabled.",
   "license": "MIT",
   "private": false,
   "dependencies": {
     "@deepseek-ai/dsh-mcp-client": "^0.1.0-rc.5",
-    "@xuanling-rs/xuanling-mcp": "0.2.10"
+    "@xuanling-rs/xuanling-mcp": "0.3.1"
   },
   "files": [
     "LICENSE",
     "README.md",
     "README-ZH.md",
     "cordis.patch.yml",
+    "lazy-mcp-client.mjs",
     "mcp-result-adapter.mjs"
   ],
   "dsh": {
@@ -38,6 +39,6 @@
     "registry": "https://registry.npmjs.org"
   },
   "xuanlingRelease": {
-    "sourceCommit": "8f87bec7959a708109c3b10dee3539e0946c7282"
+    "sourceCommit": "df27d2e962d33731e4beba44f23ed1fd58adaae6"
   }
 }