@qilin-agent/client-ui-agent-opens 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,22 @@
+# 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-agent-opens/README.md
+/:
+  en: 4229f048f4b85bcf
+  zh: 6f3bcf3fa8f84842
+/qilin-client-ui-agent-opens:
+  en: 5e211958f9b9125a
+  zh: 6e44e7b616852f3b
+/qilin-client-ui-agent-opens/summary:
+  en: ab228b85522273b5
+  zh: 0799db69741f07c6
+/qilin-client-ui-agent-opens/table-of-contents:
+  en: 8be5c7fe49b63b1f
+  zh: c698cfc8c561a921
+/qilin-client-ui-agent-opens/known-limitations-and-deferred-work:
+  en: 2284af55257e37c1
+  zh: b2663a37bcd536da
+/qilin-client-ui-agent-opens/known-limitations-and-deferred-work/dev-note:
+  en: e67f633dc6fe7773
+  zh: 4e706f1b2b984e63

package/README.md

@@ -1,3 +1,36 @@
-# Temporary Holding Version
+---
+description: "Opens what the model asked to see in the Session's own Sidebar."
+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-agent-opens
+
+English | [中文](README.zh.md)
+
+## Summary
+
+The browser half of `sidebar_open`: it follows `ctx.remote.sidebarOpens.watch` for the Session the user is viewing and opens each request there. A page opens in the built-in browser when `@qilin-agent/client-ui-sidebar-browser` is composed and in a new browser tab otherwise; a file opens through its resource address, because which tab type claims an address is the Sidebar's decision. The plugin keeps no state: a request is delivered once and never replayed.
+
+## Table of Contents
+
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="known-limitations-and-deferred-work"></a>
+## Known Limitations and Deferred Work
+
+- **No folder targets.** A directory has no Sidebar surface to open (the file tree is rooted at the workspace), so the host tool refuses one before it reaches here.
+- **One viewer per Session.** Two browser views of one Session share one Host stream: the newest attachment takes it over, and the older view stops receiving opens.
+- **A carrier failure ends the watch silently.** The next Session switch opens a fresh stream; a request made while the stream was down and no view was attached still waits in the Host queue until then.
+
+<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,36 @@
+---
+description: "在所属会话自己的侧栏中打开模型要求查看的内容。"
+kind: "package-reference"
+---
+
+# @qilin-agent/client-ui-agent-opens
+
+[English](README.md) | 中文
+
+## 概述
+
+`sidebar_open` 的浏览器半边：跟随当前查看会话的 `ctx.remote.sidebarOpens.watch`，并在该会话的侧栏中打开每个请求。组合了 `@qilin-agent/client-ui-sidebar-browser` 时页面在**内置浏览器**中打开，否则退回新浏览器标签页；文件通过其资源地址打开，因为"哪个 tab 类型认领这个地址"是侧栏的决定。插件不保留状态：请求只投递一次，绝不重放。
+
+## 目录
+
+- [已知限制与后续工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="known-limitations-and-deferred-work"></a>
+## 已知限制与后续工作
+
+- **不支持目录目标。** 目录没有可打开的侧栏界面（文件树以工作区为根），所以宿主工具在到达这里之前就拒绝了。
+- **每个会话只有一个观看者。** 同一会话的两个浏览器视图共享一条 Host 流：最新的附着接管它，较旧的视图不再收到打开请求。
+- **载体失败会静默结束监听。** 下一次切换会话会开一条新流；在流中断且无人附着期间发出的请求仍留在 Host 队列里，等到那时再投递。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者信息 — 点击展开</summary>
+
+无。
+
+</details>

package/lib/client.js

@@ -0,0 +1,130 @@
+window.__ModuleLoader__.load({
+	id: "@qilin-agent/client-ui-agent-opens",
+	factory: (require) => {
+		var module = { exports: {} };
+		var exports = module.exports;
+		Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+		//#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);
+		}
+		/**
+		* 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/index.js
+		/** Required browser services: the Remote carrier, the Sidebar's tabs, and the viewed Session. */
+		const inject = [
+			"remote",
+			"sidebarRight",
+			"sidebarRightTabs",
+			"sessions",
+			"uiSession"
+		];
+		/**
+		* Client plugin body: follow the viewed Session's open requests and dispatch them.
+		* @param ctx - client root context carrying the Remote carrier and the Sidebar face.
+		*/
+		function apply(ctx) {
+			ctx.effect(() => {
+				const current = ctx.uiSession.adapter.current;
+				let stop;
+				const sync = () => {
+					stop?.();
+					stop = void 0;
+					const sessionId = current.getSnapshot().key;
+					if (sessionId === void 0) return;
+					const controller = new AbortController();
+					stop = () => {
+						controller.abort();
+					};
+					(async () => {
+						try {
+							for await (const request of ctx.remote.sidebarOpens.watch(sessionId, controller.signal)) {
+								if (controller.signal.aborted) return;
+								openRequested(ctx, sessionId, request);
+							}
+						} catch {}
+					})();
+				};
+				const unsubscribe = current.subscribe(sync);
+				sync();
+				return () => {
+					unsubscribe();
+					stop?.();
+				};
+			}, "ui-agent-opens: model open requests");
+		}
+		/**
+		* Open one request in the Session's Sidebar.
+		* @param ctx - client root context.
+		* @param sessionId - the Session whose Sidebar the request targets.
+		* @param request - the resolved request.
+		*/
+		function openRequested(ctx, sessionId, request) {
+			if (request.kind === "url") {
+				if (ctx.sidebarRightTabs.get("browser") !== void 0) ctx.sidebarRight.openTab("browser", { params: { url: request.target } });
+				else window.open(request.target, "_blank", "noopener,noreferrer");
+				return;
+			}
+			const cwd = ctx.sessions.list.getSnapshot().byId[sessionId]?.cwd;
+			ctx.sidebarRight.openResource(fileAddressFor(sessionId, cwd, request.target));
+		}
+		//#endregion
+		exports.apply = apply;
+		exports.inject = inject;
+		return module.exports;
+	}
+});
+
+//# sourceMappingURL=client.js.map

package/lib/index.js

@@ -0,0 +1,6 @@
+//#region lib/types/index.js
+/** Host companion for the agent-open Client plugin. */
+/** Mount the browser-only plugin through the Client loader. */
+function apply() {}
+//#endregion
+export { apply };

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

@@ -0,0 +1,24 @@
+/**
+ * Browser half: open what the model asked to see in the Session's own Sidebar.
+ *
+ * The requests arrive as a Host Remote stream (`ctx.remote.sidebarOpens.watch`)
+ * for the Session the user is viewing, so the plugin watches the current Session
+ * and re-subscribes when the view switches. Delivery is transient by design: the
+ * Host consumes a request on send and drops it, so nothing here replays an open
+ * the user already saw — and nothing here is durable, which is why this package
+ * owns no store, no slot, and no copy.
+ *
+ * A page opens in the built-in browser when that tab type is composed and in a
+ * new browser tab otherwise. A file opens through its resource address, because
+ * which tab type claims an address is the Sidebar's decision, not this
+ * dispatcher's.
+ */
+import type { Context } from '@qilin-agent/kylin';
+/** Required browser services: the Remote carrier, the Sidebar's tabs, and the viewed Session. */
+export declare const inject: string[];
+/**
+ * Client plugin body: follow the viewed Session's open requests and dispatch them.
+ * @param ctx - client root context carrying the Remote carrier and the Sidebar face.
+ */
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,4 @@
+/** Host companion for the agent-open Client plugin. */
+/** Mount the browser-only plugin through the Client loader. */
+export declare function apply(): void;
+//# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,6 +1,72 @@
 {
   "name": "@qilin-agent/client-ui-agent-opens",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Opens what the model asked to see in the Session's Sidebar",
+  "version": "3.1.3",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kkutysllb/QiLin.git",
+    "directory": "packages/client/ui-agent-opens"
+  },
+  "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-gateway",
+        "@qilin-agent/api-remotes",
+        "@qilin-agent/client-ui-sidebar-browser",
+        "@qilin-agent/client-ui-sidebar-right",
+        "@qilin-agent/client-ui-session"
+      ],
+      "platform": "web"
+    }
+  },
+  "license": "MIT",
+  "peerDependencies": {
+    "@qilin-agent/kylin": "~4.0.3"
+  },
+  "devDependencies": {
+    "@qilin-agent/kylin": "~4.0.3",
+    "@qilin-agent/api-gateway": "3.1.3",
+    "@qilin-agent/client-locale": "3.1.3",
+    "@qilin-agent/api-remotes": "3.1.3",
+    "@qilin-agent/client-store": "3.1.3",
+    "@qilin-agent/client-test-runtime": "3.1.3",
+    "@qilin-agent/client-ui-renderer": "3.1.3",
+    "@qilin-agent/client-ui-session": "3.1.3",
+    "@qilin-agent/client-ui-sidebar-browser": "3.1.3",
+    "@qilin-agent/client-ui-sidebar-right": "3.1.3",
+    "@qilin-agent/client-ui-slots": "3.1.3",
+    "@qilin-agent/util-workspace-path": "3.1.3",
+    "@qilin-agent/sidebar-opens": "3.1.3",
+    "@qilin-agent/session": "3.1.3"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  }
 }