@deepseek-ai/dsh-file-reference-local 0.1.0-rc.8

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+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.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/context/file-reference-local/README.md
+README.md: 67b07eef4b59fdcc5e21104cac4628feb1c15f4e
+README.zh.md: beded13250daf041294e4e2656d0e1374407ff94

package/README.md

@@ -0,0 +1,45 @@
+# `@deepseek-ai/dsh-file-reference-local`
+
+English | [中文](README.zh.md)
+
+Local-filesystem implementation of `ctx.fileReferences`. It maintains one bounded `WorkspaceFileSearch` per agent, rooted at that session's `cwd` and falling back to the host process cwd. The index ranks direct directory listings for queries containing `/`, otherwise fuzzy-ranks a bounded recursive index; it never follows directory symlinks.
+
+Tool-result events invalidate the addressed agent's reusable index so later completion observes likely workspace mutations. Agent disposal releases that index and its scoped prompt contribution; plugin disposal awaits every prompt fiber and releases all cached searches.
+
+## Configuration
+
+| Key | Default | Contract |
+|---|---:|---|
+| `maxResults` | `20` | Maximum ranked candidates returned for one query. |
+| `maxEntries` | `10000` | Maximum files and directories indexed per agent workspace. |
+| `excludedDirectories` | `[".git", "node_modules"]` | Directory basenames omitted from traversal and candidates. |
+
+Every numeric value must be a positive safe integer. Excluded names must be non-empty basenames without `/` or `\`.
+
+## Model Experience
+
+### File-reference guidance when `read` is available
+
+#### What the model sees
+
+When the addressed agent has an effective `read` tool, the provider contributes this stable system-prompt section:
+
+##### File-reference instruction
+
+```markdown
+Paths prefixed with @ are files explicitly referenced by the user. Use the read tool when their contents are needed; do not claim to have inspected a file before reading it.
+```
+
+#### Token effect
+
+Conditional and fixed: the one sentence is present while `read` is visible to the addressed agent; candidate lookup itself adds no tokens, and a selected path contributes only its ordinary user-message characters.
+
+#### KV Cache effect
+
+The stable sentence joins the system-prompt prefix. Mounting or removing this provider, or changing whether `read` is visible, changes that prefix; queries, candidates, and index invalidations do not.
+
+## Known Limitations and Deferred Work
+
+- **Host-local namespace** — the provider scans the Harness host filesystem, so remote or virtual `read` implementations require a provider whose namespace matches the tool.
+- **Bounded advisory index** — very large workspaces may omit paths after `maxEntries`, and excluded or unreadable directories do not appear.
+- **No ignore-file semantics** — `.gitignore` and other project ignore files do not influence discovery; only configured directory basenames are excluded.

package/README.zh.md

@@ -0,0 +1,45 @@
+# `@deepseek-ai/dsh-file-reference-local`
+
+[English](README.md) | 中文
+
+`ctx.fileReferences` 的本地文件系统实现。它为每个 agent（智能体）维护一个有界的 `WorkspaceFileSearch`，以该会话的 `cwd` 为根目录；缺少该值时回退到宿主进程的 cwd。查询包含 `/` 时，索引会对直接列出的目录项排序；否则会对有界递归索引进行模糊排序。索引永远不会跟随目录符号链接。
+
+工具结果事件会使指定 agent 的可复用索引失效，使后续补全能够反映工作区中可能发生的变更。agent 的 dispose（资源释放）会释放该索引及其作用域内的提示词贡献；插件 dispose 会等待所有提示词 fiber，并释放全部缓存的搜索器。
+
+## 配置
+
+| 配置键 | 默认值 | 契约 |
+|---|---:|---|
+| `maxResults` | `20` | 单次查询返回的候选项最大数量。 |
+| `maxEntries` | `10000` | 每个 agent 工作区建立索引的文件和目录最大数量。 |
+| `excludedDirectories` | `[".git", "node_modules"]` | 遍历和候选项中排除的目录基名。 |
+
+所有数值都必须是正的安全整数。排除名称必须是非空基名，且不能包含 `/` 或 `\`。
+
+## 模型体验
+
+### `read` 可用时的文件引用指引
+
+#### 模型看到什么
+
+当指定 agent 有实际生效的 `read` 工具时，提供方会贡献以下稳定的系统提示词段：
+
+##### 文件引用指令
+
+```markdown
+Paths prefixed with @ are files explicitly referenced by the user. Use the read tool when their contents are needed; do not claim to have inspected a file before reading it.
+```
+
+#### Token 影响
+
+该影响有条件且固定：只要 `read` 对指定 agent 可见，这一句就会存在；候选查询本身不增加 token，所选路径只会贡献普通用户消息中的对应字符。
+
+#### KV 缓存影响
+
+该稳定句子会加入系统提示词前缀。挂载或移除此提供方，或者改变 `read` 是否可见，都会改变该前缀；查询、候选项和索引失效不会改变前缀。
+
+## 已知限制与暂缓事项
+
+- **宿主本地命名空间**：提供方扫描 Harness 宿主的文件系统，因此远程或虚拟 `read` 实现需要使用命名空间与该工具一致的提供方。
+- **有界的提示性索引**：超大型工作区可能省略 `maxEntries` 之后的路径；被排除或无法读取的目录不会出现。
+- **没有忽略文件语义**：`.gitignore` 和其他项目忽略文件不会影响发现；系统只排除已配置的目录基名。

package/lib/index.js

@@ -0,0 +1,327 @@
+import z from "@deepseek-ai/schemastery";
+import FileReferenceService, { FILE_REFERENCE_PROMPT, FILE_REFERENCE_PROMPT as FILE_REFERENCE_PROMPT$1 } from "@deepseek-ai/dsh-file-reference";
+import { lstat, readdir } from "node:fs/promises";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { activeAtToken, formatFileMention } from "@deepseek-ai/dsh-file-reference/grammar";
+//#region lib/types/search.js
+/**
+* Host-workspace discovery for `@file` completion. The index contains paths
+* only: selected values remain ordinary prompt text and file contents stay
+* behind the model-facing `read` tool.
+*
+* @module @deepseek-ai/dsh-file-reference-local/search
+*/
+/** Default maximum file and directory candidates rendered for one query. */
+const DEFAULT_FILE_SEARCH_MAX_RESULTS = 20;
+/** Default maximum entries retained in one workspace search index. */
+const DEFAULT_FILE_SEARCH_MAX_ENTRIES = 1e4;
+/** Directory basenames omitted from traversal unless the deployment overrides them. */
+const DEFAULT_FILE_SEARCH_EXCLUDED_DIRECTORIES = [".git", "node_modules"];
+/**
+* Cancellable, reusable fuzzy index rooted at one agent working directory.
+* Directory-scoped queries list live state; bare fuzzy queries share one
+* bounded traversal until the `@` interaction ends or a tool result invalidates it.
+*/
+var WorkspaceFileSearch = class {
+	root;
+	config;
+	excludedDirectories;
+	generation;
+	disposed = false;
+	constructor(root, config) {
+		this.root = root;
+		this.config = config;
+		if (!Number.isSafeInteger(config.maxResults) || config.maxResults <= 0) throw new Error("file search maxResults must be a positive safe integer");
+		if (!Number.isSafeInteger(config.maxEntries) || config.maxEntries <= 0) throw new Error("file search maxEntries must be a positive safe integer");
+		if (config.excludedDirectories.some((name) => name.length === 0 || name.includes("/") || name.includes("\\"))) throw new Error("file search excludedDirectories entries must be non-empty directory basenames");
+		this.excludedDirectories = new Set(config.excludedDirectories);
+	}
+	/**
+	* Return ranked path candidates for the current token.
+	* @param rawQuery - path text following `@` or `@"`.
+	* @param signal - cancels this caller's wait without killing an index shared by a newer query.
+	* @returns at most `maxResults` deterministic candidates.
+	*/
+	async list(rawQuery, signal) {
+		signal.throwIfAborted();
+		if (this.disposed) return [];
+		const query = rawQuery.replaceAll("\\", "/");
+		const slash = query.lastIndexOf("/");
+		if (query === "" || slash >= 0) {
+			const directory = slash < 0 ? "" : query.slice(0, slash + 1);
+			const fragment = slash < 0 ? "" : query.slice(slash + 1);
+			return this.listDirectory(directory, fragment, signal);
+		}
+		return rankCandidates((await waitForPromise(this.ensureIndex(), signal)).filter((candidate) => visibleForGlobalQuery(candidate.path, query)), query, this.config.maxResults);
+	}
+	/** Discard the current index so the next bare query observes a fresh tree. */
+	invalidate() {
+		this.generation?.controller.abort(/* @__PURE__ */ new Error("file search index invalidated"));
+		this.generation = void 0;
+	}
+	/** Abort traversal and make later queries return no candidates. */
+	dispose() {
+		if (this.disposed) return;
+		this.disposed = true;
+		this.invalidate();
+	}
+	ensureIndex() {
+		if (this.generation !== void 0) return this.generation.promise;
+		const controller = new AbortController();
+		const generation = {
+			controller,
+			promise: Promise.resolve([])
+		};
+		generation.promise = this.scanWorkspace(controller.signal).catch((error) => {
+			/* v8 ignore next -- every owned abort clears `generation` synchronously; this only protects an unexpected scan failure */
+			if (this.generation === generation) this.generation = void 0;
+			throw error;
+		});
+		this.generation = generation;
+		return generation.promise;
+	}
+	async scanWorkspace(signal) {
+		const indexed = [];
+		const directories = [{
+			absolute: this.root,
+			relative: ""
+		}];
+		for (let cursor = 0; cursor < directories.length && indexed.length < this.config.maxEntries; cursor += 1) {
+			signal.throwIfAborted();
+			const directory = directories[cursor];
+			/* v8 ignore next 3 -- cursor is bounded by this exact queue's length. */
+			if (directory === void 0) throw new Error("file search selected a missing directory");
+			const entries = await readDirectory(directory.absolute, signal);
+			for (const entry of entries) {
+				signal.throwIfAborted();
+				const path = directory.relative === "" ? entry.name : `${directory.relative}/${entry.name}`;
+				if (entry.isDirectory()) {
+					if (this.excludedDirectories.has(entry.name)) continue;
+					indexed.push({
+						path,
+						kind: "directory"
+					});
+					directories.push({
+						absolute: join(directory.absolute, entry.name),
+						relative: path
+					});
+				} else if (entry.isFile()) indexed.push({
+					path,
+					kind: "file"
+				});
+				if (indexed.length >= this.config.maxEntries) break;
+			}
+		}
+		return indexed;
+	}
+	async listDirectory(displayDirectory, fragment, signal) {
+		if (displayDirectory.split("/").some((segment) => this.excludedDirectories.has(segment))) return [];
+		const absolute = await resolveDisplayDirectory(this.root, displayDirectory, signal);
+		if (absolute === void 0) return [];
+		const entries = await readDirectory(absolute, signal);
+		const candidates = [];
+		for (const entry of entries) {
+			if (entry.name.startsWith(".") && !fragment.startsWith(".")) continue;
+			if (entry.isDirectory()) {
+				if (this.excludedDirectories.has(entry.name)) continue;
+				candidates.push({
+					path: `${displayDirectory}${entry.name}`,
+					kind: "directory"
+				});
+			} else if (entry.isFile()) candidates.push({
+				path: `${displayDirectory}${entry.name}`,
+				kind: "file"
+			});
+		}
+		return rankCandidates(candidates, fragment, this.config.maxResults);
+	}
+};
+async function resolveDisplayDirectory(root, displayDirectory, signal) {
+	const resolvedRoot = resolve(root);
+	const absolute = resolve(resolvedRoot, displayDirectory === "" ? "." : displayDirectory);
+	const fromRoot = relative(resolvedRoot, absolute);
+	if (fromRoot === ".." || fromRoot.startsWith(`..${sep}`)) return void 0;
+	/* v8 ignore next -- only Windows can produce a cross-volume absolute relative path */
+	if (isAbsolute(fromRoot)) return void 0;
+	let current = resolvedRoot;
+	for (const segment of fromRoot.split(sep).filter(Boolean)) {
+		signal.throwIfAborted();
+		current = join(current, segment);
+		try {
+			const status = await lstat(current);
+			signal.throwIfAborted();
+			if (status.isSymbolicLink() || !status.isDirectory()) return void 0;
+		} catch (_error) {
+			signal.throwIfAborted();
+			return;
+		}
+	}
+	return absolute;
+}
+async function readDirectory(absolute, signal) {
+	signal.throwIfAborted();
+	try {
+		const entries = await readdir(absolute, { withFileTypes: true });
+		signal.throwIfAborted();
+		return entries.sort((left, right) => compareText(left.name, right.name));
+	} catch (_error) {
+		signal.throwIfAborted();
+		return [];
+	}
+}
+function visibleForGlobalQuery(path, query) {
+	if (query.startsWith(".") || query.includes("/.")) return true;
+	return !path.split("/").some((segment) => segment.startsWith("."));
+}
+function rankCandidates(candidates, query, limit) {
+	const ranked = [];
+	for (const candidate of candidates) {
+		const score = scoreCandidate(candidate, query);
+		if (score !== void 0) ranked.push({
+			candidate,
+			score
+		});
+	}
+	ranked.sort((left, right) => right.score - left.score || kindRank(left.candidate.kind) - kindRank(right.candidate.kind) || (query === "" ? 0 : left.candidate.path.length - right.candidate.path.length) || compareText(left.candidate.path, right.candidate.path));
+	return ranked.slice(0, limit).map((entry) => entry.candidate);
+}
+function scoreCandidate(candidate, query) {
+	if (query === "") return 0;
+	const path = candidate.path.toLowerCase();
+	const name = path.slice(path.lastIndexOf("/") + 1);
+	const needle = query.toLowerCase();
+	const directoryBonus = candidate.kind === "directory" ? 25 : 0;
+	if (name === needle) return 1e3 + directoryBonus;
+	if (name.startsWith(needle)) return 900 + directoryBonus;
+	if (name.includes(needle)) return 700 + directoryBonus;
+	if (path.includes(needle)) return 500 + directoryBonus;
+	const subsequence = subsequenceScore(path, needle);
+	return subsequence === void 0 ? void 0 : 300 + subsequence + directoryBonus;
+}
+function subsequenceScore(target, query) {
+	let targetIndex = 0;
+	let gap = 0;
+	for (const character of query) {
+		const found = target.indexOf(character, targetIndex);
+		if (found < 0) return void 0;
+		gap += found - targetIndex;
+		targetIndex = found + 1;
+	}
+	return Math.max(0, 100 - gap);
+}
+function kindRank(kind) {
+	return kind === "directory" ? 0 : 1;
+}
+function compareText(left, right) {
+	/* v8 ignore next -- entries and candidates are unique; host enumeration
+	* order determines which comparison direction sort requests. */
+	return left < right ? -1 : left > right ? 1 : 0;
+}
+function waitForPromise(promise, signal) {
+	/* v8 ignore next -- `list()` checks this signal immediately before its synchronous call into this helper */
+	if (signal.aborted) return Promise.reject(errorReason(signal.reason, "file search aborted"));
+	return new Promise((resolvePromise, rejectPromise) => {
+		const onAbort = () => {
+			rejectPromise(errorReason(signal.reason, "file search aborted"));
+		};
+		signal.addEventListener("abort", onAbort, { once: true });
+		promise.then((value) => {
+			signal.removeEventListener("abort", onAbort);
+			resolvePromise(value);
+		}, (error) => {
+			signal.removeEventListener("abort", onAbort);
+			rejectPromise(errorReason(error, "file search index failed"));
+		});
+	});
+}
+function errorReason(reason, fallback) {
+	return reason instanceof Error ? reason : new Error(fallback, { cause: reason });
+}
+//#endregion
+//#region lib/types/index.js
+/**
+* Local-filesystem implementation of `ctx.fileReferences`.
+*
+* @module @deepseek-ai/dsh-file-reference-local
+*/
+/** Local-filesystem owner of the file-reference discovery service. */
+var LocalFileReferenceService = class extends FileReferenceService {
+	static inject = ["agents"];
+	static Config = z.object({
+		maxResults: z.number().step(1).min(1).default(20),
+		maxEntries: z.number().step(1).min(1).default(DEFAULT_FILE_SEARCH_MAX_ENTRIES),
+		excludedDirectories: z.array(z.string()).default([...DEFAULT_FILE_SEARCH_EXCLUDED_DIRECTORIES])
+	});
+	config;
+	searches = /* @__PURE__ */ new Map();
+	promptFibers = /* @__PURE__ */ new Map();
+	promptDisposals = /* @__PURE__ */ new Set();
+	constructor(ctx, config = {}) {
+		super(ctx);
+		this.config = {
+			maxResults: config.maxResults ?? 20,
+			maxEntries: config.maxEntries ?? 1e4,
+			excludedDirectories: config.excludedDirectories ?? DEFAULT_FILE_SEARCH_EXCLUDED_DIRECTORIES
+		};
+		validateConfig(this.config);
+		const installPrompt = (agent) => {
+			if (this.promptFibers.has(agent)) return;
+			const fiber = agent.ctx.inject(["systemPrompt", "tools"], (scope) => {
+				scope.systemPrompt.section({
+					name: "context:file-reference",
+					order: 99,
+					text: () => agent.ctx.tools.get("read", agent) === void 0 ? "" : FILE_REFERENCE_PROMPT$1
+				});
+			});
+			this.promptFibers.set(agent, fiber);
+		};
+		const disposePrompt = (agent) => {
+			const fiber = this.promptFibers.get(agent);
+			if (fiber === void 0) return;
+			this.promptFibers.delete(agent);
+			const task = fiber.dispose().catch((error) => {
+				ctx.logger.warn(`file-reference-local: prompt cleanup failed: ${error instanceof Error ? error.message : String(error)}`);
+			});
+			this.promptDisposals.add(task);
+			task.finally(() => {
+				this.promptDisposals.delete(task);
+			});
+		};
+		for (const agent of ctx.agents.list()) installPrompt(agent);
+		ctx.on("agent/created", ({ agent }) => {
+			installPrompt(agent);
+		});
+		ctx.on("agent/disposed", ({ agent }) => {
+			this.searches.get(agent)?.dispose();
+			this.searches.delete(agent);
+			disposePrompt(agent);
+		});
+		ctx.on("session/event", (session, event) => {
+			if (event.type !== "tool/result") return;
+			const agent = ctx.agents.get(session.id);
+			if (agent !== void 0) this.searches.get(agent)?.invalidate();
+		});
+		ctx.effect(() => async () => {
+			for (const search of this.searches.values()) search.dispose();
+			this.searches.clear();
+			const promptFibers = [...this.promptFibers.values()];
+			this.promptFibers.clear();
+			await Promise.all([...promptFibers.map((fiber) => fiber.dispose()), ...this.promptDisposals]);
+		}, "file-reference-local: search cache");
+	}
+	list(agent, query, signal) {
+		let search = this.searches.get(agent);
+		if (search === void 0) {
+			search = new WorkspaceFileSearch(agent.session.header.cwd ?? process.cwd(), this.config);
+			this.searches.set(agent, search);
+		}
+		return search.list(query, signal);
+	}
+};
+function validateConfig(config) {
+	if (!Number.isSafeInteger(config.maxResults) || config.maxResults <= 0) throw new Error("file-reference-local: maxResults must be a positive safe integer");
+	if (!Number.isSafeInteger(config.maxEntries) || config.maxEntries <= 0) throw new Error("file-reference-local: maxEntries must be a positive safe integer");
+	if (config.excludedDirectories.some((name) => name.length === 0 || name.includes("/") || name.includes("\\"))) throw new Error("file-reference-local: excludedDirectories entries must be non-empty directory basenames");
+}
+//#endregion
+export { DEFAULT_FILE_SEARCH_EXCLUDED_DIRECTORIES, DEFAULT_FILE_SEARCH_MAX_ENTRIES, DEFAULT_FILE_SEARCH_MAX_RESULTS, FILE_REFERENCE_PROMPT, LocalFileReferenceService, LocalFileReferenceService as default, WorkspaceFileSearch, activeAtToken, formatFileMention };

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-file-reference-local`.
+* @module @deepseek-ai/dsh-file-reference-local/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-file-reference-local";
+/** Cordis companion plugin name. */
+const name = "file-reference-local-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: per-agent indexes are private advisory caches whose
+* invalidation and disposal are observed directly through service tests.
+*/
+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.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Local-filesystem implementation of `ctx.fileReferences`.
+ *
+ * @module @deepseek-ai/dsh-file-reference-local
+ */
+import { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import FileReferenceService, { type FileReferenceCandidate } from '@deepseek-ai/dsh-file-reference';
+export { DEFAULT_FILE_SEARCH_EXCLUDED_DIRECTORIES, DEFAULT_FILE_SEARCH_MAX_ENTRIES, DEFAULT_FILE_SEARCH_MAX_RESULTS, WorkspaceFileSearch, } from './search.ts';
+export type { FileSearchConfig } from './search.ts';
+export { FILE_REFERENCE_PROMPT } from '@deepseek-ai/dsh-file-reference';
+export { activeAtToken, formatFileMention } from '@deepseek-ai/dsh-file-reference/grammar';
+/** Local file-reference discovery configuration. */
+export interface Config {
+    /** Maximum ranked candidates returned for one query. */
+    maxResults?: number;
+    /** Maximum indexed files and directories per agent workspace. */
+    maxEntries?: number;
+    /** Directory basenames never traversed or offered. */
+    excludedDirectories?: string[];
+}
+/** Local-filesystem owner of the file-reference discovery service. */
+export declare class LocalFileReferenceService extends FileReferenceService {
+    static inject: string[];
+    static Config: z<Config>;
+    private readonly config;
+    private readonly searches;
+    private readonly promptFibers;
+    private readonly promptDisposals;
+    constructor(ctx: Context, config?: Config);
+    list(agent: Agent, query: string, signal: AbortSignal): Promise<FileReferenceCandidate[]>;
+}
+export default LocalFileReferenceService;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/index.js

@@ -0,0 +1,105 @@
+/**
+ * Local-filesystem implementation of `ctx.fileReferences`.
+ *
+ * @module @deepseek-ai/dsh-file-reference-local
+ */
+import z from '@deepseek-ai/schemastery';
+import FileReferenceService, { FILE_REFERENCE_PROMPT, } from '@deepseek-ai/dsh-file-reference';
+import { DEFAULT_FILE_SEARCH_EXCLUDED_DIRECTORIES, DEFAULT_FILE_SEARCH_MAX_ENTRIES, DEFAULT_FILE_SEARCH_MAX_RESULTS, WorkspaceFileSearch, } from "./search.js";
+export { DEFAULT_FILE_SEARCH_EXCLUDED_DIRECTORIES, DEFAULT_FILE_SEARCH_MAX_ENTRIES, DEFAULT_FILE_SEARCH_MAX_RESULTS, WorkspaceFileSearch, } from "./search.js";
+export { FILE_REFERENCE_PROMPT } from '@deepseek-ai/dsh-file-reference';
+export { activeAtToken, formatFileMention } from '@deepseek-ai/dsh-file-reference/grammar';
+/** Local-filesystem owner of the file-reference discovery service. */
+export class LocalFileReferenceService extends FileReferenceService {
+    static inject = ['agents'];
+    static Config = z.object({
+        maxResults: z.number().step(1).min(1).default(DEFAULT_FILE_SEARCH_MAX_RESULTS),
+        maxEntries: z.number().step(1).min(1).default(DEFAULT_FILE_SEARCH_MAX_ENTRIES),
+        excludedDirectories: z.array(z.string()).default([...DEFAULT_FILE_SEARCH_EXCLUDED_DIRECTORIES]),
+    });
+    config;
+    searches = new Map();
+    promptFibers = new Map();
+    promptDisposals = new Set();
+    constructor(ctx, config = {}) {
+        super(ctx);
+        this.config = {
+            maxResults: config.maxResults ?? DEFAULT_FILE_SEARCH_MAX_RESULTS,
+            maxEntries: config.maxEntries ?? DEFAULT_FILE_SEARCH_MAX_ENTRIES,
+            excludedDirectories: config.excludedDirectories ?? DEFAULT_FILE_SEARCH_EXCLUDED_DIRECTORIES,
+        };
+        validateConfig(this.config);
+        const installPrompt = (agent) => {
+            if (this.promptFibers.has(agent))
+                return;
+            const fiber = agent.ctx.inject(['systemPrompt', 'tools'], (scope) => {
+                scope.systemPrompt.section({
+                    name: 'context:file-reference',
+                    order: 99,
+                    text: () => agent.ctx.tools.get('read', agent) === undefined ? '' : FILE_REFERENCE_PROMPT,
+                });
+            });
+            this.promptFibers.set(agent, fiber);
+        };
+        const disposePrompt = (agent) => {
+            const fiber = this.promptFibers.get(agent);
+            if (fiber === undefined)
+                return;
+            this.promptFibers.delete(agent);
+            const task = fiber.dispose().catch((error) => {
+                ctx.logger.warn(`file-reference-local: prompt cleanup failed: ${error instanceof Error ? error.message : String(error)}`);
+            });
+            this.promptDisposals.add(task);
+            void task.finally(() => {
+                this.promptDisposals.delete(task);
+            });
+        };
+        for (const agent of ctx.agents.list())
+            installPrompt(agent);
+        ctx.on('agent/created', ({ agent }) => { installPrompt(agent); });
+        ctx.on('agent/disposed', ({ agent }) => {
+            this.searches.get(agent)?.dispose();
+            this.searches.delete(agent);
+            disposePrompt(agent);
+        });
+        ctx.on('session/event', (session, event) => {
+            if (event.type !== 'tool/result')
+                return;
+            const agent = ctx.agents.get(session.id);
+            if (agent !== undefined)
+                this.searches.get(agent)?.invalidate();
+        });
+        ctx.effect(() => async () => {
+            for (const search of this.searches.values())
+                search.dispose();
+            this.searches.clear();
+            const promptFibers = [...this.promptFibers.values()];
+            this.promptFibers.clear();
+            await Promise.all([
+                ...promptFibers.map(fiber => fiber.dispose()),
+                ...this.promptDisposals,
+            ]);
+        }, 'file-reference-local: search cache');
+    }
+    list(agent, query, signal) {
+        let search = this.searches.get(agent);
+        if (search === undefined) {
+            search = new WorkspaceFileSearch(agent.session.header.cwd ?? process.cwd(), this.config);
+            this.searches.set(agent, search);
+        }
+        return search.list(query, signal);
+    }
+}
+function validateConfig(config) {
+    if (!Number.isSafeInteger(config.maxResults) || config.maxResults <= 0) {
+        throw new Error('file-reference-local: maxResults must be a positive safe integer');
+    }
+    if (!Number.isSafeInteger(config.maxEntries) || config.maxEntries <= 0) {
+        throw new Error('file-reference-local: maxEntries must be a positive safe integer');
+    }
+    if (config.excludedDirectories.some(name => name.length === 0 || name.includes('/') || name.includes('\\'))) {
+        throw new Error('file-reference-local: excludedDirectories entries must be non-empty directory basenames');
+    }
+}
+export default LocalFileReferenceService;
+//# sourceMappingURL=index.js.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-file-reference-local`.
+ * @module @deepseek-ai/dsh-file-reference-local/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "file-reference-local-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/types/invariant.js

@@ -0,0 +1,22 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-file-reference-local`.
+ * @module @deepseek-ai/dsh-file-reference-local/invariant
+ */
+const PACKAGE_NAME = '@deepseek-ai/dsh-file-reference-local';
+/** Cordis companion plugin name. */
+export const name = 'file-reference-local-invariant';
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants'];
+/**
+ * No runtime invariant: per-agent indexes are private advisory caches whose
+ * invalidation and disposal are observed directly through service tests.
+ */
+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/types/search.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Host-workspace discovery for `@file` completion. The index contains paths
+ * only: selected values remain ordinary prompt text and file contents stay
+ * behind the model-facing `read` tool.
+ *
+ * @module @deepseek-ai/dsh-file-reference-local/search
+ */
+import type { FileReferenceCandidate } from '@deepseek-ai/dsh-file-reference';
+export { activeAtToken, formatFileMention } from '@deepseek-ai/dsh-file-reference/grammar';
+/** Default maximum file and directory candidates rendered for one query. */
+export declare const DEFAULT_FILE_SEARCH_MAX_RESULTS = 20;
+/** Default maximum entries retained in one workspace search index. */
+export declare const DEFAULT_FILE_SEARCH_MAX_ENTRIES = 10000;
+/** Directory basenames omitted from traversal unless the deployment overrides them. */
+export declare const DEFAULT_FILE_SEARCH_EXCLUDED_DIRECTORIES: readonly [".git", "node_modules"];
+/** Resolved limits and exclusions for one workspace index. */
+export interface FileSearchConfig {
+    /** Maximum ranked candidates returned for one query. */
+    maxResults: number;
+    /** Maximum indexed files and directories. */
+    maxEntries: number;
+    /** Directory basenames never traversed or offered. */
+    excludedDirectories: readonly string[];
+}
+/**
+ * Cancellable, reusable fuzzy index rooted at one agent working directory.
+ * Directory-scoped queries list live state; bare fuzzy queries share one
+ * bounded traversal until the `@` interaction ends or a tool result invalidates it.
+ */
+export declare class WorkspaceFileSearch {
+    private readonly root;
+    private readonly config;
+    private readonly excludedDirectories;
+    private generation;
+    private disposed;
+    constructor(root: string, config: FileSearchConfig);
+    /**
+     * Return ranked path candidates for the current token.
+     * @param rawQuery - path text following `@` or `@"`.
+     * @param signal - cancels this caller's wait without killing an index shared by a newer query.
+     * @returns at most `maxResults` deterministic candidates.
+     */
+    list(rawQuery: string, signal: AbortSignal): Promise<FileReferenceCandidate[]>;
+    /** Discard the current index so the next bare query observes a fresh tree. */
+    invalidate(): void;
+    /** Abort traversal and make later queries return no candidates. */
+    dispose(): void;
+    private ensureIndex;
+    private scanWorkspace;
+    private listDirectory;
+}
+//# sourceMappingURL=search.d.ts.map

package/lib/types/search.js

@@ -0,0 +1,258 @@
+/**
+ * Host-workspace discovery for `@file` completion. The index contains paths
+ * only: selected values remain ordinary prompt text and file contents stay
+ * behind the model-facing `read` tool.
+ *
+ * @module @deepseek-ai/dsh-file-reference-local/search
+ */
+import { lstat, readdir } from 'node:fs/promises';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
+export { activeAtToken, formatFileMention } from '@deepseek-ai/dsh-file-reference/grammar';
+/** Default maximum file and directory candidates rendered for one query. */
+export const DEFAULT_FILE_SEARCH_MAX_RESULTS = 20;
+/** Default maximum entries retained in one workspace search index. */
+export const DEFAULT_FILE_SEARCH_MAX_ENTRIES = 10_000;
+/** Directory basenames omitted from traversal unless the deployment overrides them. */
+export const DEFAULT_FILE_SEARCH_EXCLUDED_DIRECTORIES = ['.git', 'node_modules'];
+/**
+ * Cancellable, reusable fuzzy index rooted at one agent working directory.
+ * Directory-scoped queries list live state; bare fuzzy queries share one
+ * bounded traversal until the `@` interaction ends or a tool result invalidates it.
+ */
+export class WorkspaceFileSearch {
+    root;
+    config;
+    excludedDirectories;
+    generation;
+    disposed = false;
+    constructor(root, config) {
+        this.root = root;
+        this.config = config;
+        if (!Number.isSafeInteger(config.maxResults) || config.maxResults <= 0) {
+            throw new Error('file search maxResults must be a positive safe integer');
+        }
+        if (!Number.isSafeInteger(config.maxEntries) || config.maxEntries <= 0) {
+            throw new Error('file search maxEntries must be a positive safe integer');
+        }
+        if (config.excludedDirectories.some(name => name.length === 0 || name.includes('/') || name.includes('\\'))) {
+            throw new Error('file search excludedDirectories entries must be non-empty directory basenames');
+        }
+        this.excludedDirectories = new Set(config.excludedDirectories);
+    }
+    /**
+     * Return ranked path candidates for the current token.
+     * @param rawQuery - path text following `@` or `@"`.
+     * @param signal - cancels this caller's wait without killing an index shared by a newer query.
+     * @returns at most `maxResults` deterministic candidates.
+     */
+    async list(rawQuery, signal) {
+        signal.throwIfAborted();
+        if (this.disposed)
+            return [];
+        const query = rawQuery.replaceAll('\\', '/');
+        const slash = query.lastIndexOf('/');
+        if (query === '' || slash >= 0) {
+            const directory = slash < 0 ? '' : query.slice(0, slash + 1);
+            const fragment = slash < 0 ? '' : query.slice(slash + 1);
+            return this.listDirectory(directory, fragment, signal);
+        }
+        const indexed = await waitForPromise(this.ensureIndex(), signal);
+        return rankCandidates(indexed.filter(candidate => visibleForGlobalQuery(candidate.path, query)), query, this.config.maxResults);
+    }
+    /** Discard the current index so the next bare query observes a fresh tree. */
+    invalidate() {
+        this.generation?.controller.abort(new Error('file search index invalidated'));
+        this.generation = undefined;
+    }
+    /** Abort traversal and make later queries return no candidates. */
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        this.invalidate();
+    }
+    ensureIndex() {
+        if (this.generation !== undefined)
+            return this.generation.promise;
+        const controller = new AbortController();
+        const generation = {
+            controller,
+            promise: Promise.resolve([]),
+        };
+        generation.promise = this.scanWorkspace(controller.signal).catch((error) => {
+            /* v8 ignore next -- every owned abort clears `generation` synchronously; this only protects an unexpected scan failure */
+            if (this.generation === generation)
+                this.generation = undefined;
+            throw error;
+        });
+        this.generation = generation;
+        return generation.promise;
+    }
+    async scanWorkspace(signal) {
+        const indexed = [];
+        const directories = [{ absolute: this.root, relative: '' }];
+        for (let cursor = 0; cursor < directories.length && indexed.length < this.config.maxEntries; cursor += 1) {
+            signal.throwIfAborted();
+            const directory = directories[cursor];
+            /* v8 ignore next 3 -- cursor is bounded by this exact queue's length. */
+            if (directory === undefined) {
+                throw new Error('file search selected a missing directory');
+            }
+            const entries = await readDirectory(directory.absolute, signal);
+            for (const entry of entries) {
+                signal.throwIfAborted();
+                const path = directory.relative === '' ? entry.name : `${directory.relative}/${entry.name}`;
+                if (entry.isDirectory()) {
+                    if (this.excludedDirectories.has(entry.name))
+                        continue;
+                    indexed.push({ path, kind: 'directory' });
+                    directories.push({ absolute: join(directory.absolute, entry.name), relative: path });
+                }
+                else if (entry.isFile()) {
+                    indexed.push({ path, kind: 'file' });
+                }
+                if (indexed.length >= this.config.maxEntries)
+                    break;
+            }
+        }
+        return indexed;
+    }
+    async listDirectory(displayDirectory, fragment, signal) {
+        if (displayDirectory.split('/').some(segment => this.excludedDirectories.has(segment)))
+            return [];
+        const absolute = await resolveDisplayDirectory(this.root, displayDirectory, signal);
+        if (absolute === undefined)
+            return [];
+        const entries = await readDirectory(absolute, signal);
+        const candidates = [];
+        for (const entry of entries) {
+            if (entry.name.startsWith('.') && !fragment.startsWith('.'))
+                continue;
+            if (entry.isDirectory()) {
+                if (this.excludedDirectories.has(entry.name))
+                    continue;
+                candidates.push({ path: `${displayDirectory}${entry.name}`, kind: 'directory' });
+            }
+            else if (entry.isFile()) {
+                candidates.push({ path: `${displayDirectory}${entry.name}`, kind: 'file' });
+            }
+        }
+        return rankCandidates(candidates, fragment, this.config.maxResults);
+    }
+}
+async function resolveDisplayDirectory(root, displayDirectory, signal) {
+    const resolvedRoot = resolve(root);
+    const absolute = resolve(resolvedRoot, displayDirectory === '' ? '.' : displayDirectory);
+    const fromRoot = relative(resolvedRoot, absolute);
+    if (fromRoot === '..' || fromRoot.startsWith(`..${sep}`))
+        return undefined;
+    /* v8 ignore next -- only Windows can produce a cross-volume absolute relative path */
+    if (isAbsolute(fromRoot))
+        return undefined;
+    let current = resolvedRoot;
+    for (const segment of fromRoot.split(sep).filter(Boolean)) {
+        signal.throwIfAborted();
+        current = join(current, segment);
+        try {
+            const status = await lstat(current);
+            signal.throwIfAborted();
+            if (status.isSymbolicLink() || !status.isDirectory())
+                return undefined;
+        }
+        catch (_error) {
+            signal.throwIfAborted();
+            return undefined;
+        }
+    }
+    return absolute;
+}
+async function readDirectory(absolute, signal) {
+    signal.throwIfAborted();
+    try {
+        const entries = await readdir(absolute, { withFileTypes: true });
+        signal.throwIfAborted();
+        return entries.sort((left, right) => compareText(left.name, right.name));
+    }
+    catch (_error) {
+        signal.throwIfAborted();
+        // An unreadable/missing subtree contributes no candidates; other readable
+        // branches remain useful and autocomplete is advisory.
+        return [];
+    }
+}
+function visibleForGlobalQuery(path, query) {
+    if (query.startsWith('.') || query.includes('/.'))
+        return true;
+    return !path.split('/').some(segment => segment.startsWith('.'));
+}
+function rankCandidates(candidates, query, limit) {
+    const ranked = [];
+    for (const candidate of candidates) {
+        const score = scoreCandidate(candidate, query);
+        if (score !== undefined)
+            ranked.push({ candidate, score });
+    }
+    ranked.sort((left, right) => right.score - left.score
+        || kindRank(left.candidate.kind) - kindRank(right.candidate.kind)
+        || (query === '' ? 0 : left.candidate.path.length - right.candidate.path.length)
+        || compareText(left.candidate.path, right.candidate.path));
+    return ranked.slice(0, limit).map(entry => entry.candidate);
+}
+function scoreCandidate(candidate, query) {
+    if (query === '')
+        return 0;
+    const path = candidate.path.toLowerCase();
+    const name = path.slice(path.lastIndexOf('/') + 1);
+    const needle = query.toLowerCase();
+    const directoryBonus = candidate.kind === 'directory' ? 25 : 0;
+    if (name === needle)
+        return 1_000 + directoryBonus;
+    if (name.startsWith(needle))
+        return 900 + directoryBonus;
+    if (name.includes(needle))
+        return 700 + directoryBonus;
+    if (path.includes(needle))
+        return 500 + directoryBonus;
+    const subsequence = subsequenceScore(path, needle);
+    return subsequence === undefined ? undefined : 300 + subsequence + directoryBonus;
+}
+function subsequenceScore(target, query) {
+    let targetIndex = 0;
+    let gap = 0;
+    for (const character of query) {
+        const found = target.indexOf(character, targetIndex);
+        if (found < 0)
+            return undefined;
+        gap += found - targetIndex;
+        targetIndex = found + 1;
+    }
+    return Math.max(0, 100 - gap);
+}
+function kindRank(kind) {
+    return kind === 'directory' ? 0 : 1;
+}
+function compareText(left, right) {
+    /* v8 ignore next -- entries and candidates are unique; host enumeration
+     * order determines which comparison direction sort requests. */
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function waitForPromise(promise, signal) {
+    /* v8 ignore next -- `list()` checks this signal immediately before its synchronous call into this helper */
+    if (signal.aborted)
+        return Promise.reject(errorReason(signal.reason, 'file search aborted'));
+    return new Promise((resolvePromise, rejectPromise) => {
+        const onAbort = () => { rejectPromise(errorReason(signal.reason, 'file search aborted')); };
+        signal.addEventListener('abort', onAbort, { once: true });
+        promise.then((value) => {
+            signal.removeEventListener('abort', onAbort);
+            resolvePromise(value);
+        }, (error) => {
+            signal.removeEventListener('abort', onAbort);
+            rejectPromise(errorReason(error, 'file search index failed'));
+        });
+    });
+}
+function errorReason(reason, fallback) {
+    return reason instanceof Error ? reason : new Error(fallback, { cause: reason });
+}
+//# sourceMappingURL=search.js.map

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@deepseek-ai/dsh-file-reference-local",
+  "description": "Local-filesystem ctx.fileReferences provider with bounded fuzzy indexes",
+  "version": "0.1.0-rc.8",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/context/file-reference-local"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./search": {
+      "types": "./lib/types/search.d.ts",
+      "default": "./lib/types/search.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-agent": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-file-reference": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-system-prompt": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.8",
+    "@deepseek-ai/cordis": "^4.0.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-agent": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-file-reference": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-system-prompt": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.8",
+    "@deepseek-ai/cordis": "^4.0.1"
+  }
+}