@deepseek-ai/dsh-experimental-browser-use-chrome-devtools-mcp 0.1.6-alpha.1

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/experimental/browser-use-chrome-devtools-mcp/README.md
+README.md: b4ef51079d79429b570ec222f283b3c20112546b
+README.zh.md: 5ce248b9759e4fb942629fc10217bb055f1a0e65

package/README.md

@@ -0,0 +1,116 @@
+---
+description: "Operate Chromium through Chrome DevTools MCP with separate browser state for each live Session."
+kind: "package-reference"
+---
+
+# @deepseek-ai/dsh-experimental-browser-use-chrome-devtools-mcp
+
+English | [中文](README.zh.md)
+
+## Summary
+
+Use Chrome DevTools MCP to inspect pages and operate Chromium through its upstream tools. The provider initializes a Session's MCP connection before creation or resume completes and retains it across turns. Launch a separate browser or attach one Session to an existing browser with its current tabs and login state. This published experimental package activates only when explicitly mounted.
+
+## 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 both entries before creating or resuming a Session, in a profile composition that supplies Agents, tools, and system prompts. Loading or reloading this provider does not adopt Sessions that are already active. Browser installation follows the upstream runtime; select an existing Chromium installation with `executablePath`.
+
+```yaml
+- name: '@deepseek-ai/dsh-browser-use'
+- name: '@deepseek-ai/dsh-experimental-browser-use-chrome-devtools-mcp'
+  config:
+    mode: launch
+    headless: true
+```
+
+Use `mode: attach` and set `endpoint` to an HTTP(S) debugging URL or WS(S) browser endpoint to operate an existing browser. The new live Session claims the attachment during initialization and retains it until unloading. If the attachment is busy, that activation continues without this browser and does not retry on later turns. After release, a newly created or resumed activation can acquire it. Direct calls from another Session fail. Cleanup disconnects and leaves the external browser and its pages running.
+
+| Field | Default | Meaning |
+|---|---|---|
+| `mode` | required | `launch` or `attach`, fixed for this provider activation |
+| `headless` | `true` | Launch without a visible window |
+| `executablePath` | upstream discovery | Chromium executable for launch |
+| `endpoint` | required for attach | Existing browser debugging endpoint |
+| `toolCallTimeoutMs` | MCP client default | Per-call timeout in milliseconds |
+
+The [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-experimental-browser-use-chrome-devtools-mcp) lists accepted fields. The profile or preset selects the browser mode.
+
+When configuring the system prompt's `toolOrder` for the whole process, leave browser tools under `<unlisted-tools>`. Explicitly listing browser tool names can make prompt assembly fail for Sessions without a browser connection.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+The provider resolves its pinned npm entry and starts it under the current Node executable. A temporary protocol probe may precede the serving process. The [shared runtime](../browser-use-runtime/README.md) owns awaited Agent initialization, per-Session serialization, and cleanup; the [MCP client](../../mcp/mcp-client/README.md) owns transport, discovery, and result projection. No runtime invariant companion is published because the provider maintains no independent connection observation.
+
+Browser state survives turns while its live Session remains attached. Disposal waits for server shutdown before releasing resources. Resume after reload starts fresh browser runtime state; stored conversation history does not restore cookies or pages.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+- [Browser use](../../../docs/subsystems/browser-use.md) — provider selection and Session ownership.
+- [Browser-use service](../../browser-use/browser-use/README.md) — exclusive provider registration.
+- [Chrome DevTools MCP](https://github.com/ChromeDevTools/chrome-devtools-mcp) — upstream installation and browser behavior.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+### Browser tools and screenshots
+
+#### What the model sees
+
+Tools retain upstream descriptions and JSON schemas under `mcp__chrome-devtools-mcp__<tool>` names. Text and screenshots use the normal tool-result pipeline and Session log. Screenshots require an attachment store and an image-capable model route; other routes receive the MCP image diagnostic. The MCP client also exposes resource helpers and attributed server instructions. Browser instructions are shown only after this Session owns a connection; targeted resource requests enforce the same ownership.
+
+#### Token effect
+
+The catalog, resource helpers, and server instructions add tool definitions and prompt text. Calls add arguments, text, and admitted images to Session history. Inline image bytes stay outside model-visible history.
+
+#### KV Cache effect
+
+An unchanged catalog preserves its tool-definition prefix. Results append to history; provider or catalog changes can reduce prefix reuse.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+The integration retains the pinned server's browser and tool restrictions.
+
+- Chromium only; Firefox and WebKit are not selectable.
+- Startup failure or cancellation rejects Session creation or resume and triggers client cleanup. A disconnected client is not retried; after fixing the cause, create a new Session or unload and resume the existing one.
+- Attachment exclusivity is local to this provider instance. Other processes and browser users can still modify the same pages.
+- The shared resource-server inventory can show inherited server names; it does not grant access to another Session's browser.
+- Cancellation does not undo navigation, clicks, or other actions already delivered to the browser.
+- Tool schemas follow the pinned experimental dependency and carry no DSH stability promise.
+- Usage statistics are disabled. Other features, including performance tools, retain their upstream behavior.
+
+<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,116 @@
+---
+description: "通过 Chrome DevTools MCP 操作 Chromium，为每个活动 Session 保持独立浏览器状态。"
+kind: "package-reference"
+---
+
+# @deepseek-ai/dsh-experimental-browser-use-chrome-devtools-mcp
+
+[English](README.md) | 中文
+
+## 概述
+
+通过 Chrome DevTools MCP 的上游工具检查网页并操作 Chromium。提供方在 Session 创建或恢复完成前初始化其 MCP 连接，并跨轮次保留连接。可以启动独立浏览器，也可以让一个 Session 接入已有浏览器，使用其现有标签页和登录状态。本包以实验状态发布，仅在显式挂载后启用。
+
+## 目录
+
+- [使用此包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与待办事项](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用此包
+
+在创建或恢复 Session 前，将以下条目挂载到已提供 Agent、工具和系统提示词的 profile 组合中。加载或重新加载此提供方不会接管已经活动的 Session。浏览器安装遵循上游运行时；使用 `executablePath` 选择已有 Chromium 安装。
+
+```yaml
+- name: '@deepseek-ai/dsh-browser-use'
+- name: '@deepseek-ai/dsh-experimental-browser-use-chrome-devtools-mcp'
+  config:
+    mode: launch
+    headless: true
+```
+
+使用 `mode: attach`，并在 `endpoint` 中设置 HTTP(S) 调试 URL 或 WS(S) 浏览器端点，即可操作已有浏览器。新的活动 Session 在初始化时占用附加连接，并持续保留直到卸载。如果连接已被占用，本次激活不使用该浏览器，但继续运行，后续轮次不会重试。连接释放后，新创建或恢复的激活可以获取它。其他 Session 的直接调用会失败。清理只断开连接，保留外部浏览器及其页面。
+
+| 字段 | 默认值 | 含义 |
+|---|---|---|
+| `mode` | 必填 | `launch` 或 `attach`，在本次提供方激活期间固定 |
+| `headless` | `true` | 启动时不显示窗口 |
+| `executablePath` | 上游发现 | 启动使用的 Chromium 可执行文件 |
+| `endpoint` | attach 时必填 | 已有浏览器调试端点 |
+| `toolCallTimeoutMs` | MCP 客户端默认值 | 单次调用超时，单位为毫秒 |
+
+[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-experimental-browser-use-chrome-devtools-mcp)列出接受的字段。浏览器模式由 profile 或 preset 选择。
+
+为整个进程配置系统提示词的 `toolOrder` 时，将浏览器工具留在 `<unlisted-tools>` 中。显式列出浏览器工具名称可能导致未获得浏览器连接的 Session 无法组装提示词。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节 — 点击展开</summary>
+
+提供方解析固定版本 npm 包的可执行入口，并使用当前 Node 启动。服务进程之前可能运行临时协议探测进程。[共享运行时](../browser-use-runtime/README.zh.md)负责等待 Agent 初始化、逐 Session 串行执行与清理；[MCP 客户端](../../mcp/mcp-client/README.zh.md)负责传输、发现和结果投影。提供方不维护独立的连接观测，因此不发布运行时不变量配套入口。
+
+只要活动 Session 保持连接，浏览器状态就会跨轮次保留。销毁会等待服务器关闭，再释放资源。重新加载后恢复 Session 会创建新的浏览器运行状态；已保存的对话历史不会还原 Cookie 或页面。
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+- [浏览器使用](../../../docs/subsystems/browser-use.zh.md) — 提供方选择与 Session 所有权。
+- [浏览器使用服务](../../browser-use/browser-use/README.zh.md) — 提供方独占注册。
+- [Chrome DevTools MCP](https://github.com/ChromeDevTools/chrome-devtools-mcp) — 上游安装与浏览器行为。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+### 浏览器工具与截图
+
+#### 模型可见内容
+
+工具以 `mcp__chrome-devtools-mcp__<tool>` 命名，保留上游描述和 JSON schema。文本与截图通过常规工具结果流程进入 Session 日志。截图需要附件存储及支持图片输入的模型路由；其他路由会收到 MCP 图片诊断。MCP 客户端还提供资源工具和注明服务器来源的指导。只有当前 Session 拥有连接后才显示浏览器指导；针对该服务器的资源请求执行相同的所有权检查。
+
+#### Token 影响
+
+工具目录、资源工具和服务器指导会增加工具定义与提示词文本。调用会向 Session 历史加入参数、文本和获准输入的图片。内联图片字节不进入模型可见历史。
+
+#### KV Cache 影响
+
+不变的工具目录会保留工具定义前缀。结果追加到历史；更换提供方或目录可能降低前缀复用率。
+
+## 已知限制与待办事项
+
+<a id="known-limitations-and-deferred-work"></a>
+
+本集成保留固定版本服务器的浏览器与工具限制。
+
+- 仅支持 Chromium；不可选择 Firefox 或 WebKit。
+- 启动失败或取消会拒绝 Session 创建或恢复，并触发客户端清理。断开的客户端不会重试；修复原因后，创建新 Session，或卸载并恢复已有 Session。
+- 连接独占仅在此提供方实例内有效。其他进程与浏览器用户仍可修改相同页面。
+- 共享资源服务器目录可以显示继承的服务器名称，但不会授予对其他 Session 浏览器的访问权限。
+- 取消不会撤销已发送给浏览器的导航、点击或其他操作。
+- 工具 schema 跟随固定的实验依赖版本，不承诺 DSH 稳定性。
+- 使用统计已禁用。包括性能工具在内的其他功能保留其上游行为。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者工作上下文 — 点击展开</summary>
+
+无。
+
+</details>

package/lib/index.js

@@ -0,0 +1,39 @@
+import { fileURLToPath } from "node:url";
+import { BrowserMcpConfig, mountSessionMcp, validateBrowserMcpConfig } from "@deepseek-ai/dsh-experimental-browser-use-runtime/mcp";
+//#region lib/types/index.js
+/** Chromium inspection and automation through the pinned Chrome DevTools MCP server. @module */
+/** Cordis identity for the Chrome DevTools MCP browser provider. */
+const name = "experimental-browser-use-chrome-devtools-mcp";
+/** Services required for scoped MCP startup and prompt readiness checks. */
+const inject = [
+	"browserUse",
+	"agents",
+	"tools",
+	"systemPrompt"
+];
+/** Validate the launch or attachment configuration before activation. */
+const Config = BrowserMcpConfig;
+/**
+* Expose Chrome DevTools' upstream catalog through one MCP process per live Session.
+* Attached browsers remain externally owned; the server disables usage statistics.
+* @param ctx - provider context supplying browser use, Agents, and tools.
+* @param config - validated browser choice and optional tool timeout.
+*/
+function apply(ctx, config) {
+	validateBrowserMcpConfig(config);
+	const args = [fileURLToPath(import.meta.resolve("chrome-devtools-mcp/build/src/bin/chrome-devtools-mcp.js")), "--no-usage-statistics"];
+	if (config.mode === "attach") args.push(/^wss?:/u.test(config.endpoint) ? "--ws-endpoint" : "--browser-url", config.endpoint);
+	else {
+		args.push("--isolated", `--headless=${String(config.headless)}`);
+		if (config.executablePath !== void 0) args.push("--executable-path", config.executablePath);
+	}
+	mountSessionMcp(ctx, {
+		name: "chrome-devtools-mcp",
+		exclusive: config.mode === "attach",
+		command: process.execPath,
+		args,
+		...config.toolCallTimeoutMs === void 0 ? {} : { toolCallTimeoutMs: config.toolCallTimeoutMs }
+	});
+}
+//#endregion
+export { Config, apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,19 @@
+/** Chromium inspection and automation through the pinned Chrome DevTools MCP server. @module */
+import type { Context } from '@deepseek-ai/cordis';
+import { BrowserMcpConfig } from '@deepseek-ai/dsh-experimental-browser-use-runtime/mcp';
+/** Cordis identity for the Chrome DevTools MCP browser provider. */
+export declare const name = "experimental-browser-use-chrome-devtools-mcp";
+/** Services required for scoped MCP startup and prompt readiness checks. */
+export declare const inject: string[];
+/** Fixed Chromium launch or existing-browser attachment settings. */
+export type Config = BrowserMcpConfig;
+/** Validate the launch or attachment configuration before activation. */
+export declare const Config: typeof BrowserMcpConfig;
+/**
+ * Expose Chrome DevTools' upstream catalog through one MCP process per live Session.
+ * Attached browsers remain externally owned; the server disables usage statistics.
+ * @param ctx - provider context supplying browser use, Agents, and tools.
+ * @param config - validated browser choice and optional tool timeout.
+ */
+export declare function apply(ctx: Context, config: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@deepseek-ai/dsh-experimental-browser-use-chrome-devtools-mcp",
+  "description": "Experimental per-Session Chromium browser tools through chrome-devtools-mcp",
+  "version": "0.1.6-alpha.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/experimental/browser-use-chrome-devtools-mcp"
+  },
+  "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"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "chrome-devtools-mcp": "1.9.0",
+    "@deepseek-ai/dsh-experimental-browser-use-runtime": "^0.1.6-alpha.1"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-browser-use": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-agent": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-tools": "^0.1.6-alpha.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.3",
+    "@deepseek-ai/dsh-browser-use": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-agent": "^0.1.6-alpha.1",
+    "@deepseek-ai/cordis-plugin-include": "^1.0.7",
+    "@deepseek-ai/dsh-agent-loop": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-llm": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-tools": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-session-projection": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-session": "^0.1.6-alpha.1"
+  }
+}