Auto-merge upstream openclaw/openclaw

Author: friuns2

CHANGELOG.md

@@ -10,6 +10,7 @@ Docs: https://docs.openclaw.ai
 - macOS/Talk: add an experimental local MLX speech provider for Talk Mode, with explicit provider selection, local utterance playback, interruption handling, and system-voice fallback. (#63539) Thanks @ImLukeF.
 - Docs i18n: chunk raw doc translation, reject truncated tagged outputs, avoid ambiguous body-only wrapper unwrapping, and recover from terminated Pi translation sessions without changing the default `openai/gpt-5.4` path. (#62969, #63808) Thanks @hxy91819.
 - QA/testing: add a `--runner multipass` lane for `openclaw qa suite` so repo-backed QA scenarios can run inside a disposable Linux VM and write back the usual report, summary, and VM logs. (#63426) Thanks @shakkernerd.
+- Gateway: split startup and runtime seams so gateway lifecycle sequencing, reload state, and shutdown behavior stay easier to maintain without changing observed behavior. (#63975) Thanks @gumadeiras.
 
 ### Fixes
 
@@ -60,6 +61,8 @@ Docs: https://docs.openclaw.ai
 - Gateway/thread routing: preserve Slack, Telegram, and Mattermost thread-child delivery targets so bound subagent completion messages land in the originating thread instead of top-level channels. (#54840) Thanks @yzzymt.
 - ACP/stream relay: pass parent delivery context to ACP stream relay system events so `streamTo="parent"` updates route to the correct thread or topic instead of falling back to the main DM. (#57056) Thanks @pingren.
 - Agents/sessions: preserve announce `threadId` when `sessions.list` fallback rehydrates agent-to-agent announce targets so final announce messages stay in the originating thread/topic. (#63506) Thanks @SnowSky1.
+- Browser/plugin SDK: route browser auth, profile, host-inspection, and doctor readiness helpers through browser plugin public facades so core compatibility helpers stop carrying duplicate runtime implementations. (#63957) Thanks @joshavant.
+
 ## 2026.4.9
 
 ### Changes

extensions/browser/browser-config.ts

@@ -5,13 +5,11 @@ export {
   DEFAULT_OPENCLAW_BROWSER_COLOR,
   DEFAULT_OPENCLAW_BROWSER_ENABLED,
   DEFAULT_OPENCLAW_BROWSER_PROFILE_NAME,
-  parseBrowserHttpUrl,
-  redactCdpUrl,
+  DEFAULT_UPLOAD_DIR,
   resolveBrowserConfig,
-  resolveBrowserControlAuth,
   resolveProfile,
-  type BrowserControlAuth,
   type ResolvedBrowserConfig,
   type ResolvedBrowserProfile,
-} from "./src/browser/config.js";
-export { DEFAULT_UPLOAD_DIR } from "./src/browser/paths.js";
+} from "./browser-profiles.js";
+export { resolveBrowserControlAuth, type BrowserControlAuth } from "./browser-control-auth.js";
+export { parseBrowserHttpUrl, redactCdpUrl } from "./src/browser/config.js";

extensions/browser/browser-control-auth.ts

@@ -1,2 +1,6 @@
 export type { BrowserControlAuth } from "./src/browser/control-auth.js";
-export { ensureBrowserControlAuth, resolveBrowserControlAuth } from "./src/browser/control-auth.js";
+export {
+  ensureBrowserControlAuth,
+  resolveBrowserControlAuth,
+  shouldAutoGenerateBrowserAuth,
+} from "./src/browser/control-auth.js";

extensions/browser/src/browser/chrome.executables.test.ts

@@ -0,0 +1,42 @@
+import fs from "node:fs";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  parseBrowserMajorVersion,
+  resolveGoogleChromeExecutableForPlatform,
+} from "./chrome.executables.js";
+
+describe("chrome executables", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("parses odd dotted browser version tokens using the last match", () => {
+    expect(parseBrowserMajorVersion("Chromium 3.0/1.2.3")).toBe(1);
+  });
+
+  it("returns null when no dotted version token exists", () => {
+    expect(parseBrowserMajorVersion("no version here")).toBeNull();
+  });
+
+  it("classifies beta Linux Google Chrome builds as canary", () => {
+    vi.spyOn(fs, "existsSync").mockImplementation((candidate) => {
+      return String(candidate) === "/usr/bin/google-chrome-beta";
+    });
+
+    expect(resolveGoogleChromeExecutableForPlatform("linux")).toEqual({
+      kind: "canary",
+      path: "/usr/bin/google-chrome-beta",
+    });
+  });
+
+  it("classifies unstable Linux Google Chrome builds as canary", () => {
+    vi.spyOn(fs, "existsSync").mockImplementation((candidate) => {
+      return String(candidate) === "/usr/bin/google-chrome-unstable";
+    });
+
+    expect(resolveGoogleChromeExecutableForPlatform("linux")).toEqual({
+      kind: "canary",
+      path: "/usr/bin/google-chrome-unstable",
+    });
+  });
+});

src/commands/doctor-browser.facade.test.ts

@@ -0,0 +1,52 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { OpenClawConfig } from "../config/config.js";
+import { noteChromeMcpBrowserReadiness } from "./doctor-browser.js";
+
+const loadBundledPluginPublicSurfaceModuleSync = vi.hoisted(() => vi.fn());
+
+vi.mock("../plugin-sdk/facade-loader.js", () => ({
+  loadBundledPluginPublicSurfaceModuleSync,
+}));
+
+describe("doctor browser facade", () => {
+  beforeEach(() => {
+    loadBundledPluginPublicSurfaceModuleSync.mockReset();
+  });
+
+  it("delegates browser readiness checks to the browser facade surface", async () => {
+    const delegate = vi.fn().mockResolvedValue(undefined);
+    loadBundledPluginPublicSurfaceModuleSync.mockReturnValue({
+      noteChromeMcpBrowserReadiness: delegate,
+    });
+
+    const cfg: OpenClawConfig = {
+      browser: {
+        defaultProfile: "user",
+      },
+    };
+    const noteFn = vi.fn();
+
+    await noteChromeMcpBrowserReadiness(cfg, { noteFn });
+
+    expect(loadBundledPluginPublicSurfaceModuleSync).toHaveBeenCalledWith({
+      dirName: "browser",
+      artifactBasename: "browser-doctor.js",
+    });
+    expect(delegate).toHaveBeenCalledWith(cfg, { noteFn });
+    expect(noteFn).not.toHaveBeenCalled();
+  });
+
+  it("warns and no-ops when the browser doctor surface is unavailable", async () => {
+    loadBundledPluginPublicSurfaceModuleSync.mockImplementation(() => {
+      throw new Error("missing browser doctor facade");
+    });
+
+    const noteFn = vi.fn();
+
+    await expect(noteChromeMcpBrowserReadiness({}, { noteFn })).resolves.toBeUndefined();
+    expect(noteFn).toHaveBeenCalledTimes(1);
+    expect(String(noteFn.mock.calls[0]?.[0])).toContain("Browser health check is unavailable");
+    expect(String(noteFn.mock.calls[0]?.[0])).toContain("missing browser doctor facade");
+    expect(noteFn.mock.calls[0]?.[1]).toBe("Browser");
+  });
+});

src/commands/doctor-browser.ts

@@ -1,146 +1,31 @@
 import type { OpenClawConfig } from "../config/config.js";
-import {
-  parseBrowserMajorVersion,
-  readBrowserVersion,
-  resolveGoogleChromeExecutableForPlatform,
-} from "../plugin-sdk/browser-host-inspection.js";
-import { asNullableRecord } from "../shared/record-coerce.js";
-import { normalizeOptionalString } from "../shared/string-coerce.js";
+import { loadBundledPluginPublicSurfaceModuleSync } from "../plugin-sdk/facade-loader.js";
 import { note } from "../terminal/note.js";
 
-const CHROME_MCP_MIN_MAJOR = 144;
-const REMOTE_DEBUGGING_PAGES = [
-  "chrome://inspect/#remote-debugging",
-  "brave://inspect/#remote-debugging",
-  "edge://inspect/#remote-debugging",
-].join(", ");
-
-type ExistingSessionProfile = {
-  name: string;
-  userDataDir?: string;
+type BrowserDoctorDeps = {
+  platform?: NodeJS.Platform;
+  noteFn?: typeof note;
+  resolveChromeExecutable?: (platform: NodeJS.Platform) => { path: string } | null;
+  readVersion?: (executablePath: string) => string | null;
 };
 
-function collectChromeMcpProfiles(cfg: OpenClawConfig): ExistingSessionProfile[] {
-  const browser = asNullableRecord(cfg.browser);
-  if (!browser) {
-    return [];
-  }
-
-  const profiles = new Map<string, ExistingSessionProfile>();
-  const defaultProfile = normalizeOptionalString(browser.defaultProfile) ?? "";
-  if (defaultProfile === "user") {
-    profiles.set("user", { name: "user" });
-  }
-
-  const configuredProfiles = asNullableRecord(browser.profiles);
-  if (!configuredProfiles) {
-    return [...profiles.values()].toSorted((a, b) => a.name.localeCompare(b.name));
-  }
-
-  for (const [profileName, rawProfile] of Object.entries(configuredProfiles)) {
-    const profile = asNullableRecord(rawProfile);
-    const driver = normalizeOptionalString(profile?.driver) ?? "";
-    if (driver === "existing-session") {
-      profiles.set(profileName, {
-        name: profileName,
-        userDataDir: normalizeOptionalString(profile?.userDataDir),
-      });
-    }
-  }
+type BrowserDoctorSurface = {
+  noteChromeMcpBrowserReadiness: (cfg: OpenClawConfig, deps?: BrowserDoctorDeps) => Promise<void>;
+};
 
-  return [...profiles.values()].toSorted((a, b) => a.name.localeCompare(b.name));
+function loadBrowserDoctorSurface(): BrowserDoctorSurface {
+  return loadBundledPluginPublicSurfaceModuleSync<BrowserDoctorSurface>({
+    dirName: "browser",
+    artifactBasename: "browser-doctor.js",
+  });
 }
 
-export async function noteChromeMcpBrowserReadiness(
-  cfg: OpenClawConfig,
-  deps?: {
-    platform?: NodeJS.Platform;
-    noteFn?: typeof note;
-    resolveChromeExecutable?: (platform: NodeJS.Platform) => { path: string } | null;
-    readVersion?: (executablePath: string) => string | null;
-  },
-) {
-  const profiles = collectChromeMcpProfiles(cfg);
-  if (profiles.length === 0) {
-    return;
+export async function noteChromeMcpBrowserReadiness(cfg: OpenClawConfig, deps?: BrowserDoctorDeps) {
+  try {
+    await loadBrowserDoctorSurface().noteChromeMcpBrowserReadiness(cfg, deps);
+  } catch (error) {
+    const noteFn = deps?.noteFn ?? note;
+    const message = error instanceof Error ? error.message : String(error);
+    noteFn(`- Browser health check is unavailable: ${message}`, "Browser");
   }
-
-  const noteFn = deps?.noteFn ?? note;
-  const platform = deps?.platform ?? process.platform;
-  const resolveChromeExecutable =
-    deps?.resolveChromeExecutable ?? resolveGoogleChromeExecutableForPlatform;
-  const readVersion = deps?.readVersion ?? readBrowserVersion;
-  const explicitProfiles = profiles.filter((profile) => profile.userDataDir);
-  const autoConnectProfiles = profiles.filter((profile) => !profile.userDataDir);
-  const profileLabel = profiles.map((profile) => profile.name).join(", ");
-
-  if (autoConnectProfiles.length === 0) {
-    noteFn(
-      [
-        `- Chrome MCP existing-session is configured for profile(s): ${profileLabel}.`,
-        "- These profiles use an explicit Chromium user data directory instead of Chrome's default auto-connect path.",
-        `- Verify the matching Chromium-based browser is version ${CHROME_MCP_MIN_MAJOR}+ on the same host as the Gateway or node.`,
-        `- Enable remote debugging in that browser's inspect page (${REMOTE_DEBUGGING_PAGES}).`,
-        "- Keep the browser running and accept the attach consent prompt the first time OpenClaw connects.",
-      ].join("\n"),
-      "Browser",
-    );
-    return;
-  }
-
-  const chrome = resolveChromeExecutable(platform);
-  const autoProfileLabel = autoConnectProfiles.map((profile) => profile.name).join(", ");
-
-  if (!chrome) {
-    const lines = [
-      `- Chrome MCP existing-session is configured for profile(s): ${profileLabel}.`,
-      `- Google Chrome was not found on this host for auto-connect profile(s): ${autoProfileLabel}. OpenClaw does not bundle Chrome.`,
-      `- Install Google Chrome ${CHROME_MCP_MIN_MAJOR}+ on the same host as the Gateway or node, or set browser.profiles.<name>.userDataDir for a different Chromium-based browser.`,
-      `- Enable remote debugging in the browser inspect page (${REMOTE_DEBUGGING_PAGES}).`,
-      "- Keep the browser running and accept the attach consent prompt the first time OpenClaw connects.",
-      "- Docker, headless, and sandbox browser flows stay on raw CDP; this check only applies to host-local Chrome MCP attach.",
-    ];
-    if (explicitProfiles.length > 0) {
-      lines.push(
-        `- Profiles with explicit userDataDir skip Chrome auto-detection: ${explicitProfiles
-          .map((profile) => profile.name)
-          .join(", ")}.`,
-      );
-    }
-    noteFn(lines.join("\n"), "Browser");
-    return;
-  }
-
-  const versionRaw = readVersion(chrome.path);
-  const major = parseBrowserMajorVersion(versionRaw);
-  const lines = [
-    `- Chrome MCP existing-session is configured for profile(s): ${profileLabel}.`,
-    `- Chrome path: ${chrome.path}`,
-  ];
-
-  if (!versionRaw || major === null) {
-    lines.push(
-      `- Could not determine the installed Chrome version. Chrome MCP requires Google Chrome ${CHROME_MCP_MIN_MAJOR}+ on this host.`,
-    );
-  } else if (major < CHROME_MCP_MIN_MAJOR) {
-    lines.push(
-      `- Detected Chrome ${versionRaw}, which is too old for Chrome MCP existing-session attach. Upgrade to Chrome ${CHROME_MCP_MIN_MAJOR}+.`,
-    );
-  } else {
-    lines.push(`- Detected Chrome ${versionRaw}.`);
-  }
-
-  lines.push(`- Enable remote debugging in the browser inspect page (${REMOTE_DEBUGGING_PAGES}).`);
-  lines.push(
-    "- Keep the browser running and accept the attach consent prompt the first time OpenClaw connects.",
-  );
-  if (explicitProfiles.length > 0) {
-    lines.push(
-      `- Profiles with explicit userDataDir still need manual validation of the matching Chromium-based browser: ${explicitProfiles
-        .map((profile) => profile.name)
-        .join(", ")}.`,
-    );
-  }
-
-  noteFn(lines.join("\n"), "Browser");
 }

src/commands/doctor.warns-state-directory-is-missing.e2e.test.ts

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { beforeEach, describe, expect, it } from "vitest";
+import { beforeEach, describe, expect, it, vi } from "vitest";
 import {
   createDoctorRuntime,
   ensureAuthProfileStore,
@@ -106,6 +106,43 @@ describe("doctor command", () => {
     expect(String(stateNote?.[0])).toContain("CRITICAL");
   });
 
+  it("routes browser readiness through health contributions and degrades gracefully when browser facade is unavailable", async () => {
+    const loadBundledPluginPublicSurfaceModuleSync = vi.fn(() => {
+      throw new Error("missing browser doctor facade");
+    });
+    vi.doMock("../plugin-sdk/facade-loader.js", () => ({
+      loadBundledPluginPublicSurfaceModuleSync,
+    }));
+    doctorCommand = await loadDoctorCommandForTest({
+      unmockModules: [
+        "../flows/doctor-health-contributions.js",
+        "./doctor-browser.js",
+        "./doctor-state-integrity.js",
+      ],
+    });
+
+    mockDoctorConfigSnapshot({
+      config: {
+        browser: {
+          defaultProfile: "user",
+        },
+      },
+    });
+
+    await runDoctorNonInteractive();
+
+    expect(loadBundledPluginPublicSurfaceModuleSync).toHaveBeenCalledWith({
+      dirName: "browser",
+      artifactBasename: "browser-doctor.js",
+    });
+    const browserFallbackNote = terminalNoteMock.mock.calls.find(
+      ([message, title]) =>
+        title === "Browser" && String(message).includes("Browser health check is unavailable"),
+    );
+    expect(browserFallbackNote).toBeTruthy();
+    expect(String(browserFallbackNote?.[0])).toContain("missing browser doctor facade");
+  });
+
   it("warns about opencode provider overrides", async () => {
     mockDoctorConfigSnapshot({
       config: {