@qilin-agent/client-ui-reference 0.0.0-stage → 3.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kkutysllb
+
+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,49 @@
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/client/ui-reference/README.md
+/:
+  en: 891fa9f998222b74
+  zh: 5eed64a6df09c534
+/qilin-client-ui-reference:
+  en: ca103c231ae55c46
+  zh: 49521fe0b8b5f1d1
+/qilin-client-ui-reference/summary:
+  en: b99e8765f2ead4d0
+  zh: 4e45668504acc043
+/qilin-client-ui-reference/table-of-contents:
+  en: d152484eb41ac6b4
+  zh: 09388d293f9be9cb
+/qilin-client-ui-reference/use-this-package:
+  en: 779a9a534eaad38b
+  zh: 3dd159a2c35702d6
+/qilin-client-ui-reference/use-this-package/what-a-pick-inserts:
+  en: a06b0309e76b743b
+  zh: 9b6e62b78093e8d2
+/qilin-client-ui-reference/use-this-package/failure-behavior:
+  en: 228ee6f4b81d96a7
+  zh: e1c960c3f5b25317
+/qilin-client-ui-reference/understand-the-implementation:
+  en: dbfe93987c800112
+  zh: 200d477cc8cd8a1a
+/qilin-client-ui-reference/understand-the-implementation/candidate-flow:
+  en: ee3a3b095cecc67b
+  zh: 6b47c3f0f50cd423
+/qilin-client-ui-reference/understand-the-implementation/serialization:
+  en: b9029bd93e628331
+  zh: a8635f62b1db85ba
+/qilin-client-ui-reference/further-exploration:
+  en: f6080f05ebc9cd5d
+  zh: b340184ea23122f4
+/qilin-client-ui-reference/model-experience:
+  en: f7fa58a80d82d63a
+  zh: 8235157cbbbd18cf
+/qilin-client-ui-reference/model-experience/kv-cache-effect:
+  en: ff23f8026f7c6050
+  zh: 6b0841800076bcd2
+/qilin-client-ui-reference/known-limitations-and-deferred-work:
+  en: e79991a25b11e342
+  zh: 15064e8374c8e63d
+/qilin-client-ui-reference/known-limitations-and-deferred-work/dev-note:
+  en: e67f633dc6fe7773
+  zh: 3bb0c20c93f16f98

package/README.md

@@ -1,3 +1,104 @@
-# Temporary Holding Version
+---
+description: "Web @file and @session reference source for the composer: candidates, ordering, and atomic inline references (unified file/session picking)."
+kind: "package-reference"
+---
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @qilin-agent/client-ui-reference
+
+English | [中文](README.zh.md)
+
+## Summary
+
+Use `qilin-client-ui-reference` when Web users need to mention files, folders, or sessions from one `@` completion menu. It lists files before sessions and keeps either group available when the other cannot load. Picking a file, folder, or session inserts an atomic reference with a stable clipboard form; folder rows also let users descend without closing completion. File rows omit redundant root locations, and session rows show a workspace only when it differs from the current one. Session mentions are validated before model context is captured, while browsing candidates has no model effect.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+The source is active whenever the composition mounts this package and a Host `ctx.fileReferences` provider is available. Type `@` followed by an unquoted token to see files first, then sessions; open `@"…` to search files only. The candidate list is a completion menu, not a search result page: pick once and keep typing.
+
+### What a pick inserts
+
+A file closes completion as an atomic inline reference displayed with a file glyph and business-color filename. A directory row carries two verbs: the settling pick (row click or Enter) resolves the folder itself as the same kind of atomic reference — folder glyph, trailing-slash label, canonical `@dir/` mention as its serialized form — while the drill action (Tab or the row's chevron) keeps plain editable path text with a folder glyph and the menu active at its trailing slash, so you can descend another level. Paths containing whitespace use `@"path with spaces"`, and a quote the user opened explicitly remains quoted.
+
+A session pick inserts an atomic inline reference whose hidden `ref` and clipboard representation is the canonical `@[label](qilin-session:…)` mention returned by the Host; its visible form is a chat-bubble glyph plus the session title. Sending carries the mention through `session.prompt`, and the session-reference service validates it and captures model context at `agent/pre-step`.
+
+### Failure behavior
+
+One unavailable or failed candidate domain yields no rows for that domain while the other still lists. A session-reference preparation failure occurs after prompt acceptance and terminates that agent turn.
+
+Click a file reference in the composer to preview its current contents in the right Sidebar. Quoted paths retain their spaces, and paths resolve in the composer Session. Folder and Session references retain their editing behavior.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+The source keeps candidate encoding internal to the registration effect: the `/client` export is the plugin body (`apply`/`inject`) only.
+
+### Candidate flow
+
+For an unquoted token, the browser starts the `fileReferences/list` and `sessionReferenceResolver/candidates` Remote calls together, then deterministically orders files, direct subagents of the current Session, and other Sessions. Rows use the resolver's display title, which prefers a subagent's creation label while ordinary Sessions retain their projected title, and render under locale-owned group headings without a redundant raw `reference` source title. A session row is dated from the Host session list's `updatedAt` through the same relative-time bucket that list uses, so one session reads the same age on both surfaces; a session the list does not carry falls back to the candidate's creation time. A drilled query publishes a breadcrumb from the workspace root to the current directory; each crumb carries the drill payload a folder row would, so returning to a step and descending into one are one outcome.
+
+### Serialization
+
+File picks preserve the natural text defined by the shared `@path` grammar as the hidden serialized and clipboard form. Session picks use the canonical `@[label](qilin-session:…)` mention; serialization never reconstructs identity from the visible title.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+These pages cover the suggestion machinery, the reference seams, and the input pipeline.
+
+- [ui-input-trigger](../ui-input-trigger/README.md) — the inline suggestion machinery the source registers into.
+- [file-reference](../../context/file-reference/README.md) — the `@file` seam and its provider contract.
+- [session-reference](../../context/session-reference/README.md) — the `@session` seam and prepared snapshot semantics.
+- [Web input machine and slash pipeline](../../../.agents/notes/archived/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md) — how references and commands share the input machine.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+Indirectly, through Host-owned providers, which own the file guidance and session snapshot preparation this package's reference selection delegates to them.
+
+#### 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
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+These limits define when the reference source cannot help; they are current package constraints.
+
+- **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.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>

package/README.zh.md

@@ -0,0 +1,104 @@
+---
+description: "Web @file 与 @session 引用 source：候选项、排序，以及原子行内引用（统一的文件/会话选取）。"
+kind: "package-reference"
+---
+
+# @qilin-agent/client-ui-reference
+
+[English](README.md) | 中文
+
+## 概述
+
+Web 用户需要从同一个 `@` 补全菜单提及文件、文件夹或会话时，可以使用 `qilin-client-ui-reference`。菜单先列出文件，再列出会话；其中一组无法加载时，另一组仍然可用。选择文件、文件夹或会话会插入带稳定剪贴板形式的原子引用；文件夹行还允许用户在不关闭补全的情况下继续下钻。文件行省略多余的根目录位置，会话行仅在工作区与当前工作区不同时显示该工作区。会话 mention 会在捕获模型上下文前接受校验，而浏览候选项不会影响模型。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+只要组合挂载了本包且存在宿主 `ctx.fileReferences` 提供方，该 source 即处于活动状态。输入 `@` 后跟一个未加引号的 token，会先看到文件、再看到会话；打开 `@"…` 则只搜索文件。候选列表是补全菜单，不是搜索结果页：选一次、继续输入即可。
+
+### 选择后会插入什么
+
+选择文件会关闭补全，并显示为带文件图标与业务色文件名的原子行内引用。目录行携带两个动词：选定 pick（点击行主体或 Enter）把文件夹本身解析为同类原子引用——文件夹图标、带尾斜杠的标签、以规范 `@dir/` mention 为序列化形式；钻取动作（Tab 或行尾 chevron）则保持带文件夹图标的可编辑路径纯文本，并让菜单在尾部斜杠处保持活跃，用户可以继续进入下一层。包含空白的路径使用 `@"path with spaces"`，用户显式打开的引号会继续保留。
+
+选择会话会插入一个原子的行内引用，其隐藏 `ref` 与剪贴板表示均为宿主返回的规范 `@[label](qilin-session:…)` mention；可见形式为聊天气泡图标加会话标题。发送会经 `session.prompt` 携带该 mention，session-reference 服务会在 `agent/pre-step` 校验它并捕获模型上下文。
+
+### 失败行为
+
+某个候选领域不可用或失败时，该领域不产生任何行，另一领域仍正常列出。会话引用准备失败发生在提示词接受后，并会终止该 agent 轮次。
+
+点击输入框中的文件引用，可在右侧栏预览文件当前的内容。带引号路径中的空格会保留，路径按输入框所属 Session 解析。文件夹和 Session 引用保留原有的编辑行为。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+该 source 把候选编码保留在注册 effect 内部：`/client` 导出接口只包含插件主体（`apply`/`inject`）。
+
+### 候选流程
+
+对于未加引号的 token，浏览器会同时启动 `fileReferences/list` 与 `sessionReferenceResolver/candidates` Remote 调用，再按文件、当前 Session 的直接 subagent、其他 Session 的确定性顺序排列。各行使用 resolver 的显示标题；subagent 优先使用创建标签，普通 Session 保持投影标题，并渲染在 locale 管理的分组标题下，不显示重复的原始 `reference` source 标题。会话行用宿主会话列表的 `updatedAt` 经该列表相同的相对时间分档标注时间，因此同一个会话在两处读到的时长一致；列表中没有的会话回落到候选自带的创建时间。下钻后的查询会发布一条从工作区根目录到当前目录的面包屑；每一节携带的下钻载荷与文件夹行相同，因此「回到某一步」与「进入某一层」是同一个结果。
+
+### 序列化
+
+文件选择把共享 `@path` 语法所定义的自然文本保留为隐藏的序列化与剪贴板形式。会话选择使用规范的 `@[label](qilin-session:…)` mention；序列化永远不会根据可见标题重建身份。
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+以下页面覆盖建议机制、引用 seam 与输入流水线。
+
+- [ui-input-trigger](../ui-input-trigger/README.zh.md)——该 source 注册进的行内建议机制。
+- [file-reference](../../context/file-reference/README.zh.md)——`@file` seam 及其提供方约定。
+- [session-reference](../../context/session-reference/README.zh.md)——`@session` seam 与准备后快照的语义。
+- [Web 输入机器与 slash 流水线](../../../.agents/notes/archived/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md)——引用与命令如何共享输入机器。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+间接影响模型体验：通过宿主拥有的提供方实现，本包的引用选择把文件指引与会话快照准备委托给它们。
+
+#### KV Cache 影响
+
+浏览候选项不会影响模型。选择文件或会话只会改变新用户消息的后缀，以及紧随该消息、由宿主准备的会话引用上下文；目标会话更早的历史保持不变。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+这些限制说明引用 source 何时帮不上忙；它们是当前包约束。
+
+- **候选失败有意保持静默**：Remote 发现调用不可用或失败时，该领域不产生候选行。会话引用准备失败发生在提示词接受后，并会终止该 agent 轮次。
+- **浏览器侧不扫描文件**：Web 补全需要挂载宿主 `ctx.fileReferences` 提供方；浏览器无法回退到自身文件系统。
+- **会话搜索仍仅使用元数据**：发现流程通过 `ctx.sessionReferenceResolver` 筛选 session id、cwd 与以日志为依据的最新标题；不搜索消息主体或完整 transcript。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+无。
+
+</details>

package/lib/client.js

@@ -0,0 +1,322 @@
+window.__ModuleLoader__.load({
+	id: "@qilin-agent/client-ui-reference",
+	factory: (require) => {
+		var module = { exports: {} };
+		var exports = module.exports;
+		Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+		let _qilin_agent_client_ui_primitives = require("@qilin-agent/client-ui-primitives");
+		//#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 ../../util/workspace-path/src/file-address.ts
+		/** The scheme and type every file address opens with. */
+		const FILE_ADDRESS_PREFIX = "qilin-resource://file/";
+		/** Component-encode one id or path segment, keeping `:` literal for drive letters. */
+		function encodeSegment(segment) {
+			return encodeURIComponent(segment).replace(/%3A/gi, ":");
+		}
+		/** Encode a `/`-separated path segment by segment. */
+		function encodePath(path) {
+			return path.split("/").map(encodeSegment).join("/");
+		}
+		/**
+		* Build the address of a file read through one Session.
+		* @param sessionId - the Session whose Host workspace resolves the path.
+		* @param path - absolute or workspace-relative path; backslashes are normalized to `/`, and leading `./` prefixes are dropped.
+		* @returns the `qilin-resource://file/session/<sessionId>/<path>` address.
+		*/
+		function sessionFileAddress(sessionId, path) {
+			const normalized = path.replace(/\\/g, "/").replace(/^(?:\.\/)+/, "");
+			return `${FILE_ADDRESS_PREFIX}session/${encodeSegment(sessionId)}/${encodePath(normalized)}`;
+		}
+		//#endregion
+		//#region ../../util/workspace-path/src/index.ts
+		/**
+		* Browser-safe Workspace path and display helpers.
+		* @module @qilin-agent/util-workspace-path
+		*/
+		/** Whether a path uses a Windows drive or UNC prefix. */
+		function isWindowsStylePath(value) {
+			return /^[A-Za-z]:[/\\]/.test(value) || value.startsWith("\\\\");
+		}
+		/**
+		* Whether a path is absolute in either spelling the Host accepts: POSIX (`/a/b`) or Windows drive or UNC.
+		* @param path - the path to classify.
+		* @returns `true` for an absolute path; `false` for a Workspace-relative one.
+		*/
+		function isAbsoluteWorkspacePath(path) {
+			return path.startsWith("/") || isWindowsStylePath(path);
+		}
+		/**
+		* Abbreviate a POSIX home directory for display.
+		* @param path - Absolute or already-short display path.
+		* @param home - Host account home; absent skips abbreviation.
+		* @returns `~` or `~/…` for the POSIX home and its descendants, otherwise `path`.
+		*/
+		function abbreviateHomePath(path, home) {
+			if (home === void 0 || home === "") return path;
+			if (isWindowsStylePath(path) || isWindowsStylePath(home)) return path;
+			const root = home.replace(/\/+$/, "");
+			if (root === "" || root === "/") return path;
+			if (path.replace(/\/+$/, "") === root) return "~";
+			if (path.startsWith(`${root}/`)) return `~${path.slice(root.length)}`;
+			return path;
+		}
+		/**
+		* The address for a path as a caller holds it: a relative path, or an absolute
+		* path inside the Session's workspace, becomes a `session`-scoped address; an
+		* absolute path outside it, or one whose workspace root is unknown, keeps its
+		* absolute path in that Session's address.
+		* @param sessionId - the Session the path is read in.
+		* @param cwd - that Session's workspace root, when known.
+		* @param path - absolute or workspace-relative path, in either separator spelling.
+		* @returns the `qilin-resource://file/…` address.
+		*/
+		function fileAddressFor(sessionId, cwd, path) {
+			const normalized = path.replace(/\\/g, "/");
+			if (!isAbsoluteWorkspacePath(normalized)) return sessionFileAddress(sessionId, normalized);
+			const root = cwd === void 0 ? "" : cwd.replace(/\\/g, "/").replace(/\/+$/, "");
+			if (root !== "" && normalized === root) return sessionFileAddress(sessionId, "");
+			if (root !== "" && normalized.startsWith(`${root}/`)) return sessionFileAddress(sessionId, normalized.slice(root.length + 1));
+			return sessionFileAddress(sessionId, normalized);
+		}
+		//#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).
+		*
+		* The `time.*` bucket words are this namespace's own copy of the session-row
+		* vocabulary: locale-owned copy keeps the words per plugin, while the
+		* bucketing they name is the one shared {@link relativeTime} in ui-primitives.
+		*/
+		const zh = {
+			"section.files": "文件与文件夹",
+			"section.subagents": "子智能体",
+			"section.sessions": "对话",
+			"candidate.noCwd": "（无工作目录）",
+			"crumb.root": "工作区",
+			"time.now": "刚刚",
+			"time.minutes": "{n}分钟",
+			"time.hours": "{n}小时",
+			"time.days": "{n}天",
+			"time.months": "{n}个月",
+			"time.years": "{n}年"
+		};
+		/** English dictionary, checked complete against the zh key set. */
+		const en = {
+			"section.files": "Files & folders",
+			"section.subagents": "Subagents",
+			"section.sessions": "Sessions",
+			"candidate.noCwd": "(no cwd)",
+			"crumb.root": "Workspace",
+			"time.now": "now",
+			"time.minutes": "{n}min",
+			"time.hours": "{n}h",
+			"time.days": "{n}d",
+			"time.months": "{n}mo",
+			"time.years": "{n}y"
+		};
+		//#endregion
+		//#region lib/types/client/index.js
+		/** Required services: the trigger registry, the Remote namespaces, and the copy. */
+		const inject = [
+			"inputTriggers",
+			"locale",
+			"sessions",
+			"remote",
+			"remote.fileReferences",
+			"remote.sessionReferenceResolver",
+			"sidebarRight"
+		];
+		/**
+		* 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 sessions = ctx.get("sessions");
+			const source = {
+				trigger: "@",
+				name: "reference",
+				showGroupTitle: false,
+				async candidates(session, { query, quoted, drilled, signal }) {
+					const fileLookup = ctx.remote.fileReferences.list(session.sessionId, query, signal).then((result) => result.ok ? result.value : []);
+					const sessionLookup = quoted === true ? Promise.resolve([]) : ctx.remote.sessionReferenceResolver.candidates(session.sessionId, query, signal).then((result) => result.ok ? result.value : []);
+					const [fileItems, sessionItems] = await Promise.all([fileLookup, sessionLookup]);
+					if (signal.aborted) return [];
+					const withLocation = crumbsFor(query, quoted === true, drilled, t) === void 0;
+					const now = Date.now();
+					const home = ctx.remote.$host.home;
+					const listed = sessions.list.getSnapshot().byId;
+					const sessionRows = sessionItems.map((candidate) => {
+						const summary = listed[candidate.sessionId];
+						const child = summary?.origin === "subagent" && summary.parentId === session.sessionId;
+						return {
+							child,
+							row: sessionCandidate(candidate, candidate.displayTitle ?? candidate.label, summary?.updatedAt ?? candidate.createdAt, now, home, t(child ? "section.subagents" : "section.sessions"), t)
+						};
+					});
+					return [
+						...fileItems.flatMap((candidate) => fileCandidate(candidate, quoted === true, withLocation, t)),
+						...sessionRows.filter((item) => item.child).map((item) => item.row),
+						...sessionRows.filter((item) => !item.child).map((item) => item.row)
+					];
+				},
+				header(_session, req) {
+					return crumbsFor(req.query, req.quoted === true, req.drilled, t);
+				},
+				onPick({ candidate, action }) {
+					const value = parseCandidate(candidate.value);
+					if (value?.kind === "file") {
+						if (value.fileKind === "directory" && action === "drill") return {
+							text: value.mention,
+							continue: true
+						};
+						return { insert: {
+							source: "reference",
+							ref: value.mention,
+							label: value.fileKind === "directory" ? `${value.label}/` : value.label,
+							appearance: value.fileKind === "directory" ? "folder" : "file",
+							clipboardText: value.mention
+						} };
+					}
+					if (value?.kind === "session") return { insert: {
+						source: "reference",
+						ref: value.mention,
+						label: value.label,
+						appearance: "session",
+						clipboardText: value.mention
+					} };
+				},
+				openReference(session, { ref, appearance }) {
+					if (appearance !== "file") return false;
+					const path = ref.startsWith("@\"") ? ref.slice(2, -1) : ref.slice(1);
+					const cwd = sessions.list.getSnapshot().byId[session.sessionId]?.cwd;
+					ctx.sidebarRight.openResource(fileAddressFor(session.sessionId, cwd, path));
+					return true;
+				},
+				codec: {
+					clipboardText: (ref) => ref,
+					serialize: (ref) => Promise.resolve(ref)
+				}
+			};
+			const inputTriggers = ctx.get("inputTriggers");
+			ctx.effect(() => inputTriggers.registerSource(source), "ui-reference: @ source");
+		}
+		/**
+		* The breadcrumb of a drilled directory listing, from the workspace root down
+		* to the directory being listed.
+		*
+		* Only a drill produces one: a path the user typed carries its own context in
+		* the draft, while a drill replaced the text they were reading with a deeper
+		* one and owes them the way back.
+		* @param query - the live query, path text following `@` or `@"`.
+		* @param quoted - whether the active token is an open quoted path.
+		* @param drilled - whether a drill pick, rather than typing, produced the query.
+		* @param t - the reference dictionary.
+		* @returns the crumbs, or undefined when this listing needs no header.
+		*/
+		function crumbsFor(query, quoted, drilled, t) {
+			if (!drilled) return void 0;
+			const slash = query.lastIndexOf("/");
+			if (slash < 0) return void 0;
+			const segments = query.slice(0, slash).split("/").filter((segment) => segment !== "");
+			const crumbs = [{
+				label: t("crumb.root"),
+				value: directoryValue(t("crumb.root"), quoted ? "@\"" : "@")
+			}];
+			for (const [index, segment] of segments.entries()) {
+				const mention = formatFileMention({
+					path: segments.slice(0, index + 1).join("/"),
+					kind: "directory"
+				}, quoted);
+				if (mention === void 0) return void 0;
+				crumbs.push({
+					label: segment,
+					value: directoryValue(segment, mention),
+					...index === segments.length - 1 ? { current: true } : {}
+				});
+			}
+			return crumbs;
+		}
+		/** Project one directory destination as the drill payload `onPick` already understands. */
+		function directoryValue(label, mention) {
+			return JSON.stringify({
+				kind: "file",
+				fileKind: "directory",
+				label,
+				mention
+			});
+		}
+		function fileCandidate(candidate, preserveQuote, withLocation, t) {
+			const mention = formatFileMention(candidate, preserveQuote);
+			if (mention === void 0) return [];
+			const slash = candidate.path.lastIndexOf("/");
+			const name = candidate.path.slice(slash + 1);
+			const parent = slash < 0 ? "" : candidate.path.slice(0, slash);
+			const directory = candidate.kind === "directory";
+			const value = {
+				kind: "file",
+				fileKind: candidate.kind,
+				label: name,
+				mention
+			};
+			return [{
+				name: `${name}${directory ? "/" : ""}`,
+				...withLocation && parent !== "" ? { description: parent } : {},
+				icon: directory ? "folder" : "file",
+				section: t("section.files"),
+				value: JSON.stringify(value),
+				...directory ? { drill: true } : {}
+			}];
+		}
+		function sessionCandidate(candidate, label, updatedAt, now, home, section, t) {
+			const { unit, n } = (0, _qilin_agent_client_ui_primitives.relativeTime)(updatedAt, now);
+			const age = unit === "now" ? t("time.now") : t(`time.${unit}`, { n });
+			const location = candidate.sameWorkspace ? void 0 : candidate.cwd === void 0 ? t("candidate.noCwd") : abbreviateHomePath(candidate.cwd, home);
+			const value = {
+				kind: "session",
+				label,
+				mention: candidate.mention
+			};
+			return {
+				name: label,
+				description: location === void 0 ? age : `${location} · ${age}`,
+				icon: "session",
+				section,
+				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
+* `qilin.client` declaration.
+*/
+/** Host plugin body — no host-side behavior for this source plugin. */
+function apply() {}
+//#endregion
+export { apply };

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

@@ -0,0 +1,9 @@
+import type { Context as ClientContext } from '@qilin-agent/kylin';
+/** 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,46 @@
+/** `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).
+ *
+ * The `time.*` bucket words are this namespace's own copy of the session-row
+ * vocabulary: locale-owned copy keeps the words per plugin, while the
+ * bucketing they name is the one shared {@link relativeTime} in ui-primitives.
+ */
+export declare const zh: {
+    'section.files': string;
+    'section.subagents': string;
+    'section.sessions': string;
+    'candidate.noCwd': string;
+    'crumb.root': string;
+    'time.now': string;
+    'time.minutes': string;
+    'time.hours': string;
+    'time.days': string;
+    'time.months': string;
+    'time.years': string;
+};
+/** The reference namespace key union. */
+export type ReferenceKey = keyof typeof zh;
+declare module '@qilin-agent/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.subagents': string;
+    'section.sessions': string;
+    'candidate.noCwd': string;
+    'crumb.root': string;
+    'time.now': string;
+    'time.minutes': string;
+    'time.hours': string;
+    'time.days': string;
+    'time.months': string;
+    'time.years': 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
+ * `qilin.client` declaration.
+ */
+/** Host plugin body — no host-side behavior for this source plugin. */
+export declare function apply(): void;
+//# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,6 +1,73 @@
 {
   "name": "@qilin-agent/client-ui-reference",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Unified Web @file and @session reference source",
+  "version": "3.1.3",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kkutysllb/QiLin.git",
+    "directory": "packages/client/ui-reference"
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "qilin": {
+    "client": {
+      "inject": [
+        "@qilin-agent/api-remotes",
+        "@qilin-agent/api-session-controller",
+        "@qilin-agent/client-connection",
+        "@qilin-agent/client-locale",
+        "@qilin-agent/client-ui-input-trigger",
+        "@qilin-agent/client-ui-sidebar-right"
+      ],
+      "platform": "web"
+    }
+  },
+  "license": "MIT",
+  "peerDependencies": {
+    "@qilin-agent/kylin": "~4.0.3"
+  },
+  "devDependencies": {
+    "@qilin-agent/api-remotes": "3.1.3",
+    "@qilin-agent/api-session-controller": "3.1.3",
+    "@qilin-agent/client-locale": "3.1.3",
+    "@qilin-agent/client-ui-input-trigger": "3.1.3",
+    "@qilin-agent/client-test-runtime": "3.1.3",
+    "@qilin-agent/client-connection": "3.1.3",
+    "@qilin-agent/client-ui-primitives": "3.1.3",
+    "@qilin-agent/session-reference": "3.1.3",
+    "@qilin-agent/file-reference": "3.1.3",
+    "@qilin-agent/typert-protocol": "3.1.3",
+    "@qilin-agent/util-workspace-path": "3.1.3",
+    "@qilin-agent/kylin": "~4.0.3",
+    "@qilin-agent/client-ui-sidebar-right": "3.1.3",
+    "@qilin-agent/client-ui-slots": "3.1.3"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  }
 }