@mind-harness/mh-browser 0.2.0 → 0.2.1

package/extension/manifest.json

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

package/lib/index.js

@@ -447,7 +447,6 @@ function formatSeconds(seconds) {
 }
 //#endregion
 //#region lib/types/types.js
-/** Public browser types. Playwright types stay inside the service. */
 var MhBrowserError = class extends Error {
 	code;
 	page;
@@ -479,10 +478,12 @@ function unknownTab() {
 //#region lib/types/tools/session.js
 /** dsh shows the model only the message, so the message starts with the code. */
 var BrowserToolError = class extends HarnessError {
+	code;
 	reason;
 	constructor(code, reason) {
 		super(`${code}: ${reason}`, code);
 		this.name = "BrowserToolError";
+		this.code = code;
 		this.reason = reason;
 	}
 };
@@ -1063,7 +1064,7 @@ const IMAGE_VALUE = {
 const TAB$1 = "Tab id copied from the latest result in this session: a tabs list, or a page element's tab attribute. Omit it to use the tab of that latest result; if it has no tab, the call fails with INVALID_ARGS. An idle tab may be closed, and a closed id fails with UNKNOWN_TAB: open the address again with browser_open. A tab with unsubmitted input is marked in use and is not closed, and opening or a declared action does not reload it. Tabs are gone after a restart. A page with an Agent View has no tab until you open it with snapshot.";
 const TARGET = "A ref copied from this tab's latest snapshot, such as e3, or a selector that matches one element. A ref that is not in the current snapshot fails with STALE_REF.";
 const ELEMENT = "What the person sees in the log. It does not locate the element.";
-const FILENAME = "A path inside the workspace. The result is saved there and the reply is the path and the byte count. Omit it and the result stays in the reply.";
+const FILENAME = "A path inside the workspace. The result is saved there and the reply is the path and the byte count. A file already at that path is replaced. Omit it and the result stays in the reply.";
 const OUTPUT = {
 	schema: {
 		type: "object",
@@ -2961,6 +2962,7 @@ async function launchBrowser(options) {
 			acceptDownloads: true,
 			chromiumSandbox: chromiumSandboxEnabled(options.browser),
 			...options.headless ? {} : {
+				viewport: null,
 				ignoreDefaultArgs: ["--disable-extensions"],
 				args: ["--enable-unsafe-extension-debugging", "--keep-alive-for-test"]
 			},
@@ -4096,6 +4098,16 @@ function watchDialog(page) {
 	};
 }
 //#endregion
+//#region lib/types/words.js
+/** Shown on a session's tab group while a handover is waiting. */
+const WAITING_TITLE = "等你：";
+/** The question on the handover card. `reason` is the sentence the model gave. */
+function handoverQuestion(reason) {
+	return `浏览器交给你了：${reason}`;
+}
+/** The option that hands the browser back. */
+const HAND_BACK = "交回";
+//#endregion
 //#region lib/types/service/extension.js
 const PACKAGE = "@mind-harness/mh-browser";
 const WORKER_MS = 5e3;
@@ -4760,7 +4772,7 @@ var Windows = class {
 		if (extension === void 0 || groupId === void 0) return;
 		const title = this.titles.get(owner) ?? "";
 		const waiting = this.waiting.has(owner);
-		await extension.styleGroup(groupId, waiting ? `等你：${title}` : title, waiting ? "red" : "blue");
+		await extension.styleGroup(groupId, waiting ? `${WAITING_TITLE}${title}` : title, waiting ? "red" : "blue");
 	}
 	async ingest(page) {
 		if (this.byPage.has(page)) return;
@@ -4997,6 +5009,9 @@ const DOWNLOAD_EVENT_MS = 3e3;
 /** More exits than this within the window and the browser is not started again until one ages out. */
 const RELAUNCH_LIMIT = 3;
 const RELAUNCH_WINDOW_MS = 6e4;
+/** Agent Views remembered for a later conditional read. Older ones are read again in full. */
+const DOCUMENT_CAP = 64;
+const OPEN_ADDRESS_REASON = "only http and https addresses are opened";
 const STOP_WAIT_MS = 5e3;
 const WAITING_STOPPED = "stopped while waiting";
 const STOPPED = Symbol("stopped");
@@ -5040,10 +5055,10 @@ let MhBrowserService = (() => {
 		windows = (__runInitializers(this, _instanceExtraInitializers), new Windows());
 		launchOptions;
 		context;
-		ready;
+		ready = Promise.resolve();
 		closing = false;
-		/** The browser exited. The next call that needs a page starts it again. */
-		exited = false;
+		/** The browser is not running. The next call that needs a page starts it. */
+		exited = true;
 		exits = [];
 		/** One queue per owner: a slow wait in one Session does not hold up another. */
 		queues = /* @__PURE__ */ new Map();
@@ -5073,7 +5088,7 @@ let MhBrowserService = (() => {
 			this.windows.onTabClosed((tab) => {
 				this.shown.delete(tab.id);
 			});
-			this.ready = this.launch();
+			this.up().catch(() => void 0);
 			ctx.on("session/disposed", (session) => {
 				const owner = session.id;
 				if (owner === void 0) return;
@@ -5478,6 +5493,10 @@ let MhBrowserService = (() => {
 		* the tab, and that tab is not listed as closed.
 		*/
 		async openAddress(owner, item, signal) {
+			if (!openableAddress(item.url)) return {
+				url: item.url,
+				reason: OPEN_ADDRESS_REASON
+			};
 			const wantsTab = owner === "person" || item.snapshot === true || item.waitFor !== void 0;
 			if (!wantsTab && this.knownOrigin(item.url)) {
 				const via = await this.readKnown(owner, item.url, signal);
@@ -5520,7 +5539,7 @@ let MhBrowserService = (() => {
 			if (!(representation.kind === "agent-view" || representation.kind === "snapshot" && representation.agentView !== void 0)) return;
 			this.rememberOrigin(opened.view.url);
 			const shown = this.shown.get(opened.live.id);
-			if (shown?.kind === "agent-view") this.documents.set(canonical(shown.pageUrl), shown);
+			if (shown?.kind === "agent-view") this.rememberDocument(shown.pageUrl, shown);
 		}
 		/**
 		* Read a known origin without a tab. `undefined` means this page has to be
@@ -5564,10 +5583,21 @@ let MhBrowserService = (() => {
 			});
 			if (stopped(signal)) return STOPPED;
 			if (shown.kind !== "agent-view") return void 0;
-			this.documents.set(pageUrl, shown);
+			this.rememberDocument(pageUrl, shown);
 			this.rememberOrigin(pageUrl);
 			return this.pageOfShown(owner, shown);
 		}
+		/** Keep the newest Agent Views. A dropped one is read in full the next time. */
+		rememberDocument(url, shown) {
+			const key = canonical(url);
+			this.documents.delete(key);
+			this.documents.set(key, shown);
+			while (this.documents.size > DOCUMENT_CAP) {
+				const oldest = this.documents.keys().next().value;
+				if (oldest === void 0) return;
+				this.documents.delete(oldest);
+			}
+		}
 		/** One page from a document, with no tab. */
 		pageOfShown(owner, shown) {
 			const view = {
@@ -6040,7 +6070,10 @@ let MhBrowserService = (() => {
 			});
 		}
 		async aria(tab) {
-			return tab.page.ariaSnapshot({ mode: "ai" }).catch(() => "");
+			return tab.page.ariaSnapshot({ mode: "ai" }).catch((error) => {
+				this.ctx.logger.debug("aria snapshot failed: %s", errorText(error));
+				return "";
+			});
 		}
 		async pageFromShown(tab, shown, extra) {
 			const current = shown ?? {
@@ -6050,7 +6083,10 @@ let MhBrowserService = (() => {
 				text: "",
 				snapshot: ""
 			};
-			const title = tab.dialogHeld ? "" : await tab.page.title().catch(() => "");
+			const title = tab.dialogHeld ? "" : await tab.page.title().catch((error) => {
+				this.ctx.logger.debug("page title failed: %s", errorText(error));
+				return "";
+			});
 			this.windows.noteTitle(tab, title);
 			const view = {
 				tab: tab.id,
@@ -6215,8 +6251,9 @@ let MhBrowserService = (() => {
 					...location === void 0 || location === "" ? {} : { location },
 					...mediaType === void 0 ? {} : { mediaType }
 				};
-			} catch {
+			} catch (error) {
 				if (signal?.aborted === true) throw new MhBrowserError(INTERRUPTED, "stopped after sending; it may have taken effect");
+				this.ctx.logger.debug("declared action was not answered: %s", errorText(error));
 				return { kind: "lost" };
 			}
 		}
@@ -6318,11 +6355,18 @@ let MhBrowserService = (() => {
 		async start() {
 			const context = await launchBrowser(this.launchOptions);
 			if (this.closing) {
-				await context.close().catch(() => void 0);
+				await this.closeContext(context);
 				return;
 			}
 			this.context = context;
-			await this.windows.attach(context, this.launchOptions.profileDir, { headed: !this.launchOptions.headless });
+			try {
+				await this.windows.attach(context, this.launchOptions.profileDir, { headed: !this.launchOptions.headless });
+			} catch (error) {
+				this.context = void 0;
+				this.windows.dropPages();
+				await this.closeContext(context);
+				throw error;
+			}
 			context.browser()?.on("disconnected", () => {
 				if (this.closing || this.context !== context) return;
 				this.onExit();
@@ -6338,22 +6382,23 @@ let MhBrowserService = (() => {
 			this.ready = Promise.resolve();
 		}
 		/**
-		* The browser for a call that needs a page. One that exited starts again
-		* here. The exit limit stops unattended restarts; a person's request is
-		* one start per click and skips it.
+		* The browser for a call that needs a page. One that is not running starts
+		* again here. The exit limit stops unattended restarts; a person's request
+		* is one start per click and skips it.
 		*/
 		up(byPerson = false) {
 			if (!this.exited || this.closing) return this.ready;
 			const now = Date.now();
 			while (this.exits.length > 0 && now - (this.exits[0] ?? now) > RELAUNCH_WINDOW_MS) this.exits.shift();
 			if (!byPerson && this.exits.length > RELAUNCH_LIMIT) {
-				this.ctx.logger.warn("browser keeps exiting; not starting it again yet");
-				return Promise.reject(new MhBrowserError(BROWSER_UNAVAILABLE, `the browser exited ${String(this.exits.length)} times within ${String(RELAUNCH_WINDOW_MS / 1e3)} s; try again in a minute`));
+				this.ctx.logger.warn("browser keeps stopping; not starting it again yet");
+				return Promise.reject(new MhBrowserError(BROWSER_UNAVAILABLE, `the browser stopped or did not start ${String(this.exits.length)} times within ${String(RELAUNCH_WINDOW_MS / 1e3)} s; try again in a minute`));
 			}
 			this.exited = false;
 			const started = this.launch();
 			started.then(() => this.windows.resumePersonInput(), () => {
 				this.exited = true;
+				if (!this.closing) this.exits.push(Date.now());
 			});
 			this.ready = started;
 			return started;
@@ -6361,10 +6406,15 @@ let MhBrowserService = (() => {
 		async stop() {
 			this.windows.suppressPersonInput();
 			await Promise.race([this.ready.catch(() => void 0), new Promise((resolve) => setTimeout(resolve, STOP_WAIT_MS))]);
-			const browser = this.context?.browser();
-			await Promise.race([this.context?.close().catch(() => void 0), new Promise((resolve) => setTimeout(resolve, 1e3))]);
-			(browser?.process?.())?.kill("SIGKILL");
+			const context = this.context;
 			this.context = void 0;
+			if (context !== void 0) await this.closeContext(context);
+		}
+		/** 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");
 		}
 		refuseIfPerson(owner, tab) {
 			if (this.control.ofTab(owner, tab) !== "person") return;
@@ -6521,6 +6571,18 @@ function requiresOf(text, pageUrl) {
 	const read = readAgentView(text, pageUrl);
 	return read.ok ? read.doc.requires : [];
 }
+function openableAddress(url) {
+	if (url === "about:blank") return true;
+	try {
+		const protocol = new URL(url).protocol;
+		return protocol === "http:" || protocol === "https:";
+	} catch {
+		return false;
+	}
+}
+function errorText(error) {
+	return error instanceof Error ? error.message : String(error);
+}
 function canonical(url) {
 	try {
 		const parsed = new URL(url);
@@ -6760,8 +6822,8 @@ async function askUntilAnswered(ctx, reason, exec) {
 		return await Promise.race([ctx.userQuestions.ask({
 			questions: [{
 				id: "handback",
-				question: `浏览器交给你了：${reason}`,
-				options: [{ label: "交回" }]
+				question: handoverQuestion(reason),
+				options: [{ label: HAND_BACK }]
 			}],
 			...exec.agent !== void 0 ? { agent: exec.agent } : {},
 			signal: exec.signal
@@ -6921,7 +6983,7 @@ const OPEN = [
 	"A page lists documents in requires; those are not fetched with it, so open their addresses to read them or to call their actions."
 ].join(" ");
 const PAGES = "The pages to read, 1 to 8, each returned in order as its own element.";
-const URL$1 = "The address to read: from a page shown to you, from the principal, or one you composed; opening a composed address is how it is checked before you use it elsewhere.";
+const URL$1 = "The address to read: from a page shown to you, from the principal, or one you composed; opening a composed address is how it is checked before you use it elsewhere. Only an http or https address is opened.";
 const WAIT = "Optional wait after the document loads for text to appear or disappear, or for time seconds; at least one must be set. If not met, the page is still returned and waited says so.";
 const SNAPSHOT = "Ask for the human page: open a tab and return its snapshot, for page operations and handover. A page without an Agent View already does.";
 function browserOpenTool(ctx, reader) {

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":616,"column":9},
+      sourceLocation: {"file":"packages/mh-browser/src/service/service.ts","line":619,"column":9},
     },
   },
 }, z)

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":616,"column":9},
+      sourceLocation: {"file":"packages/mh-browser/src/service/service.ts","line":619,"column":9},
     },
   },
 }, z)

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

@@ -36,7 +36,7 @@ export declare class MhBrowserService extends TypertRemoteService {
     private context;
     private ready;
     private closing;
-    /** The browser exited. The next call that needs a page starts it again. */
+    /** The browser is not running. The next call that needs a page starts it. */
     private exited;
     private readonly exits;
     /** One queue per owner: a slow wait in one Session does not hold up another. */
@@ -170,6 +170,8 @@ export declare class MhBrowserService extends TypertRemoteService {
      * ends the read without falling back to a tab.
      */
     private readKnown;
+    /** Keep the newest Agent Views. A dropped one is read in full the next time. */
+    private rememberDocument;
     /** One page from a document, with no tab. */
     private pageOfShown;
     /**
@@ -225,12 +227,14 @@ export declare class MhBrowserService extends TypertRemoteService {
     /** No window opens on exit: the person may have quit it. Calls on old tabs find none. */
     private onExit;
     /**
-     * The browser for a call that needs a page. One that exited starts again
-     * here. The exit limit stops unattended restarts; a person's request is
-     * one start per click and skips it.
+     * The browser for a call that needs a page. One that is not running starts
+     * again here. The exit limit stops unattended restarts; a person's request
+     * is one start per click and skips it.
      */
     private up;
     private stop;
+    /** Close a context the service is done with, and kill it if close stalls. */
+    private closeContext;
     private refuseIfPerson;
     private takenOver;
     private presenceUrls;

package/lib/types/tools/session.d.ts

@@ -3,10 +3,12 @@ import { HarnessError } from '@deepseek-ai/dsh-llm';
 import type { Session } from '@deepseek-ai/dsh-session';
 import type { ToolRunContext } from '@deepseek-ai/dsh-tools';
 import type { WriteTarget } from '../service/service.ts';
+import { type BrowserCode } from '../types.ts';
 /** dsh shows the model only the message, so the message starts with the code. */
 export declare class BrowserToolError extends HarnessError {
+    readonly code: BrowserCode;
     readonly reason: string;
-    constructor(code: string, reason: string);
+    constructor(code: BrowserCode, reason: string);
 }
 export declare const NO_WORKSPACE_REASON = "this session has no working directory";
 export interface ToolSession {

package/lib/types/types.d.ts

@@ -175,22 +175,25 @@ export interface TabInfo {
     inPresence: boolean;
     mayHaveChanged: boolean;
 }
+/** Every code this package reports. The values are the model-facing contract. */
+export declare const BROWSER_CODES: readonly ["AUTHORITY_MISMATCH", "BROWSER_UNAVAILABLE", "INTERRUPTED", "INVALID_ARGS", "INVALID_INPUT", "ITEM_REFUSED", "MODAL_STATE", "NO_SESSION", "NO_WORKSPACE", "NOT_DECLARED", "NOT_DELIVERED", "OUTSIDE_WORKSPACE", "PERSON_IN_CONTROL", "SANDBOX_DENIED", "STALE_REF", "TAKEN_OVER", "UNKNOWN_TAB"];
+export type BrowserCode = (typeof BROWSER_CODES)[number];
 export declare class MhBrowserError extends Error {
-    readonly code: string;
+    readonly code: BrowserCode;
     readonly page?: PageView;
-    constructor(code: string, message: string, page?: PageView);
+    constructor(code: BrowserCode, message: string, page?: PageView);
 }
 /** Owner of the person's own window. It belongs to no Session. */
 export declare const PERSON_OWNER = "person";
-export declare const UNKNOWN_TAB = "UNKNOWN_TAB";
+export declare const UNKNOWN_TAB: BrowserCode;
 export declare const UNKNOWN_TAB_REASON = "no such tab in this session";
 /**
  * Internal: a wait ended because its signal aborted. A tool never reports it:
  * a stopped call ends as the tool runtime's abort, a takeover as `TAKEN_OVER`.
  */
-export declare const INTERRUPTED = "INTERRUPTED";
+export declare const INTERRUPTED: BrowserCode;
 /** The browser did not start or could not be restarted. */
-export declare const BROWSER_UNAVAILABLE = "BROWSER_UNAVAILABLE";
+export declare const BROWSER_UNAVAILABLE: BrowserCode;
 export declare function unknownTab(): PageError;
 export type Download = {
     kind: 'saved';

package/lib/types/words.d.ts

@@ -0,0 +1,7 @@
+/** Shown on a session's tab group while a handover is waiting. */
+export declare const WAITING_TITLE = "\u7B49\u4F60\uFF1A";
+/** The question on the handover card. `reason` is the sentence the model gave. */
+export declare function handoverQuestion(reason: string): string;
+/** The option that hands the browser back. */
+export declare const HAND_BACK = "\u4EA4\u56DE";
+//# sourceMappingURL=words.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mind-harness/mh-browser",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "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": [