@x1a0f3n9/dsh-file-reference 0.1.5-rc.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 DeepSeek
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,6 @@
1
+ # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
2
+ # side as of the last confirmed-consistent state. Both languages carry equal authority;
3
+ # after editing either side, bring the other along and re-record with:
4
+ # pnpm run verify-translation-pairing --write packages/context/file-reference/README.md
5
+ README.md: ce84a91e96988fb662ee665707d1ce2ad1651327
6
+ README.zh.md: ffdce668dd1b4a5a39a076d6abc998ec6db2ce92
package/README.md ADDED
@@ -0,0 +1,112 @@
1
+ ---
2
+ description: "File-reference discovery and @file mention grammar for host-backed UIs, for users and maintainers choosing the seam or pairing it with a provider."
3
+ kind: "package-reference"
4
+ ---
5
+
6
+ # @x1a0f3n9/dsh-file-reference
7
+
8
+ English | [中文](README.zh.md)
9
+
10
+ ## Summary
11
+
12
+ Host-backed user interfaces use `dsh-file-reference` to offer `@file` completion: a UI asks for path candidates for the addressed agent, the model types `@path` or `@"path with spaces"`, and picking a candidate inserts the matching mention as ordinary prompt text. The seam itself owns no filesystem access — a concrete provider such as `@x1a0f3n9/dsh-file-reference-local` supplies candidates, ranking, caching, and invalidation. Selecting a candidate never reads or attaches file contents; the model must call a filesystem tool to inspect a file. Session Controller exposes the same discovery to browser consumers through the `fileReferences/list` Remote.
13
+
14
+ ## Table of Contents
15
+
16
+ - [Use this package](#use-this-package)
17
+ - [Understand the implementation](#understand-the-implementation)
18
+ - [Further Exploration](#further-exploration)
19
+ - [Model Experience](#model-experience)
20
+ - [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
21
+ - [Dev Note](#dev-note)
22
+
23
+ -----
24
+
25
+ <a id="use-this-package"></a>
26
+ ## Use this package
27
+
28
+ Choose this package when a host-backed UI (web or terminal) should offer `@file` completion, and pair it with a provider whose namespace matches the agent's effective `read` tool. Mounting the seam without a provider gives the UI an empty completion surface.
29
+
30
+ ### Mention grammar
31
+
32
+ An `@path` token at the start of input or after whitespace triggers completion; an `@` inside another token, such as an email address, does not. `@"path with spaces"` opens a quoted mention, and a directory candidate keeps that quote open after its trailing slash so completion can descend another level. The formatter rejects paths with control characters or embedded quotes that the grammar cannot represent safely.
33
+
34
+ ### Getting candidates
35
+
36
+ `ctx.fileReferences.list(agent, query, signal)` returns path-only file and directory candidates for one agent's working directory, deterministically ranked by the provider. Directory mentions render with a trailing `/` so completion can descend another level. Browser consumers call the Session Controller adapter as `ctx.remote.fileReferences.list`; the trailing signal cancels a slow autocomplete.
37
+
38
+ ### Pairing with a provider
39
+
40
+ For a local filesystem, mount `@x1a0f3n9/dsh-file-reference-local`; other namespaces (remote or virtual filesystems) need a provider whose discovery matches the effective tool. When the addressed agent can call `read`, a provider may install the stable `FILE_REFERENCE_PROMPT` guidance that tells the model to read a referenced file before claiming to have inspected it.
41
+
42
+ -----
43
+
44
+ <a id="understand-the-implementation"></a>
45
+ ## Understand the implementation
46
+
47
+ <details>
48
+ <summary>Implementation internals — click to expand</summary>
49
+
50
+ This section explains the design of the seam; the observable behavior is covered in [Use this package](#use-this-package).
51
+
52
+ ### Design concept
53
+
54
+ The package separates an abstract discovery service from a shared, browser-safe mention grammar, with providers owning namespace access, ranking, caching, and invalidation. The service remains wire-neutral; `dsh-api-session-controller` owns the `fileReferences/list` Remote adapter and delegates to the active provider after resolving its Agent.
55
+
56
+ ### Source map
57
+
58
+ | File | Role |
59
+ |---|---|
60
+ | [`src/index.ts`](src/index.ts) | Abstract `FileReferenceService` and `FILE_REFERENCE_PROMPT` |
61
+ | [`src/grammar.ts`](src/grammar.ts) | `activeAtToken` recognition and `formatFileMention` rendering |
62
+ | [`src/types.ts`](src/types.ts) | `FileReferenceCandidate` path-only result type |
63
+ | — | No runtime invariant companion is published; the interface retains no candidate or lifecycle state; concrete providers own their cache and invalidation relationships. |
64
+
65
+ ### Main flow
66
+
67
+ The UI recognizes an active `@` token through `activeAtToken`, calls `list` with the query text, and renders the ranked candidates. On selection, `formatFileMention` emits the matching prompt spelling (`@path`, `@"path with spaces"`, or an open `@"dir/` for a quoted directory). No file content is read at any point; providers may additionally install the stable `FILE_REFERENCE_PROMPT` section when the addressed agent has a `read` tool.
68
+
69
+ </details>
70
+
71
+ -----
72
+
73
+ <a id="further-exploration"></a>
74
+ ## Further Exploration
75
+
76
+ Read these pages when the package-level contract is not enough. They move from the shipped provider to the shared reference surface and the tools the candidates point at.
77
+
78
+ - [Local file-reference provider](../file-reference-local/README.md) — the shipped local-workspace implementation of this seam.
79
+ - [Session-reference subsystem](../../../docs/subsystems/session-reference.md) — the shared file-reference and session-reference contracts behind host UIs.
80
+ - [Context group map](../README.md) — sibling request-context packages.
81
+ - [Filesystem tool catalog](../../../docs/tool-catalog.md#deepseek-aidsh-tool-fs) — the `read` tool that referenced paths are meant for.
82
+
83
+ -----
84
+
85
+ <a id="model-experience"></a>
86
+ ## Model Experience
87
+
88
+ Indirectly, through the composed provider, which owns the file-reference guidance that this package's discovery seam and grammar delegate to it.
89
+
90
+ #### KV Cache effect
91
+
92
+ The interface and grammar add no request tokens; a provider-owned prompt section determines whether the reusable prefix changes.
93
+
94
+ ## Known Limitations and Deferred Work
95
+
96
+ <a id="known-limitations-and-deferred-work"></a>
97
+
98
+
99
+ These limits define when the seam is a poor fit. They are current package constraints.
100
+
101
+ - **Path candidates are advisory** — the seam does not prove that a later model-facing filesystem tool can access the same namespace; deployments must align the provider with the effective `read` implementation.
102
+ - **No file-content reference object** — selected files remain ordinary prompt text and require an explicit model tool call before their contents become model-visible.
103
+
104
+ <a id="dev-note"></a>
105
+ ### Dev Note
106
+
107
+ <details>
108
+ <summary>Working context for maintainers — click to expand</summary>
109
+
110
+ None.
111
+
112
+ </details>
package/README.zh.md ADDED
@@ -0,0 +1,112 @@
1
+ ---
2
+ description: "面向宿主驱动 UI 的文件引用发现与 @file mention 语法,供选择该 seam 或为其搭配提供方的用户与维护者阅读。"
3
+ kind: "package-reference"
4
+ ---
5
+
6
+ # @x1a0f3n9/dsh-file-reference
7
+
8
+ [English](README.md) | 中文
9
+
10
+ ## 概述
11
+
12
+ 宿主驱动 UI 使用 `dsh-file-reference` 提供 `@file` 补全:UI 为指定 agent(智能体)请求路径候选,模型输入 `@path` 或 `@"path with spaces"`,选中候选后,匹配的 mention 作为普通提示词文本插入。seam 本身不拥有文件系统访问——具体提供方(如 `@x1a0f3n9/dsh-file-reference-local`)负责提供候选、排序、缓存与失效。选中候选绝不读取或附带文件内容;模型必须调用文件系统工具才能查看文件。Session Controller 通过 `fileReferences/list` Remote 向浏览器消费方暴露同一发现能力。
13
+
14
+ ## 目录
15
+
16
+ - [使用本包](#use-this-package)
17
+ - [理解实现](#understand-the-implementation)
18
+ - [进一步探索](#further-exploration)
19
+ - [模型体验](#model-experience)
20
+ - [已知限制与延期工作](#known-limitations-and-deferred-work)
21
+ - [开发备注](#dev-note)
22
+
23
+ -----
24
+
25
+ <a id="use-this-package"></a>
26
+ ## 使用本包
27
+
28
+ 当宿主驱动 UI(Web 或终端)需要提供 `@file` 补全时选择本包,并搭配一个命名空间与 agent 实际生效的 `read` 工具一致的提供方。单独挂载该 seam 而没有提供方时,UI 只能得到空的补全列表。
29
+
30
+ ### mention 语法
31
+
32
+ 输入开头或空白后的 `@path` token 会触发补全;其他 token 内部的 `@`(如电子邮件地址)不会。`@"path with spaces"` 打开带引号的 mention,目录候选在其尾斜杠后保持引号打开,使补全可以继续深入下一层。格式化器会拒绝含有语法无法安全表示的控制字符或内嵌引号的路径。
33
+
34
+ ### 获取候选
35
+
36
+ `ctx.fileReferences.list(agent, query, signal)` 返回指定 agent 工作目录中仅含路径的文件与目录候选,由提供方确定性地排序。目录 mention 呈现时带尾随 `/`,使补全可以继续深入下一层。浏览器消费方通过 Session Controller 适配器的 `ctx.remote.fileReferences.list` 调用同一发现能力;末位 signal 参数可取消慢速自动补全。
37
+
38
+ ### 搭配提供方
39
+
40
+ 本地文件系统请挂载 `@x1a0f3n9/dsh-file-reference-local`;其他命名空间(远程或虚拟文件系统)需要发现能力与生效工具一致的提供方。当指定 agent 可以调用 `read` 时,提供方可以安装稳定的 `FILE_REFERENCE_PROMPT` 指引,告诉模型先读取被引用文件、再声称检查过它。
41
+
42
+ -----
43
+
44
+ <a id="understand-the-implementation"></a>
45
+ ## 理解实现
46
+
47
+ <details>
48
+ <summary>实现细节——点击展开</summary>
49
+
50
+ 本节解释该 seam 的设计;可观察行为见[使用本包](#use-this-package)。
51
+
52
+ ### 设计理念
53
+
54
+ 本包把抽象发现服务与共享、浏览器安全的 mention 语法分开,由提供方负责命名空间访问、排序、缓存与失效。该服务保持 wire 中立;`dsh-api-session-controller` 持有 `fileReferences/list` Remote 适配器,并在解析 Agent 后委派给当前提供方。
55
+
56
+ ### 源码地图
57
+
58
+ | 文件 | 职责 |
59
+ |---|---|
60
+ | [`src/index.ts`](src/index.ts) | 抽象 `FileReferenceService` 与 `FILE_REFERENCE_PROMPT` |
61
+ | [`src/grammar.ts`](src/grammar.ts) | `activeAtToken` 识别与 `formatFileMention` 渲染 |
62
+ | [`src/types.ts`](src/types.ts) | 仅含路径的结果类型 `FileReferenceCandidate` |
63
+ | — | 不发布运行时不变式伴生入口;接口不保留 candidate 或 lifecycle 状态;具体提供方负责自己的 cache 与 invalidation 关系。 |
64
+
65
+ ### 主要流程
66
+
67
+ UI 通过 `activeAtToken` 识别活动 `@` token,用查询文本调用 `list`,再渲染排序后的候选。选中后,`formatFileMention` 发出匹配的提示词写法(`@path`、`@"path with spaces"`,或带引号目录的开放形式 `@"dir/`)。任何环节都不读取文件内容;当指定 agent 拥有 `read` 工具时,提供方还可以安装稳定的 `FILE_REFERENCE_PROMPT` 提示词段。
68
+
69
+ </details>
70
+
71
+ -----
72
+
73
+ <a id="further-exploration"></a>
74
+ ## 进一步探索
75
+
76
+ 包级约定不够用时阅读以下页面。它们从随附提供方进入共享引用表面,以及候选所指向的工具。
77
+
78
+ - [本地文件引用提供方](../file-reference-local/README.zh.md)——本 seam 的随附本地工作区实现。
79
+ - [会话引用子系统](../../../docs/subsystems/session-reference.zh.md)——宿主 UI 背后的共享文件引用与会话引用约定。
80
+ - [上下文组地图](../README.zh.md)——相邻的请求上下文包。
81
+ - [文件系统工具目录](../../../docs/tool-catalog.zh.md#deepseek-aidsh-tool-fs)——被引用路径所对应的 `read` 工具。
82
+
83
+ -----
84
+
85
+ <a id="model-experience"></a>
86
+ ## 模型体验
87
+
88
+ 间接影响模型体验:本包的发现 seam 与语法把文件引用指引委托给组合的提供方,由它负责呈现。
89
+
90
+ #### KV Cache 影响
91
+
92
+ 接口与语法本身不增加请求 token;提供方拥有的提示词段决定可复用前缀是否改变。
93
+
94
+ ## 已知限制与延期工作
95
+
96
+ <a id="known-limitations-and-deferred-work"></a>
97
+
98
+
99
+ 这些限制说明该 seam 何时不合适。它们是当前包约束。
100
+
101
+ - **路径候选仅供参考**:该 seam 不保证后续面向模型的文件系统工具能够访问同一命名空间;部署时必须让提供方与实际生效的 `read` 实现对齐。
102
+ - **没有文件内容引用对象**:所选文件仍是普通提示词文本,其内容必须经过模型显式调用工具后才对模型可见。
103
+
104
+ <a id="dev-note"></a>
105
+ ### 开发备注
106
+
107
+ <details>
108
+ <summary>维护者的工作上下文——点击展开</summary>
109
+
110
+ 无。
111
+
112
+ </details>
package/lib/index.js ADDED
@@ -0,0 +1,62 @@
1
+ import { Service } from "@deepseek-ai/cordis";
2
+ //#region lib/types/grammar.js
3
+ /**
4
+ * Browser-safe `@file` token grammar shared by terminal and web clients.
5
+ *
6
+ * @module @x1a0f3n9/dsh-file-reference/grammar
7
+ */
8
+ /**
9
+ * Extract an `@path` or `@"path with spaces` token at the cursor. An `@`
10
+ * inside another token, such as an email address, is not a completion trigger.
11
+ * @param line - current editor line.
12
+ * @param cursorCol - cursor column within that line.
13
+ * @returns the active token, or `undefined` outside an `@` token.
14
+ */
15
+ function activeAtToken(line, cursorCol) {
16
+ const beforeCursor = line.slice(0, cursorCol);
17
+ const quoted = /(?:^|\s)(@"([^"]*))$/u.exec(beforeCursor);
18
+ if (quoted?.[1] !== void 0 && quoted[2] !== void 0) return {
19
+ prefix: quoted[1],
20
+ query: quoted[2],
21
+ quoted: true
22
+ };
23
+ const plain = /(?:^|\s)(@([^\s]*))$/u.exec(beforeCursor);
24
+ if (plain?.[1] === void 0 || plain[2] === void 0) return void 0;
25
+ return {
26
+ prefix: plain[1],
27
+ query: plain[2],
28
+ quoted: false
29
+ };
30
+ }
31
+ /**
32
+ * Format a selected path as prompt text. Whitespace uses the quoted
33
+ * `@"path"` grammar; a quoted directory keeps that quote open after its
34
+ * trailing slash so completion can descend another level.
35
+ * @param candidate - selected file or directory.
36
+ * @param preserveQuote - retain an explicitly opened quote even when unnecessary.
37
+ * @returns the insertion value, or `undefined` for a path the editor grammar cannot represent safely.
38
+ */
39
+ function formatFileMention(candidate, preserveQuote) {
40
+ const path = candidate.kind === "directory" ? `${candidate.path}/` : candidate.path;
41
+ if (/[\u0000-\u001f\u007f-\u009f"]/u.test(path)) return void 0;
42
+ if (!(preserveQuote || /\s/u.test(path))) return `@${path}`;
43
+ if (candidate.kind === "directory") return `@"${path}`;
44
+ return `@"${path}"`;
45
+ }
46
+ //#endregion
47
+ //#region lib/types/index.js
48
+ /**
49
+ * File-reference discovery seam shared by host-backed user interfaces.
50
+ *
51
+ * @module @x1a0f3n9/dsh-file-reference
52
+ */
53
+ /** Model guidance for path-only references selected by a user interface. */
54
+ const FILE_REFERENCE_PROMPT = "Tokens prefixed with @ are workspace paths the user explicitly referenced, relative to the workspace root. A trailing slash marks a directory: list it when its contents matter. Anything else is a file: use the read tool when its contents are needed, and do not claim to have inspected it before reading. @\"...\" quotes a path containing spaces.";
55
+ /** Host capability for cancellable file-reference discovery. */
56
+ var FileReferenceService = class extends Service {
57
+ constructor(ctx) {
58
+ super(ctx, "fileReferences");
59
+ }
60
+ };
61
+ //#endregion
62
+ export { FILE_REFERENCE_PROMPT, FileReferenceService, FileReferenceService as default, activeAtToken, formatFileMention };
@@ -0,0 +1,33 @@
1
+ /**
2
+ * Browser-safe `@file` token grammar shared by terminal and web clients.
3
+ *
4
+ * @module @x1a0f3n9/dsh-file-reference/grammar
5
+ */
6
+ import type { FileReferenceCandidate } from './types.ts';
7
+ /** Active `@` token ending at the editor cursor. */
8
+ export interface ActiveAtToken {
9
+ /** Complete token replaced when the user accepts a completion. */
10
+ prefix: string;
11
+ /** Path query after `@` or `@"`. */
12
+ query: string;
13
+ /** Whether the user opened a quoted path. */
14
+ quoted: boolean;
15
+ }
16
+ /**
17
+ * Extract an `@path` or `@"path with spaces` token at the cursor. An `@`
18
+ * inside another token, such as an email address, is not a completion trigger.
19
+ * @param line - current editor line.
20
+ * @param cursorCol - cursor column within that line.
21
+ * @returns the active token, or `undefined` outside an `@` token.
22
+ */
23
+ export declare function activeAtToken(line: string, cursorCol: number): ActiveAtToken | undefined;
24
+ /**
25
+ * Format a selected path as prompt text. Whitespace uses the quoted
26
+ * `@"path"` grammar; a quoted directory keeps that quote open after its
27
+ * trailing slash so completion can descend another level.
28
+ * @param candidate - selected file or directory.
29
+ * @param preserveQuote - retain an explicitly opened quote even when unnecessary.
30
+ * @returns the insertion value, or `undefined` for a path the editor grammar cannot represent safely.
31
+ */
32
+ export declare function formatFileMention(candidate: FileReferenceCandidate, preserveQuote: boolean): string | undefined;
33
+ //# sourceMappingURL=grammar.d.ts.map
@@ -0,0 +1,43 @@
1
+ /**
2
+ * Browser-safe `@file` token grammar shared by terminal and web clients.
3
+ *
4
+ * @module @x1a0f3n9/dsh-file-reference/grammar
5
+ */
6
+ /**
7
+ * Extract an `@path` or `@"path with spaces` token at the cursor. An `@`
8
+ * inside another token, such as an email address, is not a completion trigger.
9
+ * @param line - current editor line.
10
+ * @param cursorCol - cursor column within that line.
11
+ * @returns the active token, or `undefined` outside an `@` token.
12
+ */
13
+ export function activeAtToken(line, cursorCol) {
14
+ const beforeCursor = line.slice(0, cursorCol);
15
+ const quoted = /(?:^|\s)(@"([^"]*))$/u.exec(beforeCursor);
16
+ if (quoted?.[1] !== undefined && quoted[2] !== undefined) {
17
+ return { prefix: quoted[1], query: quoted[2], quoted: true };
18
+ }
19
+ const plain = /(?:^|\s)(@([^\s]*))$/u.exec(beforeCursor);
20
+ if (plain?.[1] === undefined || plain[2] === undefined)
21
+ return undefined;
22
+ return { prefix: plain[1], query: plain[2], quoted: false };
23
+ }
24
+ /**
25
+ * Format a selected path as prompt text. Whitespace uses the quoted
26
+ * `@"path"` grammar; a quoted directory keeps that quote open after its
27
+ * trailing slash so completion can descend another level.
28
+ * @param candidate - selected file or directory.
29
+ * @param preserveQuote - retain an explicitly opened quote even when unnecessary.
30
+ * @returns the insertion value, or `undefined` for a path the editor grammar cannot represent safely.
31
+ */
32
+ export function formatFileMention(candidate, preserveQuote) {
33
+ const path = candidate.kind === 'directory' ? `${candidate.path}/` : candidate.path;
34
+ if (/[\u0000-\u001f\u007f-\u009f"]/u.test(path))
35
+ return undefined;
36
+ const quoted = preserveQuote || /\s/u.test(path);
37
+ if (!quoted)
38
+ return `@${path}`;
39
+ if (candidate.kind === 'directory')
40
+ return `@"${path}`;
41
+ return `@"${path}"`;
42
+ }
43
+ //# sourceMappingURL=grammar.js.map
@@ -0,0 +1,32 @@
1
+ /**
2
+ * File-reference discovery seam shared by host-backed user interfaces.
3
+ *
4
+ * @module @x1a0f3n9/dsh-file-reference
5
+ */
6
+ import { Service, type Context } from '@deepseek-ai/cordis';
7
+ import type { Agent } from '@x1a0f3n9/dsh-agent';
8
+ import type { FileReferenceCandidate } from './types.ts';
9
+ export { activeAtToken, formatFileMention } from './grammar.ts';
10
+ export type { ActiveAtToken } from './grammar.ts';
11
+ export type { FileReferenceCandidate } from './types.ts';
12
+ /** Model guidance for path-only references selected by a user interface. */
13
+ export declare const FILE_REFERENCE_PROMPT = "Tokens prefixed with @ are workspace paths the user explicitly referenced, relative to the workspace root. A trailing slash marks a directory: list it when its contents matter. Anything else is a file: use the read tool when its contents are needed, and do not claim to have inspected it before reading. @\"...\" quotes a path containing spaces.";
14
+ declare module '@deepseek-ai/cordis' {
15
+ interface Context {
16
+ fileReferences: FileReferenceService;
17
+ }
18
+ }
19
+ /** Host capability for cancellable file-reference discovery. */
20
+ export declare abstract class FileReferenceService extends Service {
21
+ constructor(ctx: Context);
22
+ /**
23
+ * List file and directory candidates for one agent's working directory.
24
+ * @param agent - target agent whose session cwd bounds discovery.
25
+ * @param query - path text following `@` or `@"`.
26
+ * @param signal - caller cancellation.
27
+ * @returns deterministic path-only candidates.
28
+ */
29
+ abstract list(agent: Agent, query: string, signal: AbortSignal): Promise<FileReferenceCandidate[]>;
30
+ }
31
+ export default FileReferenceService;
32
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1,17 @@
1
+ /**
2
+ * File-reference discovery seam shared by host-backed user interfaces.
3
+ *
4
+ * @module @x1a0f3n9/dsh-file-reference
5
+ */
6
+ import { Service } from '@deepseek-ai/cordis';
7
+ export { activeAtToken, formatFileMention } from "./grammar.js";
8
+ /** Model guidance for path-only references selected by a user interface. */
9
+ export const FILE_REFERENCE_PROMPT = 'Tokens prefixed with @ are workspace paths the user explicitly referenced, relative to the workspace root. A trailing slash marks a directory: list it when its contents matter. Anything else is a file: use the read tool when its contents are needed, and do not claim to have inspected it before reading. @"..." quotes a path containing spaces.';
10
+ /** Host capability for cancellable file-reference discovery. */
11
+ export class FileReferenceService extends Service {
12
+ constructor(ctx) {
13
+ super(ctx, 'fileReferences');
14
+ }
15
+ }
16
+ export default FileReferenceService;
17
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1,13 @@
1
+ /**
2
+ * Public file-reference discovery records. This module contains types only so
3
+ * generated Remote clients can consume it without Host runtime code.
4
+ * @module @x1a0f3n9/dsh-file-reference/types
5
+ */
6
+ /** One path-only completion candidate inside the target session cwd. */
7
+ export interface FileReferenceCandidate {
8
+ /** User-facing path accepted by normal prompts and filesystem tools. */
9
+ path: string;
10
+ /** Directories keep completion open; files finish the mention. */
11
+ kind: 'file' | 'directory';
12
+ }
13
+ //# sourceMappingURL=types.d.ts.map
@@ -0,0 +1,7 @@
1
+ /**
2
+ * Public file-reference discovery records. This module contains types only so
3
+ * generated Remote clients can consume it without Host runtime code.
4
+ * @module @x1a0f3n9/dsh-file-reference/types
5
+ */
6
+ export {};
7
+ //# sourceMappingURL=types.js.map
package/package.json ADDED
@@ -0,0 +1,46 @@
1
+ {
2
+ "name": "@x1a0f3n9/dsh-file-reference",
3
+ "description": "File-reference discovery contract and shared @file grammar",
4
+ "version": "0.1.5-rc.3",
5
+ "publishConfig": {
6
+ "access": "public"
7
+ },
8
+ "repository": {
9
+ "type": "git",
10
+ "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
11
+ "directory": "packages/context/file-reference"
12
+ },
13
+ "type": "module",
14
+ "main": "lib/index.js",
15
+ "types": "lib/types/index.d.ts",
16
+ "exports": {
17
+ ".": {
18
+ "types": "./lib/types/index.d.ts",
19
+ "default": "./lib/index.js"
20
+ },
21
+ "./grammar": {
22
+ "types": "./lib/types/grammar.d.ts",
23
+ "default": "./lib/types/grammar.js"
24
+ },
25
+ "./types": {
26
+ "types": "./lib/types/types.d.ts",
27
+ "default": "./lib/types/types.js"
28
+ },
29
+ "./src/*": "./src/*",
30
+ "./package.json": "./package.json"
31
+ },
32
+ "files": [
33
+ "lib/index.js",
34
+ "lib/types/**/*.js",
35
+ "lib/types/**/*.d.ts"
36
+ ],
37
+ "license": "MIT",
38
+ "peerDependencies": {
39
+ "@x1a0f3n9/dsh-agent": "^0.1.5-rc.3",
40
+ "@deepseek-ai/cordis": "^4.0.2"
41
+ },
42
+ "devDependencies": {
43
+ "@x1a0f3n9/dsh-agent": "^0.1.5-rc.3",
44
+ "@deepseek-ai/cordis": "^4.0.2"
45
+ }
46
+ }