@mind-harness/mh-browser 0.2.2 → 0.2.4

package/THIRD-PARTY-NOTICES

@@ -0,0 +1,23 @@
+lib/client.cjs includes code from @deepseek-ai/dsh-typert-protocol, distributed under the following license.
+
+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/extension/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "Mind Harness",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "permissions": ["tabGroups"],
   "background": { "service_worker": "sw.js" }
 }

package/extension/welcome.css

@@ -0,0 +1,94 @@
+/* Keep in step with the sign-in callback page in packages/mh-cloud/src/page.ts. */
+:root {
+  --bg: #f4f4f6;
+  --card: #fff;
+  --stroke: rgba(0, 0, 0, 0.08);
+  --text: #18181b;
+  --muted: #6b6b73;
+  --accent: #4d6bfe;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --bg: #161618;
+    --card: #202023;
+    --stroke: rgba(255, 255, 255, 0.08);
+    --text: #ededf0;
+    --muted: #9a9aa3;
+    --accent: #7f95ff;
+  }
+}
+
+* {
+  box-sizing: border-box;
+}
+
+html,
+body {
+  height: 100%;
+}
+
+body {
+  margin: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 24px;
+  background: var(--bg);
+  color: var(--text);
+  font:
+    15px/1.6 -apple-system,
+    BlinkMacSystemFont,
+    'Segoe UI',
+    'PingFang SC',
+    'Hiragino Sans GB',
+    'Microsoft YaHei',
+    sans-serif;
+}
+
+.card {
+  width: 100%;
+  max-width: 420px;
+  padding: 36px 32px 28px;
+  border: 1px solid var(--stroke);
+  border-radius: 20px;
+  background: var(--card);
+  text-align: center;
+}
+
+.product {
+  margin: 0 0 24px;
+  font-size: 12px;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+  color: var(--muted);
+}
+
+.mark {
+  width: 56px;
+  height: 56px;
+  margin: 0 auto 16px;
+  border-radius: 50%;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  color: var(--accent);
+  background: color-mix(in srgb, var(--accent) 14%, transparent);
+}
+
+h1 {
+  margin: 0 0 8px;
+  font-size: 20px;
+  font-weight: 600;
+}
+
+.line {
+  margin: 0 0 4px;
+  color: var(--muted);
+}
+
+.hint {
+  margin: 12px 0 0;
+  font-size: 13px;
+  color: var(--muted);
+}

package/extension/welcome.html

@@ -0,0 +1,40 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="color-scheme" content="light dark" />
+    <title data-text="tab">Mind Harness browser</title>
+    <link rel="stylesheet" href="welcome.css" />
+    <script src="welcome.js" defer></script>
+  </head>
+  <body>
+    <main class="card">
+      <p class="product">Mind Harness</p>
+      <div class="mark" aria-hidden="true">
+        <svg
+          viewBox="0 0 24 24"
+          width="28"
+          height="28"
+          fill="none"
+          stroke="currentColor"
+          stroke-width="2.2"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+        >
+          <rect x="3.5" y="5" width="17" height="14" rx="2.5" />
+          <path d="M3.5 9.5h17" />
+        </svg>
+      </div>
+      <h1 data-text="title">This is the Mind&nbsp;Harness browser</h1>
+      <p class="line" data-text="what">
+        The agent opens pages, reads them, and acts on them here. Sites you sign in to here stay
+        signed in for the agent.
+      </p>
+      <p class="line" data-text="keep">
+        Please keep this browser running. When the agent needs you, the conversation will tell you.
+      </p>
+      <p class="hint" data-text="closes">This window closes when the agent opens its first page.</p>
+    </main>
+  </body>
+</html>

package/extension/welcome.js

@@ -0,0 +1,15 @@
+const ZH = {
+  tab: 'Mind Harness 浏览器',
+  title: '这是 Mind\u00a0Harness 的浏览器',
+  what: 'Agent 在这里替你打开网页、读取内容、完成操作。你在这里登录过的网站，Agent 之后也能用上。',
+  keep: '请不要退出这个浏览器。需要你来接手时，对话里会提示你。',
+  closes: 'Agent 打开第一个网页后，这个窗口会自动关闭。',
+}
+
+if (navigator.language.toLowerCase().startsWith('zh')) {
+  document.documentElement.lang = 'zh-CN'
+  for (const node of document.querySelectorAll('[data-text]')) {
+    const text = ZH[node.getAttribute('data-text')]
+    if (text !== undefined) node.textContent = text
+  }
+}

package/lib/client.cjs

@@ -0,0 +1,446 @@
+window.__ModuleLoader__.load({
+	id: "@mind-harness/mh-browser",
+	factory: (require) => {
+		var module = { exports: {} };
+		var exports = module.exports;
+		Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+		let zod = require("zod");
+		let react = require("react");
+		//#region ../../node_modules/.pnpm/@deepseek-ai+dsh-typert-protocol@0.2.2-rc.1_@deepseek-ai+cordis@4.1.0/node_modules/@deepseek-ai/dsh-typert-protocol/lib/types/remote-info.js
+		/** Lazy assembly of generated Remote definitions using caller-supplied Zod; no runtime imports. */
+		/**
+		* Retain one generated definition per endpoint without constructing parsers or projections.
+		* The class instance builds its shared descriptor/method index on first access;
+		* input schemas and JSON Schema projections are cached only when requested.
+		* @param spec - compiler-produced method facts and Zod factories.
+		* @param zod - the generated artifact's Zod runtime for named-input parsers.
+		* @returns a lazy, mountable info instance with no registration or transport effects.
+		*/
+		function createTypertRemoteInfo(spec, zod) {
+			return new RemoteInfo(spec, zod);
+		}
+		var RemoteInfo = class {
+			spec;
+			zod;
+			index;
+			constructor(spec, zod) {
+				this.spec = spec;
+				this.zod = zod;
+			}
+			get package() {
+				return this.spec.package;
+			}
+			get descriptors() {
+				return this.resolve().descriptors;
+			}
+			get methods() {
+				return this.resolve().methods;
+			}
+			resolve() {
+				if (this.index !== void 0) return this.index;
+				const zod = this.zod;
+				const descriptors = [];
+				const methods = Object.create(null);
+				for (const [endpoint, definition] of Object.entries(this.spec.methods)) {
+					const separator = endpoint.indexOf("/");
+					const namespace = endpoint.slice(0, separator);
+					const method = endpoint.slice(separator + 1);
+					const parameters = definition.parameters.map((parameter) => ({
+						...parameter,
+						wire: parameter.wire ?? parameter.name
+					}));
+					const descriptor = {
+						...definition,
+						id: `${this.spec.package}#${endpoint}`,
+						namespace,
+						method,
+						parameters,
+						result: definition.result.description === void 0 ? definition.result : new ResultValue(definition.result)
+					};
+					if (definition.invocation.kind === "direct") {
+						const inputs = [];
+						methods[endpoint] = Object.assign(descriptor, {
+							input(options) {
+								const strict = options?.strict === true;
+								return inputs[strict ? 1 : 0] ??= new NamedInput(parameters, strict, zod);
+							},
+							invoke(remote, input, signal) {
+								const named = input;
+								const values = parameters.map((parameter) => named[parameter.wire]);
+								if (definition.cancellation !== void 0) values.push(signal);
+								const receiver = Reflect.get(remote, namespace);
+								return Reflect.get(receiver, method).apply(receiver, values);
+							}
+						});
+					}
+					descriptors.push(descriptor);
+				}
+				return this.index = {
+					descriptors,
+					methods
+				};
+			}
+		};
+		function optional(parameter) {
+			return parameter.source === "json" && parameter.acceptsUndefined === true;
+		}
+		var NamedInput = class {
+			parameters;
+			strict;
+			zod;
+			schema;
+			projection;
+			constructor(parameters, strict, zod) {
+				this.parameters = parameters;
+				this.strict = strict;
+				this.zod = zod;
+			}
+			codec(parameter) {
+				return this.strict ? parameter.strictCodec : parameter.codec;
+			}
+			create = () => this.schema ??= this.zod.strictObject(Object.fromEntries(this.parameters.map((parameter) => {
+				const value = this.codec(parameter).create();
+				return [parameter.wire, optional(parameter) ? value.optional() : value.nonoptional()];
+			})));
+			get jsonSchema() {
+				return this.project().jsonSchema;
+			}
+			get jsonSchemaError() {
+				return this.project().jsonSchemaError;
+			}
+			project() {
+				if (this.projection !== void 0) return this.projection;
+				const unavailable = this.parameters.find((parameter) => this.codec(parameter).jsonSchema === void 0);
+				if (unavailable !== void 0) return this.projection = { jsonSchemaError: this.codec(unavailable).jsonSchemaError ?? `No JSON Schema for parameter ${unavailable.wire}` };
+				return this.projection = { jsonSchema: {
+					type: "object",
+					properties: Object.fromEntries(this.parameters.map((parameter) => [parameter.wire, {
+						...this.codec(parameter).jsonSchema,
+						...parameter.description === void 0 ? {} : { description: parameter.description }
+					}])),
+					required: this.parameters.filter((parameter) => !optional(parameter)).map((parameter) => parameter.wire),
+					additionalProperties: false
+				} };
+			}
+		};
+		var ResultValue = class {
+			spec;
+			projection;
+			constructor(spec) {
+				this.spec = spec;
+			}
+			get mode() {
+				return this.spec.mode;
+			}
+			get typeSymbol() {
+				return this.spec.typeSymbol;
+			}
+			get create() {
+				return this.spec.create;
+			}
+			get decode() {
+				return this.spec.decode;
+			}
+			get encode() {
+				return this.spec.encode;
+			}
+			get description() {
+				return this.spec.description;
+			}
+			get jsonSchemaError() {
+				return this.spec.jsonSchemaError;
+			}
+			get jsonSchema() {
+				if (this.projection === void 0) {
+					const schema = this.spec.jsonSchema;
+					this.projection = { value: schema === void 0 ? void 0 : {
+						...schema,
+						description: this.spec.description
+					} };
+				}
+				return this.projection.value;
+			}
+		};
+		//#endregion
+		//#region lib/typert.remote-client.js
+		let _mind_harness_mh_browser_mhBrowser_revealHandover_parameter_0$schema$value;
+		const _mind_harness_mh_browser_mhBrowser_revealHandover_parameter_0$schema = () => _mind_harness_mh_browser_mhBrowser_revealHandover_parameter_0$schema$value ??= zod.z.string();
+		let _mind_harness_mh_browser_mhBrowser_revealHandover_result$schema$value;
+		const _mind_harness_mh_browser_mhBrowser_revealHandover_result$schema = () => _mind_harness_mh_browser_mhBrowser_revealHandover_result$schema$value ??= zod.z.object({ "status": zod.z.union([
+			zod.z.literal("revealed"),
+			zod.z.literal("not-handing-over"),
+			zod.z.literal("no-tab")
+		]) });
+		let _mind_harness_mh_browser_mhBrowser_revealHandover_parameter_0_strict$schema$value;
+		const _mind_harness_mh_browser_mhBrowser_revealHandover_parameter_0_strict$schema = () => _mind_harness_mh_browser_mhBrowser_revealHandover_parameter_0_strict$schema$value ??= zod.z.string();
+		const TYPERT_REMOTE = createTypertRemoteInfo({
+			package: "@mind-harness/mh-browser",
+			methods: { "mhBrowser/revealHandover": {
+				service: "mhBrowser",
+				description: "The person asked to see the page this Session handed over.",
+				invocation: { kind: "direct" },
+				parameters: [{
+					name: "sessionId",
+					source: "json",
+					codec: {
+						mode: "strict",
+						typeSymbol: "@mind-harness/mh-browser#mhBrowser/revealHandover:sessionId",
+						create: _mind_harness_mh_browser_mhBrowser_revealHandover_parameter_0$schema,
+						jsonSchema: { "type": "string" }
+					},
+					strictCodec: {
+						mode: "strict",
+						typeSymbol: "@mind-harness/mh-browser#mhBrowser/revealHandover:sessionId",
+						create: _mind_harness_mh_browser_mhBrowser_revealHandover_parameter_0_strict$schema,
+						jsonSchema: { "type": "string" }
+					}
+				}],
+				cancellation: { parameter: "signal" },
+				result: {
+					mode: "strict",
+					typeSymbol: "@mind-harness/mh-browser#mhBrowser/revealHandover:result",
+					create: _mind_harness_mh_browser_mhBrowser_revealHandover_result$schema,
+					jsonSchema: {
+						"type": "object",
+						"properties": { "status": {
+							"type": "string",
+							"enum": [
+								"revealed",
+								"not-handing-over",
+								"no-tab"
+							]
+						} },
+						"required": ["status"],
+						"additionalProperties": true
+					}
+				},
+				sourceLocation: {
+					"file": "packages/mh-browser/src/service/service.ts",
+					"line": 624,
+					"column": 9
+				}
+			} }
+		}, zod.z);
+		//#endregion
+		//#region src/client/card.ts
+		/** Host theme tokens only; the rules unmount with the row. */
+		const STYLE = `
+.mh-br { display: flex; flex-direction: column; align-items: flex-start; gap: 8px; color: var(--dsw-alias-label-primary); font-size: 14px; line-height: 20px; }
+.mh-br-line { margin: 0; }
+.mh-br-status { margin: 0; color: var(--dsw-alias-label-secondary); }
+.mh-br-button { padding: 4px 10px; border: 0.5px solid var(--dsw-alias-border-l3); border-radius: var(--dsw-radius-md); background: transparent; color: var(--dsw-alias-label-primary); font: inherit; cursor: pointer; }
+`;
+		/** The open handover: the reason and the button that raises its window. */
+		function HandoverRow(props) {
+			const [note, setNote] = (0, react.useState)(void 0);
+			return (0, react.createElement)("section", { className: "mh-br" }, (0, react.createElement)("style", null, STYLE), (0, react.createElement)("p", { className: "mh-br-line" }, props.t("waiting", { reason: props.reason })), (0, react.createElement)("button", {
+				type: "button",
+				className: "mh-br-button",
+				onClick: () => {
+					props.reveal(props.sessionId, new AbortController().signal).then((result) => {
+						setNote(noteFor(result, props.t));
+					}).catch(() => {
+						setNote(props.t("failed"));
+					});
+				}
+			}, props.t("reveal")), note !== void 0 ? (0, react.createElement)("p", { className: "mh-br-status" }, note) : null);
+		}
+		/** `revealed` adds no status line. */
+		function noteFor(result, t) {
+			if (!result.ok) return t("failed");
+			if (result.value.status === "not-handing-over") return t("notHandingOver");
+			if (result.value.status === "no-tab") return t("noTab");
+		}
+		//#endregion
+		//#region src/client/locales.ts
+		/** Dictionary namespace for the handover row. */
+		const NS = "mh-browser";
+		const zh = {
+			waiting: "浏览器交给你了：{reason}",
+			reveal: "去浏览器",
+			notHandingOver: "这次交接已经结束",
+			noTab: "没有可以去的页面",
+			failed: "没能切到浏览器"
+		};
+		const en = {
+			waiting: "The browser is yours: {reason}",
+			reveal: "Go to the browser",
+			notHandingOver: "This handover has already ended",
+			noTab: "There is no page to open",
+			failed: "Could not switch to the browser"
+		};
+		//#endregion
+		//#region src/client/row.ts
+		/**
+		* One chat row for the open `browser_handover` in a turn.
+		* `groupTree: 'turn'` stands outside the process group. A settled call keeps
+		* the same key and hides the row; a hidden row is omitted from group order.
+		*/
+		const HANDOVER_KIND = "browser-handover";
+		const HANDOVER_TOOL = "browser_handover";
+		function isRecord(value) {
+			return typeof value === "object" && value !== null && !Array.isArray(value);
+		}
+		function turnOf(data) {
+			if (!isRecord(data) || typeof data.turn !== "number") return void 0;
+			return data.turn;
+		}
+		function reasonOf(value) {
+			if (typeof value !== "string") return "";
+			try {
+				const parsed = JSON.parse(value);
+				if (!isRecord(parsed) || typeof parsed.reason !== "string") return "";
+				return parsed.reason;
+			} catch {
+				return "";
+			}
+		}
+		function callOf(data) {
+			if (!isRecord(data) || typeof data.callId !== "string" || typeof data.name !== "string") return void 0;
+			return {
+				callId: data.callId,
+				name: data.name,
+				arguments: data.arguments
+			};
+		}
+		/** A result names its call on `message.source` and again on `message.toolCallId`. */
+		function callIdOf(data) {
+			if (!isRecord(data) || !isRecord(data.message)) return void 0;
+			const message = data.message;
+			if (isRecord(message.source) && typeof message.source.callId === "string" && message.source.callId !== "") return message.source.callId;
+			if (typeof message.toolCallId === "string" && message.toolCallId !== "") return message.toolCallId;
+		}
+		function hidden(current) {
+			return {
+				...current,
+				visibility: "hidden",
+				data: { reason: "" }
+			};
+		}
+		/**
+		* The row for one turn. Absent until a handover in that turn has been seen;
+		* hidden, with the same key, once the open call settles.
+		*/
+		function buildHandoverView(context) {
+			const current = context.current.get("chat") ?? null;
+			const anchorSeq = context.state?.anchorSeq;
+			if (anchorSeq === void 0) return current === null ? null : hidden(current);
+			const open = context.state?.open;
+			return {
+				key: context.key,
+				kind: HANDOVER_KIND,
+				id: context.id,
+				target: "chat",
+				anchorSeq,
+				location: context.start?.location ?? { kind: "unresolved" },
+				visibility: open === void 0 ? "hidden" : "visible",
+				groupTree: "turn",
+				data: { reason: open?.reason ?? "" }
+			};
+		}
+		const handoverRowDefinition = {
+			kind: HANDOVER_KIND,
+			target: "chat",
+			match(event) {
+				const turn = turnOf(event.data);
+				if (turn === void 0) return null;
+				const id = String(turn);
+				if (event.type === "turn/start") return {
+					id,
+					role: "start"
+				};
+				if (event.type === "tool/call") return callOf(event.data)?.name === HANDOVER_TOOL ? {
+					id,
+					role: "update"
+				} : null;
+				if (event.type === "tool/result" && callIdOf(event.data) !== void 0) return {
+					id,
+					role: "update"
+				};
+				return null;
+			},
+			start() {
+				return {
+					open: void 0,
+					anchorSeq: void 0
+				};
+			},
+			update(context, match) {
+				const event = match.event;
+				if (event.type === "tool/call") {
+					const call = callOf(event.data);
+					if (call === void 0 || call.name !== HANDOVER_TOOL) return context.state;
+					return {
+						open: {
+							callId: call.callId,
+							reason: reasonOf(call.arguments),
+							seq: event.seq
+						},
+						anchorSeq: event.seq
+					};
+				}
+				if (event.type === "tool/result") {
+					const callId = callIdOf(event.data);
+					if (context.state.open === void 0 || callId !== context.state.open.callId) return context.state;
+					return {
+						open: void 0,
+						anchorSeq: context.state.anchorSeq
+					};
+				}
+				return context.state;
+			},
+			buildViewNode(context) {
+				return buildHandoverView(context);
+			}
+		};
+		//#endregion
+		//#region src/client/client.ts
+		/**
+		* Cordis services this client reads. `dsh.client.inject` is package load
+		* order, not this list. `remote.mhBrowser` is absent until `$mount`.
+		*/
+		const inject = [
+			"slots",
+			"locale",
+			"remote",
+			"uiConversation"
+		];
+		const namespaceInject = [...inject, "remote.mhBrowser"];
+		async function apply(ctx) {
+			const unmount = await ctx.remote.$mount(TYPERT_REMOTE);
+			let release = () => void 0;
+			await ctx.inject(namespaceInject, (inner) => {
+				release = start(inner);
+			});
+			return async () => {
+				release();
+				await unmount();
+			};
+		}
+		/** Register the handover row. The tool call itself keeps the generic tool row. */
+		function start(ctx) {
+			ctx.effect(() => ctx.locale.register(NS, {
+				zh,
+				en
+			}));
+			ctx.effect(() => ctx.uiConversation.events.register(handoverRowDefinition));
+			const remote = ctx.remote.mhBrowser;
+			ctx.slots.inject("conversation.chat.node", () => ctx.slots.register({
+				name: "conversation.chat.node",
+				key: HANDOVER_KIND,
+				locale: NS
+			}, (props) => (0, react.createElement)(HandoverRow, {
+				sessionId: props.sessionId,
+				reason: props.node.data.reason,
+				t: props.t,
+				reveal: (sessionId, signal) => remote.revealHandover(sessionId, signal)
+			})));
+			return () => void 0;
+		}
+		//#endregion
+		exports.apply = apply;
+		exports.inject = inject;
+		exports.start = start;
+		return module.exports;
+	}
+});

package/lib/index.js

@@ -7,7 +7,7 @@ import { assertSupportedJsonSchema, defineTool, validateJsonSchemaValue } from "
 import { createHash, randomUUID } from "node:crypto";
 import { parse } from "yaml";
 import { constants, readFileSync } from "node:fs";
-import { lstat, mkdir, open, readFile, realpath, unlink, writeFile } from "node:fs/promises";
+import { lstat, mkdir, open, readFile, readlink, realpath, unlink, writeFile } from "node:fs/promises";
 import { z as z$1 } from "zod";
 import { Remote, TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
 import { chromium } from "playwright";
@@ -2979,6 +2979,50 @@ async function launchBrowser(options) {
 		throw error;
 	}
 }
+/**
+* Process id of the browser's main process. Playwright gives none for a
+* persistent context. Asks the browser first; on POSIX the profile's
+* `SingletonLock` link names it as `<host>-<pid>`.
+*/
+async function browserPid(context, profileDir) {
+	const browser = context.browser();
+	if (browser !== null) try {
+		const session = await browser.newBrowserCDPSession();
+		try {
+			const main = (await session.send("SystemInfo.getProcessInfo")).processInfo.find((item) => item.type === "browser");
+			if (main !== void 0 && main.id > 0) return main.id;
+		} finally {
+			await session.detach().catch(() => void 0);
+		}
+	} catch {}
+	if (process.platform === "win32") return void 0;
+	try {
+		const target = await readlink(join(profileDir, "SingletonLock"));
+		const pid = Number(target.slice(target.lastIndexOf("-") + 1));
+		return Number.isInteger(pid) && pid > 0 ? pid : void 0;
+	} catch {
+		return;
+	}
+}
+/**
+* Ask the browser to close; kill `pid` when that fails or takes longer than
+* `waitMs`, so a stuck browser does not keep the profile locked.
+*/
+async function closeOrKill(close, pid, waitMs = 1e3, kill = (target) => {
+	process.kill(target, "SIGKILL");
+}) {
+	let timer;
+	const outcome = await Promise.race([close().then(() => "closed", () => "failed"), new Promise((resolve) => {
+		timer = setTimeout(() => resolve("timeout"), waitMs);
+	})]);
+	clearTimeout(timer);
+	if (outcome === "closed") return "closed";
+	if (pid === void 0) return "stuck";
+	try {
+		kill(pid);
+	} catch {}
+	return "killed";
+}
 //#endregion
 //#region lib/types/service/control.js
 /**
@@ -4121,7 +4165,7 @@ const REPLIED = "继续";
 //#endregion
 //#region lib/types/service/extension.js
 const PACKAGE = "@mind-harness/mh-browser";
-const WORKER_MS = 5e3;
+const WORKER_MS = 15e3;
 /**
 * Directory of the unpacked extension shipped with this package.
 * Walks up from this module: sources live in `src/`, the bundle in `lib/`.
@@ -4156,6 +4200,10 @@ var Extension = class Extension {
 		const worker = await findWorker(context, loaded.id);
 		return new Extension(context, loaded.id, worker);
 	}
+	/** Address of a page shipped in the extension directory. */
+	pageUrl(name) {
+		return `chrome-extension://${this.id}/${name}`;
+	}
 	/** `chrome.tabs.create` in the named window. Returns the extension's tab id. */
 	async createTab(windowId, url) {
 		return (await this.worker()).evaluate(async (arg) => {
@@ -4231,13 +4279,21 @@ var Extension = class Extension {
 		return worker;
 	}
 };
-async function findWorker(context, id) {
-	const open = context.serviceWorkers().find((worker) => worker.url().includes(id));
+/** The extension's service worker. Looks once more after the wait times out. */
+async function findWorker(context, id, timeoutMs = WORKER_MS) {
+	const find = () => context.serviceWorkers().find((worker) => worker.url().includes(id));
+	const open = find();
 	if (open !== void 0) return open;
-	return context.waitForEvent("serviceworker", {
-		predicate: (worker) => worker.url().includes(id),
-		timeout: WORKER_MS
-	});
+	try {
+		return await context.waitForEvent("serviceworker", {
+			predicate: (worker) => worker.url().includes(id),
+			timeout: timeoutMs
+		});
+	} catch (error) {
+		const late = find();
+		if (late !== void 0) return late;
+		throw new Error(`the browser extension did not start within ${String(timeoutMs / 1e3)} s`, { cause: error });
+	}
 }
 //#endregion
 //#region lib/types/service/windows.js
@@ -4319,9 +4375,14 @@ var Windows = class {
 		this.browserSession = await browser.newBrowserCDPSession();
 		if (options.headed) this.extension = await Extension.load(context, this.browserSession);
 		const launched = context.pages().filter((page) => page.url() === "about:blank");
+		const extension = this.extension;
+		if (extension !== void 0) for (const page of launched) await page.goto(extension.pageUrl("welcome.html")).catch(() => void 0);
 		context.on("page", (page) => {
 			for (const blank of launched.splice(0)) blank.close().catch(() => void 0);
-			this.ingest(page);
+			this.ingest(page).catch((error) => {
+				if (closedTarget(error)) return;
+				throw error;
+			});
 		});
 	}
 	setPersonInput(fn) {
@@ -4865,19 +4926,29 @@ var Windows = class {
 			const known = this.byPage.get(page);
 			if (known !== void 0) this.forget(known);
 		});
-		const session = await context.newCDPSession(page);
-		this.sessions.set(page, session);
-		await session.send("Runtime.enable");
-		await session.send("Page.enable");
-		await session.send("Runtime.addBinding", {
-			name: BINDING,
-			executionContextName: WORLD
-		});
-		await session.send("Page.addScriptToEvaluateOnNewDocument", {
-			source: LISTENER,
-			worldName: WORLD,
-			runImmediately: true
-		});
+		let session;
+		try {
+			session = await context.newCDPSession(page);
+			this.sessions.set(page, session);
+			await session.send("Runtime.enable");
+			await session.send("Page.enable");
+			await session.send("Runtime.addBinding", {
+				name: BINDING,
+				executionContextName: WORLD
+			});
+			await session.send("Page.addScriptToEvaluateOnNewDocument", {
+				source: LISTENER,
+				worldName: WORLD,
+				runImmediately: true
+			});
+		} catch (error) {
+			if (closedTarget(error)) {
+				const known = this.byPage.get(page);
+				if (known !== void 0) this.forget(known);
+				else this.dropSession(page);
+			}
+			throw error;
+		}
 		session.on("Runtime.bindingCalled", () => {
 			this.report(owner, tab, page);
 		});
@@ -4921,6 +4992,11 @@ var Windows = class {
 			});
 		});
 	}
+	dropSession(page) {
+		const session = this.sessions.get(page);
+		this.sessions.delete(page);
+		session?.detach().catch(() => void 0);
+	}
 	async targetIdOf(page) {
 		const context = this.context;
 		if (context === void 0) throw new Error("browser is not running");
@@ -4938,6 +5014,10 @@ var Windows = class {
 		return (await session.send("Browser.getWindowForTarget", { targetId })).windowId;
 	}
 };
+/** Playwright's error once the page, its context, or the browser has gone. */
+function closedTarget(error) {
+	return error instanceof Error && (error.message.includes("has been closed") || error.message.includes("Target closed"));
+}
 function idleTab() {
 	return {
 		title: "",
@@ -5066,6 +5146,7 @@ let MhBrowserService = (() => {
 		windows = (__runInitializers(this, _instanceExtraInitializers), new Windows());
 		launchOptions;
 		context;
+		pids = /* @__PURE__ */ new WeakMap();
 		ready = Promise.resolve();
 		closing = false;
 		/** The browser is not running. The next call that needs a page starts it. */
@@ -5123,7 +5204,8 @@ let MhBrowserService = (() => {
 				this.agentViewOrigins.add(parsed.origin);
 			} catch {}
 		}
-		async open(owner, items, signal) {
+		async open(owner, items, signal, options) {
+			const reveal = options?.reveal === true;
 			return this.exclusive(owner, async () => {
 				await this.up(owner === PERSON_OWNER);
 				const views = [];
@@ -5135,7 +5217,7 @@ let MhBrowserService = (() => {
 						});
 						continue;
 					}
-					views.push(await this.openAddress(owner, item, signal));
+					views.push(await this.openAddress(owner, item, signal, reveal));
 				}
 				await this.enforceCap(owner);
 				return views;
@@ -5298,7 +5380,9 @@ let MhBrowserService = (() => {
 					await (this.context?.browser())?.close();
 				},
 				page: (owner, tab) => this.windows.get(owner, tab)?.page,
-				running: () => this.context !== void 0
+				running: () => this.context !== void 0,
+				pages: () => this.context?.pages() ?? [],
+				pid: () => this.context === void 0 ? void 0 : this.pids.get(this.context)
 			};
 		}
 		async act(owner, tab, op, signal) {
@@ -5503,7 +5587,7 @@ let MhBrowserService = (() => {
 		* A readable Agent View found on a tab this call opened is returned without
 		* the tab, and that tab is not listed as closed.
 		*/
-		async openAddress(owner, item, signal) {
+		async openAddress(owner, item, signal, reveal = false) {
 			if (!openableAddress(item.url)) return {
 				url: item.url,
 				reason: OPEN_ADDRESS_REASON
@@ -5517,7 +5601,7 @@ let MhBrowserService = (() => {
 				};
 				if (via !== void 0) return via;
 			}
-			const opened = await this.openOne(owner, item.url, item.waitFor, signal, item.snapshot === true);
+			const opened = await this.openOne(owner, item.url, item.waitFor, signal, item.snapshot === true, reveal);
 			this.keepAgentView(opened);
 			if (!wantsTab && opened.fresh && this.closable(owner, opened.live) && "representation" in opened.view && opened.view.representation.kind === "agent-view") {
 				await this.windows.closeTab(opened.live);
@@ -5686,12 +5770,13 @@ let MhBrowserService = (() => {
 				return body;
 			}
 		}
-		async openOne(owner, url, waitFor, signal, snapshot = false) {
+		async openOne(owner, url, waitFor, signal, snapshot = false, reveal = false) {
 			assertWaitFor(waitFor);
 			const reused = this.idleTabOn(owner, url);
 			const live = reused ?? await this.windows.openBlank(owner);
 			const fresh = reused === void 0;
 			const linked = this.control.link(owner, signal, live.id);
+			if (reveal && !linked.signal.aborted) await live.page.bringToFront().catch(() => void 0);
 			const nextDialog = this.windows.nextDialog(live);
 			try {
 				let seenDialog;
@@ -6365,6 +6450,8 @@ let MhBrowserService = (() => {
 		}
 		async start() {
 			const context = await launchBrowser(this.launchOptions);
+			const pid = await browserPid(context, this.launchOptions.profileDir);
+			if (pid !== void 0) this.pids.set(context, pid);
 			if (this.closing) {
 				await this.closeContext(context);
 				return;
@@ -6423,9 +6510,8 @@ let MhBrowserService = (() => {
 		}
 		/** Close a context the service is done with, and kill it if close stalls. */
 		async closeContext(context) {
-			const browser = context.browser();
-			await Promise.race([context.close().catch(() => void 0), new Promise((resolve) => setTimeout(resolve, 1e3))]);
-			(browser?.process?.())?.kill("SIGKILL");
+			await closeOrKill(() => context.close(), this.pids.get(context));
+			this.pids.delete(context);
 		}
 		refuseIfPerson(owner, tab) {
 			if (this.control.ofTab(owner, tab) !== "person") return;

package/lib/typert.host.js

@@ -44,7 +44,7 @@ const $remote = createTypertRemoteInfo({
         create: _mind_harness_mh_browser_mhBrowser_revealHandover_result$schema,
         jsonSchema: {"type":"object","properties":{"status":{"type":"string","enum":["revealed","not-handing-over","no-tab"]}},"required":["status"],"additionalProperties":true},
       },
-      sourceLocation: {"file":"packages/mh-browser/src/service/service.ts","line":619,"column":9},
+      sourceLocation: {"file":"packages/mh-browser/src/service/service.ts","line":624,"column":9},
     },
   },
 }, z)
@@ -75,7 +75,7 @@ export const TYPERT = {
           {
             "kind": "method",
             "name": "open",
-            "signature": "async open( owner: string, items: { url: string; waitFor?: WaitFor; snapshot?: boolean }[], signal?: AbortSignal, ): Promise<(PageView | PageError)[]>"
+            "signature": "async open( owner: string, items: { url: string; waitFor?: WaitFor; snapshot?: boolean }[], signal?: AbortSignal, options?: { reveal?: boolean }, ): Promise<(PageView | PageError)[]>"
           },
           {
             "kind": "method",
@@ -359,7 +359,7 @@ export const TYPERT = {
           },
           {
             "name": "TestHooks",
-            "declaration": "export interface TestHooks {\n    crash(): Promise<void>;\n    page(owner: string, tab: string): unknown;\n    running(): boolean;\n}"
+            "declaration": "export interface TestHooks {\n    crash(): Promise<void>;\n    page(owner: string, tab: string): unknown;\n    running(): boolean;\n    pages(): unknown[];\n    pid(): number | undefined;\n}"
           },
           {
             "name": "WaitFor",

package/lib/typert.remote-client.js

@@ -44,7 +44,7 @@ export const TYPERT_REMOTE = createTypertRemoteInfo({
         create: _mind_harness_mh_browser_mhBrowser_revealHandover_result$schema,
         jsonSchema: {"type":"object","properties":{"status":{"type":"string","enum":["revealed","not-handing-over","no-tab"]}},"required":["status"],"additionalProperties":true},
       },
-      sourceLocation: {"file":"packages/mh-browser/src/service/service.ts","line":619,"column":9},
+      sourceLocation: {"file":"packages/mh-browser/src/service/service.ts","line":624,"column":9},
     },
   },
 }, z)

package/lib/types/card.d.ts

@@ -0,0 +1,24 @@
+import { type ReactElement } from 'react';
+import { type Translate } from './locales.ts';
+export type RevealStatus = 'revealed' | 'not-handing-over' | 'no-tab';
+export type RevealResult = {
+    ok: true;
+    value: {
+        status: RevealStatus;
+    };
+} | {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+    };
+};
+export interface HandoverRowProps {
+    sessionId: string;
+    reason: string;
+    t: Translate;
+    reveal: (sessionId: string, signal: AbortSignal) => Promise<RevealResult>;
+}
+/** The open handover: the reason and the button that raises its window. */
+export declare function HandoverRow(props: HandoverRowProps): ReactElement;
+//# sourceMappingURL=card.d.ts.map

package/lib/types/client.d.ts

@@ -0,0 +1,53 @@
+import { type ReactElement } from 'react';
+import { type RevealResult } from './card.ts';
+import { type Translate } from './locales.ts';
+import { handoverRowDefinition } from './row.ts';
+/**
+ * Cordis services this client reads. `dsh.client.inject` is package load
+ * order, not this list. `remote.mhBrowser` is absent until `$mount`.
+ */
+export declare const inject: readonly ["slots", "locale", "remote", "uiConversation"];
+export interface MhBrowserRemote {
+    revealHandover(sessionId: string, signal?: AbortSignal): Promise<RevealResult>;
+}
+interface RemoteCarrier {
+    $mount(contribution: object): Promise<() => Promise<void>>;
+}
+/** Props the session-scoped chat-node seat passes in. The session id is that seat's. */
+export interface HostRowProps {
+    sessionId: string;
+    node: {
+        readonly data: {
+            readonly reason: string;
+        };
+    };
+    t: Translate;
+}
+export interface ClientHost {
+    slots: {
+        inject(name: string, register: () => unknown): unknown;
+        register(options: {
+            name: string;
+            key: string;
+            locale: string;
+        }, component: (props: HostRowProps) => ReactElement): () => void;
+    };
+    locale: {
+        register(ns: string, dicts: Record<'zh' | 'en', Record<string, string>>): () => void;
+    };
+    uiConversation: {
+        events: {
+            register(definition: typeof handoverRowDefinition): () => void;
+        };
+    };
+    effect(execute: () => () => void): unknown;
+    remote: RemoteCarrier & {
+        mhBrowser: MhBrowserRemote;
+    };
+    inject(names: readonly string[], apply: (ctx: ClientHost) => void): PromiseLike<unknown>;
+}
+export declare function apply(ctx: ClientHost): Promise<() => Promise<void>>;
+/** Register the handover row. The tool call itself keeps the generic tool row. */
+export declare function start(ctx: ClientHost): () => void;
+export {};
+//# sourceMappingURL=client.d.ts.map

package/lib/types/locales.d.ts

@@ -0,0 +1,15 @@
+/** Dictionary namespace for the handover row. */
+export declare const NS = "mh-browser";
+export declare const zh: {
+    readonly waiting: "浏览器交给你了：{reason}";
+    readonly reveal: "去浏览器";
+    readonly notHandingOver: "这次交接已经结束";
+    readonly noTab: "没有可以去的页面";
+    readonly failed: "没能切到浏览器";
+};
+export type CardKey = keyof typeof zh;
+export declare const en: Record<CardKey, string>;
+export type Translate = (key: CardKey, params?: Record<string, unknown>) => string;
+/** A translator over one dictionary, for rendering outside the host (tests). */
+export declare function translator(dict: Record<CardKey, string>): Translate;
+//# sourceMappingURL=locales.d.ts.map

package/lib/types/row.d.ts

@@ -0,0 +1,69 @@
+/**
+ * One chat row for the open `browser_handover` in a turn.
+ * `groupTree: 'turn'` stands outside the process group. A settled call keeps
+ * the same key and hides the row; a hidden row is omitted from group order.
+ */
+export declare const HANDOVER_KIND = "browser-handover";
+export interface HandoverRowData {
+    readonly reason: string;
+}
+interface OpenCall {
+    readonly callId: string;
+    readonly reason: string;
+    readonly seq: number;
+}
+export interface HandoverTurnState {
+    readonly open: OpenCall | undefined;
+    readonly anchorSeq: number | undefined;
+}
+/** A session event this row reads. Other fields are ignored. */
+export interface FoldEvent {
+    readonly type: string;
+    readonly seq: number;
+    readonly data: unknown;
+}
+export interface HandoverMatch {
+    readonly id: string;
+    readonly role: 'start' | 'update';
+}
+export interface HandoverChatNode {
+    readonly key: string;
+    readonly kind: typeof HANDOVER_KIND;
+    readonly id: string;
+    readonly target: 'chat';
+    readonly anchorSeq: number;
+    readonly location: unknown;
+    readonly visibility: 'visible' | 'hidden';
+    readonly groupTree: 'turn';
+    readonly data: HandoverRowData;
+}
+export interface HandoverNodeContext {
+    readonly key: string;
+    readonly id: string;
+    readonly state: HandoverTurnState | undefined;
+    readonly start: {
+        readonly location: unknown;
+    } | undefined;
+    readonly current: {
+        get(target: string): HandoverChatNode | null | undefined;
+    };
+}
+/**
+ * The row for one turn. Absent until a handover in that turn has been seen;
+ * hidden, with the same key, once the open call settles.
+ */
+export declare function buildHandoverView(context: HandoverNodeContext): HandoverChatNode | null;
+export declare const handoverRowDefinition: {
+    kind: string;
+    target: "chat";
+    match(event: FoldEvent): HandoverMatch | null;
+    start(): HandoverTurnState;
+    update(context: {
+        readonly state: HandoverTurnState;
+    }, match: {
+        readonly event: FoldEvent;
+    }): HandoverTurnState;
+    buildViewNode(context: HandoverNodeContext): HandoverChatNode | null;
+};
+export {};
+//# sourceMappingURL=row.d.ts.map

package/lib/types/service/browser.d.ts

@@ -20,4 +20,15 @@ export declare function chromiumSandboxEnabled(browser: BrowserName, platform?:
  * A missing browser is reported and not downloaded.
  */
 export declare function launchBrowser(options: LaunchOptions): Promise<BrowserContext>;
+/**
+ * Process id of the browser's main process. Playwright gives none for a
+ * persistent context. Asks the browser first; on POSIX the profile's
+ * `SingletonLock` link names it as `<host>-<pid>`.
+ */
+export declare function browserPid(context: BrowserContext, profileDir: string): Promise<number | undefined>;
+/**
+ * Ask the browser to close; kill `pid` when that fails or takes longer than
+ * `waitMs`, so a stuck browser does not keep the profile locked.
+ */
+export declare function closeOrKill(close: () => Promise<void>, pid: number | undefined, waitMs?: number, kill?: (target: number) => void): Promise<'closed' | 'killed' | 'stuck'>;
 //# sourceMappingURL=browser.d.ts.map

package/lib/types/service/extension.d.ts

@@ -1,4 +1,4 @@
-import type { BrowserContext, CDPSession } from 'playwright';
+import type { BrowserContext, CDPSession, Worker } from 'playwright';
 /**
  * Directory of the unpacked extension shipped with this package.
  * Walks up from this module: sources live in `src/`, the bundle in `lib/`.
@@ -14,6 +14,8 @@ export declare class Extension {
     private workerPage;
     private constructor();
     static load(context: BrowserContext, browserSession: CDPSession): Promise<Extension>;
+    /** Address of a page shipped in the extension directory. */
+    pageUrl(name: string): string;
     /** `chrome.tabs.create` in the named window. Returns the extension's tab id. */
     createTab(windowId: number, url: string): Promise<number>;
     tabIdsIn(windowId: number): Promise<number[]>;
@@ -27,4 +29,6 @@ export declare class Extension {
     ungroup(tabId: number): Promise<void>;
     private worker;
 }
+/** The extension's service worker. Looks once more after the wait times out. */
+export declare function findWorker(context: BrowserContext, id: string, timeoutMs?: number): Promise<Worker>;
 //# sourceMappingURL=extension.d.ts.map

package/lib/types/service/service.d.ts

@@ -34,6 +34,7 @@ export declare class MhBrowserService extends TypertRemoteService {
     private readonly windows;
     private readonly launchOptions;
     private context;
+    private readonly pids;
     private ready;
     private closing;
     /** The browser is not running. The next call that needs a page starts it. */
@@ -58,7 +59,9 @@ export declare class MhBrowserService extends TypertRemoteService {
         url: string;
         waitFor?: WaitFor;
         snapshot?: boolean;
-    }[], signal?: AbortSignal): Promise<(PageView | PageError)[]>;
+    }[], signal?: AbortSignal, options?: {
+        reveal?: boolean;
+    }): Promise<(PageView | PageError)[]>;
     view(owner: string, tab: string, signal?: AbortSignal): Promise<PageView | PageError>;
     /** Pages whose current representation is already in the model's presence. */
     rememberPresence(owner: string, urls: string[]): void;

package/lib/types/service/test-hooks.d.ts

@@ -5,5 +5,9 @@ export interface TestHooks {
     page(owner: string, tab: string): unknown;
     /** A browser process is up. */
     running(): boolean;
+    /** Every page of the running browser, launch page included. */
+    pages(): unknown[];
+    /** The main browser process id recorded at start. */
+    pid(): number | undefined;
 }
 //# sourceMappingURL=test-hooks.d.ts.map

package/lib/types/service/windows.d.ts

@@ -173,6 +173,7 @@ export declare class Windows {
     private arm;
     private report;
     private waitForTarget;
+    private dropSession;
     private targetIdOf;
     private windowIdOf;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mind-harness/mh-browser",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Opens pages in a real browser for the agent, keeps chosen Agent Views in context, and hands the browser to you when a person is needed.",
   "license": "SEE LICENSE IN LICENSE",
   "files": [
@@ -11,9 +11,11 @@
     "lib/typert.host.d.ts",
     "lib/typert.remote-client.js",
     "lib/typert.remote-client.d.ts",
+    "lib/client.cjs",
     "locale/*.json",
     "icon.svg",
-    "extension/*"
+    "extension/*",
+    "THIRD-PARTY-NOTICES"
   ],
   "type": "module",
   "main": "./lib/index.js",
@@ -35,6 +37,10 @@
       "types": "./lib/typert.remote-client.d.ts",
       "default": "./lib/typert.remote-client.js"
     },
+    "./client": {
+      "types": "./lib/types/client.d.ts",
+      "default": "./lib/client.cjs"
+    },
     "./package.json": "./package.json",
     "./locale/*.json": "./locale/*.json",
     "./icon": "./icon.svg"
@@ -63,7 +69,11 @@
     "@deepseek-ai/dsh-tools": "^0.2.2-rc.1",
     "@deepseek-ai/dsh-typert-protocol": "^0.2.2-rc.1",
     "@deepseek-ai/dsh-user-questions": "^0.2.2-rc.1",
-    "@deepseek-ai/schemastery": "~3.19.0"
+    "@deepseek-ai/schemastery": "~3.19.0",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.1.0",
@@ -72,12 +82,22 @@
     "@deepseek-ai/dsh-tools": ">=0.2.2-rc.1 <0.2.3-0",
     "@deepseek-ai/dsh-typert-protocol": ">=0.2.2-rc.1 <0.2.3-0",
     "@deepseek-ai/dsh-user-questions": ">=0.2.2-rc.1 <0.2.3-0",
-    "@deepseek-ai/schemastery": "^3.19.0"
+    "@deepseek-ai/schemastery": "^3.19.0",
+    "react": "^19.2.8"
   },
   "icon": "./icon.svg",
   "engines": {
     "dsh": ">=0.2.2-rc.1 <0.2.3-0"
   },
+  "dsh": {
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-conversation"
+      ]
+    }
+  },
   "scripts": {
     "version": "node ../../scripts/mh/sync-extension-version.ts"
   }