@deepseek-ai/dsh-file-reference 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/README.md
+README.md: ae0e1ef68f927890af78767660cac094d831380c
+README.zh.md: 1645dd345cd52cf5d3e02270c1fbd4c4344ada37

package/README.md

@@ -0,0 +1,22 @@
+# `@deepseek-ai/dsh-file-reference`
+
+English | [中文](README.zh.md)
+
+File-reference discovery seam and browser-safe `@file` grammar shared by host-backed user interfaces. `ctx.fileReferences.list(agent, query, signal)` returns path-only file or directory candidates for the addressed agent; concrete providers own namespace access, ranking, caching, and invalidation. The same contract is remotely callable as the unary `fileReferences/list` Remote method (`@Remote` on the Service Definition, cancelled through the reserved trailing signal), so browser consumers call `ctx.remote.fileReferences.list` without an API Proxy route.
+
+`activeAtToken()` recognizes an `@path` or open `@"path with spaces` token only at the start of input or after whitespace, so email-like text does not open completion. `formatFileMention()` emits the matching prompt spelling, appends `/` to directory candidates, preserves an explicitly opened quote, and rejects control characters or embedded quotes that the editor grammar cannot represent safely.
+
+Selecting a candidate does not read or attach file contents. The exported `FILE_REFERENCE_PROMPT` is stable guidance that a provider may install when the addressed agent can call `read`.
+
+## Model Experience
+
+Indirectly, through `@deepseek-ai/dsh-file-reference-local`, which conditionally contributes this package's stable file-reference guidance.
+
+#### KV Cache effect
+
+The interface and grammar add no request tokens themselves; a provider-owned prompt section determines cache behavior.
+
+## Known Limitations and Deferred Work
+
+- **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.
+- **No file-content reference object** — selected files remain ordinary prompt text and require an explicit model tool call before their contents become model-visible.

package/README.zh.md

@@ -0,0 +1,22 @@
+# `@deepseek-ai/dsh-file-reference`
+
+[English](README.md) | 中文
+
+文件引用发现 seam，以及供宿主驱动的用户界面共享、可在浏览器中安全使用的 `@file` 语法。`ctx.fileReferences.list(agent, query, signal)` 为指定 agent（智能体）返回仅含路径的文件或目录候选；具体提供方负责命名空间访问、排序、缓存和失效处理。同一契约以一元 `fileReferences/list` Remote 方法对外可调（`@Remote` 标注在 Service Definition 上，经保留的末位 signal 参数取消），浏览器消费方直接调用 `ctx.remote.fileReferences.list`，无需 API Proxy 路由。
+
+`activeAtToken()` 只在输入开头或空白后识别 `@path` 或尚未闭合的 `@"path with spaces` token，因此类似电子邮件的文本不会打开补全。`formatFileMention()` 会生成与提示词匹配的写法，为目录候选追加 `/`，保留显式打开的引号，并拒绝编辑器语法无法安全表示的控制字符或内嵌引号。
+
+选择候选项不会读取或附加文件内容。导出的 `FILE_REFERENCE_PROMPT` 是稳定指引；当指定 agent 可以调用 `read` 时，提供方可以安装该指引。
+
+## 模型体验
+
+间接影响模型体验：`@deepseek-ai/dsh-file-reference-local` 会按条件贡献本包的稳定文件引用指引。
+
+#### KV 缓存影响
+
+接口和语法本身不会增加请求 token；缓存行为取决于提供方拥有的提示词段。
+
+## 已知限制与暂缓事项
+
+- **路径候选仅供参考**：该 seam 不保证后续面向模型的文件系统工具能够访问同一命名空间；部署时必须让提供方与实际生效的 `read` 实现对齐。
+- **没有文件内容引用对象**：所选文件仍是普通提示词文本，其内容必须经过模型显式调用工具后才对模型可见。

package/lib/index.js

@@ -0,0 +1,138 @@
+import { Remote, TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
+//#region lib/types/grammar.js
+/**
+* Browser-safe `@file` token grammar shared by terminal and web clients.
+*
+* @module @deepseek-ai/dsh-file-reference/grammar
+*/
+/**
+* Extract an `@path` or `@"path with spaces` token at the cursor. An `@`
+* inside another token, such as an email address, is not a completion trigger.
+* @param line - current editor line.
+* @param cursorCol - cursor column within that line.
+* @returns the active token, or `undefined` outside an `@` token.
+*/
+function activeAtToken(line, cursorCol) {
+	const beforeCursor = line.slice(0, cursorCol);
+	const quoted = /(?:^|\s)(@"([^"]*))$/u.exec(beforeCursor);
+	if (quoted?.[1] !== void 0 && quoted[2] !== void 0) return {
+		prefix: quoted[1],
+		query: quoted[2],
+		quoted: true
+	};
+	const plain = /(?:^|\s)(@([^\s]*))$/u.exec(beforeCursor);
+	if (plain?.[1] === void 0 || plain[2] === void 0) return void 0;
+	return {
+		prefix: plain[1],
+		query: plain[2],
+		quoted: false
+	};
+}
+/**
+* Format a selected path as prompt text. Whitespace uses the quoted
+* `@"path"` grammar; a quoted directory keeps that quote open after its
+* trailing slash so completion can descend another level.
+* @param candidate - selected file or directory.
+* @param preserveQuote - retain an explicitly opened quote even when unnecessary.
+* @returns the insertion value, or `undefined` for a path the editor grammar cannot represent safely.
+*/
+function formatFileMention(candidate, preserveQuote) {
+	const path = candidate.kind === "directory" ? `${candidate.path}/` : candidate.path;
+	if (/[\u0000-\u001f\u007f-\u009f"]/u.test(path)) return void 0;
+	if (!(preserveQuote || /\s/u.test(path))) return `@${path}`;
+	if (candidate.kind === "directory") return `@"${path}`;
+	return `@"${path}"`;
+}
+//#endregion
+//#region lib/types/index.js
+/**
+* File-reference discovery seam shared by host-backed user interfaces.
+*
+* @module @deepseek-ai/dsh-file-reference
+*/
+var __runInitializers = function(thisArg, initializers, value) {
+	var useValue = arguments.length > 2;
+	for (var i = 0; i < initializers.length; i++) value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+	return useValue ? value : void 0;
+};
+var __esDecorate = function(ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
+	function accept(f) {
+		if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected");
+		return f;
+	}
+	var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
+	var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+	var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+	var _, done = false;
+	for (var i = decorators.length - 1; i >= 0; i--) {
+		var context = {};
+		for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+		for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+		context.addInitializer = function(f) {
+			if (done) throw new TypeError("Cannot add initializers after decoration has completed");
+			extraInitializers.push(accept(f || null));
+		};
+		var result = (0, decorators[i])(kind === "accessor" ? {
+			get: descriptor.get,
+			set: descriptor.set
+		} : descriptor[key], context);
+		if (kind === "accessor") {
+			if (result === void 0) continue;
+			if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+			if (_ = accept(result.get)) descriptor.get = _;
+			if (_ = accept(result.set)) descriptor.set = _;
+			if (_ = accept(result.init)) initializers.unshift(_);
+		} else if (_ = accept(result)) if (kind === "field") initializers.unshift(_);
+		else descriptor[key] = _;
+	}
+	if (target) Object.defineProperty(target, contextIn.name, descriptor);
+	done = true;
+};
+/** Model guidance for path-only references selected by a user interface. */
+const FILE_REFERENCE_PROMPT = "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.";
+/** Host capability for cancellable file-reference discovery. */
+let FileReferenceService = (() => {
+	let _classSuper = TypertRemoteService;
+	let _instanceExtraInitializers = [];
+	let _remoteExportList_decorators;
+	return class FileReferenceService extends _classSuper {
+		static {
+			const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
+			_remoteExportList_decorators = [Remote("list")];
+			__esDecorate(this, null, _remoteExportList_decorators, {
+				kind: "method",
+				name: "remoteExportList",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "remoteExportList" in obj,
+					get: (obj) => obj.remoteExportList
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			if (_metadata) Object.defineProperty(this, Symbol.metadata, {
+				enumerable: true,
+				configurable: true,
+				writable: true,
+				value: _metadata
+			});
+		}
+		constructor(ctx) {
+			super(ctx, "fileReferences");
+			__runInitializers(this, _instanceExtraInitializers);
+		}
+		/**
+		* Remote face of {@link list}; the decorator cannot mark the abstract
+		* member, so this concrete adapter carries the identical contract.
+		* @param agent - target agent whose session cwd bounds discovery.
+		* @param query - path text following `@` or `@"`.
+		* @param signal - caller cancellation.
+		* @returns deterministic path-only candidates.
+		*/
+		remoteExportList(agent, query, signal) {
+			return this.list(agent, query, signal);
+		}
+	};
+})();
+//#endregion
+export { FILE_REFERENCE_PROMPT, FileReferenceService, FileReferenceService as default, 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`.
+* @module @deepseek-ai/dsh-file-reference/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-file-reference";
+/** Cordis companion plugin name. */
+const name = "file-reference-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: the interface retains no candidate or lifecycle
+* state; concrete providers own their cache and invalidation relationships.
+*/
+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/typert.host.d.ts

@@ -0,0 +1,3 @@
+/* Generated by @deepseek-ai/dsh-typert-generator from FaceModel — do not edit. */
+
+export declare const TYPERT: unknown

package/lib/typert.host.js

@@ -0,0 +1,436 @@
+/* Generated by @deepseek-ai/dsh-typert-generator from FaceModel — do not edit. */
+import { z } from 'zod'
+
+const _deepseek_ai_dsh_file_reference_fileReferences_list_parameter_0$schema = z.intersection(z.string(), z.unknown())
+const _deepseek_ai_dsh_file_reference_fileReferences_list_parameter_1$schema = z.string()
+const _deepseek_ai_dsh_file_reference_fileReferences_list_result$schema = z.array(z.object({
+  'path': z.string(),
+  'kind': z.union([z.literal("file"), z.literal("directory")]),
+}))
+
+export const TYPERT = {
+  package: '@deepseek-ai/dsh-file-reference',
+  face: 'host',
+  schemas: [
+  ],
+  invocations: [
+    {
+      id: '@deepseek-ai/dsh-file-reference#fileReferences/list',
+      service: 'fileReferences',
+      namespace: 'fileReferences',
+      method: 'list',
+      implementation: 'remoteExportList',
+      invocation: { kind: 'direct' },
+      scope: {
+        context: 'agent',
+        wire: 'agentId',
+      },
+      parameters: [
+        {
+          name: 'agent',
+          wire: 'agentId',
+          source: 'lookup',
+          lookup: 'agent',
+          codec: {
+            mode: 'strict',
+            typeSymbol: '@deepseek-ai/dsh-session/types#SessionId',
+            schema: _deepseek_ai_dsh_file_reference_fileReferences_list_parameter_0$schema,
+          },
+        },
+        {
+          name: 'query',
+          wire: 'query',
+          source: 'json',
+          codec: {
+            mode: 'strict',
+            typeSymbol: '@deepseek-ai/dsh-file-reference#fileReferences/list:query',
+            schema: _deepseek_ai_dsh_file_reference_fileReferences_list_parameter_1$schema,
+          },
+        },
+      ],
+      cancellation: { parameter: 'signal' },
+      result: {
+        mode: 'strict',
+        typeSymbol: '@deepseek-ai/dsh-file-reference#fileReferences/list:result',
+        schema: _deepseek_ai_dsh_file_reference_fileReferences_list_result$schema,
+      },
+      sourceLocation: {"file":"packages/context/file-reference/src/index.ts","line":54,"column":3},
+    },
+  ],
+  model: {
+    "services": [
+      {
+        "description": "Host capability for cancellable file-reference discovery.",
+        "summary": "Host capability for cancellable file-reference discovery.",
+        "tags": [],
+        "jsDoc": "/** Host capability for cancellable file-reference discovery. */",
+        "key": "fileReferences",
+        "exportName": "FileReferenceService",
+        "members": [
+          {
+            "kind": "method",
+            "name": "list",
+            "signature": "abstract list( agent: Agent, query: string, signal: AbortSignal, ): Promise<FileReferenceCandidate[]>",
+            "summary": "List file and directory candidates for one agent's working directory.",
+            "jsDoc": "/**\n * List file and directory candidates for one agent's working directory.\n * @param agent - target agent whose session cwd bounds discovery.\n * @param query - path text following `@` or `@\"`.\n * @param signal - caller cancellation.\n * @returns deterministic path-only candidates.\n */"
+          },
+          {
+            "kind": "method",
+            "name": "remoteExportList",
+            "signature": "@Remote('list') remoteExportList( agent: Agent, query: string, signal: AbortSignal, ): Promise<FileReferenceCandidate[]>",
+            "summary": "Remote face of {@link list}; the decorator cannot mark the abstract member, so this concrete adapter carries the identical contract.",
+            "jsDoc": "/**\n * Remote face of {@link list}; the decorator cannot mark the abstract\n * member, so this concrete adapter carries the identical contract.\n * @param agent - target agent whose session cwd bounds discovery.\n * @param query - path text following `@` or `@\"`.\n * @param signal - caller cancellation.\n * @returns deterministic path-only candidates.\n */"
+          }
+        ],
+        "types": [
+          {
+            "name": "Agent",
+            "declaration": "export interface Agent {\n    readonly id: SessionId;\n    readonly options: AgentOptions;\n    readonly session: Session;\n    readonly inbox: Inbox;\n    readonly status: AgentStatus;\n    readonly ctx: Context;\n    cancel(cause: AgentCancelCause, options?: CancelOptions): void;\n    whenIdle(): Promise<void>;\n    runMaintenance<T>(task: (signal: AbortSignal) => Promise<T>): Promise<T>;\n    send(message: UserMessage, target: InboxTarget, wakeup: boolean): void;\n    followup(message: UserMessage): void;\n    steer(message: UserMessage): void;\n    inject(message: UserMessage): void;\n}"
+          },
+          {
+            "name": "AgentCancelCause",
+            "declaration": "export type AgentCancelCause = { readonly kind: 'user'; } | { readonly kind: 'parent'; } | { readonly kind: 'hook'; readonly reason: string; } | { readonly kind: 'disposed'; };"
+          },
+          {
+            "name": "AgentOptions",
+            "declaration": "export interface AgentOptions {\n    provider?: string;\n    model?: string;\n    maxTokens?: number;\n}"
+          },
+          {
+            "name": "AgentStatus",
+            "declaration": "export type AgentStatus = 'idle' | 'running';"
+          },
+          {
+            "name": "ApprovalOutcome",
+            "declaration": "export type ApprovalOutcome = 'allowed-once' | 'rejected' | 'cancelled' | 'unavailable';"
+          },
+          {
+            "name": "ApprovalPolicy",
+            "declaration": "export type ApprovalPolicy = 'ask' | 'never';"
+          },
+          {
+            "name": "ApprovalRequestId",
+            "declaration": "export type ApprovalRequestId = Branded<'ApprovalRequestId'>;"
+          },
+          {
+            "name": "AssistantMessage",
+            "declaration": "export interface AssistantMessage extends Message {\n    readonly role: 'assistant';\n    readonly source: ModelMessageSource;\n}"
+          },
+          {
+            "name": "AssistantProvenance",
+            "declaration": "export interface AssistantProvenance {\n    provider: string;\n    model: string;\n    replayState?: unknown;\n}"
+          },
+          {
+            "name": "AttachmentId",
+            "declaration": "export type AttachmentId = Branded<'AttachmentId'>;"
+          },
+          {
+            "name": "Branded",
+            "declaration": "export type Branded<B extends string> = string & { readonly [BRAND]: B; };"
+          },
+          {
+            "name": "CallId",
+            "declaration": "export type CallId = Branded<'CallId'>;"
+          },
+          {
+            "name": "CancelOptions",
+            "declaration": "export interface CancelOptions {\n    keepInbox?: boolean | undefined;\n}"
+          },
+          {
+            "name": "CodeDispatchEventData",
+            "declaration": "export interface CodeDispatchEventData extends CodeDispatchStartEventData {\n    isError: boolean;\n    content: ContentBlock[];\n}"
+          },
+          {
+            "name": "CodeDispatchStartEventData",
+            "declaration": "export interface CodeDispatchStartEventData {\n    rootCallId: CallId;\n    parentCallId: CallId;\n    subCallId: CallId;\n    name: string;\n    arguments: unknown;\n}"
+          },
+          {
+            "name": "CommandId",
+            "declaration": "export type CommandId = Branded<'CommandId'>;"
+          },
+          {
+            "name": "CommandSource",
+            "declaration": "export type CommandSource = CommandSourceMap[keyof CommandSourceMap];"
+          },
+          {
+            "name": "CommandSourceMap",
+            "declaration": "export interface CommandSourceMap {\n    user: { kind: 'user'; };\n}"
+          },
+          {
+            "name": "CompactionId",
+            "declaration": "export type CompactionId = Branded<'CompactionId'>;"
+          },
+          {
+            "name": "ContentBlock",
+            "declaration": "export type ContentBlock = ContentBlockMap[ContentBlockType];"
+          },
+          {
+            "name": "ContentBlockMap",
+            "declaration": "export interface ContentBlockMap {\n    text: TextBlock;\n    reasoning: ReasoningBlock;\n    image: ImageBlock;\n    'tool-call': ToolCallBlock;\n    'tool-result': ToolResultBlock;\n}"
+          },
+          {
+            "name": "ContentBlockType",
+            "declaration": "export type ContentBlockType = keyof ContentBlockMap;"
+          },
+          {
+            "name": "ContextFormed",
+            "declaration": "export type ContextFormed = { readonly form?: never; } | { readonly form: 'instructions'; } | { readonly form: 'catalog'; } | { readonly form: 'snapshot'; readonly sections: readonly ContextSnapshotSection[]; } | { readonly form: 'notice'; readonly summary: string; } | { readonly form: 'relay'; } | { readonly form: 'recall'; };"
+          },
+          {
+            "name": "ContextSnapshotSection",
+            "declaration": "export interface ContextSnapshotSection {\n    readonly name: string;\n    readonly text: string;\n}"
+          },
+          {
+            "name": "EpochHeader",
+            "declaration": "export interface EpochHeader {\n    config: LlmCallConfig;\n    adapterDefaults?: LlmCallConfigAdapterDefaults;\n    system?: string;\n    tools?: ToolSchema[];\n}"
+          },
+          {
+            "name": "FileReferenceCandidate",
+            "declaration": "export interface FileReferenceCandidate {\n    path: string;\n    kind: 'file' | 'directory';\n}"
+          },
+          {
+            "name": "FinishReason",
+            "declaration": "export type FinishReason = FinishReasonMap[keyof FinishReasonMap];"
+          },
+          {
+            "name": "FinishReasonMap",
+            "declaration": "export interface FinishReasonMap {\n    stop: { kind: 'stop'; };\n    'tool-calls': { kind: 'tool-calls'; };\n    'max-tokens': { kind: 'max-tokens'; };\n    aborted: { kind: 'aborted'; failure: LlmFailure; };\n    error: { kind: 'error'; failure: LlmFailure; };\n}"
+          },
+          {
+            "name": "GoalBlockReason",
+            "declaration": "export interface GoalBlockReason {\n    readonly code: string;\n    readonly message: string;\n}"
+          },
+          {
+            "name": "GoalChangeMeta",
+            "declaration": "export type GoalChangeMeta = GoalSnapshotChangeMeta | GoalClearChangeMeta;"
+          },
+          {
+            "name": "GoalClearChangeMeta",
+            "declaration": "export interface GoalClearChangeMeta {\n    readonly kind: 'goal/change';\n    readonly version: 1;\n    readonly operation: 'clear';\n    readonly cleared: GoalRef;\n    readonly clearedAt: number;\n}"
+          },
+          {
+            "name": "GoalId",
+            "declaration": "export type GoalId = Branded<'GoalId'>;"
+          },
+          {
+            "name": "GoalMessageSource",
+            "declaration": "export interface GoalMessageSource {\n    readonly kind: 'goal';\n    readonly goalId: GoalId;\n    readonly revision: number;\n    readonly round: number;\n}"
+          },
+          {
+            "name": "GoalOperation",
+            "declaration": "export type GoalOperation = 'create' | 'edit' | 'pause' | 'resume' | 'complete' | 'block' | 'clear';"
+          },
+          {
+            "name": "GoalPhase",
+            "declaration": "export type GoalPhase = 'active' | 'paused' | 'blocked' | 'complete';"
+          },
+          {
+            "name": "GoalRef",
+            "declaration": "export interface GoalRef {\n    readonly id: GoalId;\n    readonly revision: number;\n}"
+          },
+          {
+            "name": "GoalSnapshot",
+            "declaration": "export interface GoalSnapshot extends GoalRef {\n    readonly objective: string;\n    readonly phase: GoalPhase;\n    readonly blockedReason?: GoalBlockReason;\n    readonly maxGoalRounds: number;\n}"
+          },
+          {
+            "name": "GoalSnapshotChangeMeta",
+            "declaration": "export interface GoalSnapshotChangeMeta {\n    readonly kind: 'goal/change';\n    readonly version: 1;\n    readonly operation: Exclude<GoalOperation, 'clear'>;\n    readonly goal: GoalSnapshot;\n    readonly roundsStarted: number;\n    readonly createdAt: number;\n    readonly updatedAt: number;\n}"
+          },
+          {
+            "name": "ImageAttachmentRef",
+            "declaration": "export interface ImageAttachmentRef {\n    attachmentId: AttachmentId;\n    mediaType: ImageMediaType;\n    bytes: number;\n    width: number;\n    height: number;\n    name?: string;\n}"
+          },
+          {
+            "name": "ImageBlock",
+            "declaration": "export interface ImageBlock {\n    type: 'image';\n    attachment: ImageAttachmentRef;\n}"
+          },
+          {
+            "name": "ImageMediaType",
+            "declaration": "export type ImageMediaType = 'image/png' | 'image/jpeg' | 'image/webp' | 'image/gif';"
+          },
+          {
+            "name": "Inbox",
+            "declaration": "export class Inbox {\n    get nextTurn(): readonly UserMessage[];\n    get nextStep(): readonly UserMessage[];\n    get hasPending(): boolean;\n    clear(): void;\n    claim(target: InboxTarget, turn: number): UserMessage[];\n    append(target: InboxTarget, message: UserMessage): void;\n    prepend(target: InboxTarget, message: UserMessage): void;\n    replace(messageId: MessageId, newMessage: UserMessage): boolean;\n    remove(messageId: MessageId): boolean;\n    splice(target: InboxTarget, start: number, deleteCount: number, inserted: UserMessage[]): UserMessage[];\n}"
+          },
+          {
+            "name": "InboxTarget",
+            "declaration": "export type InboxTarget = 'next-turn' | 'next-step';"
+          },
+          {
+            "name": "JsonValue",
+            "declaration": "export type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue; };"
+          },
+          {
+            "name": "LlmCallConfig",
+            "declaration": "export interface LlmCallConfig {\n    provider: string;\n    model: string;\n    reasoningEffort?: ReasoningEffortId;\n    temperature?: number;\n    maxTokens?: number;\n    stop?: string[];\n}"
+          },
+          {
+            "name": "LlmCallConfigAdapterDefaults",
+            "declaration": "export interface LlmCallConfigAdapterDefaults {\n    reasoningEffort?: true;\n    maxTokens?: true;\n}"
+          },
+          {
+            "name": "LlmFailure",
+            "declaration": "export interface LlmFailure {\n    readonly message: string;\n    readonly code: string;\n    readonly status?: number;\n    readonly providerRetryAfterMs?: number;\n    readonly requestId?: ProviderRequestId;\n}"
+          },
+          {
+            "name": "Message",
+            "declaration": "export interface Message {\n    readonly id: MessageId;\n    readonly role: 'system' | 'user' | 'assistant';\n    readonly content: ContentBlock[];\n    readonly source: MessageSource;\n}"
+          },
+          {
+            "name": "MessageId",
+            "declaration": "export type MessageId = Branded<'MessageId'>;"
+          },
+          {
+            "name": "MessageSource",
+            "declaration": "export type MessageSource = MessageSourceMap[keyof MessageSourceMap];"
+          },
+          {
+            "name": "MessageSourceMap",
+            "declaration": "export interface MessageSourceMap {\n    user: { kind: 'user'; };\n    plugin: { kind: 'plugin'; plugin: string; } & ContextFormed;\n    model: ModelMessageSource;\n    tool: ToolMessageSource;\n    goal: GoalMessageSource;\n    'session-reference': SessionReferenceSource;\n}"
+          },
+          {
+            "name": "ModelMessageSource",
+            "declaration": "export interface ModelMessageSource extends AssistantProvenance {\n    kind: 'model';\n}"
+          },
+          {
+            "name": "ProviderRequestId",
+            "declaration": "export type ProviderRequestId = Branded<'ProviderRequestId'>;"
+          },
+          {
+            "name": "ReasoningBlock",
+            "declaration": "export interface ReasoningBlock {\n    type: 'reasoning';\n    text: string;\n}"
+          },
+          {
+            "name": "ReasoningEffortId",
+            "declaration": "export type ReasoningEffortId = Branded<'ReasoningEffortId'>;"
+          },
+          {
+            "name": "ReplayEnvelope",
+            "declaration": "export interface ReplayEnvelope {\n    response: unknown;\n    blocks?: readonly unknown[];\n}"
+          },
+          {
+            "name": "RequestContext",
+            "declaration": "export interface RequestContext {\n    provider: string;\n    model: string;\n    contextWindow?: number;\n}"
+          },
+          {
+            "name": "RequestHeaderReason",
+            "declaration": "export type RequestHeaderReason = 'initial' | 'resume' | 'change';"
+          },
+          {
+            "name": "Session",
+            "declaration": "export class Session {\n    get surface(): SessionSurface;\n    readonly header: SessionHeader;\n    get id(): SessionId;\n    readonly firstLiveSeq: number;\n    get events(): readonly SessionEvent[];\n    get seq(): number;\n    append<T extends SessionEventType>(type: T, data: SessionEventMap[T], ...opts: T extends SurfaceEventType ? [opts: SurfaceIntent] : []): SessionEvent<T>;\n    requestHeader(): EpochHeader | undefined;\n    requestContext(): RequestContext | undefined;\n    deriveMessages(): Message[];\n    deriveEventMessage(event: SessionEvent): Message | null;\n}"
+          },
+          {
+            "name": "SessionEvent",
+            "declaration": "export type SessionEvent<T extends SessionEventType = SessionEventType> = { [K in SessionEventType]: { type: K; seq: number; time: number; data: SessionEventMap[K]; ignorable?: true; } & (K extends SurfaceEventType ? { sourceEventSeqs?: number[]; surfaceOp?: SurfaceOp; } : object) }[T];"
+          },
+          {
+            "name": "SessionEventMap",
+            "declaration": "export interface SessionEventMap {\n    'turn/start': { turn: number; };\n    'turn/end': { turn: number; reason: TurnEndReason; };\n    'step/start': { turn: number; step: number; };\n    'step/end': { turn: number; step: number; };\n    'user/message': UserMessage;\n    'assistant/chunk': { turn: number; step: number; chunk: StreamChunk; };\n    'assistant/message': { turn: number; step: number; message: AssistantMessage; usage?: TokenUsage; interrupted?: true; };\n    'tool/call': { turn: number; step: number; callId: CallId; name: string; arguments: string; };\n    'tool/result': { turn: number; step: number; message: ToolResultMessage; error?: { name: string; code: string; }; meta?: JsonValue; };\n    'todo/write': { todos: TodoItem[]; };\n    'request/header': { header: EpochHeader; reason: RequestHeaderReason; };\n    'request/context': RequestContext;\n    'session/end-seed': Record<string, never>;\n    'agent/inbox/spliced': { target: InboxTarget; start: number; removedCount?: number; inserted: UserMessage[]; outcome?: 'canceled'; };\n    'command/run': { commandId: CommandId; name: string; args?: string; source: CommandSource; };\n    'command/done': { commandId: CommandId; kind: 'success' | 'error'; text?: string; sourceEventSeq?: number; };\n    'approval/asked': { id: ApprovalRequestId; toolName: string; callId?: CallId; reason?: string; };\n    'approval/decided': { id: ApprovalRequestId; outcome: ApprovalOutcome; };\n    'approval/policy': { policy: ApprovalPolicy; source?: 'delegation'; };\n    'tool/code-dispatch-start': CodeDispatchStartEventData;\n    'tool/code-dispatch': CodeDispatchEventData;\n    'goal/change': GoalChangeMeta;\n    'session/title': SessionTitleEventData;\n    'compaction/start': { compactionId: CompactionId; sourceCommandId?: CommandId; turn: number | null; };\n    'compaction/summary': { compactionId: CompactionId; sourceCommandId?: CommandId; summary: ContentBlock[]; shadowedRange: { start: number; end: number; }; shadowedSeqs: number[]; shadowedTokenCount: number; provider: string; model: string; maxTokens?: number; usage?: TokenUsage; } & ({ rawOutput: ContentBlock[]; llmStreamCall: true; } | { rawOutput?: ContentBlock[]; llmStreamCall?: never; });\n    'compaction/end': { compactionId: CompactionId; sourceCommandId?: CommandId; turn: number | null; error?: string; };\n    'compaction/prune': { shadowedRange: { start: number; end: number; }; shadowedSeqs: number[]; shadowedTokenCount: number; };\n}"
+          },
+          {
+            "name": "SessionEventType",
+            "declaration": "export type SessionEventType = keyof SessionEventMap;"
+          },
+          {
+            "name": "SessionHeader",
+            "declaration": "export interface SessionHeader {\n    readonly version: number;\n    readonly id: SessionId;\n    readonly createdAt: number;\n    readonly cwd?: string;\n    readonly parentSession?: SessionId;\n    readonly seedLength?: number;\n    readonly origin?: 'subagent';\n    readonly delegationDepth?: number;\n    readonly agentPreset?: string;\n}"
+          },
+          {
+            "name": "SessionId",
+            "declaration": "export type SessionId = Branded<'SessionId'>;"
+          },
+          {
+            "name": "SessionReferenceSource",
+            "declaration": "export interface SessionReferenceSource {\n    kind: 'session-reference';\n    form: 'recall';\n    version: 1;\n    references: { sessionId: string; label: string; capturedThroughSeq: number | null; compacted: boolean; originalMessages: number; retainedMessages: number; omittedMessages: number; omittedBytes: number; truncated: boolean; inputIndex: number; }[];\n}"
+          },
+          {
+            "name": "SessionSurface",
+            "declaration": "export interface SessionSurface {\n    readonly nodes: readonly number[];\n    readonly replaceGeneration: number;\n}"
+          },
+          {
+            "name": "SessionTitleEventData",
+            "declaration": "export interface SessionTitleEventData {\n    readonly title: string;\n    readonly messageSeqs: number[];\n    readonly source: SessionTitleSource;\n}"
+          },
+          {
+            "name": "SessionTitleModelProvenance",
+            "declaration": "export interface SessionTitleModelProvenance {\n    readonly provider: string;\n    readonly model: string;\n}"
+          },
+          {
+            "name": "SessionTitleProviderId",
+            "declaration": "export type SessionTitleProviderId = Branded<'SessionTitleProviderId'>;"
+          },
+          {
+            "name": "SessionTitleSource",
+            "declaration": "export type SessionTitleSource = { readonly kind: 'fallback'; } | { readonly kind: 'provider'; readonly provider: SessionTitleProviderId; readonly model?: SessionTitleModelProvenance; } | { readonly kind: 'user'; };"
+          },
+          {
+            "name": "StreamChunk",
+            "declaration": "export type StreamChunk = { type: 'block-start'; index: number; blockType: ContentBlockType; } | { type: 'text-delta'; index: number; text: string; } | { type: 'reasoning-delta'; index: number; text: string; } | { type: 'tool-call-delta'; index: number; id: CallId; name?: string; argumentsDelta: string; } | { type: 'block-end'; index: number; block: ContentBlock; } | { type: 'usage'; usage: TokenUsage; } | { type: 'finish'; reason: FinishReason; replayState?: ReplayEnvelope; };"
+          },
+          {
+            "name": "SurfaceEventType",
+            "declaration": "export type SurfaceEventType = 'user/message' | 'assistant/message' | 'tool/result';"
+          },
+          {
+            "name": "SurfaceIntent",
+            "declaration": "export interface SurfaceIntent {\n    surfaceOp: SurfaceOp;\n    sourceEventSeqs?: number[];\n}"
+          },
+          {
+            "name": "SurfaceOp",
+            "declaration": "export type SurfaceOp = 'append' | { op: 'replace'; start: number; end: number; };"
+          },
+          {
+            "name": "TextBlock",
+            "declaration": "export interface TextBlock {\n    type: 'text';\n    text: string;\n}"
+          },
+          {
+            "name": "TodoItem",
+            "declaration": "export interface TodoItem {\n    content: string;\n    status: 'pending' | 'in_progress' | 'completed';\n}"
+          },
+          {
+            "name": "TokenUsage",
+            "declaration": "export interface TokenUsage {\n    inputTokens: number;\n    outputTokens: number;\n    cacheReadTokens?: number;\n    cacheWriteTokens?: number;\n    reasoningTokens?: number;\n}"
+          },
+          {
+            "name": "ToolCallBlock",
+            "declaration": "export interface ToolCallBlock {\n    type: 'tool-call';\n    id: CallId;\n    name: string;\n    arguments: string;\n}"
+          },
+          {
+            "name": "ToolMessageSource",
+            "declaration": "export interface ToolMessageSource {\n    kind: 'tool';\n    callId: CallId;\n}"
+          },
+          {
+            "name": "ToolResultBlock",
+            "declaration": "export interface ToolResultBlock {\n    type: 'tool-result';\n    toolCallId: CallId;\n    content: ContentBlock[];\n    isError?: boolean;\n}"
+          },
+          {
+            "name": "ToolResultMessage",
+            "declaration": "export interface ToolResultMessage extends Message {\n    readonly role: 'user';\n    readonly content: [ToolResultBlock];\n    readonly source: ToolMessageSource;\n}"
+          },
+          {
+            "name": "ToolSchema",
+            "declaration": "export interface ToolSchema {\n    name: string;\n    description: string;\n    parameters: Record<string, unknown>;\n}"
+          },
+          {
+            "name": "TurnEndCancelCause",
+            "declaration": "export type TurnEndCancelCause = AgentCancelCause | { readonly kind: 'legacy'; };"
+          },
+          {
+            "name": "TurnEndReason",
+            "declaration": "export type TurnEndReason = TurnEndReasonMap[keyof TurnEndReasonMap];"
+          },
+          {
+            "name": "TurnEndReasonMap",
+            "declaration": "export interface TurnEndReasonMap {\n    completed: { kind: 'completed'; };\n    aborted: { kind: 'aborted'; reason: TurnEndCancelCause; };\n    blocked: { kind: 'blocked'; };\n    error: { kind: 'error'; error: LlmFailure; };\n    'max-tokens': { kind: 'max-tokens'; };\n    interrupted: { kind: 'interrupted'; };\n}"
+          },
+          {
+            "name": "UserMessage",
+            "declaration": "export interface UserMessage extends Message {\n    readonly role: 'user';\n}"
+          }
+        ]
+      }
+    ],
+    "events": [],
+    "objects": []
+  },
+}

package/lib/typert.remote-client.d.ts

@@ -0,0 +1,26 @@
+/* Generated by @deepseek-ai/dsh-typert-generator from the Host FaceModel — do not edit. */
+import type {
+  RemoteResult,
+  TypertRemoteContribution,
+} from '@deepseek-ai/dsh-typert-protocol'
+import type { FileReferenceCandidate } from '@deepseek-ai/dsh-file-reference/types'
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+
+declare module '@deepseek-ai/dsh-typert-protocol' {
+  interface TypertRemoteNamespace$66696c655265666572656e636573 {
+    list: (agentId: SessionId, query: string, signal?: AbortSignal) => Promise<RemoteResult<FileReferenceCandidate[]>>
+  }
+  interface TypertRemoteMap {
+    'fileReferences/list': (agentId: SessionId, query: string, signal?: AbortSignal) => Promise<RemoteResult<FileReferenceCandidate[]>>
+  }
+  interface TypertRemoteNamespaceMap {
+    'fileReferences': TypertRemoteNamespace$66696c655265666572656e636573
+  }
+  interface TypertRemoteScopeMap {
+    'agent:fileReferences/list': (query: string, signal?: AbortSignal) => Promise<RemoteResult<FileReferenceCandidate[]>>
+  }
+}
+
+export declare const TYPERT_REMOTE: TypertRemoteContribution
+export default TYPERT_REMOTE
+//# sourceMappingURL=typert.remote-client.d.ts.map

package/lib/typert.remote-client.js

@@ -0,0 +1,59 @@
+/* Generated by @deepseek-ai/dsh-typert-generator from the Host FaceModel — do not edit. */
+import { z } from 'zod'
+
+const _deepseek_ai_dsh_file_reference_fileReferences_list_parameter_0$schema = z.intersection(z.string(), z.unknown())
+const _deepseek_ai_dsh_file_reference_fileReferences_list_parameter_1$schema = z.string()
+const _deepseek_ai_dsh_file_reference_fileReferences_list_result$schema = z.array(z.object({
+  'path': z.string(),
+  'kind': z.union([z.literal("file"), z.literal("directory")]),
+}))
+
+export const TYPERT_REMOTE = {
+  package: '@deepseek-ai/dsh-file-reference',
+  descriptors: [
+    {
+      id: '@deepseek-ai/dsh-file-reference#fileReferences/list',
+      service: 'fileReferences',
+      namespace: 'fileReferences',
+      method: 'list',
+      implementation: 'remoteExportList',
+      invocation: { kind: 'direct' },
+      scope: {
+        context: 'agent',
+        wire: 'agentId',
+      },
+      parameters: [
+        {
+          name: 'agent',
+          wire: 'agentId',
+          source: 'lookup',
+          lookup: 'agent',
+          codec: {
+            mode: 'strict',
+            typeSymbol: '@deepseek-ai/dsh-session/types#SessionId',
+            schema: _deepseek_ai_dsh_file_reference_fileReferences_list_parameter_0$schema,
+          },
+        },
+        {
+          name: 'query',
+          wire: 'query',
+          source: 'json',
+          codec: {
+            mode: 'strict',
+            typeSymbol: '@deepseek-ai/dsh-file-reference#fileReferences/list:query',
+            schema: _deepseek_ai_dsh_file_reference_fileReferences_list_parameter_1$schema,
+          },
+        },
+      ],
+      cancellation: { parameter: 'signal' },
+      result: {
+        mode: 'strict',
+        typeSymbol: '@deepseek-ai/dsh-file-reference#fileReferences/list:result',
+        schema: _deepseek_ai_dsh_file_reference_fileReferences_list_result$schema,
+      },
+      sourceLocation: {"file":"packages/context/file-reference/src/index.ts","line":54,"column":3},
+    },
+  ],
+}
+
+export default TYPERT_REMOTE

package/lib/types/grammar.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Browser-safe `@file` token grammar shared by terminal and web clients.
+ *
+ * @module @deepseek-ai/dsh-file-reference/grammar
+ */
+import type { FileReferenceCandidate } from './types.ts';
+/** Active `@` token ending at the editor cursor. */
+export interface ActiveAtToken {
+    /** Complete token replaced when the user accepts a completion. */
+    prefix: string;
+    /** Path query after `@` or `@"`. */
+    query: string;
+    /** Whether the user opened a quoted path. */
+    quoted: boolean;
+}
+/**
+ * Extract an `@path` or `@"path with spaces` token at the cursor. An `@`
+ * inside another token, such as an email address, is not a completion trigger.
+ * @param line - current editor line.
+ * @param cursorCol - cursor column within that line.
+ * @returns the active token, or `undefined` outside an `@` token.
+ */
+export declare function activeAtToken(line: string, cursorCol: number): ActiveAtToken | undefined;
+/**
+ * Format a selected path as prompt text. Whitespace uses the quoted
+ * `@"path"` grammar; a quoted directory keeps that quote open after its
+ * trailing slash so completion can descend another level.
+ * @param candidate - selected file or directory.
+ * @param preserveQuote - retain an explicitly opened quote even when unnecessary.
+ * @returns the insertion value, or `undefined` for a path the editor grammar cannot represent safely.
+ */
+export declare function formatFileMention(candidate: FileReferenceCandidate, preserveQuote: boolean): string | undefined;
+//# sourceMappingURL=grammar.d.ts.map

package/lib/types/grammar.js

@@ -0,0 +1,43 @@
+/**
+ * Browser-safe `@file` token grammar shared by terminal and web clients.
+ *
+ * @module @deepseek-ai/dsh-file-reference/grammar
+ */
+/**
+ * Extract an `@path` or `@"path with spaces` token at the cursor. An `@`
+ * inside another token, such as an email address, is not a completion trigger.
+ * @param line - current editor line.
+ * @param cursorCol - cursor column within that line.
+ * @returns the active token, or `undefined` outside an `@` token.
+ */
+export function activeAtToken(line, cursorCol) {
+    const beforeCursor = line.slice(0, cursorCol);
+    const quoted = /(?:^|\s)(@"([^"]*))$/u.exec(beforeCursor);
+    if (quoted?.[1] !== undefined && quoted[2] !== undefined) {
+        return { prefix: quoted[1], query: quoted[2], quoted: true };
+    }
+    const plain = /(?:^|\s)(@([^\s]*))$/u.exec(beforeCursor);
+    if (plain?.[1] === undefined || plain[2] === undefined)
+        return undefined;
+    return { prefix: plain[1], query: plain[2], quoted: false };
+}
+/**
+ * Format a selected path as prompt text. Whitespace uses the quoted
+ * `@"path"` grammar; a quoted directory keeps that quote open after its
+ * trailing slash so completion can descend another level.
+ * @param candidate - selected file or directory.
+ * @param preserveQuote - retain an explicitly opened quote even when unnecessary.
+ * @returns the insertion value, or `undefined` for a path the editor grammar cannot represent safely.
+ */
+export function formatFileMention(candidate, preserveQuote) {
+    const path = candidate.kind === 'directory' ? `${candidate.path}/` : candidate.path;
+    if (/[\u0000-\u001f\u007f-\u009f"]/u.test(path))
+        return undefined;
+    const quoted = preserveQuote || /\s/u.test(path);
+    if (!quoted)
+        return `@${path}`;
+    if (candidate.kind === 'directory')
+        return `@"${path}`;
+    return `@"${path}"`;
+}
+//# sourceMappingURL=grammar.js.map

package/lib/types/index.d.ts

@@ -0,0 +1,42 @@
+/**
+ * File-reference discovery seam shared by host-backed user interfaces.
+ *
+ * @module @deepseek-ai/dsh-file-reference
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
+import type { FileReferenceCandidate } from './types.ts';
+export { activeAtToken, formatFileMention } from './grammar.ts';
+export type { ActiveAtToken } from './grammar.ts';
+export type { FileReferenceCandidate } from './types.ts';
+/** Model guidance for path-only references selected by a user interface. */
+export declare const FILE_REFERENCE_PROMPT = "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.";
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        fileReferences: FileReferenceService;
+    }
+}
+/** Host capability for cancellable file-reference discovery. */
+export declare abstract class FileReferenceService extends TypertRemoteService {
+    constructor(ctx: Context);
+    /**
+     * List file and directory candidates for one agent's working directory.
+     * @param agent - target agent whose session cwd bounds discovery.
+     * @param query - path text following `@` or `@"`.
+     * @param signal - caller cancellation.
+     * @returns deterministic path-only candidates.
+     */
+    abstract list(agent: Agent, query: string, signal: AbortSignal): Promise<FileReferenceCandidate[]>;
+    /**
+     * Remote face of {@link list}; the decorator cannot mark the abstract
+     * member, so this concrete adapter carries the identical contract.
+     * @param agent - target agent whose session cwd bounds discovery.
+     * @param query - path text following `@` or `@"`.
+     * @param signal - caller cancellation.
+     * @returns deterministic path-only candidates.
+     */
+    remoteExportList(agent: Agent, query: string, signal: AbortSignal): Promise<FileReferenceCandidate[]>;
+}
+export default FileReferenceService;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/index.js

@@ -0,0 +1,75 @@
+/**
+ * File-reference discovery seam shared by host-backed user interfaces.
+ *
+ * @module @deepseek-ai/dsh-file-reference
+ */
+var __runInitializers = (this && this.__runInitializers) || function (thisArg, initializers, value) {
+    var useValue = arguments.length > 2;
+    for (var i = 0; i < initializers.length; i++) {
+        value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+    }
+    return useValue ? value : void 0;
+};
+var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
+    function accept(f) { if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected"); return f; }
+    var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
+    var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+    var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+    var _, done = false;
+    for (var i = decorators.length - 1; i >= 0; i--) {
+        var context = {};
+        for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+        for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+        context.addInitializer = function (f) { if (done) throw new TypeError("Cannot add initializers after decoration has completed"); extraInitializers.push(accept(f || null)); };
+        var result = (0, decorators[i])(kind === "accessor" ? { get: descriptor.get, set: descriptor.set } : descriptor[key], context);
+        if (kind === "accessor") {
+            if (result === void 0) continue;
+            if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+            if (_ = accept(result.get)) descriptor.get = _;
+            if (_ = accept(result.set)) descriptor.set = _;
+            if (_ = accept(result.init)) initializers.unshift(_);
+        }
+        else if (_ = accept(result)) {
+            if (kind === "field") initializers.unshift(_);
+            else descriptor[key] = _;
+        }
+    }
+    if (target) Object.defineProperty(target, contextIn.name, descriptor);
+    done = true;
+};
+import { Remote, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
+export { activeAtToken, formatFileMention } from "./grammar.js";
+/** Model guidance for path-only references selected by a user interface. */
+export const FILE_REFERENCE_PROMPT = '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.';
+/** Host capability for cancellable file-reference discovery. */
+let FileReferenceService = (() => {
+    let _classSuper = TypertRemoteService;
+    let _instanceExtraInitializers = [];
+    let _remoteExportList_decorators;
+    return class FileReferenceService extends _classSuper {
+        static {
+            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
+            _remoteExportList_decorators = [Remote('list')];
+            __esDecorate(this, null, _remoteExportList_decorators, { kind: "method", name: "remoteExportList", static: false, private: false, access: { has: obj => "remoteExportList" in obj, get: obj => obj.remoteExportList }, metadata: _metadata }, null, _instanceExtraInitializers);
+            if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+        }
+        constructor(ctx) {
+            super(ctx, 'fileReferences');
+            __runInitializers(this, _instanceExtraInitializers);
+        }
+        /**
+         * Remote face of {@link list}; the decorator cannot mark the abstract
+         * member, so this concrete adapter carries the identical contract.
+         * @param agent - target agent whose session cwd bounds discovery.
+         * @param query - path text following `@` or `@"`.
+         * @param signal - caller cancellation.
+         * @returns deterministic path-only candidates.
+         */
+        remoteExportList(agent, query, signal) {
+            return this.list(agent, query, signal);
+        }
+    };
+})();
+export { FileReferenceService };
+export default FileReferenceService;
+//# sourceMappingURL=index.js.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-file-reference`.
+ * @module @deepseek-ai/dsh-file-reference/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "file-reference-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`.
+ * @module @deepseek-ai/dsh-file-reference/invariant
+ */
+const PACKAGE_NAME = '@deepseek-ai/dsh-file-reference';
+/** Cordis companion plugin name. */
+export const name = 'file-reference-invariant';
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants'];
+/**
+ * No runtime invariant: the interface retains no candidate or lifecycle
+ * state; concrete providers own their cache and invalidation relationships.
+ */
+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/types.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Public file-reference discovery records. This module contains types only so
+ * generated Remote clients can consume it without Host runtime code.
+ * @module @deepseek-ai/dsh-file-reference/types
+ */
+/** One path-only completion candidate inside the target session cwd. */
+export interface FileReferenceCandidate {
+    /** User-facing path accepted by normal prompts and filesystem tools. */
+    path: string;
+    /** Directories keep completion open; files finish the mention. */
+    kind: 'file' | 'directory';
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types/types.js

@@ -0,0 +1,7 @@
+/**
+ * Public file-reference discovery records. This module contains types only so
+ * generated Remote clients can consume it without Host runtime code.
+ * @module @deepseek-ai/dsh-file-reference/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@deepseek-ai/dsh-file-reference",
+  "description": "File-reference discovery contract and shared @file grammar",
+  "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"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./grammar": {
+      "types": "./lib/types/grammar.d.ts",
+      "default": "./lib/types/grammar.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./types": {
+      "types": "./lib/types/types.d.ts",
+      "default": "./lib/types/types.js"
+    },
+    "./typert": {
+      "types": "./lib/typert.host.d.ts",
+      "default": "./lib/typert.host.js"
+    },
+    "./remote": {
+      "types": "./lib/typert.remote-client.d.ts",
+      "default": "./lib/typert.remote-client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.js",
+    "lib/types/**/*.d.ts",
+    "lib/typert.host.js",
+    "lib/typert.host.d.ts",
+    "lib/typert.remote-client.js",
+    "lib/typert.remote-client.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-agent": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-typert-protocol": "^0.1.0-rc.8",
+    "@deepseek-ai/cordis": "^4.0.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-typert-protocol": "^0.1.0-rc.8",
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-agent": "^0.1.0-rc.8"
+  },
+  "dependencies": {
+    "zod": "^4.4.3"
+  }
+}