@jianxx/dsh-cc-tool-search 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/core/tool-search/README.md
+README.md: 3d64b50c6a37ccb683d786ecba7618f888b9015e
+README.zh.md: d347ab0bedf02e7c16a9cd8e98f949263448e550

package/README.md

@@ -0,0 +1,42 @@
+# dsh-tool-search
+
+English | [中文](README.zh.md)
+
+Deferred tool registration plus a model-facing **ToolSearch** tool that loads heavy tools on demand. A tool that is expensive to load or token-heavy in the prompt can be registered **deferred**: it contributes a name, description, and search hint to a searchable registry, but its real definition stays **out of the model-visible schema and prompt** until the model asks for it.
+
+## Why defer tools
+
+Every visible tool schema costs prompt tokens and, for a heavy capability, load time. Most sessions need only a handful of tools from a large catalog. Deferral carries the *capability metadata* cheaply and loads the material definition only when the model actually summons it — generalizing the `shouldDefer`/ToolSearch mechanism (and the MCP `_meta['anthropic/alwaysLoad']` escape hatch) into the harness's effect-based registry model.
+
+## What it does
+
+[`DeferredToolRegistry`](src/index.ts) is the `ctx.toolSearch` service. A plugin registers a capability deferred:
+
+```ts
+ctx.toolSearch.registerDeferred({
+  name: 'big_fs_tool',
+  description: 'Heavy filesystem capability invoked once per session.',
+  searchHint: 'read write edit files',
+  alwaysLoad: false,
+  activate: () => ctx.tools.register(bigFsToolDefinition), // returns the exact disposer
+})
+```
+
+The **ToolSearch** model tool then ranks the deferred set against a `query` (`max_results`, default 5) using weighted substring/token matching over name, `searchHint`, and description. On a hit it calls the registration's `activate()` callback — a real `ctx.tools.register()` — so the tool becomes visible to the **next** assembly and then callable exactly like any top-of-prompt tool. `alwaysLoad: true` registers immediately at defer time and is never a deferred candidate.
+
+The design rides the repo's effect conventions:
+
+- **Deferred registration is an effect.** The returned disposer reclaims the deferred entry *and* any activated `ctx.tools` registration together, so a plugin unloading mid-session tears down both.
+- **Activation is idempotent.** Re-activating an already-loaded tool is a no-op; re-registration (which would throw on a duplicate name) never happens.
+- **Restriction stays authoritative.** `registerDeferred` reserves the tool's name in the `dsh-tools` registry (known but not visible), so a scoped `restrict()` can deny it *before* it loads. ToolSearch checks that gate: a deferred tool a scope denies is **not** activated for that scope, and the result says why.
+- **Search is scope-visible.** A deferred registration lands in the calling scope's layer, and ToolSearch searches the *calling agent's* scope chain (itself and ancestors) — so a tool an agent deferred is visible to that agent's search and its descendants, but a sibling scope or the global view never sees it. A globally-deferred tool remains globally visible as before.
+- **Deferred names never leak into the prompt.** Only activated (`alwaysLoad` or loaded) tools enter the schema; reserved-but-unloaded names are known for restriction/`toolOrder` purposes but never model-visible.
+
+## Model Experience
+
+Turn one, the model sees only `ToolSearch` plus whatever is already loaded (including `alwaysLoad` tools). It searches for a capability by keywords, and the result names the now-available tools. On the next turn those tools are first-class: declare them, call them. Already-loaded tools drop out of the deferred set, so a second search for them is correctly empty.
+
+## Known Limitations and Deferred Work
+
+- **Matching is lexical, not semantic.** Ranking uses weighted substring/token scoring; there is no embedding/vector search. This keeps the seam dependency-free and deterministic, at the cost of synonyms that share no token.
+- **Global activation.** Loading happens on the host plane (global registration); a per-agent scope sees a loaded tool only if its restriction admits it. There is no per-conversation discovery history — loading is an in-memory effect, so a re-registered composition starts from the deferred pool again.

package/README.zh.md

@@ -0,0 +1,41 @@
+# dsh-tool-search
+
+[English](README.md) | 中文
+
+延迟工具注册，外加一个模型可见的 **ToolSearch** 工具，按需加载重工具。一个加载成本高、或提示词里占用 token 很多的工具，可以**延迟**注册：它只贡献名字、描述和搜索提示到这个可搜索的注册表，真正的定义在模型主动索要之前始终**不进模型可见的 schema 与提示词**。
+
+## 为什么要延迟工具
+
+每一个可见的工具 schema 都要花提示词 token，重工具还要花加载时间。大多数会话只需要一个大目录里的一小部分工具。延迟机制以很低的成本携带*能力元数据*，只有当模型真正召唤时才加载实体定义——把 `shouldDefer`/ToolSearch 机制（以及 MCP 的 `_meta['anthropic/alwaysLoad']` 逃生舱）泛化进本仓基于 effect 的注册表模型。
+
+## 它做什么
+
+[`DeferredToolRegistry`](src/index.ts) 就是 `ctx.toolSearch` 服务。插件可以这样延迟注册一个能力：
+
+```ts
+ctx.toolSearch.registerDeferred({
+  name: 'big_fs_tool',
+  description: 'Heavy filesystem capability invoked once per session.',
+  searchHint: 'read write edit files',
+  alwaysLoad: false,
+  activate: () => ctx.tools.register(bigFsToolDefinition), // returns the exact disposer
+})
+```
+
+**ToolSearch** 模型工具随后针对 `query`（`max_results`，默认 5）对延迟集合做排序——在名字、`searchHint`、描述上做加权的子串/词元匹配。命中后就调用该注册的 `activate()` 回调——一次真实的 `ctx.tools.register()`——于是该工具在**下一轮**组装中变得可见，此后与任何提示词顶部的工具无异地被调用。`alwaysLoad: true` 在延迟之时立即注册，且永远不会成为延迟候选。
+
+这套设计贴合本仓的 effect 约定：
+
+- **延迟注册本身就是 effect。** 返回的 disposer 会连同回收延迟条目*以及*任何已激活的 `ctx.tools` 注册，因此插件在会话中途卸载时，两者一起被拆除。
+- **激活是幂等的。** 再次激活一个已加载的工具是空操作；重复注册（否则会因重名而抛错）绝不会发生。
+- **限制仍然优先。** `registerDeferred` 会在 `dsh-tools` 注册表里预留这个工具名（已知但不可见），因此局部的 `restrict()` 可以在它*加载前*将其拒绝。ToolSearch 会检查这道闸：被某个作用域拒绝的延迟工具，绝不会为该作用域激活，结果里会说明原因。
+- **延迟名字永不泄漏进提示词。** 只有已激活（`alwaysLoad` 或已加载）的工具才进 schema；被预留而未加载的名字仅用于限制/`toolOrder` 判定，不对外可见。
+
+## 模型体验
+
+第一轮，模型只看到 `ToolSearch` 加已加载的（包括 `alwaysLoad` 的）工具。它按关键字搜索某个能力，结果里点名现在可用哪些工具。下一轮这些工具就成头等公民：声明它们，调用它们。已加载的工具会退出延迟集合，因此再次搜索它们会正确地得到空结果。
+
+## 已知限制与暂缓事项
+
+- **匹配是词法而非语义的。** 排序用加权的子串/词元打分；没有嵌入/向量检索。这让接缝保持零依赖且确定，代价是无法命中不共享词元的同义词。
+- **全局激活。** 加载发生在宿主平面（全局注册）；某个 per-agent 作用域只有在它的限制放行时才能看到已加载的工具。没有按会话的记忆历史——加载是内存里的 effect，因此重新组装后又会从延迟池重新开始。

package/lib/index.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Deferred tool registration and the model-facing ToolSearch tool that loads
+ * heavy tools on demand.
+ *
+ * A tool that is expensive to load or token-heavy in the prompt can register
+ * DEFERRED: it contributes name + description + search hint to a registry the
+ * model can search, but its real definition stays out of the model-visible
+ * schema and prompt until the model asks for it. The ToolSearch tool ranks the
+ * deferred set against a query and, on a hit, runs the deferred registration's
+ * activation callback — which performs the real `ctx.tools.register()`. Because
+ * registration is an effect, the tool becomes visible to the NEXT assembly and
+ * lives exactly as long as its owning plugin fiber.
+ *
+ * The design generalizes the `shouldDefer`/ToolSearch mechanism (and the MCP
+ * `anthropic/alwaysLoad` escape hatch) into the harness's effect-based registry
+ * model: {@link DeferredToolRegistry.registerDeferred} is itself an effect, and
+ * {@link registry.activate} gate the load behind the calling scope's tool
+ * restriction, so a deferred tool a scope denies is never loaded for it.
+ * @module @jianxx/dsh-cc-tool-search
+ */
+import { Context, Service } from '@deepseek-ai/cordis';
+import type { ScopeKey } from '@deepseek-ai/dsh-scope';
+/** The model-facing ToolSearch tool name. */
+export declare const TOOL_SEARCH_NAME = "ToolSearch";
+/** A deferred registration: capability metadata before its heavy definition loads. */
+export interface DeferredToolRegistration {
+    /** The eventual registered tool name, unique within one deferred registry layer. */
+    readonly name: string;
+    /** The model-facing description, shown in the ToolSearch result and later the tool schema. */
+    readonly description: string;
+    /** A short capability phrase for keyword matching; prefer terms not in the name. */
+    readonly searchHint?: string;
+    /**
+     * Escape hatch that never defers: `true` activates the tool immediately at
+     * registration, generalizing MCP's `_meta['anthropic/alwaysLoad']`. An
+     * `alwaysLoad` tool is registered and model-visible from the start and is
+     * never a ToolSearch candidate.
+     */
+    readonly alwaysLoad?: boolean;
+    /**
+     * Perform the real registration. Called at most once (the first admitting
+     * ToolSearch hit, or immediately for an {@link DeferredToolRegistration.alwaysLoad}
+     * tool). Must register a definition on `ctx.tools` and return that exact
+     * disposer, so the tool unloads with the deferred entry.
+     */
+    readonly activate: () => () => void;
+}
+/** One ranked deferred-tool match returned by a ToolSearch query. */
+export interface DeferredSearchHit {
+    /** The deferred tool name. */
+    readonly name: string;
+    /** The deferred tool description. */
+    readonly description: string;
+    /** The deferred tool's optional search hint. */
+    readonly searchHint?: string;
+}
+/** Result of attempting to load one deferred tool for a scope. */
+export type DeferredActivationResult = {
+    readonly status: 'loaded';
+    readonly name: string;
+} | {
+    readonly status: 'already-loaded';
+    readonly name: string;
+} | {
+    readonly status: 'denied';
+    readonly name: string;
+    readonly reason: string;
+} | {
+    readonly status: 'unknown';
+    readonly name: string;
+};
+/**
+ * Deferred tool registry and the ToolSearch tool.
+ *
+ * Deferred registrations are host-plane effects: they land in the calling
+ * context's scope layer and unwind with it. The tool itself (registered on the
+ * `tools` row) lets a model search the deferred set and load a hit — gated by
+ * the calling agent's tool restriction, so a deferred tool a scope denies is
+ * never loaded for it.
+ */
+export declare class DeferredToolRegistry extends Service {
+    static inject: string[];
+    private readonly layers;
+    constructor(ctx: Context);
+    /**
+     * Register a deferred capability. The name+description (+hint) are searchable
+     * but invisible until activated; an {@link DeferredToolRegistration.alwaysLoad}
+     * tool activates immediately for everyone. Registration is an effect: the
+     * returned disposer removes the deferred entry and, if it was activated, its
+     * real `ctx.tools` registration together.
+     * @param reg - the deferred descriptor and activation callback.
+     * @returns the exact disposer that reclaims both the deferred entry and any loaded tool.
+     */
+    registerDeferred(reg: DeferredToolRegistration): () => void;
+    /**
+     * Rank the deferred, not-yet-loaded tools against a query, searching the scope
+     * chain the caller lives in. Returns the top `maxResults` accessible
+     * candidates in descending relevance. This is the pure matching step; loading
+     * (and its restriction gate) happens in {@link DeferredToolRegistry.activate}.
+     * @param query - free-text keyword query.
+     * @param maxResults - how many hits to return (default 5).
+     * @param scope - the calling scope whose deferred set (and its ancestors') is
+     *   searched; defaults to this registry's own scope ([`scopeOf`]) on the
+     *   service context, which is global for a global registry.
+     * @returns ranked, scored matches that are still deferred.
+     */
+    search(query: string, maxResults?: number, scope?: ScopeKey): DeferredSearchHit[];
+    /**
+     * Load one deferred tool for a scope, idempotently. A hit that the scope's
+     * tool restriction denies is NOT loaded (guard semantics take priority over
+     * ToolSearch, so the loading gate is not an end-run around `restrict()`); an
+     * already-loaded or `alwaysLoad` tool reports `already-loaded` without
+     * re-registering; an absent name reports `unknown`.
+     * @param name - the deferred tool name.
+     * @param scope - the calling agent scope whose restriction gates the load.
+     * @returns the load outcome for the model-facing result.
+     */
+    activate(name: string, scope?: ScopeKey): DeferredActivationResult;
+    /**
+     * Every deferred entry in scope order (global then the scope chain nearest
+     * last) for the calling scope. A caller with no explicit scope searches the
+     * registry's own scope: a global registry resolves to the global layer
+     * (`scopeOf(this.ctx)` is `undefined` on an unscoped service context), while
+     * a registry hosted under a scoped preset backs a child scope so its deferred
+     * set — and its ancestors' — stays visible to it.
+     */
+    private allDeferred;
+    /** Run the entry's activation callback once and retain its disposer. */
+    private activateStore;
+    /** Tear down an activated tool's real registration, if any. */
+    private deactivateStore;
+    /** The model-facing ToolSearch tool, registered once at construction. */
+    private toolDefinition;
+}
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        toolSearch: DeferredToolRegistry;
+    }
+}
+export default DeferredToolRegistry;
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAEtD,OAAO,KAAK,EAAE,QAAQ,EAAc,MAAM,wBAAwB,CAAA;AAMlE,6CAA6C;AAC7C,eAAO,MAAM,gBAAgB,eAAe,CAAA;AAE5C,sFAAsF;AACtF,MAAM,WAAW,wBAAwB;IACvC,oFAAoF;IACpF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,8FAA8F;IAC9F,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,oFAAoF;IACpF,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAA;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,MAAM,IAAI,CAAA;CACpC;AAED,qEAAqE;AACrE,MAAM,WAAW,iBAAiB;IAChC,8BAA8B;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,qCAAqC;IACrC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,gDAAgD;IAChD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAC7B;AAED,kEAAkE;AAClE,MAAM,MAAM,wBAAwB,GAChC;IAAE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACpD;IAAE,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC5D;IAAE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC7E;IAAE,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAA;AA2DzD;;;;;;;;GAQG;AACH,qBAAa,oBAAqB,SAAQ,OAAO;IAC/C,MAAM,CAAC,MAAM,WAAY;IAEzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAKtB;gBAEW,GAAG,EAAE,OAAO;IAOxB;;;;;;;;OAQG;IACH,gBAAgB,CAAC,GAAG,EAAE,wBAAwB,GAAG,MAAM,IAAI;IA4B3D;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,GAAE,MAAU,EAAE,KAAK,CAAC,EAAE,QAAQ,GAAG,iBAAiB,EAAE;IAepF;;;;;;;;;OASG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,QAAQ,GAAG,wBAAwB;IAelE;;;;;;;OAOG;IACH,OAAO,CAAC,WAAW;IAKnB,wEAAwE;IACxE,OAAO,CAAC,aAAa;IAQrB,+DAA+D;IAC/D,OAAO,CAAC,eAAe;IAQvB,yEAAyE;IACzE,OAAO,CAAC,cAAc;CAyEvB;AAqBD,OAAO,QAAQ,qBAAqB,CAAC;IACnC,UAAU,OAAO;QACf,UAAU,EAAE,oBAAoB,CAAA;KACjC;CACF;AAED,eAAe,oBAAoB,CAAA"}

package/lib/index.js

@@ -0,0 +1,297 @@
+/**
+ * Deferred tool registration and the model-facing ToolSearch tool that loads
+ * heavy tools on demand.
+ *
+ * A tool that is expensive to load or token-heavy in the prompt can register
+ * DEFERRED: it contributes name + description + search hint to a registry the
+ * model can search, but its real definition stays out of the model-visible
+ * schema and prompt until the model asks for it. The ToolSearch tool ranks the
+ * deferred set against a query and, on a hit, runs the deferred registration's
+ * activation callback — which performs the real `ctx.tools.register()`. Because
+ * registration is an effect, the tool becomes visible to the NEXT assembly and
+ * lives exactly as long as its owning plugin fiber.
+ *
+ * The design generalizes the `shouldDefer`/ToolSearch mechanism (and the MCP
+ * `anthropic/alwaysLoad` escape hatch) into the harness's effect-based registry
+ * model: {@link DeferredToolRegistry.registerDeferred} is itself an effect, and
+ * {@link registry.activate} gate the load behind the calling scope's tool
+ * restriction, so a deferred tool a scope denies is never loaded for it.
+ * @module @jianxx/dsh-cc-tool-search
+ */
+import { Service } from '@deepseek-ai/cordis';
+import { NamedEntries, ScopedLayers, scopeOf } from '@deepseek-ai/dsh-scope';
+import { defineTool } from '@jianxx/dsh-cc-tools';
+/** The model-facing ToolSearch tool name. */
+export const TOOL_SEARCH_NAME = 'ToolSearch';
+/** One scope's aggregate deferred-tool registration. */
+class DeferredLayer {
+    tools = new NamedEntries(name => new Error(`tool "${name}" is already registered as deferred in this scope`));
+    isEmpty() {
+        return this.tools.isEmpty();
+    }
+}
+/**
+ * How much a deferred tool matches a query, summed over query tokens and the
+ * weighted name/description/searchHint fields. `name` carries the most weight,
+ * `searchHint` next, then `description`; an exact name match is conclusive.
+ * Pure and deterministic: used only to rank the candidate set.
+ * @param stored - the deferred registration.
+ * @param query - the raw ToolSearch query.
+ * @returns a non-negative score; `0` means no match.
+ */
+function scoreStored(stored, query) {
+    const q = query.toLowerCase().trim();
+    if (q.length === 0)
+        return 0;
+    const qTokens = tokenize(q);
+    const fields = [
+        [stored.reg.name.toLowerCase(), 10],
+        [(stored.reg.searchHint ?? '').toLowerCase(), 4],
+        [stored.reg.description.toLowerCase(), 2],
+    ];
+    let total = 0;
+    for (const [text, weight] of fields) {
+        if (text.length === 0)
+            continue;
+        for (const token of qTokens) {
+            if (token.length === 0)
+                continue;
+            if (text.includes(token)) {
+                total += weight;
+            }
+            else if (tokenize(text).some(word => word.startsWith(token) || token.startsWith(word))) {
+                total += Math.max(1, Math.floor(weight / 2));
+            }
+        }
+    }
+    return total;
+}
+/** Lowercase the input and split into alphanumeric tokens, dropping empty ones. */
+function tokenize(value) {
+    return value.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
+}
+/**
+ * Deferred tool registry and the ToolSearch tool.
+ *
+ * Deferred registrations are host-plane effects: they land in the calling
+ * context's scope layer and unwind with it. The tool itself (registered on the
+ * `tools` row) lets a model search the deferred set and load a hit — gated by
+ * the calling agent's tool restriction, so a deferred tool a scope denies is
+ * never loaded for it.
+ */
+export class DeferredToolRegistry extends Service {
+    static inject = ['tools'];
+    layers = new ScopedLayers(() => new DeferredLayer(), 
+    // Deferred-set changes are not model-visible (deferred tools never enter
+    // the prompt); actual activations fire `tools/change` through `register()`.
+    () => { });
+    constructor(ctx) {
+        super(ctx, 'toolSearch');
+        // The ToolSearch tool itself is never deferred: it is the load path, so it
+        // must be visible on the first assembly.
+        ctx.tools.register(this.toolDefinition());
+    }
+    /**
+     * Register a deferred capability. The name+description (+hint) are searchable
+     * but invisible until activated; an {@link DeferredToolRegistration.alwaysLoad}
+     * tool activates immediately for everyone. Registration is an effect: the
+     * returned disposer removes the deferred entry and, if it was activated, its
+     * real `ctx.tools` registration together.
+     * @param reg - the deferred descriptor and activation callback.
+     * @returns the exact disposer that reclaims both the deferred entry and any loaded tool.
+     */
+    registerDeferred(reg) {
+        const stored = {
+            reg,
+            alwaysLoad: reg.alwaysLoad === true,
+            activated: false,
+            disposer: undefined,
+        };
+        const unwind = this.layers.effect(this.ctx, (layer) => {
+            const undo = layer.tools.insert(reg.name, stored);
+            if (stored.alwaysLoad)
+                this.activateStore(stored);
+            return () => {
+                undo();
+                this.deactivateStore(stored);
+            };
+        }, { label: 'toolSearch.registerDeferred()' });
+        // Reserve the name in the tools registry so a scoped restriction can gate
+        // it before its definition loads (restrict only names known capabilities).
+        const reserve = this.ctx.tools.reserve(reg.name);
+        return () => {
+            unwind();
+            reserve();
+        };
+    }
+    /**
+     * Rank the deferred, not-yet-loaded tools against a query, searching the scope
+     * chain the caller lives in. Returns the top `maxResults` accessible
+     * candidates in descending relevance. This is the pure matching step; loading
+     * (and its restriction gate) happens in {@link DeferredToolRegistry.activate}.
+     * @param query - free-text keyword query.
+     * @param maxResults - how many hits to return (default 5).
+     * @param scope - the calling scope whose deferred set (and its ancestors') is
+     *   searched; defaults to this registry's own scope ([`scopeOf`]) on the
+     *   service context, which is global for a global registry.
+     * @returns ranked, scored matches that are still deferred.
+     */
+    search(query, maxResults = 5, scope) {
+        const candidates = [];
+        for (const stored of this.allDeferred(scope)) {
+            if (stored.alwaysLoad || stored.activated)
+                continue;
+            const score = scoreStored(stored, query);
+            if (score > 0)
+                candidates.push({ stored, score });
+        }
+        candidates.sort((a, b) => b.score - a.score || a.stored.reg.name.localeCompare(b.stored.reg.name));
+        return candidates.slice(0, maxResults).map(({ stored }) => ({
+            name: stored.reg.name,
+            description: stored.reg.description,
+            ...stored.reg.searchHint !== undefined ? { searchHint: stored.reg.searchHint } : {},
+        }));
+    }
+    /**
+     * Load one deferred tool for a scope, idempotently. A hit that the scope's
+     * tool restriction denies is NOT loaded (guard semantics take priority over
+     * ToolSearch, so the loading gate is not an end-run around `restrict()`); an
+     * already-loaded or `alwaysLoad` tool reports `already-loaded` without
+     * re-registering; an absent name reports `unknown`.
+     * @param name - the deferred tool name.
+     * @param scope - the calling agent scope whose restriction gates the load.
+     * @returns the load outcome for the model-facing result.
+     */
+    activate(name, scope) {
+        const stored = this.allDeferred(scope).find(candidate => candidate.reg.name === name);
+        if (stored === undefined) {
+            return { status: 'unknown', name };
+        }
+        if (stored.alwaysLoad || stored.activated) {
+            return { status: 'already-loaded', name };
+        }
+        if (!this.ctx.tools.isAdmitted(name, scope)) {
+            return { status: 'denied', name, reason: `"${name}" is restricted for this agent; loading it would be refused` };
+        }
+        this.activateStore(stored);
+        return { status: 'loaded', name };
+    }
+    /**
+     * Every deferred entry in scope order (global then the scope chain nearest
+     * last) for the calling scope. A caller with no explicit scope searches the
+     * registry's own scope: a global registry resolves to the global layer
+     * (`scopeOf(this.ctx)` is `undefined` on an unscoped service context), while
+     * a registry hosted under a scoped preset backs a child scope so its deferred
+     * set — and its ancestors' — stays visible to it.
+     */
+    allDeferred(scope) {
+        const key = scope ?? scopeOf(this.ctx) ?? undefined;
+        return [...this.layers.merge(key, layer => layer.tools).values()];
+    }
+    /** Run the entry's activation callback once and retain its disposer. */
+    activateStore(stored) {
+        if (stored.activated)
+            return;
+        // The callback performs `ctx.tools.register(...)` and returns that exact
+        // disposer, so unloading the deferred entry also unregisters the tool.
+        stored.disposer = stored.reg.activate();
+        stored.activated = true;
+    }
+    /** Tear down an activated tool's real registration, if any. */
+    deactivateStore(stored) {
+        if (stored.activated) {
+            stored.disposer?.();
+            stored.disposer = undefined;
+            stored.activated = false;
+        }
+    }
+    /** The model-facing ToolSearch tool, registered once at construction. */
+    toolDefinition() {
+        return defineTool({
+            name: TOOL_SEARCH_NAME,
+            description: 'Search for deferred tools that are NOT currently loaded, then load the ones you need by their name. '
+                + 'Deferred tools are capabilities (e.g. filesystem, shell, or web tools) omitted from your function list to save prompt '
+                + 'space. Search with the capability you need; loading a tool makes it available to call exactly like any tool defined at '
+                + 'the top of the prompt. Loading is idempotent: loading an already-available tool is a harmless no-op.',
+            parameters: {
+                query: {
+                    type: 'string',
+                    required: true,
+                    description: 'The capability or tool to find, as keywords (e.g. "read file", "edit", "bash").',
+                },
+                max_results: {
+                    type: 'number',
+                    description: 'How many matching deferred tools to evaluate (default 5).',
+                },
+            },
+            output: {
+                schema: {
+                    type: 'object',
+                    additionalProperties: false,
+                    properties: {
+                        query: { type: 'string', required: true },
+                        results: {
+                            type: 'array',
+                            required: true,
+                            items: {
+                                type: 'object',
+                                additionalProperties: false,
+                                properties: {
+                                    name: { type: 'string', required: true },
+                                    description: { type: 'string', required: true },
+                                    status: {
+                                        type: 'string',
+                                        required: true,
+                                        enum: ['loaded', 'already-loaded', 'unknown', 'denied'],
+                                    },
+                                    reason: { type: 'string' },
+                                },
+                            },
+                        },
+                    },
+                },
+                render: (_args, value) => [{
+                        type: 'text',
+                        text: renderToolSearchText(value.query, value.results),
+                    }],
+            },
+            // Arrow bodies keep `this` bound to the registry service; the schema
+            // narrows args to match the parameter spec (`query` required, `max_results`
+            // optional).
+            execute: (args, exec) => {
+                const scope = exec.agent;
+                const maxResults = args.max_results ?? 5;
+                const hits = this.search(args.query, maxResults, scope);
+                const results = hits.map((hit) => {
+                    const outcome = this.activate(hit.name, scope);
+                    return {
+                        name: outcome.name,
+                        description: hit.description,
+                        status: outcome.status,
+                        ...outcome.status === 'denied' ? { reason: outcome.reason } : {},
+                    };
+                });
+                return Promise.resolve({ query: args.query, results });
+            },
+            presentCall: (args) => ({ card: 'generic', title: 'Search deferred tools', kind: 'search', rawInput: args.query }),
+            presentResult: (_args, result) => ({ card: 'generic', title: 'Tool search', content: result.content }),
+        });
+    }
+}
+/** Compose the model-facing summary of a ToolSearch outcome. */
+function renderToolSearchText(query, results) {
+    if (results.length === 0) {
+        return `No deferred tools matched "${query}".`;
+    }
+    const lines = results.map((result) => {
+        const statusLabel = result.status === 'loaded' ? 'now available'
+            : result.status === 'already-loaded' ? 'already available'
+                : result.status === 'denied' ? 'denied'
+                    : 'not found';
+        const tail = result.status === 'denied' && result.reason !== undefined ? ` — ${result.reason}` : '';
+        return `- ${result.name}: ${result.description} (${statusLabel})${tail}`;
+    });
+    return `ToolSearch "${query}":\n${lines.join('\n')}`;
+}
+export default DeferredToolRegistry;
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/lib/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@jianxx/dsh-cc-tool-search`.
+ * @module @jianxx/dsh-cc-tool-search/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "tool-search-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/invariant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invariant.d.ts","sourceRoot":"","sources":["../src/invariant.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAKlD,oCAAoC;AACpC,eAAO,MAAM,IAAI,0BAA0B,CAAA;AAC3C,2EAA2E;AAC3E,eAAO,MAAM,MAAM,UAAiB,CAAA;AAUpC;;;;GAIG;AACH,eAAO,MAAM,KAAK,GAAI,KAAK,OAAO,KAAG,OAAO,CAAC,MAAM,IAAI,CACU,CAAA"}

package/lib/invariant.js

@@ -0,0 +1,24 @@
+/**
+ * Package-owned invariant companion for `@jianxx/dsh-cc-tool-search`.
+ * @module @jianxx/dsh-cc-tool-search/invariant
+ */
+const PACKAGE_NAME = '@jianxx/dsh-cc-tool-search';
+/** Cordis companion plugin name. */
+export const name = 'tool-search-invariant';
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants'];
+/**
+ * No runtime invariant: this package owns no event or snapshot of its own. The
+ * relation it establishes — a deferred tool being loaded into the tool registry
+ * after a ToolSearch hit — is the tool registry's to hold, and `dsh-tools`
+ * observes registration there through `tools/change`.
+ */
+const install = () => { };
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+/* jscpd:ignore-end */
+//# sourceMappingURL=invariant.js.map

package/lib/invariant.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invariant.js","sourceRoot":"","sources":["../src/invariant.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,MAAM,YAAY,GAAG,4BAA4B,CAAA;AAEjD,oCAAoC;AACpC,MAAM,CAAC,MAAM,IAAI,GAAG,uBAAuB,CAAA;AAC3C,2EAA2E;AAC3E,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,YAAY,CAAC,CAAA;AAEpC;;;;;GAKG;AACH,MAAM,OAAO,GAAuB,GAAG,EAAE,GAAE,CAAC,CAAA;AAE5C;;;;GAIG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,GAAY,EAAuB,EAAE,CACzD,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC,CAAA;AACjE,sBAAsB"}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@jianxx/dsh-cc-tool-search",
+  "description": "Deferred tool registration and a ToolSearch model tool that loads heavy tools on demand",
+  "version": "0.1.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jianxx/dsh-cc-plugins.git",
+    "directory": "packages/core/tool-search"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib"
+  ],
+  "license": "Apache-2.0",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": ">=0.1.1-rc.2",
+    "@deepseek-ai/dsh-scope": ">=0.1.1-rc.2",
+    "@deepseek-ai/dsh-system-prompt": ">=0.1.1-rc.2",
+    "@deepseek-ai/cordis": ">=0.1.1-rc.2",
+    "@jianxx/dsh-cc-tools": "^0.1.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-agent": "link:../../../../deepseek-harness/packages/core/agent",
+    "@deepseek-ai/dsh-invariants": "link:../../../../deepseek-harness/packages/runtime-diagnostics/invariants",
+    "@deepseek-ai/dsh-llm": "link:../../../../deepseek-harness/packages/llm/llm",
+    "@deepseek-ai/dsh-scope": "link:../../../../deepseek-harness/packages/core/scope",
+    "@deepseek-ai/dsh-session": "link:../../../../deepseek-harness/packages/core/session",
+    "@deepseek-ai/dsh-system-prompt": "link:../../../../deepseek-harness/packages/core/system-prompt",
+    "@deepseek-ai/cordis": "link:../../../../deepseek-harness/vendor/cordis",
+    "@jianxx/dsh-cc-tools": "^0.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}