@qilin-agent/browser-use 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,37 @@
+# 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/browser-use/browser-use/README.md
+/:
+  en: f40b34f771caa863
+  zh: f61d7ce73e0720e2
+/qilin-browser-use:
+  en: 3faed0ad44a63838
+  zh: 1647a85ef39b0ab2
+/qilin-browser-use/summary:
+  en: 3e2c0d4aad911b93
+  zh: 3e3903754a46de8e
+/qilin-browser-use/table-of-contents:
+  en: d152484eb41ac6b4
+  zh: f14f34fce35a8d90
+/qilin-browser-use/use-this-package:
+  en: b981e34a09985257
+  zh: c482fb97bc096e1a
+/qilin-browser-use/understand-the-implementation:
+  en: c4d9ec0df22a30ea
+  zh: 06057e2a56cebbb9
+/qilin-browser-use/further-exploration:
+  en: c32c24ca938f2a97
+  zh: fb577661f82fcac7
+/qilin-browser-use/model-experience:
+  en: 8780c250dfaefaaa
+  zh: f1fd94f7531b60a1
+/qilin-browser-use/model-experience/kv-cache-effect:
+  en: 0cc866a67a19d08b
+  zh: c6a46b147b042cff
+/qilin-browser-use/known-limitations-and-deferred-work:
+  en: 43952e97817e9e32
+  zh: a5e494860a71fc71
+/qilin-browser-use/known-limitations-and-deferred-work/dev-note:
+  en: e67f633dc6fe7773
+  zh: 8ec3e73528ddb1a6

package/README.md

@@ -1,3 +1,88 @@
-# Temporary Holding Version
+---
+description: "Browser-use provider registration for deployments that enable one browser backend at a time."
+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/browser-use
+
+English | [中文](README.zh.md)
+
+## Summary
+
+A deployment can enable one browser-use provider at a time. Loading another provider fails with the registered provider name. Each provider supplies its own tools and owns browser sessions. This package adds no model-visible tools or browser operations.
+
+## 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
+
+Mount the service once beside the chosen provider in a Cordis composition:
+
+```yaml
+- name: '@qilin-agent/browser-use'
+```
+
+The service has no configuration. Provider plugins inject `browserUse` and call `ctx.browserUse.register(BrowserUseProviderName(name))`; the brand is exported from `@qilin-agent/browser-use/brand`. The returned effect disposer releases that registration.
+
+Providers stop admitting tool calls, close their resources, and await owned work before releasing the registration. `ctx.browserUse.providerName` reports the registered name until release.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+One private name owns the slot. Cordis effects remove contributions when their plugin unloads; a repeated disposer cannot remove a later registration. The [source](src/index.ts) contains no browser object, operation interface, resource lifecycle, or provider selector.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+- [Browser use](../../../docs/subsystems/browser-use.md) — provider selection and Session ownership.
+- [Playwright MCP provider](../../experimental/browser-use-playwright-mcp/README.md) — Playwright browser tools.
+- [Chrome DevTools MCP provider](../../experimental/browser-use-chrome-devtools-mcp/README.md) — Chromium inspection and control.
+- [Stagehand provider](../../experimental/browser-use-stagehand-native/README.md) — native browser operations with AI assistance.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+None, as this registry only records provider names.
+
+#### KV Cache effect
+
+Registration does not alter model requests. Provider-owned tools and guidance determine their own request-prefix effects.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+The service limits registrations within its Cordis service instance.
+
+- **Browser ownership** — providers own browser resources and enforce Session isolation; this service stores no browser state.
+- **Provider selection** — configuration selects the provider; the model cannot switch registered backends at runtime.
+
+<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,88 @@
+---
+description: "浏览器操作 提供方 注册服务，供一次启用一个浏览器后端的部署使用。"
+kind: "package-reference"
+---
+
+# @qilin-agent/browser-use
+
+[English](README.md) | 中文
+
+## 概述
+
+部署可以一次启用一个浏览器操作 提供方。加载另一个 提供方 时会报错并指出已注册的 提供方 名称。各 提供方 提供自己的工具并拥有浏览器会话。本包不添加模型可见工具或浏览器操作。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [延伸阅读](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+在 Cordis 组合中，将服务与所选 提供方 一起挂载一次：
+
+```yaml
+- name: '@qilin-agent/browser-use'
+```
+
+服务没有配置。提供方 插件注入 `browserUse` 并调用 `ctx.browserUse.register(BrowserUseProviderName(name))`；品牌类型从 `@qilin-agent/browser-use/brand` 导出。返回的 effect 清理器释放该注册。
+
+提供方 在释放注册前停止接收工具调用、关闭资源并等待自己拥有的工作结束。`ctx.browserUse.providerName` 在释放之前持续报告已注册名称。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现内部机制 — 点击展开</summary>
+
+一个私有名称拥有该注册位。Cordis effect 在插件卸载时移除贡献；重复调用清理器不能移除后续注册。[源码](src/index.ts) 不包含浏览器对象、操作接口、资源生命周期或 提供方 选择器。
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 延伸阅读
+
+- [浏览器操作](../../../docs/subsystems/browser-use.zh.md) — 提供方 选择与 Session 所有权。
+- [Playwright MCP 提供方](../../experimental/browser-use-playwright-mcp/README.zh.md) — Playwright 浏览器工具。
+- [Chrome DevTools MCP 提供方](../../experimental/browser-use-chrome-devtools-mcp/README.zh.md) — Chromium 检查与控制。
+- [Stagehand 提供方](../../experimental/browser-use-stagehand-native/README.zh.md) — 支持 AI（人工智能）辅助的原生浏览器操作。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+无，因为此注册表只记录 提供方 名称。
+
+#### KV Cache 影响
+
+注册不改变模型请求。提供方 拥有的工具与指导决定各自对请求前缀的影响。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+服务在其 Cordis 服务实例内限制注册。
+
+- **浏览器所有权** — 提供方 拥有浏览器资源并实施 Session 隔离；此服务不保存浏览器状态。
+- **提供方 选择** — 配置选择 提供方；模型不能在运行时切换已注册后端。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者工作上下文 — 点击展开</summary>
+
+无。
+
+</details>

package/lib/index.js

@@ -0,0 +1,35 @@
+import { Service } from "@qilin-agent/kylin";
+//#region lib/types/index.js
+/**
+* Exclusive named registration for the browser-use capability.
+* @module @qilin-agent/browser-use
+*/
+/** Owns one optional provider registration in the shared browser-use service. */
+var BrowserUseRegistry = class extends Service {
+	registration;
+	constructor(ctx) {
+		super(ctx, "browserUse");
+	}
+	/** Name of the registered provider, including while its resources are closing. */
+	get providerName() {
+		return this.registration;
+	}
+	/**
+	* Reserve the sole provider slot until the contribution is disposed.
+	* A second registration fails even when it repeats the current name. Providers
+	* must stop their tools and await owned work before releasing this registration.
+	* @param name - provider-owned name used in registration diagnostics.
+	* @returns the effect disposer for this exact registration.
+	*/
+	register(name) {
+		if (this.registration !== void 0) throw new Error(`browser use provider "${this.registration}" is already registered`);
+		return this.ctx.effect(() => {
+			this.registration = name;
+			return () => {
+				this.registration = void 0;
+			};
+		}, "browserUse.register()");
+	}
+};
+//#endregion
+export { BrowserUseRegistry, BrowserUseRegistry as default };

package/lib/types/brand.d.ts

@@ -0,0 +1,11 @@
+/** Browser-use provider identities. @module @qilin-agent/browser-use/brand */
+import type { Branded } from '@qilin-agent/brand';
+/** Provider-owned name identifying a browser-use registration. */
+export type BrowserUseProviderName = Branded<'BrowserUseProviderName'>;
+/**
+ * Brand a provider-owned name without changing or validating it.
+ * @param name - name chosen by the provider implementation.
+ * @returns the same name with its browser-use provider brand.
+ */
+export declare function BrowserUseProviderName(name: string): BrowserUseProviderName;
+//# sourceMappingURL=brand.d.ts.map

package/lib/types/brand.js

@@ -0,0 +1,10 @@
+/** Browser-use provider identities. @module @qilin-agent/browser-use/brand */
+/**
+ * Brand a provider-owned name without changing or validating it.
+ * @param name - name chosen by the provider implementation.
+ * @returns the same name with its browser-use provider brand.
+ */
+export function BrowserUseProviderName(name) {
+    return name;
+}
+//# sourceMappingURL=brand.js.map

package/lib/types/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Exclusive named registration for the browser-use capability.
+ * @module @qilin-agent/browser-use
+ */
+import { Context, Service } from '@qilin-agent/kylin';
+import type { BrowserUseProviderName } from './brand.ts';
+declare module '@qilin-agent/kylin' {
+    interface Context {
+        browserUse: BrowserUseRegistry;
+    }
+}
+/** Owns one optional provider registration in the shared browser-use service. */
+export declare class BrowserUseRegistry extends Service {
+    private registration;
+    constructor(ctx: Context);
+    /** Name of the registered provider, including while its resources are closing. */
+    get providerName(): BrowserUseProviderName | undefined;
+    /**
+     * Reserve the sole provider slot until the contribution is disposed.
+     * A second registration fails even when it repeats the current name. Providers
+     * must stop their tools and await owned work before releasing this registration.
+     * @param name - provider-owned name used in registration diagnostics.
+     * @returns the effect disposer for this exact registration.
+     */
+    register(name: BrowserUseProviderName): () => Promise<void>;
+}
+export default BrowserUseRegistry;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/index.js

@@ -0,0 +1,36 @@
+/**
+ * Exclusive named registration for the browser-use capability.
+ * @module @qilin-agent/browser-use
+ */
+import { Service } from '@qilin-agent/kylin';
+/** Owns one optional provider registration in the shared browser-use service. */
+export class BrowserUseRegistry extends Service {
+    registration;
+    constructor(ctx) {
+        super(ctx, 'browserUse');
+    }
+    /** Name of the registered provider, including while its resources are closing. */
+    get providerName() {
+        return this.registration;
+    }
+    /**
+     * Reserve the sole provider slot until the contribution is disposed.
+     * A second registration fails even when it repeats the current name. Providers
+     * must stop their tools and await owned work before releasing this registration.
+     * @param name - provider-owned name used in registration diagnostics.
+     * @returns the effect disposer for this exact registration.
+     */
+    register(name) {
+        if (this.registration !== undefined) {
+            throw new Error(`browser use provider "${this.registration}" is already registered`);
+        }
+        return this.ctx.effect(() => {
+            this.registration = name;
+            return () => {
+                this.registration = undefined;
+            };
+        }, 'browserUse.register()');
+    }
+}
+export default BrowserUseRegistry;
+//# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "@qilin-agent/browser-use",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Exclusive named browser-use provider registration",
+  "version": "3.1.3",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kkutysllb/QiLin.git",
+    "directory": "packages/browser-use/browser-use"
+  },
+  "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"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json",
+    "./brand": {
+      "types": "./lib/types/brand.d.ts",
+      "default": "./lib/types/brand.js"
+    }
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@qilin-agent/kylin": "~4.0.3",
+    "@qilin-agent/brand": "3.1.3"
+  },
+  "devDependencies": {
+    "@qilin-agent/brand": "3.1.3",
+    "@qilin-agent/kylin": "~4.0.3"
+  }
 }