@huanlin/dsh-plugin-better-glob 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 huanlinoto
+
+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

@@ -0,0 +1,69 @@
+<p align="center">
+  <a href="https://dshfind.com/zh/plugins/huanlinoto/dsh-plugin-better-glob"><img src="https://dshfind.com/api/card/huanlinoto/dsh-plugin-better-glob?lang=zh" alt="dsh-plugin-better-glob card"></a>
+</p>
+
+# dsh-plugin-better-glob
+
+以 **per-agent 阴影**顶替 DSH 内置 `glob` 工具：自动排除无底洞目录（`node_modules`、`dist`、`build`、`.venv` 等），模型要搜这些目录时必须显式传 `include` 白名单。`grep` 不受影响，不改任何内置插件注册面。
+
+## 为什么是 per-agent 阴影
+
+- 工具注册表按 scope 分层解析：**agent 自己层的注册遮蔽一切继承层**（headless 的全局层、web profile 里 preset 挂载的 standing scope 层）。
+- 全局注册在 web profile 下会输给 preset 挂载；bundle patch 够不到 preset 文件。所以唯一全覆盖的机制是监听 `agent/session-start`，把同名工具经 `agent.ctx` 注册进 agent 自己的层 —— 同时注册同名 `tool:glob` 提示词 section（同 order）遮蔽内置文案。
+- `startup`/`resume`/`clear`/`compact` 都会触发 session-start，WeakSet 保证幂等；插件配置热重载时对存活 agent 做dispose-再注册的 resync。
+
+## 工具行为
+
+- `pattern`（必填）/ `path`（可选）：与内置 glob 语义一致，mtime 排序、含隐藏与被 ignore 文件、100 条封顶 + spill 恢复。
+- **`include`（可选，string[]）**：白名单。include 模式的路径段命中某排除目录名 → 该目录在本调用中被放行（argv 构造期摘掉它的否定 glob）；`include: ["**"]` 放行全部。include 永不过滤结果 —— `pattern` 才是匹配器。
+- 排除的实现在 argv 构造期而非后置 glob：ripgrep 在遍历期 prune 掉被排除目录，后置 glob 救不回被剪的子树。
+- VCS 目录（`.git/.svn/.hg/.bzr/.jj/.sl`）永远排除，不配置化。
+- 执行底座复用内置 `@deepseek-ai/dsh-tool-fs-search` 的打包 ripgrep 二进制、subprocess 缝、错误词汇表与 spill 设施。
+
+### 默认排除清单（`excludeDirs` 整体替换式）
+
+`node_modules` `bower_components` `vendor` `Pods` `.yarn` `dist` `build` `out` `target` `obj` `.next` `.nuxt` `.output` `.svelte-kit` `.turbo` `.parcel-cache` `.cache` `coverage` `__pycache__` `.venv` `venv` `.tox` `.mypy_cache` `.pytest_cache` `.ruff_cache` `.gradle` `.terraform` `.idea`
+
+### 配置
+
+| 字段 | 默认 | 说明 |
+|------|------|------|
+| `excludeDirs` | 上表 | 排除目录名（裸名，不允许分隔符），整体替换默认清单 |
+| `sampleOverCapGlobResults` | `false` | 超帽页是否按顶层条目抽样（同内置开关） |
+| `globMaxResults` | `100` | 单次内联保留路径数，超出部分 spill |
+| `globMetaMaxBytes` | `65536` | 卡片 meta 字节预算 |
+| `rawOutputMaxBytes` | `20000000` | 单次解析的 rg stdout 上限 |
+| `graceMs` / `stderrMaxBytes` / `timeoutMs` | `3000` / `65536` / `30000` | 同内置语义 |
+
+## 开发
+
+```sh
+pnpm install            # pnpm-workspace.yaml 锚定本目录（防止向上并入 D:\Projects 的 workspace）
+pnpm exec node scripts/relink-deps.mjs   # 把 @deepseek-ai/* junction 到 ~/.dsh/source/current 的已构建包（pretest/prebuild 自动跑）
+pnpm run typecheck      # tsc --noEmit（类型经 tsconfig paths 解析 source/current 的 lib/types）
+pnpm test               # vitest：argv/meta 纯逻辑 + 真实 ToolRuntime 组合 preflight
+pnpm run build          # tsdown（lib/index.js）+ tsc（lib/types/*.d.ts）
+```
+
+peer 依赖（`@deepseek-ai/cordis`、`dsh-tools`、`dsh-tool-fs-search`、`dsh-system-prompt`、`dsh-agent`）由宿主提供，均为 optional peer；`schemastery` 是直接依赖。
+
+## 运行
+
+```sh
+dsh plugin --profile web add "link:D:/Projects/deepseek-harness/dsh-plugin-better-glob"
+# 之后重启 dsh web（由人类执行）+ 浏览器硬刷新
+```
+
+`link:` 引用下改源码后 `pnpm run build` 重建 `lib/` 即生效，无需重装。发布形态：GitHub `huanlinoto/dsh-plugin-better-glob`（预构建 `lib/` 入库，无 prepare）/ npm `@huanlin/dsh-plugin-better-glob`。
+
+## 检查
+
+- `pnpm run typecheck` — 严格模式类型门禁
+- `pnpm test` — 40 用例：argv 构造（默认排除、include 按段提升、`**` 全提升、VCS 恒排除）、参数与配置校验、meta 投影/收窄、render 页脚；组合 preflight 用真实 `ToolRuntime` + `SystemPrompt` 验证阴影生效、全局视图不受污染、re-fire 幂等、reload resync
+- `pnpm run build` — 产物 `lib/index.js`（peer 全 external）+ `lib/types/`
+
+## 已知限制
+
+- 插件停用后，已存活 agent 的阴影注册会保留到该 agent 销毁（注册挂在 agent scope 上，随其 unwind）。
+- 配置热重载对「已在会话中的 agent」经 resync 生效；若加载器将来改为 cache-bust 重导入模块（同进程新模块实例），resync 会因 agent 层重名而失败报错（fail loud，不会静默失效）。
+- `include` 的提升粒度是「目录名」，include 模式中目录名之后的子路径不影响遍历范围（`node_modules/a/**` 放行整个 `node_modules`）；精确到子目录的放行需缩小 `excludeDirs` 配置。

package/cordis.patch.yml

@@ -0,0 +1,14 @@
+# better-glob bundle layer: inserts the better-glob plugin row.
+# Loaded by `dsh plugin --profile <name> add @huanlin/dsh-plugin-better-glob`.
+# The `name` is the package entry; Loader resolves it from profile node_modules.
+#
+# No built-in rows are disabled: the plugin shadows the built-in `glob` tool
+# (and its `tool:glob` prompt section) per agent through agent-scope
+# registration, which beats both the host-plane row (headless) and the
+# preset-mounted row (web) by scope-layer precedence. `grep` is untouched.
+# Plugin defaults (excludeDirs, caps) live in the plugin's Config schema;
+# override them here when a deployment needs different values.
+- insert:
+    - id: better-glob
+      name: '@huanlin/dsh-plugin-better-glob'
+      config: {}

package/lib/index.js

@@ -0,0 +1,469 @@
+import { FIRST_PARTY_SECTION_ORDER } from "@deepseek-ai/dsh-system-prompt";
+import z from "schemastery";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+import { runRipgrep, sampleAcrossTopLevel, toWorkdirRelative, trySaveFormattedResult } from "@deepseek-ai/dsh-tool-fs-search";
+//#region src/argv.ts
+/**
+* Pure argument handling for the better `glob` tool: model-argument
+* validation, include-whitelist lift computation, and ripgrep argv
+* construction. No I/O — every function here is testable without a host.
+* @module @huanlin/dsh-plugin-better-glob/argv
+*/
+/**
+* Directory names the tool never descends into, regardless of the
+* `excludeDirs` configuration: VCS metadata stores (the built-in tool's
+* fixed exclusion set).
+*/
+const VCS_EXCLUDES = [
+	".git",
+	".svn",
+	".hg",
+	".bzr",
+	".jj",
+	".sl"
+];
+/**
+* Default bottomless directories excluded from every search: dependency
+* installs, build outputs, framework state, caches, and virtualenvs that
+* routinely hold hundreds of thousands of files. The `excludeDirs` config
+* replaces this list wholesale.
+*/
+const DEFAULT_EXCLUDE_DIRS = [
+	"node_modules",
+	"bower_components",
+	"vendor",
+	"Pods",
+	".yarn",
+	"dist",
+	"build",
+	"out",
+	"target",
+	"obj",
+	".next",
+	".nuxt",
+	".output",
+	".svelte-kit",
+	".turbo",
+	".parcel-cache",
+	".cache",
+	"coverage",
+	"__pycache__",
+	".venv",
+	"venv",
+	".tox",
+	".mypy_cache",
+	".pytest_cache",
+	".ruff_cache",
+	".gradle",
+	".terraform",
+	".idea"
+];
+/**
+* Validate the value constraints the schema DSL cannot express: a non-blank
+* `pattern`, a non-blank `path` when given, and non-blank `include` entries
+* when given. Throws a plain `Error` (an ordinary tool argument error)
+* otherwise.
+* @param args - the schema-validated `glob` arguments.
+* @returns the accepted input, unchanged.
+*/
+function parseGlobArgs(args) {
+	if (args.pattern.trim().length === 0) throw new Error("pattern must be a non-empty string");
+	if (args.path !== void 0 && args.path.trim().length === 0) throw new Error("path must be a non-empty string when given");
+	if (args.include !== void 0) {
+		for (const entry of args.include) if (entry.trim().length === 0) throw new Error("include entries must be non-empty strings");
+	}
+	return {
+		pattern: args.pattern,
+		...args.path !== void 0 ? { path: args.path } : {},
+		...args.include !== void 0 ? { include: args.include } : {}
+	};
+}
+/** Whether one include pattern names no concrete directory (every segment is a wildcard or empty), lifting every excluded directory. */
+function liftsEveryDirectory(pattern) {
+	return pattern.split("/").every((segment) => segment === "**" || segment === "*" || segment.length === 0);
+}
+/**
+* The excluded directory names the include whitelist lifts back into one
+* call's search. A name lifts when an include pattern carries it as a path
+* segment (`node_modules/**` + `/package.json` lifts `node_modules`); a
+* pattern of only wildcard segments (`**`) lifts every candidate. Segments
+* that name no configured exclusion are ignored.
+*
+* The lift happens at argv construction time, not as a later ripgrep glob:
+* ripgrep prunes an excluded directory during traversal, so a glob emitted
+* after the exclusion could never re-enter the pruned subtree.
+* @param include - the call's include whitelist, when the model passed one.
+* @param excludeDirs - the configured exclusion names.
+* @returns the subset of `excludeDirs` the whitelist lifts.
+*/
+function liftedExcludeNames(include, excludeDirs) {
+	if (include === void 0) return /* @__PURE__ */ new Set();
+	const candidates = /* @__PURE__ */ new Set();
+	for (const pattern of include) {
+		if (liftsEveryDirectory(pattern)) {
+			for (const name of excludeDirs) candidates.add(name);
+			continue;
+		}
+		for (const segment of pattern.split("/")) {
+			if (segment === "**" || segment === "*" || segment.length === 0) continue;
+			candidates.add(segment);
+		}
+	}
+	const lifted = /* @__PURE__ */ new Set();
+	for (const name of excludeDirs) if (candidates.has(name)) lifted.add(name);
+	return lifted;
+}
+/**
+* Build the fixed `rg --files` argv for one better-`glob` call. Every
+* model-controlled value is a plain argv element — no shell layer exists, so
+* no quoting applies; the search root rides behind `--` so a leading-dash
+* path can never parse as a flag. `--sort=modified` orders by modification
+* time and `--no-ignore --hidden` searches ignored and hidden files, matching
+* the built-in tool's contract. Each excluded name carries TWO negated globs
+* (the bare form prunes the directory during traversal; the contents form
+* still excludes the internals when the search root sits at or inside the
+* directory). VCS excludes are unconditional; a lifted name omits both of
+* its globs, which is what lets ripgrep descend into it again.
+* @param input - the validated arguments.
+* @param excludeDirs - the configured exclusion names.
+* @returns the complete ripgrep argument vector (excluding the binary itself).
+*/
+function buildGlobArgv(input, excludeDirs) {
+	const lifted = liftedExcludeNames(input.include, excludeDirs);
+	const parts = [
+		"--files",
+		`--glob=${input.pattern}`,
+		"--sort=modified",
+		"--no-ignore",
+		"--hidden"
+	];
+	const pushExclusion = (name) => {
+		parts.push(`--glob=!**/${name}`, `--glob=!**/${name}/**`);
+	};
+	for (const name of VCS_EXCLUDES) pushExclusion(name);
+	for (const name of excludeDirs) if (!lifted.has(name)) pushExclusion(name);
+	if (input.path !== void 0) parts.push("--", input.path);
+	return parts;
+}
+//#endregion
+//#region src/caps.ts
+/**
+* Plugin configuration: the Schemastery schema, the resolved caps, and the
+* load-time validation. Every field defaults, so a patch insert row without
+* a `config` block boots.
+* @module @huanlin/dsh-plugin-better-glob/caps
+*/
+const Config = z.object({
+	excludeDirs: z.array(z.string()).default([...DEFAULT_EXCLUDE_DIRS]).description("Bottomless directory names excluded from every glob search. Replaces the default list wholesale; VCS directories (.git etc.) are always excluded on top. include lifts a name back into one call."),
+	sampleOverCapGlobResults: z.boolean().default(false).description("Whether an over-cap glob page is sampled across top-level entries instead of taking the modification-time head."),
+	globMaxResults: z.number().default(100).description("Max paths one glob call retains inline; the complete list spills to a file past it."),
+	globMetaMaxBytes: z.number().default(65536).description("Max bytes of one glob result's serialized presentationMeta; trailing paths drop past it."),
+	rawOutputMaxBytes: z.number().default(2e7).description("Max complete raw rg stdout one call parses."),
+	graceMs: z.number().default(3e3).description("Terminate-escalation grace period (ms) for the search process."),
+	stderrMaxBytes: z.number().default(65536).description("Max bytes of the retained stderr diagnostic tail."),
+	timeoutMs: z.number().default(3e4).description("Cooperative tool-call timeout budget (ms).")
+});
+/** The `@deepseek-ai/dsh-timeout` MAX_TIMER_DELAY_MS (2^31-1), inlined to keep the peer set minimal. */
+const MAX_GRACE_MS = 2147483647;
+/** Every cap counts items/bytes/milliseconds — a positive integer, or retention and timeout arithmetic misbehaves silently. */
+function assertPositiveInteger(name, value) {
+	if (!Number.isInteger(value) || value < 1) throw new Error(`better-glob: ${name} must be a positive integer`);
+}
+/**
+* Validate the schemastery-defaulted config into caps. Fails loud at load:
+* excludeDirs entries must be bare directory names (a separator or a blank
+* name would silently never match a directory in the traversal globs), caps
+* must be positive integers, and graceMs must fit a timer delay.
+* @param config - the schemastery-defaulted plugin config.
+* @returns the resolved caps.
+*/
+function resolveConfig(config) {
+	const excludeDirs = config.excludeDirs ?? [...DEFAULT_EXCLUDE_DIRS];
+	for (const name of excludeDirs) if (name.length === 0 || name.includes("/") || name.includes("\\")) throw new Error(`better-glob: excludeDirs entries must be bare directory names without path separators, got ${JSON.stringify(name)}`);
+	const maxResults = config.globMaxResults ?? 100;
+	const maxMetaBytes = config.globMetaMaxBytes ?? 65536;
+	const rawOutputMaxBytes = config.rawOutputMaxBytes ?? 2e7;
+	const graceMs = config.graceMs ?? 3e3;
+	const stderrMaxBytes = config.stderrMaxBytes ?? 65536;
+	const timeoutMs = config.timeoutMs ?? 3e4;
+	assertPositiveInteger("globMaxResults", maxResults);
+	assertPositiveInteger("globMetaMaxBytes", maxMetaBytes);
+	assertPositiveInteger("rawOutputMaxBytes", rawOutputMaxBytes);
+	assertPositiveInteger("graceMs", graceMs);
+	if (graceMs > MAX_GRACE_MS) throw new Error(`better-glob: graceMs must be no greater than ${MAX_GRACE_MS}`);
+	assertPositiveInteger("stderrMaxBytes", stderrMaxBytes);
+	assertPositiveInteger("timeoutMs", timeoutMs);
+	return {
+		excludeDirs,
+		sampleOverCapGlobResults: config.sampleOverCapGlobResults ?? false,
+		maxResults,
+		maxMetaBytes,
+		rawOutputMaxBytes,
+		graceMs,
+		stderrMaxBytes,
+		timeoutMs
+	};
+}
+//#endregion
+//#region src/tool.ts
+/** The serialized UTF-8 byte size of one meta payload (the size persisted and re-sent). */
+function metaBytes(meta) {
+	return Buffer.byteLength(JSON.stringify(meta), "utf8");
+}
+/**
+* Drop trailing paths until the serialized meta fits `maxMetaBytes`, marking
+* the result `truncated` when anything was dropped. `total` is preserved. A
+* single path too large to fit on its own is kept: the invariant is a bounded
+* payload wherever droppable, never an empty card that hides a real result.
+*/
+function capMetaBytes(meta, maxMetaBytes) {
+	if (metaBytes(meta) <= maxMetaBytes) return meta;
+	const paths = [...meta.paths];
+	while (paths.length > 1 && metaBytes({
+		...meta,
+		paths,
+		truncated: true
+	}) > maxMetaBytes) paths.pop();
+	return {
+		...meta,
+		paths,
+		truncated: true
+	};
+}
+/** Project one canonical value into the bounded `presentationMeta` the search card renders. */
+function pathsMeta(value, maxMetaBytes) {
+	return capMetaBytes({
+		shape: "paths",
+		paths: value.paths,
+		truncated: value.truncated,
+		total: value.total
+	}, maxMetaBytes);
+}
+/**
+* Narrow opaque live or replayed result metadata to a {@link SearchResultView}.
+* Malformed metadata returns `undefined` so `presentResult` falls back to the
+* generic card instead of throwing during replay of an older or hand-edited
+* log. A zero-result meta narrows to a valid empty card.
+* @param meta - result metadata (the {@link PathsSearchMeta} the tool projected).
+* @returns the search view, or `undefined` for absent or malformed metadata.
+*/
+function pathsViewFromMeta(meta) {
+	if (typeof meta !== "object" || meta === null || Array.isArray(meta)) return void 0;
+	const record = meta;
+	const { truncated, total } = record;
+	if (typeof truncated !== "boolean" || typeof total !== "number") return void 0;
+	if (record.shape !== "paths") return void 0;
+	const { paths } = record;
+	if (!Array.isArray(paths) || !paths.every((path) => typeof path === "string")) return void 0;
+	return {
+		card: "search",
+		shape: "paths",
+		paths,
+		truncated,
+		total
+	};
+}
+/** Format one canonical value for the Native surface: the page, plus the cap basis and recovery path when capped. */
+function renderGlobValue(value) {
+	if (value.paths.length === 0) return "No files found";
+	const body = value.paths.join("\n");
+	if (!value.truncated) return body;
+	const basis = value.sampled ? ", sampled across top-level entries instead of taken in modification-time order" : ", the modification-time-ordered head";
+	const recovery = value.spill !== void 0 ? `Full sorted result stored at: ${value.spill.locator}. ${value.spill.hint}` : "The complete result could not be saved; narrow pattern or path to see more.";
+	return `${body}\n\n(Showing ${value.paths.length} of ${value.total} paths${basis}. ${recovery})`;
+}
+/**
+* Build the better `glob` tool definition.
+* @param ctx - the plugin context; execution reads its `subprocess` service and opportunistic `spillStore`.
+* @param caps - the deployment's resolved caps (plugin config after defaulting).
+* @returns the registry-ready definition; the caller registers it into agent scopes.
+*/
+function defineBetterGlobTool(ctx, caps) {
+	const overCapDescription = caps.sampleOverCapGlobResults ? `a larger result instead returns ${caps.maxResults} paths sampled across top-level entries` : `a larger result returns the first ${caps.maxResults} paths in modification-time order`;
+	const excludedNote = caps.excludeDirs.length > 0 ? `Bottomless directories are excluded automatically (${caps.excludeDirs.join(", ")}); pass include to search inside one.` : "No directories are excluded by configuration.";
+	return defineTool({
+		name: "glob",
+		description: `Find files whose paths match a glob pattern. Returns matching file paths — never directories — in modification-time order, including hidden and ignored files (VCS metadata directories are always excluded). Up to ${caps.maxResults} paths come back inline; ${overCapDescription}, says so, and reports where the complete sorted list was saved. This tool does not enumerate directory entries. ` + excludedNote,
+		parameters: {
+			pattern: {
+				type: "string",
+				required: true,
+				description: "Glob pattern to match file paths against (e.g. \"**/*.ts\", \"src/**/*.test.js\"). A pattern with no \"/\" matches the basename at any depth, so \"*\" and \"*.ts\" both search the whole tree; include a separator to anchor the depth."
+			},
+			path: {
+				type: "string",
+				description: "Directory to search in. Defaults to the session workspace; a relative path resolves against it."
+			},
+			include: {
+				type: "array",
+				items: { type: "string" },
+				description: "Whitelist that lifts excluded directories back into THIS search: an include pattern naming an excluded directory as a path segment (e.g. \"node_modules/**/package.json\") removes that directory from the exclusion set; a bare wildcard pattern (\"**\") lifts every excluded directory. include never filters results — pattern does. Omit it for ordinary searches."
+			}
+		},
+		timeoutMs: caps.timeoutMs,
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					root: {
+						type: "string",
+						required: true
+					},
+					paths: {
+						type: "array",
+						required: true,
+						items: { type: "string" }
+					},
+					total: {
+						type: "integer",
+						required: true
+					},
+					truncated: {
+						type: "boolean",
+						required: true
+					},
+					sampled: {
+						type: "boolean",
+						required: true
+					},
+					spill: {
+						type: "object",
+						additionalProperties: false,
+						properties: {
+							locator: {
+								type: "string",
+								required: true
+							},
+							hint: {
+								type: "string",
+								required: true
+							}
+						}
+					}
+				}
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: renderGlobValue(value)
+			}],
+			presentationMeta: (_args, value) => pathsMeta(value, caps.maxMetaBytes)
+		},
+		async execute(args, exec) {
+			const input = parseGlobArgs(args);
+			const run = await runRipgrep(ctx, exec, "glob", buildGlobArgv(input, caps.excludeDirs), caps.rawOutputMaxBytes, caps.graceMs, caps.stderrMaxBytes);
+			const root = input.path === void 0 ? "." : toWorkdirRelative(input.path, run.workdir);
+			const all = [];
+			if (!run.noMatches) for (const line of run.stdout.split("\n")) {
+				if (line.length === 0) continue;
+				all.push(toWorkdirRelative(line, run.workdir));
+			}
+			if (all.length <= caps.maxResults) return {
+				root,
+				paths: all,
+				total: all.length,
+				truncated: false,
+				sampled: false
+			};
+			const page = caps.sampleOverCapGlobResults ? sampleAcrossTopLevel(all, caps.maxResults, root).items : all.slice(0, caps.maxResults);
+			const spillRef = await trySaveFormattedResult(ctx, exec, "glob-results.txt", all.join("\n"));
+			return {
+				root,
+				paths: page,
+				total: all.length,
+				truncated: true,
+				sampled: caps.sampleOverCapGlobResults,
+				...spillRef !== void 0 ? { spill: {
+					locator: spillRef.locator,
+					hint: spillRef.retrievalHint
+				} } : {}
+			};
+		},
+		presentCall: (args) => {
+			const where = args.path !== void 0 ? ` in ${args.path}` : "";
+			return {
+				card: "generic",
+				title: `Glob ${args.pattern}${where}`,
+				kind: "search",
+				rawInput: args.pattern
+			};
+		},
+		presentResult: (_args, result) => {
+			if (result.isError) return void 0;
+			return pathsViewFromMeta(result.meta);
+		}
+	});
+}
+//#endregion
+//#region src/index.ts
+/** Cordis plugin name used by loader diagnostics. */
+const name = "better-glob";
+/**
+* Services required by the plugin: `tools`/`systemPrompt` register the
+* shadow into agent scopes, `subprocess` executes ripgrep, `agents` lists
+* live agents for the reload resync.
+*/
+const inject = [
+	"tools",
+	"systemPrompt",
+	"subprocess",
+	"agents"
+];
+/**
+* The prompt section the shadow registers per agent. Same name and order as
+* the built-in `tool:glob` section, so the agent-layer registration shadows
+* the built-in text; the section text names the configured exclusions and
+* the include whitelist escape hatch.
+* @param caps - the deployment's resolved caps.
+* @returns the section to register through `agent.ctx.systemPrompt`.
+*/
+function shadowSection(caps) {
+	const excluded = caps.excludeDirs.length > 0 ? `Bottomless directories (${caps.excludeDirs.join(", ")}) are excluded automatically — pass include (for example ["node_modules/**"]) when a search must look inside one.` : "No directories are excluded by configuration.";
+	return {
+		name: "tool:glob",
+		order: FIRST_PARTY_SECTION_ORDER.TOOL_GLOB,
+		text: "Use the glob tool — not shell find — to discover files by path pattern. A pattern with no \"/\" matches basenames at any depth, so \"*\" matches every file in the tree rather than its top level. Results are files only, never directories, and include hidden and ignored files. " + excluded + " A result that fits comes back in modification-time order."
+	};
+}
+/** Register the shadow into one agent's own layer; returns the combined disposer for reload resync. */
+function shadowAgent(agent, tool, section) {
+	const disposeTool = agent.ctx.tools.register(tool);
+	const disposeSection = agent.ctx.systemPrompt.section(section);
+	return () => {
+		disposeTool();
+		disposeSection();
+	};
+}
+/**
+* Per-agent shadow registrations, module-level so a config reload (the same
+* module instance re-running `apply`) can dispose the previous fiber's
+* registration before re-registering with the fresh config.
+*/
+const shadowed = /* @__PURE__ */ new WeakMap();
+/**
+* Register the better-`glob` shadow: a `agent/session-start` listener that
+* mounts the tool and prompt section into every agent's own layer, plus a
+* resync over already-live agents so a config reload takes effect without a
+* restart.
+* @param ctx - the plugin context; registrations are effects scoped to it.
+* @param config - the (schemastery-defaulted) plugin configuration.
+*/
+function apply(ctx, config) {
+	const caps = resolveConfig(config);
+	const tool = defineBetterGlobTool(ctx, caps);
+	const section = shadowSection(caps);
+	const shadow = (agent) => {
+		if (shadowed.has(agent)) return;
+		shadowed.set(agent, shadowAgent(agent, tool, section));
+	};
+	ctx.on("agent/session-start", ({ agent }) => {
+		shadow(agent);
+	});
+	for (const agent of ctx.agents.list()) {
+		shadowed.get(agent)?.();
+		shadowed.delete(agent);
+		shadow(agent);
+	}
+}
+//#endregion
+export { Config, DEFAULT_EXCLUDE_DIRS, VCS_EXCLUDES, apply, buildGlobArgv, defineBetterGlobTool, inject, liftedExcludeNames, name, parseGlobArgs, pathsMeta, pathsViewFromMeta, renderGlobValue, resolveConfig, shadowSection };

package/lib/types/argv.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Pure argument handling for the better `glob` tool: model-argument
+ * validation, include-whitelist lift computation, and ripgrep argv
+ * construction. No I/O — every function here is testable without a host.
+ * @module @huanlin/dsh-plugin-better-glob/argv
+ */
+/**
+ * Directory names the tool never descends into, regardless of the
+ * `excludeDirs` configuration: VCS metadata stores (the built-in tool's
+ * fixed exclusion set).
+ */
+export declare const VCS_EXCLUDES: readonly string[];
+/**
+ * Default bottomless directories excluded from every search: dependency
+ * installs, build outputs, framework state, caches, and virtualenvs that
+ * routinely hold hundreds of thousands of files. The `excludeDirs` config
+ * replaces this list wholesale.
+ */
+export declare const DEFAULT_EXCLUDE_DIRS: readonly string[];
+/** Validated `glob` arguments after value-constraint checks. */
+export interface GlobInput {
+    pattern: string;
+    path?: string;
+    include?: string[];
+}
+/**
+ * Validate the value constraints the schema DSL cannot express: a non-blank
+ * `pattern`, a non-blank `path` when given, and non-blank `include` entries
+ * when given. Throws a plain `Error` (an ordinary tool argument error)
+ * otherwise.
+ * @param args - the schema-validated `glob` arguments.
+ * @returns the accepted input, unchanged.
+ */
+export declare function parseGlobArgs(args: {
+    pattern: string;
+    path?: string;
+    include?: string[];
+}): GlobInput;
+/**
+ * The excluded directory names the include whitelist lifts back into one
+ * call's search. A name lifts when an include pattern carries it as a path
+ * segment (`node_modules/**` + `/package.json` lifts `node_modules`); a
+ * pattern of only wildcard segments (`**`) lifts every candidate. Segments
+ * that name no configured exclusion are ignored.
+ *
+ * The lift happens at argv construction time, not as a later ripgrep glob:
+ * ripgrep prunes an excluded directory during traversal, so a glob emitted
+ * after the exclusion could never re-enter the pruned subtree.
+ * @param include - the call's include whitelist, when the model passed one.
+ * @param excludeDirs - the configured exclusion names.
+ * @returns the subset of `excludeDirs` the whitelist lifts.
+ */
+export declare function liftedExcludeNames(include: readonly string[] | undefined, excludeDirs: readonly string[]): ReadonlySet<string>;
+/**
+ * Build the fixed `rg --files` argv for one better-`glob` call. Every
+ * model-controlled value is a plain argv element — no shell layer exists, so
+ * no quoting applies; the search root rides behind `--` so a leading-dash
+ * path can never parse as a flag. `--sort=modified` orders by modification
+ * time and `--no-ignore --hidden` searches ignored and hidden files, matching
+ * the built-in tool's contract. Each excluded name carries TWO negated globs
+ * (the bare form prunes the directory during traversal; the contents form
+ * still excludes the internals when the search root sits at or inside the
+ * directory). VCS excludes are unconditional; a lifted name omits both of
+ * its globs, which is what lets ripgrep descend into it again.
+ * @param input - the validated arguments.
+ * @param excludeDirs - the configured exclusion names.
+ * @returns the complete ripgrep argument vector (excluding the binary itself).
+ */
+export declare function buildGlobArgv(input: GlobInput, excludeDirs: readonly string[]): string[];

package/lib/types/caps.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Plugin configuration: the Schemastery schema, the resolved caps, and the
+ * load-time validation. Every field defaults, so a patch insert row without
+ * a `config` block boots.
+ * @module @huanlin/dsh-plugin-better-glob/caps
+ */
+import z from 'schemastery';
+/** Plugin config; every field has a default. */
+export interface BetterGlobConfig {
+    /** Bottomless directory NAMES excluded from every search; replaces the built-in default list wholesale (VCS directories are always excluded on top). */
+    excludeDirs?: string[];
+    /** Whether an over-cap page is sampled across top-level entries instead of taking the modification-time head (the built-in deployment's switch). */
+    sampleOverCapGlobResults?: boolean;
+    /** Max paths one `glob` call retains inline; the complete list spills to a file past it. */
+    globMaxResults?: number;
+    /** Max bytes of serialized `presentationMeta`; trailing paths drop past it. */
+    globMetaMaxBytes?: number;
+    /** Max complete raw `rg` stdout one call parses. */
+    rawOutputMaxBytes?: number;
+    /** Terminate-escalation grace period (ms) for the search process. */
+    graceMs?: number;
+    /** Max bytes of the retained stderr diagnostic tail. */
+    stderrMaxBytes?: number;
+    /** Cooperative tool-call timeout budget (ms). */
+    timeoutMs?: number;
+}
+export declare const Config: z<BetterGlobConfig>;
+/** Resolved caps after schemastery defaulting — every field required. */
+export interface BetterGlobCaps {
+    excludeDirs: readonly string[];
+    sampleOverCapGlobResults: boolean;
+    maxResults: number;
+    maxMetaBytes: number;
+    rawOutputMaxBytes: number;
+    graceMs: number;
+    stderrMaxBytes: number;
+    timeoutMs: number;
+}
+/**
+ * Validate the schemastery-defaulted config into caps. Fails loud at load:
+ * excludeDirs entries must be bare directory names (a separator or a blank
+ * name would silently never match a directory in the traversal globs), caps
+ * must be positive integers, and graceMs must fit a timer delay.
+ * @param config - the schemastery-defaulted plugin config.
+ * @returns the resolved caps.
+ */
+export declare function resolveConfig(config: BetterGlobConfig): BetterGlobCaps;

package/lib/types/index.d.ts

@@ -0,0 +1,71 @@
+/**
+ * dsh-plugin-better-glob — per-agent shadow replacement for the built-in
+ * `glob` tool.
+ *
+ * ## Why per-agent registration
+ *
+ * The tools registry resolves a scope's view by layering: a scope's OWN
+ * registrations shadow every inherited one (the global layer in headless
+ * compositions, the preset's standing scope in web profiles, where the
+ * web-app bundle disables the host-plane row and the `standard` preset mounts
+ * `tool-fs-search` per session). A global registration cannot win in either
+ * composition, and a bundle patch cannot reach preset files — so the shadow
+ * registers into each agent's own layer (`agent.ctx`), which beats both.
+ * `grep` is untouched, and no built-in rows are disabled.
+ *
+ * ## Mount points
+ *
+ * `agent/session-start` fires for every agent (main and subagents) before the
+ * first prompt assembly, across startup/resume/clear/compact — each agent
+ * gets the shadow exactly once, guarded by a WeakSet. On plugin reload
+ * (config change), `apply` re-runs on the same module instance: live agents
+ * listed from the `agents` registry have their previous shadow disposed and
+ * re-registered so the fresh config applies.
+ *
+ * ## Execution
+ *
+ * The tool reuses the built-in search suite's spawn plumbing (`runRipgrep`,
+ * `toWorkdirRelative`, `trySaveFormattedResult`, `sampleAcrossTopLevel`) —
+ * same packaged ripgrep binary, same subprocess seam, same error vocabulary.
+ * Its own contribution is the exclusion set (VCS always + configurable
+ * bottomless directories) and the `include` whitelist that lifts an excluded
+ * directory back into one call at argv-construction time.
+ * @module @huanlin/dsh-plugin-better-glob
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { PromptSection } from '@deepseek-ai/dsh-system-prompt';
+import type { BetterGlobCaps, BetterGlobConfig } from './caps.ts';
+/** Cordis plugin name used by loader diagnostics. */
+export declare const name = "better-glob";
+/**
+ * Services required by the plugin: `tools`/`systemPrompt` register the
+ * shadow into agent scopes, `subprocess` executes ripgrep, `agents` lists
+ * live agents for the reload resync.
+ */
+export declare const inject: string[];
+export { Config } from './caps.ts';
+export type { BetterGlobConfig } from './caps.ts';
+export { buildGlobArgv, DEFAULT_EXCLUDE_DIRS, liftedExcludeNames, parseGlobArgs, VCS_EXCLUDES } from './argv.ts';
+export type { GlobInput } from './argv.ts';
+export type { GlobOutput, PathsSearchMeta } from './tool.ts';
+export { defineBetterGlobTool, pathsMeta, pathsViewFromMeta, renderGlobValue } from './tool.ts';
+export { resolveConfig } from './caps.ts';
+export type { BetterGlobCaps } from './caps.ts';
+/**
+ * The prompt section the shadow registers per agent. Same name and order as
+ * the built-in `tool:glob` section, so the agent-layer registration shadows
+ * the built-in text; the section text names the configured exclusions and
+ * the include whitelist escape hatch.
+ * @param caps - the deployment's resolved caps.
+ * @returns the section to register through `agent.ctx.systemPrompt`.
+ */
+export declare function shadowSection(caps: BetterGlobCaps): PromptSection;
+/**
+ * Register the better-`glob` shadow: a `agent/session-start` listener that
+ * mounts the tool and prompt section into every agent's own layer, plus a
+ * resync over already-live agents so a config reload takes effect without a
+ * restart.
+ * @param ctx - the plugin context; registrations are effects scoped to it.
+ * @param config - the (schemastery-defaulted) plugin configuration.
+ */
+export declare function apply(ctx: Context, config: BetterGlobConfig): void;

package/lib/types/tool.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The better `glob` tool definition: the model-facing schema (with the
+ * `include` whitelist), execution over the packaged ripgrep binary through
+ * the built-in search suite's spawn plumbing, inline-cap + spill retention,
+ * and the model/card projections. Registration happens per agent (see
+ * `index.ts`); this module only builds the definition.
+ * @module @huanlin/dsh-plugin-better-glob/tool
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { SearchResultView, ToolDefinition } from '@deepseek-ai/dsh-tools';
+import type { BetterGlobCaps } from './caps.ts';
+/**
+ * The canonical value of one `glob` call: the retained inline page plus the
+ * recovery info for a capped result. The complete modification-time-ordered
+ * list exists only in the spill file (when the cap bit and the spill backend
+ * accepted it); the canonical value stays bounded for the session log.
+ *
+ * Object-literal type aliases rather than interfaces: only an alias is
+ * assignable to the `JsonValue` index signature the tool contract uses.
+ */
+export type GlobOutput = {
+    /** The search root in the same display-path space as `paths`. */
+    root: string;
+    /** The retained page of matching paths, in modification-time order. */
+    paths: string[];
+    /** How many paths the complete search found. */
+    total: number;
+    /** Whether `paths` is a capped page rather than the complete result. */
+    truncated: boolean;
+    /** Whether an over-cap page was sampled across top-level entries (only meaningful when `truncated`). */
+    sampled: boolean;
+    /** Where the complete sorted result was saved, when the spill backend accepted it. */
+    spill?: {
+        locator: string;
+        hint: string;
+    };
+};
+/** The `glob` tool's private `tool/result` meta payload: the search card's path list (object-literal alias for `JsonValue` assignability). */
+export type PathsSearchMeta = {
+    shape: 'paths';
+    paths: string[];
+    truncated: boolean;
+    total: number;
+};
+/** Project one canonical value into the bounded `presentationMeta` the search card renders. */
+export declare function pathsMeta(value: GlobOutput, maxMetaBytes: number): PathsSearchMeta;
+/**
+ * Narrow opaque live or replayed result metadata to a {@link SearchResultView}.
+ * Malformed metadata returns `undefined` so `presentResult` falls back to the
+ * generic card instead of throwing during replay of an older or hand-edited
+ * log. A zero-result meta narrows to a valid empty card.
+ * @param meta - result metadata (the {@link PathsSearchMeta} the tool projected).
+ * @returns the search view, or `undefined` for absent or malformed metadata.
+ */
+export declare function pathsViewFromMeta(meta: unknown): SearchResultView | undefined;
+/** Format one canonical value for the Native surface: the page, plus the cap basis and recovery path when capped. */
+export declare function renderGlobValue(value: GlobOutput): string;
+/**
+ * Build the better `glob` tool definition.
+ * @param ctx - the plugin context; execution reads its `subprocess` service and opportunistic `spillStore`.
+ * @param caps - the deployment's resolved caps (plugin config after defaulting).
+ * @returns the registry-ready definition; the caller registers it into agent scopes.
+ */
+export declare function defineBetterGlobTool(ctx: Context, caps: BetterGlobCaps): ToolDefinition;

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@huanlin/dsh-plugin-better-glob",
+  "version": "0.1.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "dsh-plugin"
+  ],
+  "description": "Shadow-replaces the built-in glob tool: auto-excludes bottomless directories (node_modules, dist, build, .venv, ...) and requires an explicit include whitelist to search inside them.",
+  "type": "module",
+  "license": "MIT",
+  "main": "./lib/index.js",
+  "types": "./lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "import": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/",
+    "cordis.patch.yml"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "dependencies": {
+    "schemastery": "^3.18.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-agent": "^0.1.2-alpha.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.1.2-alpha.1",
+    "@deepseek-ai/dsh-tool-fs-search": "^0.1.2-alpha.1",
+    "@deepseek-ai/dsh-tools": "^0.1.2-alpha.1"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/cordis": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-agent": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-system-prompt": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-tool-fs-search": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-tools": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.0",
+    "tsdown": "^0.22.2",
+    "typescript": "^5.9.0",
+    "vitest": "^3.2.0"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "pretest": "node scripts/relink-deps.mjs",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run",
+    "prebuild": "node scripts/relink-deps.mjs",
+    "build": "tsdown -c tsdown.config.ts && tsc -p tsconfig.json"
+  }
+}