fix(browser): keep static helper seams cold (#59471)

vincentkoc · web-flow · commit 08962b681258 · 2026-04-02T17:12:32.000+09:00
* fix(browser): keep static helper seams cold

* fix(browser): narrow sandbox helper facade imports

* fix(browser): harden host inspection helpers
diff --git a/scripts/lib/plugin-sdk-facades.mjs b/scripts/lib/plugin-sdk-facades.mjs
@@ -226,9 +226,12 @@ export const GENERATED_PLUGIN_SDK_FACADES = [
       DEFAULT_UPLOAD_DIR: "./browser-config.js",
       closeTrackedBrowserTabsForSessions: "./browser-maintenance.js",
       movePathToTrash: "./browser-maintenance.js",
+      parseBrowserMajorVersion: "./browser-host-inspection.js",
       redactCdpUrl: "./browser-config.js",
+      readBrowserVersion: "./browser-host-inspection.js",
       resolveBrowserConfig: "./browser-config.js",
       resolveBrowserControlAuth: "./browser-config.js",
+      resolveGoogleChromeExecutableForPlatform: "./browser-host-inspection.js",
       resolveProfile: "./browser-config.js",
     },
     exports: [
diff --git a/src/agents/sandbox/browser.ts b/src/agents/sandbox/browser.ts
@@ -5,9 +5,11 @@ import {
   DEFAULT_OPENCLAW_BROWSER_COLOR,
   DEFAULT_OPENCLAW_BROWSER_PROFILE_NAME,
   resolveProfile,
+  type ResolvedBrowserConfig,
+} from "../../plugin-sdk/browser-config.js";
+import {
   startBrowserBridgeServer,
   stopBrowserBridgeServer,
-  type ResolvedBrowserConfig,
 } from "../../plugin-sdk/browser-runtime.js";
 import { defaultRuntime } from "../../runtime.js";
 import { BROWSER_BRIDGES } from "./browser-bridges.js";
diff --git a/src/agents/sandbox/context.ts b/src/agents/sandbox/context.ts
@@ -3,9 +3,9 @@ import type { OpenClawConfig } from "../../config/config.js";
 import { loadConfig } from "../../config/config.js";
 import {
   DEFAULT_BROWSER_EVALUATE_ENABLED,
-  ensureBrowserControlAuth,
   resolveBrowserControlAuth,
-} from "../../plugin-sdk/browser-runtime.js";
+} from "../../plugin-sdk/browser-config.js";
+import { ensureBrowserControlAuth } from "../../plugin-sdk/browser-runtime.js";
 import { defaultRuntime } from "../../runtime.js";
 import { resolveUserPath } from "../../utils.js";
 import { syncSkillsToWorkspace } from "../skills.js";
diff --git a/src/commands/doctor-browser.ts b/src/commands/doctor-browser.ts
@@ -3,7 +3,7 @@ import {
   parseBrowserMajorVersion,
   readBrowserVersion,
   resolveGoogleChromeExecutableForPlatform,
-} from "../plugin-sdk/browser-runtime.js";
+} from "../plugin-sdk/browser-host-inspection.js";
 import { note } from "../terminal/note.js";
 
 const CHROME_MCP_MIN_MAJOR = 144;
diff --git a/src/gateway/server-methods/agents-mutate.test.ts b/src/gateway/server-methods/agents-mutate.test.ts
@@ -71,7 +71,7 @@ vi.mock("../../config/sessions/paths.js", () => ({
   resolveSessionTranscriptsDirForAgent: mocks.resolveSessionTranscriptsDirForAgent,
 }));
 
-vi.mock("../../plugin-sdk/browser-runtime.js", () => ({
+vi.mock("../../plugin-sdk/browser-maintenance.js", () => ({
   movePathToTrash: mocks.movePathToTrash,
 }));
 
diff --git a/src/gateway/server-methods/agents.ts b/src/gateway/server-methods/agents.ts
@@ -35,7 +35,7 @@ import {
 } from "../../infra/fs-safe.js";
 import { assertNoPathAliasEscape } from "../../infra/path-alias-guards.js";
 import { isNotFoundPathError } from "../../infra/path-guards.js";
-import { movePathToTrash } from "../../plugin-sdk/browser-runtime.js";
+import { movePathToTrash } from "../../plugin-sdk/browser-maintenance.js";
 import { DEFAULT_AGENT_ID, normalizeAgentId } from "../../routing/session-key.js";
 import { resolveUserPath } from "../../utils.js";
 import {
diff --git a/src/gateway/server.sessions.gateway-server-sessions-a.test.ts b/src/gateway/server.sessions.gateway-server-sessions-a.test.ts
@@ -168,7 +168,7 @@ vi.mock("../acp/control-plane/manager.js", () => ({
   }),
 }));
 
-vi.mock("../plugin-sdk/browser-runtime.js", () => ({
+vi.mock("../plugin-sdk/browser-maintenance.js", () => ({
   closeTrackedBrowserTabsForSessions: browserSessionTabMocks.closeTrackedBrowserTabsForSessions,
   movePathToTrash: vi.fn(async () => {}),
 }));
diff --git a/src/gateway/session-reset-service.ts b/src/gateway/session-reset-service.ts
@@ -17,7 +17,7 @@ import {
 import { resolveSessionFilePath, resolveSessionFilePathOptions } from "../config/sessions/paths.js";
 import { logVerbose } from "../globals.js";
 import { createInternalHookEvent, triggerInternalHook } from "../hooks/internal-hooks.js";
-import { closeTrackedBrowserTabsForSessions } from "../plugin-sdk/browser-runtime.js";
+import { closeTrackedBrowserTabsForSessions } from "../plugin-sdk/browser-maintenance.js";
 import { getGlobalHookRunner } from "../plugins/hook-runner-global.js";
 import { createPluginRuntime } from "../plugins/runtime/index.js";
 import {
diff --git a/src/node-host/runner.ts b/src/node-host/runner.ts
@@ -11,7 +11,7 @@ import {
   NODE_SYSTEM_RUN_COMMANDS,
 } from "../infra/node-commands.js";
 import { ensureOpenClawCliOnPath } from "../infra/path-env.js";
-import { resolveBrowserConfig } from "../plugin-sdk/browser-runtime.js";
+import { resolveBrowserConfig } from "../plugin-sdk/browser-config.js";
 import { GATEWAY_CLIENT_MODES, GATEWAY_CLIENT_NAMES } from "../utils/message-channel.js";
 import { VERSION } from "../version.js";
 import { ensureNodeHostConfig, saveNodeHostConfig, type NodeHostGatewayConfig } from "./config.js";
diff --git a/src/plugin-activation-boundary.test.ts b/src/plugin-activation-boundary.test.ts
@@ -35,9 +35,12 @@ describe("plugin activation boundary", () => {
         DEFAULT_OPENCLAW_BROWSER_PROFILE_NAME: typeof import("./plugin-sdk/browser-runtime.js").DEFAULT_OPENCLAW_BROWSER_PROFILE_NAME;
         DEFAULT_UPLOAD_DIR: typeof import("./plugin-sdk/browser-runtime.js").DEFAULT_UPLOAD_DIR;
         closeTrackedBrowserTabsForSessions: typeof import("./plugin-sdk/browser-runtime.js").closeTrackedBrowserTabsForSessions;
+        parseBrowserMajorVersion: typeof import("./plugin-sdk/browser-runtime.js").parseBrowserMajorVersion;
         redactCdpUrl: typeof import("./plugin-sdk/browser-runtime.js").redactCdpUrl;
+        readBrowserVersion: typeof import("./plugin-sdk/browser-runtime.js").readBrowserVersion;
         resolveBrowserConfig: typeof import("./plugin-sdk/browser-runtime.js").resolveBrowserConfig;
         resolveBrowserControlAuth: typeof import("./plugin-sdk/browser-runtime.js").resolveBrowserControlAuth;
+        resolveGoogleChromeExecutableForPlatform: typeof import("./plugin-sdk/browser-runtime.js").resolveGoogleChromeExecutableForPlatform;
         resolveProfile: typeof import("./plugin-sdk/browser-runtime.js").resolveProfile;
       }>
     | undefined;
@@ -84,9 +87,12 @@ describe("plugin activation boundary", () => {
       DEFAULT_OPENCLAW_BROWSER_PROFILE_NAME: module.DEFAULT_OPENCLAW_BROWSER_PROFILE_NAME,
       DEFAULT_UPLOAD_DIR: module.DEFAULT_UPLOAD_DIR,
       closeTrackedBrowserTabsForSessions: module.closeTrackedBrowserTabsForSessions,
+      parseBrowserMajorVersion: module.parseBrowserMajorVersion,
       redactCdpUrl: module.redactCdpUrl,
+      readBrowserVersion: module.readBrowserVersion,
       resolveBrowserConfig: module.resolveBrowserConfig,
       resolveBrowserControlAuth: module.resolveBrowserControlAuth,
+      resolveGoogleChromeExecutableForPlatform: module.resolveGoogleChromeExecutableForPlatform,
       resolveProfile: module.resolveProfile,
     }));
     return browserHelpersPromise;
@@ -96,6 +102,7 @@ describe("plugin activation boundary", () => {
     browserAmbientImportsPromise ??= Promise.all([
       import("./agents/sandbox/browser.js"),
       import("./agents/sandbox/context.js"),
+      import("./commands/doctor-browser.js"),
       import("./node-host/runner.js"),
       import("./security/audit.js"),
       import("./security/audit-extra.sync.js"),
@@ -148,6 +155,7 @@ describe("plugin activation boundary", () => {
     expect(browser.DEFAULT_OPENCLAW_BROWSER_COLOR).toBe("#FF4500");
     expect(browser.DEFAULT_OPENCLAW_BROWSER_PROFILE_NAME).toBe("openclaw");
     expect(browser.DEFAULT_UPLOAD_DIR).toContain("uploads");
+    expect(browser.parseBrowserMajorVersion("Google Chrome 144.0.7534.0")).toBe(144);
     expect(browser.resolveBrowserControlAuth({}, {} as NodeJS.ProcessEnv)).toEqual({
       token: undefined,
       password: undefined,
@@ -162,6 +170,8 @@ describe("plugin activation boundary", () => {
     expect(
       browser.redactCdpUrl("wss://user:secret@example.com/devtools/browser/123"),
     ).not.toContain("secret");
+    expect(browser.readBrowserVersion("/path/that/does/not/exist")).toBeNull();
+    expect(browser.resolveGoogleChromeExecutableForPlatform("aix")).toBeNull();
     expect(loadBundledPluginPublicSurfaceModuleSync).not.toHaveBeenCalled();
   });
 
diff --git a/src/plugin-sdk/browser-host-inspection.test.ts b/src/plugin-sdk/browser-host-inspection.test.ts
@@ -0,0 +1,42 @@
+import fs from "node:fs";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  parseBrowserMajorVersion,
+  resolveGoogleChromeExecutableForPlatform,
+} from "./browser-host-inspection.js";
+
+describe("browser host inspection", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("parses the last dotted browser version token", () => {
+    expect(parseBrowserMajorVersion("Google Chrome 144.0.7534.0")).toBe(144);
+    expect(parseBrowserMajorVersion("Chromium 3.0/1.2.3")).toBe(1);
+    expect(parseBrowserMajorVersion("no version here")).toBeNull();
+  });
+
+  it("classifies beta Linux Chrome builds as prerelease", () => {
+    vi.spyOn(fs, "existsSync").mockImplementation((candidate) => {
+      const normalized = String(candidate);
+      return normalized === "/usr/bin/google-chrome-beta";
+    });
+
+    expect(resolveGoogleChromeExecutableForPlatform("linux")).toEqual({
+      kind: "canary",
+      path: "/usr/bin/google-chrome-beta",
+    });
+  });
+
+  it("classifies unstable Linux Chrome builds as prerelease", () => {
+    vi.spyOn(fs, "existsSync").mockImplementation((candidate) => {
+      const normalized = String(candidate);
+      return normalized === "/usr/bin/google-chrome-unstable";
+    });
+
+    expect(resolveGoogleChromeExecutableForPlatform("linux")).toEqual({
+      kind: "canary",
+      path: "/usr/bin/google-chrome-unstable",
+    });
+  });
+});
diff --git a/src/plugin-sdk/browser-host-inspection.ts b/src/plugin-sdk/browser-host-inspection.ts
@@ -0,0 +1,127 @@
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import type { PluginSdkFacadeTypeMap } from "../generated/plugin-sdk-facade-type-map.generated.js";
+
+type BrowserExecutable = PluginSdkFacadeTypeMap["browser-runtime"]["types"]["BrowserExecutable"];
+
+const CHROME_VERSION_RE = /\b(\d+)(?:\.\d+){1,3}\b/g;
+
+function exists(filePath: string) {
+  try {
+    return fs.existsSync(filePath);
+  } catch {
+    return false;
+  }
+}
+
+function execText(
+  command: string,
+  args: string[],
+  timeoutMs = 1200,
+  maxBuffer = 1024 * 1024,
+): string | null {
+  try {
+    const output = execFileSync(command, args, {
+      timeout: timeoutMs,
+      encoding: "utf8",
+      maxBuffer,
+    });
+    return String(output ?? "").trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+function findFirstChromeExecutable(candidates: string[]): BrowserExecutable | null {
+  for (const candidate of candidates) {
+    if (exists(candidate)) {
+      const normalizedPath = candidate.toLowerCase();
+      return {
+        kind:
+          normalizedPath.includes("beta") ||
+          normalizedPath.includes("canary") ||
+          normalizedPath.includes("sxs") ||
+          normalizedPath.includes("unstable")
+            ? "canary"
+            : "chrome",
+        path: candidate,
+      };
+    }
+  }
+  return null;
+}
+
+function findGoogleChromeExecutableMac(): BrowserExecutable | null {
+  return findFirstChromeExecutable([
+    "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+    path.join(os.homedir(), "Applications/Google Chrome.app/Contents/MacOS/Google Chrome"),
+    "/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary",
+    path.join(
+      os.homedir(),
+      "Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary",
+    ),
+  ]);
+}
+
+function findGoogleChromeExecutableLinux(): BrowserExecutable | null {
+  return findFirstChromeExecutable([
+    "/usr/bin/google-chrome",
+    "/usr/bin/google-chrome-stable",
+    "/usr/bin/google-chrome-beta",
+    "/usr/bin/google-chrome-unstable",
+    "/snap/bin/google-chrome",
+  ]);
+}
+
+function findGoogleChromeExecutableWindows(): BrowserExecutable | null {
+  const localAppData = process.env.LOCALAPPDATA ?? "";
+  const programFiles = process.env.ProgramFiles ?? "C:\\Program Files";
+  const programFilesX86 = process.env["ProgramFiles(x86)"] ?? "C:\\Program Files (x86)";
+  const joinWin = path.win32.join;
+  const candidates: string[] = [];
+
+  if (localAppData) {
+    candidates.push(joinWin(localAppData, "Google", "Chrome", "Application", "chrome.exe"));
+    candidates.push(joinWin(localAppData, "Google", "Chrome SxS", "Application", "chrome.exe"));
+  }
+
+  candidates.push(joinWin(programFiles, "Google", "Chrome", "Application", "chrome.exe"));
+  candidates.push(joinWin(programFilesX86, "Google", "Chrome", "Application", "chrome.exe"));
+
+  return findFirstChromeExecutable(candidates);
+}
+
+export function resolveGoogleChromeExecutableForPlatform(
+  platform: NodeJS.Platform,
+): BrowserExecutable | null {
+  if (platform === "darwin") {
+    return findGoogleChromeExecutableMac();
+  }
+  if (platform === "linux") {
+    return findGoogleChromeExecutableLinux();
+  }
+  if (platform === "win32") {
+    return findGoogleChromeExecutableWindows();
+  }
+  return null;
+}
+
+export function readBrowserVersion(executablePath: string): string | null {
+  const output = execText(executablePath, ["--version"], 2000);
+  if (!output) {
+    return null;
+  }
+  return output.replace(/\s+/g, " ").trim();
+}
+
+export function parseBrowserMajorVersion(rawVersion: string | null | undefined): number | null {
+  const matches = [...String(rawVersion ?? "").matchAll(CHROME_VERSION_RE)];
+  const match = matches.at(-1);
+  if (!match?.[1]) {
+    return null;
+  }
+  const major = Number.parseInt(match[1], 10);
+  return Number.isFinite(major) ? major : null;
+}
diff --git a/src/plugin-sdk/browser-runtime.ts b/src/plugin-sdk/browser-runtime.ts
@@ -13,6 +13,11 @@ export {
   resolveBrowserControlAuth,
   resolveProfile,
 } from "./browser-config.js";
+export {
+  parseBrowserMajorVersion,
+  readBrowserVersion,
+  resolveGoogleChromeExecutableForPlatform,
+} from "./browser-host-inspection.js";
 export { closeTrackedBrowserTabsForSessions, movePathToTrash } from "./browser-maintenance.js";
 import {
   createLazyFacadeObjectValue,
@@ -151,16 +156,10 @@ export const normalizeBrowserRequestPath: FacadeModule["normalizeBrowserRequestP
   loadFacadeModule()["normalizeBrowserRequestPath"](
     ...args,
   )) as FacadeModule["normalizeBrowserRequestPath"];
-export const parseBrowserMajorVersion: FacadeModule["parseBrowserMajorVersion"] = ((...args) =>
-  loadFacadeModule()["parseBrowserMajorVersion"](
-    ...args,
-  )) as FacadeModule["parseBrowserMajorVersion"];
 export const persistBrowserProxyFiles: FacadeModule["persistBrowserProxyFiles"] = ((...args) =>
   loadFacadeModule()["persistBrowserProxyFiles"](
     ...args,
   )) as FacadeModule["persistBrowserProxyFiles"];
-export const readBrowserVersion: FacadeModule["readBrowserVersion"] = ((...args) =>
-  loadFacadeModule()["readBrowserVersion"](...args)) as FacadeModule["readBrowserVersion"];
 export const registerBrowserCli: FacadeModule["registerBrowserCli"] = ((...args) =>
   loadFacadeModule()["registerBrowserCli"](...args)) as FacadeModule["registerBrowserCli"];
 export const registerBrowserRoutes: FacadeModule["registerBrowserRoutes"] = ((...args) =>
@@ -171,11 +170,6 @@ export const resolveExistingPathsWithinRoot: FacadeModule["resolveExistingPathsW
   loadFacadeModule()["resolveExistingPathsWithinRoot"](
     ...args,
   )) as FacadeModule["resolveExistingPathsWithinRoot"];
-export const resolveGoogleChromeExecutableForPlatform: FacadeModule["resolveGoogleChromeExecutableForPlatform"] =
-  ((...args) =>
-    loadFacadeModule()["resolveGoogleChromeExecutableForPlatform"](
-      ...args,
-    )) as FacadeModule["resolveGoogleChromeExecutableForPlatform"];
 export const resolveRequestedBrowserProfile: FacadeModule["resolveRequestedBrowserProfile"] = ((
   ...args
 ) =>
diff --git a/src/security/audit-extra.sync.ts b/src/security/audit-extra.sync.ts
@@ -23,7 +23,7 @@ import {
   DEFAULT_DANGEROUS_NODE_COMMANDS,
   resolveNodeCommandAllowlist,
 } from "../gateway/node-command-policy.js";
-import { resolveBrowserConfig } from "../plugin-sdk/browser-runtime.js";
+import { resolveBrowserConfig } from "../plugin-sdk/browser-config.js";
 import { hasBundledWebSearchCredential } from "../plugins/bundled-web-search-registry.js";
 import { inferParamBFromIdOrName } from "../shared/model-param-b.js";
 import { pickSandboxToolPolicy } from "./audit-tool-policy.js";
diff --git a/src/security/audit.ts b/src/security/audit.ts
@@ -22,7 +22,7 @@ import {
   resolveBrowserConfig,
   resolveBrowserControlAuth,
   resolveProfile,
-} from "../plugin-sdk/browser-runtime.js";
+} from "../plugin-sdk/browser-config.js";
 import { DEFAULT_AGENT_ID } from "../routing/session-key.js";
 import {
   formatPermissionDetail,
