@mind-harness/mh-browser 0.2.5 → 0.2.6

package/lib/index.js

@@ -1,4 +1,4 @@
-import { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
+import { basename, dirname, extname, isAbsolute, join, posix, relative, resolve, win32 } from "node:path";
 import z from "@deepseek-ai/schemastery";
 import { resolveDshHome } from "@deepseek-ai/dsh-home-paths";
 import { isDeepStrictEqual } from "node:util";
@@ -6,11 +6,13 @@ import { HarnessError, createUserMessage } from "@deepseek-ai/dsh-llm";
 import { assertSupportedJsonSchema, defineTool, validateJsonSchemaValue } from "@deepseek-ai/dsh-tools";
 import { createHash, randomUUID } from "node:crypto";
 import { parse } from "yaml";
-import { constants, readFileSync } from "node:fs";
+import { accessSync, constants, readFileSync, realpathSync, statSync } from "node:fs";
 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";
+import { execFile } from "node:child_process";
+import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { UserQuestionError } from "@deepseek-ai/dsh-user-questions";
 //#region lib/types/config.js
@@ -20,7 +22,8 @@ const browserConfig = z.object({
 		"chrome",
 		"msedge",
 		"chromium"
-	]).default("chrome").description("Which installed browser to drive. chromium is the one Playwright downloads."),
+	]).default("chrome").volatile().description("Which browser to drive. chromium is the one Playwright downloads. A new value restarts the browser once it is idle."),
+	executablePath: z.string().volatile().description("Absolute path of the browser executable. `~` is expanded. Leave empty to locate one. A new value restarts the browser once it is idle."),
 	profileDir: z.string().description("Browser profile directory, kept between runs. Defaults to mh/profiles/<dsh profile>/browser under the dsh home."),
 	headless: z.boolean().default(false).description("Run the browser without a window.")
 });
@@ -3069,16 +3072,267 @@ function sameOrigin$1(left, right) {
 	}
 }
 //#endregion
-//#region lib/types/service/browser.js
-const MISSING = {
-	chrome: "Google Chrome not found; install it, or change `browser` in the configuration",
-	msedge: "Microsoft Edge not found; install it, or change `browser` in the configuration",
-	chromium: "Playwright's Chromium not found; install it, or change `browser` in the configuration"
+//#region lib/types/service/locate.js
+const MAC_APP = {
+	chrome: [
+		"Google Chrome.app",
+		"Contents",
+		"MacOS",
+		"Google Chrome"
+	],
+	msedge: [
+		"Microsoft Edge.app",
+		"Contents",
+		"MacOS",
+		"Microsoft Edge"
+	]
+};
+const LINUX_PATH = {
+	chrome: "/opt/google/chrome/chrome",
+	msedge: "/opt/microsoft/msedge/msedge"
+};
+const WIN_SUFFIX = {
+	chrome: "Google\\Chrome\\Application\\chrome.exe",
+	msedge: "Microsoft\\Edge\\Application\\msedge.exe"
+};
+const MAC_BUNDLE = {
+	chrome: {
+		id: "com.google.Chrome",
+		binary: "Google Chrome"
+	},
+	msedge: {
+		id: "com.microsoft.edgemac",
+		binary: "Microsoft Edge"
+	}
+};
+const LINUX_NAMES = {
+	chrome: ["google-chrome-stable", "google-chrome"],
+	msedge: ["microsoft-edge-stable", "microsoft-edge"]
+};
+const WIN_EXE = {
+	chrome: "chrome.exe",
+	msedge: "msedge.exe"
 };
-function missingExecutable(error) {
-	const message = error instanceof Error ? error.message : String(error);
-	return /ENOENT|doesn.t exist|Executable doesn't exist|not found/i.test(message);
+const TITLE = {
+	chrome: "Google Chrome",
+	msedge: "Microsoft Edge"
+};
+const DISCOVER_MS = 2e3;
+/** The fixed paths checked for `browser` on `env`, in the order they are tried. */
+function candidatePaths(browser, env) {
+	if (env.platform === "darwin") return ["/Applications", posix.join(env.home, "Applications")].map((root) => posix.join(root, ...MAC_APP[browser]));
+	if (env.platform === "linux") return [LINUX_PATH[browser]];
+	if (env.platform !== "win32") return [];
+	const drive = env.env.HOMEDRIVE;
+	const roots = [
+		env.env.LOCALAPPDATA,
+		env.env.PROGRAMFILES,
+		env.env["PROGRAMFILES(X86)"],
+		typeof drive === "string" && drive !== "" ? `${drive}\\Program Files` : void 0,
+		typeof drive === "string" && drive !== "" ? `${drive}\\Program Files (x86)` : void 0
+	];
+	const suffix = WIN_SUFFIX[browser];
+	const paths = [];
+	for (const root of roots) {
+		if (root === void 0 || root === "") continue;
+		paths.push(win32.join(root, suffix));
+	}
+	return paths;
+}
+/**
+* `configured` is used as given: a path that cannot be run is a failure, and
+* nothing else is searched. `~` expands to `env.home`.
+*/
+function checkConfigured(configured, env) {
+	const path = expandHome(configured, env.home, env.platform);
+	if (!(env.platform === "win32" ? win32 : posix).isAbsolute(path)) return {
+		ok: false,
+		path,
+		code: "not-absolute"
+	};
+	const access = env.access(path);
+	if (access !== "ok") return {
+		ok: false,
+		path,
+		code: access.code
+	};
+	return {
+		ok: true,
+		path
+	};
+}
+/** Failure for a path the configuration names. */
+function configuredPathError(path, code) {
+	if (code === "not-absolute") return /* @__PURE__ */ new Error(`The configured browser path must be absolute: ${path}`);
+	return /* @__PURE__ */ new Error(`The configured browser path cannot be run (${code}): ${path}`);
+}
+/** Failure listing every path that was tried. */
+function browserNotFoundError(browser, missing) {
+	const tried = missing.map((item) => `${item.path} (${item.reason})`).join("; ");
+	const detail = tried === "" ? "" : ` Tried: ${tried}.`;
+	return /* @__PURE__ */ new Error(`${TITLE[browser]} not found.${detail} Install it, or set the browser's path in the configuration.`);
+}
+/**
+* The path to launch. A configured path is checked and never replaced.
+* `chromium` without one returns undefined, so Playwright uses its own build.
+* An installed browser that cannot be found throws.
+*/
+async function resolveExecutable(browser, configured, env, signal) {
+	if (configured !== void 0 && configured !== "") {
+		const checked = checkConfigured(configured, env);
+		if (!checked.ok) throw configuredPathError(checked.path, checked.code);
+		return checked.path;
+	}
+	if (browser === "chromium") return void 0;
+	const located = await locateInstalled(browser, env, signal);
+	if ("found" in located) return located.found;
+	throw browserNotFoundError(browser, located.missing);
+}
+/**
+* Where `browser` is installed when the configuration names no path.
+* Fixed candidates first, then `env.discover`.
+*/
+async function locateInstalled(browser, env, signal) {
+	const missing = [];
+	const seen = /* @__PURE__ */ new Set();
+	const visit = (path) => {
+		if (seen.has(path)) return void 0;
+		seen.add(path);
+		const access = env.access(path);
+		if (access === "ok") return path;
+		missing.push({
+			path,
+			reason: reasonForCode(access.code)
+		});
+	};
+	for (const path of candidatePaths(browser, env)) {
+		const found = visit(path);
+		if (found !== void 0) return { found };
+	}
+	if (signal?.aborted === true) return { missing };
+	for (const path of await env.discover(browser, signal)) {
+		const found = visit(path);
+		if (found !== void 0) return { found };
+	}
+	return { missing };
+}
+/** `path` is Playwright's Chromium. Missing or not executable is `missing`. */
+function locateBundled(path, access) {
+	const result = access(path);
+	if (result === "ok") return { found: path };
+	return { missing: [{
+		path,
+		reason: reasonForCode(result.code)
+	}] };
+}
+/** This machine: fixed paths, then Spotlight, App Paths, or `PATH`. */
+function hostLocateEnv() {
+	const env = {
+		platform: process.platform,
+		env: process.env,
+		home: homedir(),
+		access: accessFile,
+		discover: (browser, signal) => discoverInstalled(browser, env, signal)
+	};
+	return env;
+}
+/** A `.app` bundle path reported by Spotlight, turned into its executable. */
+function executableInApp(reported, binary) {
+	const at = reported.indexOf(".app");
+	if (at < 0) return void 0;
+	return posix.join(reported.slice(0, at + 4), "Contents", "MacOS", binary);
+}
+/** The default value from `reg query ... /ve` output. */
+function regValue(stdout) {
+	for (const line of stdout.split(/\r?\n/)) {
+		const value = /\bREG_(?:EXPAND_)?SZ\s+(\S.*?)\s*$/.exec(line)?.[1]?.trim();
+		if (value !== void 0 && value !== "") return value;
+	}
+}
+/** Text for an errno from {@link LocateEnv.access}. */
+function reasonForCode(code) {
+	if (code === "ENOENT" || code === "ENOTDIR") return "does not exist";
+	if (code === "EISDIR") return "is a directory";
+	return `permission denied: ${code}`;
+}
+function expandHome(configured, home, platform) {
+	const slash = platform === "win32" ? win32 : posix;
+	if (configured === "~") return home;
+	if (configured.startsWith("~/") || configured.startsWith("~\\")) return slash.join(home, configured.slice(2));
+	return configured;
+}
+function accessFile(path) {
+	try {
+		if (statSync(path).isDirectory()) return { code: "EISDIR" };
+		accessSync(path, constants.X_OK);
+		return "ok";
+	} catch (error) {
+		return { code: error !== null && typeof error === "object" && "code" in error && typeof error.code === "string" ? error.code : "EACCES" };
+	}
+}
+async function discoverInstalled(browser, env, signal) {
+	try {
+		if (env.platform === "darwin") return await discoverMac(browser, signal);
+		if (env.platform === "win32") return await discoverWindows(browser, signal);
+		if (env.platform === "linux") return discoverLinux(browser, env);
+	} catch {}
+	return [];
+}
+async function discoverMac(browser, signal) {
+	const bundle = MAC_BUNDLE[browser];
+	const stdout = await command("mdfind", [`kMDItemCFBundleIdentifier == '${bundle.id}'`], signal);
+	const found = [];
+	for (const line of stdout.split(/\r?\n/)) {
+		const trimmed = line.trim();
+		if (trimmed === "") continue;
+		const executable = executableInApp(trimmed, bundle.binary);
+		if (executable !== void 0) found.push(executable);
+	}
+	return found;
+}
+async function discoverWindows(browser, signal) {
+	const exe = WIN_EXE[browser];
+	const found = [];
+	for (const hive of ["HKCU", "HKLM"]) {
+		const value = regValue(await command("reg", [
+			"query",
+			`${hive}\\Software\\Microsoft\\Windows\\CurrentVersion\\App Paths\\${exe}`,
+			"/ve"
+		], signal));
+		if (value !== void 0) found.push(value);
+	}
+	return found;
+}
+function discoverLinux(browser, env) {
+	const entries = (env.env.PATH ?? "").split(posix.delimiter);
+	const found = [];
+	for (const name of LINUX_NAMES[browser]) for (const dir of entries) {
+		if (dir === "") continue;
+		const candidate = posix.join(dir, name);
+		if (env.access(candidate) !== "ok") continue;
+		try {
+			found.push(realpathSync(candidate));
+		} catch {
+			found.push(candidate);
+		}
+	}
+	return found;
+}
+function command(file, args, signal) {
+	if (signal?.aborted === true) return Promise.resolve("");
+	const timer = AbortSignal.timeout(DISCOVER_MS);
+	const stop = signal === void 0 ? timer : AbortSignal.any([signal, timer]);
+	return new Promise((resolve) => {
+		execFile(file, args, {
+			windowsHide: true,
+			signal: stop
+		}, (error, stdout) => {
+			resolve(error ? "" : String(stdout));
+		});
+	});
 }
+//#endregion
+//#region lib/types/service/browser.js
 /**
 * Playwright appends `--no-sandbox` unless this is true, and branded Chrome
 * then warns that stability and security will suffer. An installed browser
@@ -3089,34 +3343,45 @@ function chromiumSandboxEnabled(browser, platform = process.platform) {
 	return platform !== "linux" || browser !== "chromium";
 }
 /**
-* One persistent context for the whole process. `chromium` omits `channel`
-* so Playwright uses its own browser; the others use a local install.
-* A missing browser is reported and not downloaded.
+* One persistent context for the whole process. An installed browser is located
+* here and passed as `executablePath`; `channel` names which install that was.
+* `chromium` omits `channel` so Playwright uses its own browser unless a path
+* is configured. A missing browser is reported and not downloaded. A launch
+* that fails after the executable was found is reported as Playwright said.
 */
-async function launchBrowser(options) {
+async function launchBrowser(options, env = hostLocateEnv()) {
 	await mkdir(options.profileDir, { recursive: true });
+	const executablePath = await resolveExecutable(options.browser, options.executablePath, env);
+	return chromium.launchPersistentContext(options.profileDir, {
+		headless: options.headless,
+		acceptDownloads: true,
+		chromiumSandbox: chromiumSandboxEnabled(options.browser),
+		...options.headless ? {} : {
+			viewport: null,
+			ignoreDefaultArgs: ["--disable-extensions"],
+			args: [
+				"--enable-unsafe-extension-debugging",
+				"--keep-alive-for-test",
+				"--disable-blink-features=AutomationControlled",
+				"--test-type"
+			]
+		},
+		...options.browser === "chromium" ? {} : { channel: options.browser },
+		...executablePath !== void 0 ? { executablePath } : {}
+	});
+}
+/** Playwright's own Chromium, or why that file cannot be run. */
+function bundledChromiumLocation(access) {
+	let path;
 	try {
-		return await chromium.launchPersistentContext(options.profileDir, {
-			headless: options.headless,
-			acceptDownloads: true,
-			chromiumSandbox: chromiumSandboxEnabled(options.browser),
-			...options.headless ? {} : {
-				viewport: null,
-				ignoreDefaultArgs: ["--disable-extensions"],
-				args: [
-					"--enable-unsafe-extension-debugging",
-					"--keep-alive-for-test",
-					"--disable-blink-features=AutomationControlled",
-					"--test-type"
-				]
-			},
-			...options.browser === "chromium" ? {} : { channel: options.browser },
-			...options.executablePath !== void 0 ? { executablePath: options.executablePath } : {}
-		});
+		path = chromium.executablePath();
 	} catch (error) {
-		if (missingExecutable(error) || options.executablePath !== void 0) throw new Error(MISSING[options.browser]);
-		throw error;
+		return { missing: [{
+			path: "chromium",
+			reason: error instanceof Error ? error.message : "does not exist"
+		}] };
 	}
+	return locateBundled(path, access);
 }
 /**
 * Process id of the browser's main process. Playwright gives none for a
@@ -3179,6 +3444,15 @@ var Control = class {
 	tabs = /* @__PURE__ */ new Map();
 	since = /* @__PURE__ */ new Map();
 	named = /* @__PURE__ */ new Map();
+	/**
+	* A handover is waiting, or the person holds a tab. The browser is not
+	* restarted out from under either.
+	*/
+	busy() {
+		if (this.holding.size > 0) return true;
+		for (const who of this.who.values()) if (who === "person") return true;
+		return false;
+	}
 	/** Whether the person holds any tab, or a handover is waiting. */
 	of(owner) {
 		return this.who.get(owner) ?? "model";
@@ -5318,11 +5592,24 @@ const NO_WORKSPACE_REASON = "this session has no working directory";
 let MhBrowserService = (() => {
 	let _classSuper = TypertRemoteService;
 	let _instanceExtraInitializers = [];
+	let _locateFor_decorators;
 	let _revealHandover_decorators;
 	return class MhBrowserService extends _classSuper {
 		static {
 			const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
+			_locateFor_decorators = [Remote];
 			_revealHandover_decorators = [Remote];
+			__esDecorate(this, null, _locateFor_decorators, {
+				kind: "method",
+				name: "locateFor",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "locateFor" in obj,
+					get: (obj) => obj.locateFor
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
 			__esDecorate(this, null, _revealHandover_decorators, {
 				kind: "method",
 				name: "revealHandover",
@@ -5341,13 +5628,23 @@ let MhBrowserService = (() => {
 				value: _metadata
 			});
 		}
-		static Config = browserConfig;
 		windows = (__runInitializers(this, _instanceExtraInitializers), new Windows());
-		launchOptions;
+		headless;
+		profileDir;
+		browserName;
+		executablePath;
+		/** Tests replace the machine lookup. Unset uses this machine. */
+		locator;
 		context;
 		pids = /* @__PURE__ */ new WeakMap();
 		ready = Promise.resolve();
 		closing = false;
+		/** A browser restart was requested and has not run yet. */
+		relaunchWanted = false;
+		/** Counts browser and path changes. A start that sampled the latest one clears the restart. */
+		configEpoch = 0;
+		/** The running browser is being closed so the new configuration can start. */
+		replacing = false;
 		/** The browser is not running. The next call that needs a page starts it. */
 		exited = true;
 		exits = [];
@@ -5366,11 +5663,16 @@ let MhBrowserService = (() => {
 		constructor(ctx, config) {
 			super(ctx, "mhBrowser");
 			this.maxBytes = config.presence.maxBytes;
-			this.launchOptions = {
-				browser: config.browser,
-				headless: config.headless,
-				profileDir: config.profileDir ?? defaultProfileDir(ctx.get("profileContext"))
-			};
+			this.headless = config.headless;
+			this.profileDir = config.profileDir ?? defaultProfileDir(ctx.get("profileContext"));
+			this.browserName = config.browser;
+			this.executablePath = config.executablePath ?? { get: () => void 0 };
+			Object.getPrototypeOf(ctx).on("loader/volatile-update", (paths) => {
+				if (!paths.some((path) => path.includes("browser") || path.includes("executablePath"))) return;
+				this.configEpoch += 1;
+				this.relaunchWanted = true;
+				this.relaunchIfIdle();
+			});
 			this.windows.setPersonInput((owner, tab) => {
 				const live = tab === void 0 ? void 0 : this.windows.get(owner, tab);
 				this.control.note(owner, tab);
@@ -5589,9 +5891,26 @@ let MhBrowserService = (() => {
 				page: (owner, tab) => this.windows.get(owner, tab)?.page,
 				running: () => this.context !== void 0,
 				pages: () => this.context?.pages() ?? [],
-				pid: () => this.context === void 0 ? void 0 : this.pids.get(this.context)
+				pid: () => this.context === void 0 ? void 0 : this.pids.get(this.context),
+				useLocator: (env) => {
+					this.locator = env;
+				}
 			};
 		}
+		/**
+		* Where `browser` would be launched from when no path is configured.
+		* The configured path is not consulted: the answer is what an empty path uses.
+		*/
+		async locateFor(browser, signal) {
+			const stopped = () => signal?.aborted === true;
+			if (stopped()) throw new MhBrowserError(INTERRUPTED, WAITING_STOPPED);
+			if (browser !== "chrome" && browser !== "msedge" && browser !== "chromium") throw new MhBrowserError("INVALID_ARGS", "browser must be chrome, msedge, or chromium");
+			const env = this.locateEnv();
+			if (browser === "chromium") return bundledChromiumLocation(env.access);
+			const located = await locateInstalled(browser, env, signal);
+			if (stopped()) throw new MhBrowserError(INTERRUPTED, WAITING_STOPPED);
+			return located;
+		}
 		async act(owner, tab, op, signal) {
 			return this.exclusive(owner, async () => {
 				await this.ready;
@@ -5777,18 +6096,22 @@ let MhBrowserService = (() => {
 			if (!this.control.releaseIfHeld(owner)) return;
 			this.windows.releaseHandover(owner);
 			this.windows.markWaiting(owner, false);
+			this.relaunchIfIdle();
 		}
 		/**
 		* The person took over between turns. The next message they send is the
 		* hand-back. A handover that is still waiting on its card is not.
+		* The addresses are read before a waiting restart closes the pages.
 		*/
 		takePersonHandback(owner) {
 			const taken = this.control.takePerson(owner);
 			if (taken === void 0) return void 0;
+			const urls = this.presenceUrls(owner, taken.tabs);
 			this.windows.releaseHandover(owner);
+			this.relaunchIfIdle();
 			return {
 				...taken,
-				urls: this.presenceUrls(owner, taken.tabs)
+				urls
 			};
 		}
 		/**
@@ -6672,8 +6995,10 @@ let MhBrowserService = (() => {
 			return started;
 		}
 		async start() {
-			const context = await launchBrowser(this.launchOptions);
-			const pid = await browserPid(context, this.launchOptions.profileDir);
+			const choice = this.launchChoice();
+			const epoch = this.configEpoch;
+			const context = await launchBrowser(choice, this.locateEnv());
+			const pid = await browserPid(context, choice.profileDir);
 			if (pid !== void 0) this.pids.set(context, pid);
 			if (this.closing) {
 				await this.closeContext(context);
@@ -6681,15 +7006,16 @@ let MhBrowserService = (() => {
 			}
 			this.context = context;
 			try {
-				await this.windows.attach(context, this.launchOptions.profileDir, { headed: !this.launchOptions.headless });
+				await this.windows.attach(context, choice.profileDir, { headed: !choice.headless });
 			} catch (error) {
 				this.context = void 0;
 				this.windows.dropPages();
 				await this.closeContext(context);
 				throw error;
 			}
+			if (this.configEpoch === epoch) this.relaunchWanted = false;
 			context.browser()?.on("disconnected", () => {
-				if (this.closing || this.context !== context) return;
+				if (this.closing || this.replacing || this.context !== context) return;
 				this.onExit();
 			});
 		}
@@ -6773,9 +7099,69 @@ let MhBrowserService = (() => {
 			this.queues.set(owner, queued.tail);
 			queued.tail.then(() => {
 				if (this.queues.get(owner) === queued.tail) this.queues.delete(owner);
+				if (this.queues.size === 0) this.relaunchIfIdle();
 			});
 			return queued.run;
 		}
+		launchChoice() {
+			const configured = this.executablePath.get();
+			return {
+				browser: this.browserName.get(),
+				headless: this.headless,
+				profileDir: this.profileDir,
+				...configured !== void 0 && configured !== "" ? { executablePath: configured } : {}
+			};
+		}
+		locateEnv() {
+			return this.locator ?? hostLocateEnv();
+		}
+		idle() {
+			return this.queues.size === 0 && !this.control.busy();
+		}
+		/**
+		* Close and start again when a configuration change is waiting and nothing
+		* is using the browser. A browser that is not running keeps the new values
+		* for the next start. The close is not counted as a crash.
+		*/
+		relaunchIfIdle() {
+			if (!this.relaunchWanted || this.closing || this.replacing) return;
+			if (!this.idle()) return;
+			if (this.context === void 0) {
+				if (this.exited) {
+					this.relaunchWanted = false;
+					return;
+				}
+				this.ready.then(() => this.relaunchIfIdle(), () => {
+					this.relaunchWanted = false;
+				});
+				return;
+			}
+			this.relaunchWanted = false;
+			this.replacing = true;
+			const run = this.replaceBrowser();
+			this.ready = run;
+			const finish = () => {
+				this.replacing = false;
+				if (this.relaunchWanted) this.relaunchIfIdle();
+			};
+			run.then(finish, finish);
+		}
+		async replaceBrowser() {
+			this.windows.suppressPersonInput();
+			const context = this.context;
+			this.context = void 0;
+			this.windows.dropPages();
+			if (context !== void 0) await this.closeContext(context);
+			if (this.closing) return;
+			this.exited = false;
+			try {
+				await this.launch();
+				this.windows.resumePersonInput();
+			} catch (error) {
+				this.exited = true;
+				throw error;
+			}
+		}
 	};
 })();
 const MAX_REDIRECTS = 10;
@@ -7541,6 +7927,7 @@ const inject = [
 ];
 const Config = browserConfig;
 async function apply(ctx, config) {
+	const resolved = browserSettings(config);
 	ctx.plugin({
 		name: "mh-browser-slot",
 		inject: ["browserUse", "mhBrowser"],
@@ -7548,16 +7935,29 @@ async function apply(ctx, config) {
 			inner.browserUse.register("mh-browser");
 		}
 	});
-	await ctx.plugin(MhBrowserService, config);
+	await ctx.plugin(MhBrowserService, resolved);
 	await ctx.plugin({
 		name: "mh-browser-runtime",
 		inject: ["mhBrowser", ...inject],
 		async apply(inner) {
 			const reader = await registerProjections(inner);
-			registerBrowserTools(inner, reader, !config.headless);
+			registerBrowserTools(inner, reader, !resolved.headless);
 			registerPresence(inner, reader);
 		}
 	});
 }
+/**
+* The loader passes a config it has already resolved, including the volatile
+* fields. A direct caller passes the raw values, which are resolved here.
+* Resolving twice rejects a volatile value as if it were the wrong type.
+*/
+function browserSettings(config) {
+	if (isResolved(config)) return config;
+	return browserConfig(config);
+}
+function isResolved(config) {
+	const browser = config.browser;
+	return typeof browser === "object" && browser !== null && "get" in browser;
+}
 //#endregion
 export { Config, MhBrowserError, MhBrowserService, UNKNOWN_TAB, UNKNOWN_TAB_REASON, apply, inject, name, readAgentView, unknownTab };