@agenticmail/enterprise 0.5.78 → 0.5.80

package/src/browser/client.ts

@@ -0,0 +1,337 @@
+import { fetchBrowserJson } from "./client-fetch.js";
+
+export type BrowserStatus = {
+  enabled: boolean;
+  profile?: string;
+  running: boolean;
+  cdpReady?: boolean;
+  cdpHttp?: boolean;
+  pid: number | null;
+  cdpPort: number;
+  cdpUrl?: string;
+  chosenBrowser: string | null;
+  detectedBrowser?: string | null;
+  detectedExecutablePath?: string | null;
+  detectError?: string | null;
+  userDataDir: string | null;
+  color: string;
+  headless: boolean;
+  noSandbox?: boolean;
+  executablePath?: string | null;
+  attachOnly: boolean;
+};
+
+export type ProfileStatus = {
+  name: string;
+  cdpPort: number;
+  cdpUrl: string;
+  color: string;
+  running: boolean;
+  tabCount: number;
+  isDefault: boolean;
+  isRemote: boolean;
+};
+
+export type BrowserResetProfileResult = {
+  ok: true;
+  moved: boolean;
+  from: string;
+  to?: string;
+};
+
+export type BrowserTab = {
+  targetId: string;
+  title: string;
+  url: string;
+  wsUrl?: string;
+  type?: string;
+};
+
+export type SnapshotAriaNode = {
+  ref: string;
+  role: string;
+  name: string;
+  value?: string;
+  description?: string;
+  backendDOMNodeId?: number;
+  depth: number;
+};
+
+export type SnapshotResult =
+  | {
+      ok: true;
+      format: "aria";
+      targetId: string;
+      url: string;
+      nodes: SnapshotAriaNode[];
+    }
+  | {
+      ok: true;
+      format: "ai";
+      targetId: string;
+      url: string;
+      snapshot: string;
+      truncated?: boolean;
+      refs?: Record<string, { role: string; name?: string; nth?: number }>;
+      stats?: {
+        lines: number;
+        chars: number;
+        refs: number;
+        interactive: number;
+      };
+      labels?: boolean;
+      labelsCount?: number;
+      labelsSkipped?: number;
+      imagePath?: string;
+      imageType?: "png" | "jpeg";
+    };
+
+function buildProfileQuery(profile?: string): string {
+  return profile ? `?profile=${encodeURIComponent(profile)}` : "";
+}
+
+function withBaseUrl(baseUrl: string | undefined, path: string): string {
+  const trimmed = baseUrl?.trim();
+  if (!trimmed) {
+    return path;
+  }
+  return `${trimmed.replace(/\/$/, "")}${path}`;
+}
+
+export async function browserStatus(
+  baseUrl?: string,
+  opts?: { profile?: string },
+): Promise<BrowserStatus> {
+  const q = buildProfileQuery(opts?.profile);
+  return await fetchBrowserJson<BrowserStatus>(withBaseUrl(baseUrl, `/${q}`), {
+    timeoutMs: 1500,
+  });
+}
+
+export async function browserProfiles(baseUrl?: string): Promise<ProfileStatus[]> {
+  const res = await fetchBrowserJson<{ profiles: ProfileStatus[] }>(
+    withBaseUrl(baseUrl, `/profiles`),
+    {
+      timeoutMs: 3000,
+    },
+  );
+  return res.profiles ?? [];
+}
+
+export async function browserStart(baseUrl?: string, opts?: { profile?: string }): Promise<void> {
+  const q = buildProfileQuery(opts?.profile);
+  await fetchBrowserJson(withBaseUrl(baseUrl, `/start${q}`), {
+    method: "POST",
+    timeoutMs: 15000,
+  });
+}
+
+export async function browserStop(baseUrl?: string, opts?: { profile?: string }): Promise<void> {
+  const q = buildProfileQuery(opts?.profile);
+  await fetchBrowserJson(withBaseUrl(baseUrl, `/stop${q}`), {
+    method: "POST",
+    timeoutMs: 15000,
+  });
+}
+
+export async function browserResetProfile(
+  baseUrl?: string,
+  opts?: { profile?: string },
+): Promise<BrowserResetProfileResult> {
+  const q = buildProfileQuery(opts?.profile);
+  return await fetchBrowserJson<BrowserResetProfileResult>(
+    withBaseUrl(baseUrl, `/reset-profile${q}`),
+    {
+      method: "POST",
+      timeoutMs: 20000,
+    },
+  );
+}
+
+export type BrowserCreateProfileResult = {
+  ok: true;
+  profile: string;
+  cdpPort: number;
+  cdpUrl: string;
+  color: string;
+  isRemote: boolean;
+};
+
+export async function browserCreateProfile(
+  baseUrl: string | undefined,
+  opts: {
+    name: string;
+    color?: string;
+    cdpUrl?: string;
+    driver?: "openclaw" | "extension";
+  },
+): Promise<BrowserCreateProfileResult> {
+  return await fetchBrowserJson<BrowserCreateProfileResult>(
+    withBaseUrl(baseUrl, `/profiles/create`),
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        name: opts.name,
+        color: opts.color,
+        cdpUrl: opts.cdpUrl,
+        driver: opts.driver,
+      }),
+      timeoutMs: 10000,
+    },
+  );
+}
+
+export type BrowserDeleteProfileResult = {
+  ok: true;
+  profile: string;
+  deleted: boolean;
+};
+
+export async function browserDeleteProfile(
+  baseUrl: string | undefined,
+  profile: string,
+): Promise<BrowserDeleteProfileResult> {
+  return await fetchBrowserJson<BrowserDeleteProfileResult>(
+    withBaseUrl(baseUrl, `/profiles/${encodeURIComponent(profile)}`),
+    {
+      method: "DELETE",
+      timeoutMs: 20000,
+    },
+  );
+}
+
+export async function browserTabs(
+  baseUrl?: string,
+  opts?: { profile?: string },
+): Promise<BrowserTab[]> {
+  const q = buildProfileQuery(opts?.profile);
+  const res = await fetchBrowserJson<{ running: boolean; tabs: BrowserTab[] }>(
+    withBaseUrl(baseUrl, `/tabs${q}`),
+    { timeoutMs: 3000 },
+  );
+  return res.tabs ?? [];
+}
+
+export async function browserOpenTab(
+  baseUrl: string | undefined,
+  url: string,
+  opts?: { profile?: string },
+): Promise<BrowserTab> {
+  const q = buildProfileQuery(opts?.profile);
+  return await fetchBrowserJson<BrowserTab>(withBaseUrl(baseUrl, `/tabs/open${q}`), {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ url }),
+    timeoutMs: 15000,
+  });
+}
+
+export async function browserFocusTab(
+  baseUrl: string | undefined,
+  targetId: string,
+  opts?: { profile?: string },
+): Promise<void> {
+  const q = buildProfileQuery(opts?.profile);
+  await fetchBrowserJson(withBaseUrl(baseUrl, `/tabs/focus${q}`), {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ targetId }),
+    timeoutMs: 5000,
+  });
+}
+
+export async function browserCloseTab(
+  baseUrl: string | undefined,
+  targetId: string,
+  opts?: { profile?: string },
+): Promise<void> {
+  const q = buildProfileQuery(opts?.profile);
+  await fetchBrowserJson(withBaseUrl(baseUrl, `/tabs/${encodeURIComponent(targetId)}${q}`), {
+    method: "DELETE",
+    timeoutMs: 5000,
+  });
+}
+
+export async function browserTabAction(
+  baseUrl: string | undefined,
+  opts: {
+    action: "list" | "new" | "close" | "select";
+    index?: number;
+    profile?: string;
+  },
+): Promise<unknown> {
+  const q = buildProfileQuery(opts.profile);
+  return await fetchBrowserJson(withBaseUrl(baseUrl, `/tabs/action${q}`), {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      action: opts.action,
+      index: opts.index,
+    }),
+    timeoutMs: 10_000,
+  });
+}
+
+export async function browserSnapshot(
+  baseUrl: string | undefined,
+  opts: {
+    format: "aria" | "ai";
+    targetId?: string;
+    limit?: number;
+    maxChars?: number;
+    refs?: "role" | "aria";
+    interactive?: boolean;
+    compact?: boolean;
+    depth?: number;
+    selector?: string;
+    frame?: string;
+    labels?: boolean;
+    mode?: "efficient";
+    profile?: string;
+  },
+): Promise<SnapshotResult> {
+  const q = new URLSearchParams();
+  q.set("format", opts.format);
+  if (opts.targetId) {
+    q.set("targetId", opts.targetId);
+  }
+  if (typeof opts.limit === "number") {
+    q.set("limit", String(opts.limit));
+  }
+  if (typeof opts.maxChars === "number" && Number.isFinite(opts.maxChars)) {
+    q.set("maxChars", String(opts.maxChars));
+  }
+  if (opts.refs === "aria" || opts.refs === "role") {
+    q.set("refs", opts.refs);
+  }
+  if (typeof opts.interactive === "boolean") {
+    q.set("interactive", String(opts.interactive));
+  }
+  if (typeof opts.compact === "boolean") {
+    q.set("compact", String(opts.compact));
+  }
+  if (typeof opts.depth === "number" && Number.isFinite(opts.depth)) {
+    q.set("depth", String(opts.depth));
+  }
+  if (opts.selector?.trim()) {
+    q.set("selector", opts.selector.trim());
+  }
+  if (opts.frame?.trim()) {
+    q.set("frame", opts.frame.trim());
+  }
+  if (opts.labels === true) {
+    q.set("labels", "1");
+  }
+  if (opts.mode) {
+    q.set("mode", opts.mode);
+  }
+  if (opts.profile) {
+    q.set("profile", opts.profile);
+  }
+  return await fetchBrowserJson<SnapshotResult>(withBaseUrl(baseUrl, `/snapshot?${q.toString()}`), {
+    timeoutMs: 20000,
+  });
+}
+
+// Actions beyond the basic read-only commands live in client-actions.ts.

package/src/browser/config.ts

@@ -0,0 +1,296 @@
+
+
+import {
+  DEFAULT_OPENCLAW_BROWSER_COLOR,
+  DEFAULT_OPENCLAW_BROWSER_ENABLED,
+  DEFAULT_BROWSER_EVALUATE_ENABLED,
+  DEFAULT_BROWSER_DEFAULT_PROFILE_NAME,
+  DEFAULT_OPENCLAW_BROWSER_PROFILE_NAME,
+} from "./constants.js";
+import { CDP_PORT_RANGE_START, getUsedPorts } from "./profiles.js";
+import { DEFAULT_BROWSER_CONTROL_PORT, deriveDefaultBrowserCdpPortRange, deriveDefaultBrowserControlPort, isLoopbackHost, resolveGatewayPort } from "./enterprise-compat.js";
+import type { BrowserConfig, BrowserProfileConfig, OpenClawConfig, SsrFPolicy } from "./enterprise-compat.js";
+
+export type ResolvedBrowserConfig = {
+  enabled: boolean;
+  evaluateEnabled: boolean;
+  controlPort: number;
+  cdpProtocol: "http" | "https";
+  cdpHost: string;
+  cdpIsLoopback: boolean;
+  remoteCdpTimeoutMs: number;
+  remoteCdpHandshakeTimeoutMs: number;
+  color: string;
+  executablePath?: string;
+  headless: boolean;
+  noSandbox: boolean;
+  attachOnly: boolean;
+  defaultProfile: string;
+  profiles: Record<string, BrowserProfileConfig>;
+  ssrfPolicy?: SsrFPolicy;
+  extraArgs: string[];
+};
+
+export type ResolvedBrowserProfile = {
+  name: string;
+  cdpPort: number;
+  cdpUrl: string;
+  cdpHost: string;
+  cdpIsLoopback: boolean;
+  color: string;
+  driver: "openclaw" | "extension";
+};
+
+function normalizeHexColor(raw: string | undefined) {
+  const value = (raw ?? "").trim();
+  if (!value) {
+    return DEFAULT_OPENCLAW_BROWSER_COLOR;
+  }
+  const normalized = value.startsWith("#") ? value : `#${value}`;
+  if (!/^#[0-9a-fA-F]{6}$/.test(normalized)) {
+    return DEFAULT_OPENCLAW_BROWSER_COLOR;
+  }
+  return normalized.toUpperCase();
+}
+
+function normalizeTimeoutMs(raw: number | undefined, fallback: number) {
+  const value = typeof raw === "number" && Number.isFinite(raw) ? Math.floor(raw) : fallback;
+  return value < 0 ? fallback : value;
+}
+
+function normalizeStringList(raw: string[] | undefined): string[] | undefined {
+  if (!Array.isArray(raw) || raw.length === 0) {
+    return undefined;
+  }
+  const values = raw
+    .map((value) => value.trim())
+    .filter((value): value is string => value.length > 0);
+  return values.length > 0 ? values : undefined;
+}
+
+function resolveBrowserSsrFPolicy(cfg: BrowserConfig | undefined): SsrFPolicy | undefined {
+  const allowPrivateNetwork = cfg?.ssrfPolicy?.allowPrivateNetwork;
+  const allowedHostnames = normalizeStringList(cfg?.ssrfPolicy?.allowedHostnames);
+  const hostnameAllowlist = normalizeStringList(cfg?.ssrfPolicy?.hostnameAllowlist);
+
+  if (
+    allowPrivateNetwork === undefined &&
+    allowedHostnames === undefined &&
+    hostnameAllowlist === undefined
+  ) {
+    return undefined;
+  }
+
+  return {
+    ...(allowPrivateNetwork === true ? { allowPrivateNetwork: true } : {}),
+    ...(allowedHostnames ? { allowedHostnames } : {}),
+    ...(hostnameAllowlist ? { hostnameAllowlist } : {}),
+  };
+}
+
+export function parseHttpUrl(raw: string, label: string) {
+  const trimmed = raw.trim();
+  const parsed = new URL(trimmed);
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new Error(`${label} must be http(s), got: ${parsed.protocol.replace(":", "")}`);
+  }
+
+  const port =
+    parsed.port && Number.parseInt(parsed.port, 10) > 0
+      ? Number.parseInt(parsed.port, 10)
+      : parsed.protocol === "https:"
+        ? 443
+        : 80;
+
+  if (Number.isNaN(port) || port <= 0 || port > 65535) {
+    throw new Error(`${label} has invalid port: ${parsed.port}`);
+  }
+
+  return {
+    parsed,
+    port,
+    normalized: parsed.toString().replace(/\/$/, ""),
+  };
+}
+
+/**
+ * Ensure the default "openclaw" profile exists in the profiles map.
+ * Auto-creates it with the legacy CDP port (from browser.cdpUrl) or first port if missing.
+ */
+function ensureDefaultProfile(
+  profiles: Record<string, BrowserProfileConfig> | undefined,
+  defaultColor: string,
+  legacyCdpPort?: number,
+  derivedDefaultCdpPort?: number,
+): Record<string, BrowserProfileConfig> {
+  const result = { ...profiles };
+  if (!result[DEFAULT_OPENCLAW_BROWSER_PROFILE_NAME]) {
+    result[DEFAULT_OPENCLAW_BROWSER_PROFILE_NAME] = {
+      cdpPort: legacyCdpPort ?? derivedDefaultCdpPort ?? CDP_PORT_RANGE_START,
+      color: defaultColor,
+    };
+  }
+  return result;
+}
+
+/**
+ * Ensure a built-in "chrome" profile exists for the Chrome extension relay.
+ *
+ * Note: this is an OpenClaw browser profile (routing config), not a Chrome user profile.
+ * It points at the local relay CDP endpoint (controlPort + 1).
+ */
+function ensureDefaultChromeExtensionProfile(
+  profiles: Record<string, BrowserProfileConfig>,
+  controlPort: number,
+): Record<string, BrowserProfileConfig> {
+  const result = { ...profiles };
+  if (result.chrome) {
+    return result;
+  }
+  const relayPort = controlPort + 1;
+  if (!Number.isFinite(relayPort) || relayPort <= 0 || relayPort > 65535) {
+    return result;
+  }
+  // Avoid adding the built-in profile if the derived relay port is already used by another profile
+  // (legacy single-profile configs may use controlPort+1 for openclaw/openclaw CDP).
+  if (getUsedPorts(result).has(relayPort)) {
+    return result;
+  }
+  result.chrome = {
+    driver: "extension",
+    cdpUrl: `http://127.0.0.1:${relayPort}`,
+    color: "#00AA00",
+  };
+  return result;
+}
+export function resolveBrowserConfig(
+  cfg: BrowserConfig | undefined,
+  rootConfig?: OpenClawConfig,
+): ResolvedBrowserConfig {
+  const enabled = cfg?.enabled ?? DEFAULT_OPENCLAW_BROWSER_ENABLED;
+  const evaluateEnabled = cfg?.evaluateEnabled ?? DEFAULT_BROWSER_EVALUATE_ENABLED;
+  const gatewayPort = resolveGatewayPort(rootConfig);
+  const controlPort = deriveDefaultBrowserControlPort(gatewayPort ?? DEFAULT_BROWSER_CONTROL_PORT);
+  const defaultColor = normalizeHexColor(cfg?.color);
+  const remoteCdpTimeoutMs = normalizeTimeoutMs(cfg?.remoteCdpTimeoutMs, 1500);
+  const remoteCdpHandshakeTimeoutMs = normalizeTimeoutMs(
+    cfg?.remoteCdpHandshakeTimeoutMs,
+    Math.max(2000, remoteCdpTimeoutMs * 2),
+  );
+
+  const derivedCdpRange = deriveDefaultBrowserCdpPortRange(controlPort);
+
+  const rawCdpUrl = (cfg?.cdpUrl ?? "").trim();
+  let cdpInfo:
+    | {
+        parsed: URL;
+        port: number;
+        normalized: string;
+      }
+    | undefined;
+  if (rawCdpUrl) {
+    cdpInfo = parseHttpUrl(rawCdpUrl, "browser.cdpUrl");
+  } else {
+    const derivedPort = controlPort + 1;
+    if (derivedPort > 65535) {
+      throw new Error(
+        `Derived CDP port (${derivedPort}) is too high; check gateway port configuration.`,
+      );
+    }
+    const derived = new URL(`http://127.0.0.1:${derivedPort}`);
+    cdpInfo = {
+      parsed: derived,
+      port: derivedPort,
+      normalized: derived.toString().replace(/\/$/, ""),
+    };
+  }
+
+  const headless = cfg?.headless === true;
+  const noSandbox = cfg?.noSandbox === true;
+  const attachOnly = cfg?.attachOnly === true;
+  const executablePath = cfg?.executablePath?.trim() || undefined;
+
+  const defaultProfileFromConfig = cfg?.defaultProfile?.trim() || undefined;
+  // Use legacy cdpUrl port for backward compatibility when no profiles configured
+  const legacyCdpPort = rawCdpUrl ? cdpInfo.port : undefined;
+  const profiles = ensureDefaultChromeExtensionProfile(
+    ensureDefaultProfile(cfg?.profiles, defaultColor, legacyCdpPort, derivedCdpRange.start),
+    controlPort,
+  );
+  const cdpProtocol = cdpInfo.parsed.protocol === "https:" ? "https" : "http";
+  const defaultProfile =
+    defaultProfileFromConfig ??
+    (profiles[DEFAULT_BROWSER_DEFAULT_PROFILE_NAME]
+      ? DEFAULT_BROWSER_DEFAULT_PROFILE_NAME
+      : DEFAULT_OPENCLAW_BROWSER_PROFILE_NAME);
+
+  const extraArgs = Array.isArray(cfg?.extraArgs)
+    ? cfg.extraArgs.filter((a): a is string => typeof a === "string" && a.trim().length > 0)
+    : [];
+  const ssrfPolicy = resolveBrowserSsrFPolicy(cfg);
+
+  return {
+    enabled,
+    evaluateEnabled,
+    controlPort,
+    cdpProtocol,
+    cdpHost: cdpInfo.parsed.hostname,
+    cdpIsLoopback: isLoopbackHost(cdpInfo.parsed.hostname),
+    remoteCdpTimeoutMs,
+    remoteCdpHandshakeTimeoutMs,
+    color: defaultColor,
+    executablePath,
+    headless,
+    noSandbox,
+    attachOnly,
+    defaultProfile,
+    profiles,
+    ssrfPolicy,
+    extraArgs,
+  };
+}
+
+/**
+ * Resolve a profile by name from the config.
+ * Returns null if the profile doesn't exist.
+ */
+export function resolveProfile(
+  resolved: ResolvedBrowserConfig,
+  profileName: string,
+): ResolvedBrowserProfile | null {
+  const profile = resolved.profiles[profileName];
+  if (!profile) {
+    return null;
+  }
+
+  const rawProfileUrl = profile.cdpUrl?.trim() ?? "";
+  let cdpHost = resolved.cdpHost;
+  let cdpPort = profile.cdpPort ?? 0;
+  let cdpUrl = "";
+  const driver = profile.driver === "extension" ? "extension" : "openclaw";
+
+  if (rawProfileUrl) {
+    const parsed = parseHttpUrl(rawProfileUrl, `browser.profiles.${profileName}.cdpUrl`);
+    cdpHost = parsed.parsed.hostname;
+    cdpPort = parsed.port;
+    cdpUrl = parsed.normalized;
+  } else if (cdpPort) {
+    cdpUrl = `${resolved.cdpProtocol}://${resolved.cdpHost}:${cdpPort}`;
+  } else {
+    throw new Error(`Profile "${profileName}" must define cdpPort or cdpUrl.`);
+  }
+
+  return {
+    name: profileName,
+    cdpPort,
+    cdpUrl,
+    cdpHost,
+    cdpIsLoopback: isLoopbackHost(cdpHost),
+    color: profile.color,
+    driver,
+  };
+}
+
+export function shouldStartLocalBrowserServer(_resolved: ResolvedBrowserConfig) {
+  return true;
+}

package/src/browser/constants.ts

@@ -0,0 +1,8 @@
+export const DEFAULT_OPENCLAW_BROWSER_ENABLED = true;
+export const DEFAULT_BROWSER_EVALUATE_ENABLED = true;
+export const DEFAULT_OPENCLAW_BROWSER_COLOR = "#FF4500";
+export const DEFAULT_OPENCLAW_BROWSER_PROFILE_NAME = "openclaw";
+export const DEFAULT_BROWSER_DEFAULT_PROFILE_NAME = "chrome";
+export const DEFAULT_AI_SNAPSHOT_MAX_CHARS = 80_000;
+export const DEFAULT_AI_SNAPSHOT_EFFICIENT_MAX_CHARS = 10_000;
+export const DEFAULT_AI_SNAPSHOT_EFFICIENT_DEPTH = 6;