@monotykamary/dsh-client-ui-reference 0.1.0-rc.10

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/client/ui-reference/README.md
+README.md: 5c12f2d29ec9d3c6904bf2a68bab3f72aa5476a3
+README.zh.md: 660bdbb423ec550a62f09b4fe45e258d2f9ad979

package/README.md

@@ -0,0 +1,25 @@
+# `@monotykamary/dsh-client-ui-reference`
+
+English | [中文](README.zh.md)
+
+Unified Web `@file` and `@session` source. The browser starts the `fileReferences/list` and `sessionReferenceResolver/candidates` Remote calls together for an unquoted token, deterministically orders files before sessions with locale-registered folder/file/session labels, and renders the rows under non-selectable file and session section headings without a redundant raw `reference` source title. Either failed candidate domain degrades independently. An open `@"…` token searches files only.
+
+File picks preserve the natural text defined by the shared `@path` grammar as their hidden serialized and clipboard form. A file closes completion as an atomic inline reference displayed with a file glyph, business-color filename, and no capsule. A directory remains plain editable path text with a folder glyph and keeps the menu active at its trailing slash so the user can descend another level. Paths containing whitespace use `@"path with spaces"`, and a quote the user opened explicitly remains quoted.
+
+Session picks insert an atomic inline reference whose hidden `ref` and clipboard representation are the canonical `@[label](dsh-session:…)` mention returned by the Host. Its visible form is a chat-bubble glyph plus the business-color session title, without a capsule; serialization never reconstructs identity from that title. Ordinary send carries the canonical mention through `session.prompt`; the session-reference service validates it and captures model context at `agent/pre-step`.
+
+The `/client` export is the plugin body (`apply`/`inject`) only; candidate encoding stays internal to the registration effect.
+
+## Model Experience
+
+Indirectly, through `@monotykamary/dsh-file-reference-local` for path guidance and `@monotykamary/dsh-session-reference` for prepared session snapshots.
+
+#### KV Cache effect
+
+Candidate browsing has no model effect. A selected file or session changes only the new user-message suffix and any Host-prepared session-reference context that follows that message; earlier target history remains unchanged.
+
+## Known Limitations and Deferred Work
+
+- **Candidate failure is intentionally quiet** — one unavailable or failed Remote discovery call yields no rows for that domain. A session-reference preparation failure occurs after prompt acceptance and terminates that agent turn.
+- **No browser-side file scan** — Web completion requires a mounted Host `ctx.fileReferences` provider; the browser cannot fall back to its own filesystem.
+- **Session search remains metadata-only** — discovery filters session id, cwd, and the latest log-backed title through `ctx.sessionReferenceResolver`; message bodies and full transcripts are not searched.

package/README.zh.md

@@ -0,0 +1,25 @@
+# `@monotykamary/dsh-client-ui-reference`
+
+[English](README.md) | 中文
+
+统一的 Web `@file` 与 `@session` source。对于未加引号的 token，浏览器会同时启动 `fileReferences/list` 和 `sessionReferenceResolver/candidates` Remote 调用，以确定性顺序把文件排在会话之前，并使用注册在 locale 字典中的文件夹、文件与会话标签；各行分别渲染在不可选择的文件与会话分组标题下，不显示重复的原始 `reference` source 标题。任一候选领域的失败都会独立降级。尚未闭合的 `@"…` token 只搜索文件。
+
+选择文件会把共享 `@path` 语法所定义的自然文本保留为隐藏的序列化与剪贴板形式。文件会关闭补全，并显示为文件图标加业务色文件名、无胶囊容器的原子行内引用。目录仍是带文件夹图标的可编辑路径纯文本，并让菜单在尾部斜杠处保持活跃，用户可以继续进入下一层。包含空白的路径使用 `@"path with spaces"`，用户显式打开的引号会继续保留。
+
+选择会话会插入一个原子的行内引用，其隐藏 `ref` 与剪贴板表示均为宿主返回的规范 `@[label](dsh-session:…)` mention。可见形式为聊天气泡图标加业务色会话标题，不使用胶囊容器；序列化永远不会根据该标题重建身份。普通发送会通过 `session.prompt` 携带规范 mention，session-reference 服务会在 `agent/pre-step` 校验它并捕获模型上下文。
+
+`/client` 只导出插件主体（`apply`／`inject`）；候选编码保留在注册 effect 内部。
+
+## 模型体验
+
+间接影响模型体验：路径指引由 `@monotykamary/dsh-file-reference-local` 提供，准备后的会话快照由 `@monotykamary/dsh-session-reference` 提供。
+
+#### KV 缓存影响
+
+浏览候选项不会影响模型。选择文件或会话只会改变新用户消息的后缀，以及紧随该消息、由宿主准备的会话引用上下文；目标会话更早的历史保持不变。
+
+## 已知限制与暂缓事项
+
+- **候选失败有意保持静默**：Remote 发现调用不可用或失败时，该领域不产生候选行。会话引用准备失败发生在提示词接受后，并会终止该 agent 轮次。
+- **浏览器侧不扫描文件**：Web 补全需要挂载宿主 `ctx.fileReferences` 提供方；浏览器无法回退到自身文件系统。
+- **会话搜索仍仅使用元数据**：发现流程通过 `ctx.sessionReferenceResolver` 筛选 session id、cwd 和以日志为依据的最新标题；不搜索消息主体或完整 transcript（文本记录）。

package/lib/client.js

@@ -0,0 +1,149 @@
+window.__ModuleLoader__.load({
+	id: "@monotykamary/dsh-client-ui-reference",
+	factory: (require) => {
+		var module = { exports: {} };
+		var exports = module.exports;
+		Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+		//#region ../../context/file-reference/src/grammar.ts
+		/**
+		* 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/client/locales.js
+		/** `reference` namespace dictionaries for the unified `@` source. */
+		/** Dictionary namespace owned by this plugin. */
+		const NS = "reference";
+		/** Simplified Chinese dictionary (the key-set source of truth). */
+		const zh = {
+			"section.files": "文件与文件夹",
+			"section.sessions": "Session 对话",
+			"candidate.file": "文件",
+			"candidate.folder": "文件夹",
+			"candidate.session": "Session",
+			"candidate.noCwd": "（无工作目录）"
+		};
+		/** English dictionary, checked complete against the zh key set. */
+		const en = {
+			"section.files": "Files & folders",
+			"section.sessions": "Session conversations",
+			"candidate.file": "File",
+			"candidate.folder": "Folder",
+			"candidate.session": "Session",
+			"candidate.noCwd": "(no cwd)"
+		};
+		//#endregion
+		//#region lib/types/client/index.js
+		/** Required services: the trigger registry, the Remote namespaces, and the copy. */
+		const inject = [
+			"inputTriggers",
+			"locale",
+			"remote",
+			"remote.fileReferences",
+			"remote.sessionReferenceResolver"
+		];
+		/**
+		* Register the combined `@file` / `@session` source.
+		* @param ctx - client root context.
+		*/
+		function apply(ctx) {
+			ctx.effect(() => ctx.locale.register(NS, {
+				zh,
+				en
+			}), "ui-reference: dictionaries");
+			const t = ctx.locale.bind(NS);
+			const source = {
+				trigger: "@",
+				name: "reference",
+				showGroupTitle: false,
+				async candidates(session, { query, quoted, signal }) {
+					const files = ctx.remote.fileReferences.list(session.sessionId, query, signal).then((result) => result.ok ? result.value : [], () => []);
+					const sessions = quoted === true ? Promise.resolve([]) : ctx.remote.sessionReferenceResolver.candidates(session.sessionId, query, signal).then((result) => result.ok ? result.value : [], () => []);
+					const [fileItems, sessionItems] = await Promise.all([files, sessions]);
+					if (signal.aborted) return [];
+					return [...fileItems.flatMap((candidate) => fileCandidate(candidate, quoted === true, t)), ...sessionItems.map((candidate) => sessionCandidate(candidate, t))];
+				},
+				onPick({ candidate }) {
+					const value = parseCandidate(candidate.value);
+					if (value?.kind === "file") return value.fileKind === "directory" ? {
+						text: value.mention,
+						continue: true
+					} : { insert: {
+						source: "reference",
+						ref: value.mention,
+						label: value.label,
+						appearance: "file",
+						clipboardText: value.mention
+					} };
+					if (value?.kind === "session") return { insert: {
+						source: "reference",
+						ref: value.mention,
+						label: value.label,
+						appearance: "session",
+						clipboardText: value.mention
+					} };
+				},
+				codec: {
+					clipboardText: (ref) => ref,
+					serialize: (ref) => Promise.resolve(ref)
+				}
+			};
+			const inputTriggers = ctx.get("inputTriggers");
+			ctx.effect(() => inputTriggers.registerSource(source), "ui-reference: @ source");
+		}
+		function fileCandidate(candidate, preserveQuote, t) {
+			const mention = formatFileMention(candidate, preserveQuote);
+			if (mention === void 0) return [];
+			const name = candidate.path.slice(candidate.path.lastIndexOf("/") + 1);
+			const directory = candidate.kind === "directory";
+			const value = {
+				kind: "file",
+				fileKind: candidate.kind,
+				label: name,
+				mention
+			};
+			return [{
+				name: `${t(directory ? "candidate.folder" : "candidate.file")} · ${name}${directory ? "/" : ""}`,
+				description: candidate.path,
+				section: t("section.files"),
+				value: JSON.stringify(value)
+			}];
+		}
+		function sessionCandidate(candidate, t) {
+			const location = candidate.cwd ?? t("candidate.noCwd");
+			const description = `${candidate.label === candidate.sessionId ? "" : `${candidate.sessionId} · `}${location} · ${new Date(candidate.createdAt).toISOString()}`;
+			const value = {
+				kind: "session",
+				label: candidate.label,
+				mention: candidate.mention
+			};
+			return {
+				name: `${t("candidate.session")} · ${candidate.label}`,
+				description,
+				section: t("section.sessions"),
+				value: JSON.stringify(value)
+			};
+		}
+		function parseCandidate(value) {
+			if (value === void 0) return void 0;
+			return JSON.parse(value);
+		}
+		//#endregion
+		exports.apply = apply;
+		exports.inject = inject;
+		return module.exports;
+	}
+});
+
+//# sourceMappingURL=client.js.map

package/lib/index.js

@@ -0,0 +1,11 @@
+//#region lib/types/index.js
+/**
+* File/session reference plugin, node half. Pure UI plugin: the empty apply
+* exists so the plugin appears in the host cordis.yml / Loader; the browser
+* half ships via exports["./client"], discovered through the package.json
+* `dsh.client` declaration.
+*/
+/** Host plugin body — no host-side behavior for this source plugin. */
+function apply() {}
+//#endregion
+export { apply };

package/lib/invariant.js

@@ -0,0 +1,24 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@monotykamary/dsh-client-ui-reference`.
+* @module @monotykamary/dsh-client-ui-reference/invariant
+*/
+const PACKAGE_NAME = "@monotykamary/dsh-client-ui-reference";
+/** Cordis companion plugin name. */
+const name = "client-ui-reference-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: a single slash-source registration whose disposal is
+* proven by the HMR-safety spec — it emits no cordis events and owns no
+* cross-plugin mutable state.
+*/
+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/client/index.d.ts

@@ -0,0 +1,9 @@
+import type { ClientContext } from '@monotykamary/dsh-client-runtime/client';
+/** Required services: the trigger registry, the Remote namespaces, and the copy. */
+export declare const inject: string[];
+/**
+ * Register the combined `@file` / `@session` source.
+ * @param ctx - client root context.
+ */
+export declare function apply(ctx: ClientContext): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/client/locales.d.ts

@@ -0,0 +1,30 @@
+/** `reference` namespace dictionaries for the unified `@` source. */
+/** Dictionary namespace owned by this plugin. */
+export declare const NS = "reference";
+/** Simplified Chinese dictionary (the key-set source of truth). */
+export declare const zh: {
+    'section.files': string;
+    'section.sessions': string;
+    'candidate.file': string;
+    'candidate.folder': string;
+    'candidate.session': string;
+    'candidate.noCwd': string;
+};
+/** The reference namespace key union. */
+export type ReferenceKey = keyof typeof zh;
+declare module '@monotykamary/dsh-client-ui-slots' {
+    interface LocaleNamespaceMap {
+        /** The unified `@` reference menu's copy. */
+        reference: ReferenceKey;
+    }
+}
+/** English dictionary, checked complete against the zh key set. */
+export declare const en: {
+    'section.files': string;
+    'section.sessions': string;
+    'candidate.file': string;
+    'candidate.folder': string;
+    'candidate.session': string;
+    'candidate.noCwd': string;
+};
+//# sourceMappingURL=locales.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * File/session reference plugin, node half. Pure UI plugin: the empty apply
+ * exists so the plugin appears in the host cordis.yml / Loader; the browser
+ * half ships via exports["./client"], discovered through the package.json
+ * `dsh.client` declaration.
+ */
+/** Host plugin body — no host-side behavior for this source plugin. */
+export declare function apply(): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@monotykamary/dsh-client-ui-reference`.
+ * @module @monotykamary/dsh-client-ui-reference/invariant
+ */
+import type { Context } from '@monotykamary/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "client-ui-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/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@monotykamary/dsh-client-ui-reference",
+  "description": "Unified Web @file and @session reference source",
+  "version": "0.1.0-rc.10",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/client/ui-reference"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "client": {
+      "inject": [
+        "@monotykamary/dsh-client-runtime",
+        "@monotykamary/dsh-api-remotes",
+        "@monotykamary/dsh-client-locale",
+        "@monotykamary/dsh-client-ui-input-trigger"
+      ],
+      "platform": "web"
+    }
+  },
+  "license": "MIT",
+  "peerDependencies": {
+    "@monotykamary/dsh-client-ui-input-trigger": "^0.1.0-rc.10",
+    "@monotykamary/dsh-client-locale": "^0.1.0-rc.10",
+    "@monotykamary/dsh-api-remotes": "^0.1.0-rc.10",
+    "@monotykamary/dsh-invariants": "^0.1.0-rc.10",
+    "@monotykamary/cordis": "^4.0.1",
+    "@monotykamary/dsh-client-runtime": "^0.1.0-rc.10",
+    "@monotykamary/dsh-file-reference": "^0.1.0-rc.10",
+    "@monotykamary/dsh-session-reference": "^0.1.0-rc.10",
+    "@monotykamary/dsh-typert-protocol": "^0.1.0-rc.10"
+  },
+  "devDependencies": {
+    "@monotykamary/dsh-client-locale": "^0.1.0-rc.10",
+    "@monotykamary/dsh-client-runtime": "^0.1.0-rc.10",
+    "@monotykamary/dsh-api-remotes": "^0.1.0-rc.10",
+    "@monotykamary/dsh-client-ui-slots": "^0.1.0-rc.10",
+    "@monotykamary/cordis": "^4.0.1",
+    "@monotykamary/dsh-typert-protocol": "^0.1.0-rc.10",
+    "@monotykamary/dsh-invariants": "^0.1.0-rc.10",
+    "@monotykamary/dsh-client-ui-input-trigger": "^0.1.0-rc.10",
+    "@monotykamary/dsh-file-reference": "^0.1.0-rc.10",
+    "@monotykamary/dsh-session-reference": "^0.1.0-rc.10"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  }
+}