opensteer 0.6.2 → 0.6.4

package/dist/cli/server.cjs

@@ -418,13 +418,19 @@ var init_extractor = __esm({
 
 // src/cli/server.ts
 var import_net = require("net");
-var import_fs4 = require("fs");
+var import_fs5 = require("fs");
 
 // src/opensteer.ts
 var import_crypto = require("crypto");
 
 // src/browser/pool.ts
-var import_playwright2 = require("playwright");
+var import_node_child_process = require("child_process");
+var import_node_fs = require("fs");
+var import_promises = require("fs/promises");
+var import_node_net = require("net");
+var import_node_os = require("os");
+var import_node_path = require("path");
+var import_playwright = require("playwright");
 
 // src/browser/cdp-proxy.ts
 var import_ws = __toESM(require("ws"), 1);
@@ -763,209 +769,263 @@ function errorMessage(error) {
   return error instanceof Error ? error.message : String(error);
 }
 
-// src/browser/chromium-profile.ts
-var import_node_util = require("util");
-var import_node_child_process2 = require("child_process");
-var import_node_crypto = require("crypto");
-var import_promises = require("fs/promises");
-var import_node_fs = require("fs");
-var import_node_path = require("path");
-var import_node_os = require("os");
-var import_playwright = require("playwright");
-
-// src/auth/keychain-store.ts
-var import_node_child_process = require("child_process");
-
 // src/browser/chrome.ts
 var import_os = require("os");
 var import_path = require("path");
+var import_fs = require("fs");
+function detectChromePaths() {
+  const os = (0, import_os.platform)();
+  if (os === "darwin") {
+    const executable2 = "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome";
+    return {
+      executable: (0, import_fs.existsSync)(executable2) ? executable2 : null,
+      defaultUserDataDir: (0, import_path.join)(
+        (0, import_os.homedir)(),
+        "Library",
+        "Application Support",
+        "Google",
+        "Chrome"
+      )
+    };
+  }
+  if (os === "win32") {
+    const executable2 = (0, import_path.join)(
+      process.env.PROGRAMFILES || "C:\\Program Files",
+      "Google",
+      "Chrome",
+      "Application",
+      "chrome.exe"
+    );
+    return {
+      executable: (0, import_fs.existsSync)(executable2) ? executable2 : null,
+      defaultUserDataDir: (0, import_path.join)(
+        process.env.LOCALAPPDATA || (0, import_path.join)((0, import_os.homedir)(), "AppData", "Local"),
+        "Google",
+        "Chrome",
+        "User Data"
+      )
+    };
+  }
+  const executable = "/usr/bin/google-chrome";
+  return {
+    executable: (0, import_fs.existsSync)(executable) ? executable : null,
+    defaultUserDataDir: (0, import_path.join)((0, import_os.homedir)(), ".config", "google-chrome")
+  };
+}
 function expandHome(p) {
   if (p.startsWith("~/") || p === "~") {
     return (0, import_path.join)((0, import_os.homedir)(), p.slice(1));
   }
   return p;
 }
-
-// src/browser/chromium-profile.ts
-var execFileAsync = (0, import_node_util.promisify)(import_node_child_process2.execFile);
-function directoryExists(filePath) {
-  try {
-    return (0, import_node_fs.statSync)(filePath).isDirectory();
-  } catch {
-    return false;
+function listLocalChromeProfiles(userDataDir = detectChromePaths().defaultUserDataDir) {
+  const resolvedUserDataDir = expandHome(userDataDir);
+  const localStatePath = (0, import_path.join)(resolvedUserDataDir, "Local State");
+  if (!(0, import_fs.existsSync)(localStatePath)) {
+    return [];
   }
-}
-function fileExists(filePath) {
   try {
-    return (0, import_node_fs.statSync)(filePath).isFile();
-  } catch {
-    return false;
-  }
-}
-function resolveCookieDbPath(profileDir) {
-  const candidates = [(0, import_node_path.join)(profileDir, "Network", "Cookies"), (0, import_node_path.join)(profileDir, "Cookies")];
-  for (const candidate of candidates) {
-    if (fileExists(candidate)) {
-      return candidate;
+    const raw = JSON.parse((0, import_fs.readFileSync)(localStatePath, "utf-8"));
+    const infoCache = raw && typeof raw === "object" && !Array.isArray(raw) && raw.profile && typeof raw.profile === "object" && !Array.isArray(raw.profile) ? raw.profile.info_cache : void 0;
+    if (!infoCache || typeof infoCache !== "object") {
+      return [];
     }
+    return Object.entries(infoCache).map(([directory, info]) => {
+      const record = info && typeof info === "object" && !Array.isArray(info) ? info : {};
+      const name = typeof record.name === "string" && record.name.trim() ? record.name.trim() : directory;
+      return {
+        directory,
+        name
+      };
+    }).filter((profile) => profile.directory.trim().length > 0).sort(
+      (left, right) => left.directory.localeCompare(right.directory)
+    );
+  } catch {
+    return [];
   }
-  return null;
-}
-function resolvePersistentChromiumLaunchProfile(inputPath) {
-  const expandedPath = expandHome(inputPath.trim());
-  if (!expandedPath) {
-    return {
-      userDataDir: inputPath
-    };
-  }
-  if (fileExists(expandedPath) && (0, import_node_path.basename)(expandedPath) === "Cookies") {
-    const directParent = (0, import_node_path.dirname)(expandedPath);
-    const profileDir = (0, import_node_path.basename)(directParent) === "Network" ? (0, import_node_path.dirname)(directParent) : directParent;
-    return {
-      userDataDir: (0, import_node_path.dirname)(profileDir),
-      profileDirectory: (0, import_node_path.basename)(profileDir)
-    };
-  }
-  if (directoryExists(expandedPath) && resolveCookieDbPath(expandedPath) && fileExists((0, import_node_path.join)((0, import_node_path.dirname)(expandedPath), "Local State"))) {
-    return {
-      userDataDir: (0, import_node_path.dirname)(expandedPath),
-      profileDirectory: (0, import_node_path.basename)(expandedPath)
-    };
-  }
-  return {
-    userDataDir: expandedPath
-  };
 }
 
 // src/browser/pool.ts
 var BrowserPool = class {
   browser = null;
-  persistentContext = null;
   cdpProxy = null;
+  launchedProcess = null;
+  tempUserDataDir = null;
   defaults;
   constructor(defaults = {}) {
     this.defaults = defaults;
   }
   async launch(options = {}) {
-    if (this.browser || this.cdpProxy) {
+    if (this.browser || this.cdpProxy || this.launchedProcess || this.tempUserDataDir) {
       await this.close();
     }
-    const connectUrl = options.connectUrl ?? this.defaults.connectUrl;
-    const channel = options.channel ?? this.defaults.channel;
-    const profileDir = options.profileDir ?? this.defaults.profileDir;
-    if (connectUrl) {
-      return this.connectToRunning(connectUrl, options.timeout);
+    const mode = options.mode ?? this.defaults.mode ?? "chromium";
+    const cdpUrl = options.cdpUrl ?? this.defaults.cdpUrl;
+    const userDataDir = options.userDataDir ?? this.defaults.userDataDir;
+    const profileDirectory = options.profileDirectory ?? this.defaults.profileDirectory;
+    const executablePath = options.executablePath ?? this.defaults.executablePath;
+    if (cdpUrl) {
+      if (mode === "real") {
+        throw new Error(
+          'cdpUrl cannot be combined with mode "real". Use one browser launch path at a time.'
+        );
+      }
+      if (userDataDir || profileDirectory) {
+        throw new Error(
+          "userDataDir/profileDirectory cannot be combined with cdpUrl."
+        );
+      }
+      if (options.context && Object.keys(options.context).length > 0) {
+        throw new Error(
+          "context launch options are not supported when attaching over CDP."
+        );
+      }
+      return this.connectToRunning(cdpUrl, options.timeout);
     }
-    if (profileDir) {
-      return this.launchPersistentProfile(options, channel, profileDir);
+    if (mode !== "real" && (userDataDir || profileDirectory)) {
+      throw new Error(
+        'userDataDir/profileDirectory require mode "real".'
+      );
     }
-    if (channel) {
-      return this.launchWithChannel(options, channel);
+    if (mode === "real") {
+      if (options.context && Object.keys(options.context).length > 0) {
+        throw new Error(
+          "context launch options are not supported for real-browser mode."
+        );
+      }
+      return this.launchOwnedRealBrowser({
+        ...options,
+        executablePath,
+        userDataDir,
+        profileDirectory
+      });
     }
     return this.launchSandbox(options);
   }
   async close() {
     const browser = this.browser;
-    const persistentContext = this.persistentContext;
+    const cdpProxy = this.cdpProxy;
+    const launchedProcess = this.launchedProcess;
+    const tempUserDataDir = this.tempUserDataDir;
     this.browser = null;
-    this.persistentContext = null;
+    this.cdpProxy = null;
+    this.launchedProcess = null;
+    this.tempUserDataDir = null;
     try {
-      if (persistentContext) {
-        await persistentContext.close();
-      } else if (browser) {
-        await browser.close();
+      if (browser) {
+        await browser.close().catch(() => void 0);
       }
     } finally {
-      this.cdpProxy?.close();
-      this.cdpProxy = null;
+      cdpProxy?.close();
+      await killProcessTree(launchedProcess);
+      if (tempUserDataDir) {
+        await (0, import_promises.rm)(tempUserDataDir, {
+          recursive: true,
+          force: true
+        }).catch(() => void 0);
+      }
     }
   }
-  async connectToRunning(connectUrl, timeout) {
-    this.cdpProxy?.close();
-    this.cdpProxy = null;
+  async connectToRunning(cdpUrl, timeout) {
     let browser = null;
+    let cdpProxy = null;
     try {
-      const { browserWsUrl, targets } = await discoverTargets(connectUrl);
+      const { browserWsUrl, targets } = await discoverTargets(cdpUrl);
       if (targets.length === 0) {
         throw new Error(
           "No page targets found. Is the browser running with an open window?"
         );
       }
-      const target = targets[0];
-      this.cdpProxy = new CDPProxy(browserWsUrl, target.id);
-      const proxyWsUrl = await this.cdpProxy.start();
-      browser = await import_playwright2.chromium.connectOverCDP(proxyWsUrl, {
+      cdpProxy = new CDPProxy(browserWsUrl, targets[0].id);
+      const proxyWsUrl = await cdpProxy.start();
+      browser = await import_playwright.chromium.connectOverCDP(proxyWsUrl, {
         timeout: timeout ?? 3e4
       });
       this.browser = browser;
-      this.persistentContext = null;
-      const contexts = browser.contexts();
-      if (contexts.length === 0) {
-        throw new Error(
-          "Connection succeeded but no browser contexts found. Is the browser running with an open window?"
-        );
-      }
-      const context = contexts[0];
-      const pages = context.pages();
-      const page = pages.length > 0 ? pages[0] : await context.newPage();
+      this.cdpProxy = cdpProxy;
+      const { context, page } = await pickBrowserContextAndPage(browser);
       return { browser, context, page, isExternal: true };
     } catch (error) {
       if (browser) {
         await browser.close().catch(() => void 0);
       }
+      cdpProxy?.close();
       this.browser = null;
-      this.persistentContext = null;
-      this.cdpProxy?.close();
       this.cdpProxy = null;
       throw error;
     }
   }
-  async launchPersistentProfile(options, channel, profileDir) {
-    const args = [];
-    const launchProfile = resolvePersistentChromiumLaunchProfile(profileDir);
-    if (launchProfile.profileDirectory) {
-      args.push(`--profile-directory=${launchProfile.profileDirectory}`);
-    }
-    const context = await import_playwright2.chromium.launchPersistentContext(
-      launchProfile.userDataDir,
-      {
-        channel,
-        headless: options.headless ?? this.defaults.headless,
-        executablePath: options.executablePath ?? this.defaults.executablePath ?? void 0,
-        slowMo: options.slowMo ?? this.defaults.slowMo ?? 0,
-        timeout: options.timeout,
-        ...options.context || {},
-        args
-      }
-    );
-    const browser = context.browser();
-    if (!browser) {
-      await context.close().catch(() => void 0);
-      throw new Error("Persistent browser launch did not expose a browser instance.");
+  async launchOwnedRealBrowser(options) {
+    const chromePaths = detectChromePaths();
+    const executablePath = options.executablePath ?? chromePaths.executable ?? void 0;
+    if (!executablePath) {
+      throw new Error(
+        "Chrome was not found. Set browser.executablePath or install Chrome in a supported location."
+      );
     }
-    this.browser = browser;
-    this.persistentContext = context;
-    const pages = context.pages();
-    const page = pages.length > 0 ? pages[0] : await context.newPage();
-    return { browser, context, page, isExternal: false };
-  }
-  async launchWithChannel(options, channel) {
-    const browser = await import_playwright2.chromium.launch({
-      channel,
-      headless: options.headless ?? this.defaults.headless,
-      executablePath: options.executablePath ?? this.defaults.executablePath ?? void 0,
-      slowMo: options.slowMo ?? this.defaults.slowMo ?? 0,
-      timeout: options.timeout
+    const sourceUserDataDir = expandHome(
+      options.userDataDir ?? chromePaths.defaultUserDataDir
+    );
+    const profileDirectory = options.profileDirectory ?? "Default";
+    const tempUserDataDir = await cloneProfileToTempDir(
+      sourceUserDataDir,
+      profileDirectory
+    );
+    const debugPort = await reserveDebugPort();
+    const headless = resolveLaunchHeadless(
+      "real",
+      options.headless,
+      this.defaults.headless
+    );
+    const launchArgs = buildRealBrowserLaunchArgs({
+      userDataDir: tempUserDataDir,
+      profileDirectory,
+      debugPort,
+      headless
     });
-    this.browser = browser;
-    this.persistentContext = null;
-    const context = await browser.newContext(options.context || {});
-    const page = await context.newPage();
-    return { browser, context, page, isExternal: false };
+    const processHandle = (0, import_node_child_process.spawn)(executablePath, launchArgs, {
+      detached: process.platform !== "win32",
+      stdio: "ignore"
+    });
+    processHandle.unref();
+    let browser = null;
+    try {
+      const wsUrl = await resolveCdpWebSocketUrl(
+        `http://127.0.0.1:${debugPort}`,
+        options.timeout ?? 3e4
+      );
+      browser = await import_playwright.chromium.connectOverCDP(wsUrl, {
+        timeout: options.timeout ?? 3e4
+      });
+      const { context, page } = await createOwnedBrowserContextAndPage(
+        browser,
+        {
+          headless,
+          initialUrl: options.initialUrl,
+          timeoutMs: options.timeout ?? 3e4
+        }
+      );
+      this.browser = browser;
+      this.launchedProcess = processHandle;
+      this.tempUserDataDir = tempUserDataDir;
+      return { browser, context, page, isExternal: false };
+    } catch (error) {
+      await browser?.close().catch(() => void 0);
+      await killProcessTree(processHandle);
+      await (0, import_promises.rm)(tempUserDataDir, {
+        recursive: true,
+        force: true
+      }).catch(() => void 0);
+      throw error;
+    }
   }
   async launchSandbox(options) {
-    const browser = await import_playwright2.chromium.launch({
-      headless: options.headless ?? this.defaults.headless,
+    const browser = await import_playwright.chromium.launch({
+      headless: resolveLaunchHeadless(
+        "chromium",
+        options.headless,
+        this.defaults.headless
+      ),
       executablePath: options.executablePath ?? this.defaults.executablePath ?? void 0,
       slowMo: options.slowMo ?? this.defaults.slowMo ?? 0,
       timeout: options.timeout
@@ -973,13 +1033,271 @@ var BrowserPool = class {
     const context = await browser.newContext(options.context || {});
     const page = await context.newPage();
     this.browser = browser;
-    this.persistentContext = null;
     return { browser, context, page, isExternal: false };
   }
 };
+async function pickBrowserContextAndPage(browser) {
+  const context = getPrimaryBrowserContext(browser);
+  const pages = context.pages();
+  const page = pages.find((candidate) => isInspectablePageUrl2(candidate.url())) || pages[0] || await context.newPage();
+  return { context, page };
+}
+function resolveLaunchHeadless(mode, requestedHeadless, defaultHeadless) {
+  if (requestedHeadless !== void 0) {
+    return requestedHeadless;
+  }
+  if (defaultHeadless !== void 0) {
+    return defaultHeadless;
+  }
+  return mode === "real";
+}
+async function createOwnedBrowserContextAndPage(browser, options) {
+  const context = getPrimaryBrowserContext(browser);
+  const page = await createOwnedBrowserPage(browser, context, options);
+  return { context, page };
+}
+async function createOwnedBrowserPage(browser, context, options) {
+  const targetUrl = options.initialUrl ?? "about:blank";
+  const existingPages = new Set(context.pages());
+  const browserSession = await browser.newBrowserCDPSession();
+  try {
+    const { targetId } = await browserSession.send("Target.createTarget", {
+      url: targetUrl,
+      newWindow: !options.headless
+    });
+    await browserSession.send("Target.activateTarget", { targetId }).catch(() => void 0);
+    const page = await waitForOwnedBrowserPage(context, {
+      existingPages,
+      targetUrl,
+      timeoutMs: options.timeoutMs
+    });
+    if (targetUrl !== "about:blank") {
+      await page.waitForLoadState("domcontentloaded", {
+        timeout: options.timeoutMs
+      });
+    }
+    await closeDisposableStartupTargets(browserSession, targetId);
+    return page;
+  } finally {
+    await browserSession.detach().catch(() => void 0);
+  }
+}
+async function closeDisposableStartupTargets(browserSession, preservedTargetId) {
+  const response = await browserSession.send("Target.getTargets").catch(() => null);
+  if (!response) {
+    return;
+  }
+  for (const targetInfo of response.targetInfos) {
+    if (targetInfo.targetId === preservedTargetId || targetInfo.type !== "page" || !isDisposableStartupPageUrl(targetInfo.url)) {
+      continue;
+    }
+    await browserSession.send("Target.closeTarget", { targetId: targetInfo.targetId }).catch(() => void 0);
+  }
+}
+async function waitForOwnedBrowserPage(context, options) {
+  const deadline = Date.now() + options.timeoutMs;
+  let fallbackPage = null;
+  while (Date.now() < deadline) {
+    for (const candidate of context.pages()) {
+      if (options.existingPages.has(candidate)) {
+        continue;
+      }
+      const url = candidate.url();
+      if (!isInspectablePageUrl2(url)) {
+        continue;
+      }
+      fallbackPage ??= candidate;
+      if (options.targetUrl === "about:blank") {
+        return candidate;
+      }
+      if (pageLooselyMatchesUrl(url, options.targetUrl)) {
+        return candidate;
+      }
+    }
+    await sleep(100);
+  }
+  if (fallbackPage) {
+    return fallbackPage;
+  }
+  throw new Error(
+    `Chrome created a target for ${options.targetUrl}, but Playwright did not expose the page in time.`
+  );
+}
+function getPrimaryBrowserContext(browser) {
+  const contexts = browser.contexts();
+  if (contexts.length === 0) {
+    throw new Error(
+      "Connection succeeded but no browser contexts were exposed."
+    );
+  }
+  return contexts[0];
+}
+function isInspectablePageUrl2(url) {
+  return url === "about:blank" || url.startsWith("http://") || url.startsWith("https://");
+}
+function isDisposableStartupPageUrl(url) {
+  return url === "about:blank" || url === "chrome://newtab/" || url === "chrome://new-tab-page/";
+}
+function pageLooselyMatchesUrl(currentUrl, initialUrl) {
+  try {
+    const current = new URL(currentUrl);
+    const requested = new URL(initialUrl);
+    if (current.href === requested.href) {
+      return true;
+    }
+    return current.hostname === requested.hostname && current.pathname === requested.pathname;
+  } catch {
+    return currentUrl === initialUrl;
+  }
+}
+function normalizeDiscoveryUrl(cdpUrl) {
+  let parsed;
+  try {
+    parsed = new URL(cdpUrl);
+  } catch {
+    throw new Error(
+      `Invalid CDP URL "${cdpUrl}". Use an http(s) or ws(s) endpoint.`
+    );
+  }
+  if (parsed.protocol === "ws:" || parsed.protocol === "wss:") {
+    return parsed;
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new Error(
+      `Unsupported CDP URL protocol "${parsed.protocol}". Use http(s) or ws(s).`
+    );
+  }
+  const normalized = new URL(parsed.toString());
+  normalized.pathname = "/json/version";
+  normalized.search = "";
+  normalized.hash = "";
+  return normalized;
+}
+async function resolveCdpWebSocketUrl(cdpUrl, timeoutMs) {
+  if (cdpUrl.startsWith("ws://") || cdpUrl.startsWith("wss://")) {
+    return cdpUrl;
+  }
+  const versionUrl = normalizeDiscoveryUrl(cdpUrl);
+  const deadline = Date.now() + timeoutMs;
+  let lastError = "CDP discovery did not respond.";
+  while (Date.now() < deadline) {
+    const remaining = Math.max(deadline - Date.now(), 1e3);
+    try {
+      const response = await fetch(versionUrl, {
+        signal: AbortSignal.timeout(Math.min(remaining, 5e3))
+      });
+      if (!response.ok) {
+        lastError = `${response.status} ${response.statusText}`;
+      } else {
+        const payload = await response.json();
+        const wsUrl = payload && typeof payload === "object" && !Array.isArray(payload) && typeof payload.webSocketDebuggerUrl === "string" ? payload.webSocketDebuggerUrl : null;
+        if (wsUrl && wsUrl.trim()) {
+          return wsUrl;
+        }
+        lastError = "CDP discovery response did not include webSocketDebuggerUrl.";
+      }
+    } catch (error) {
+      lastError = error instanceof Error ? error.message : "Unknown error";
+    }
+    await sleep(100);
+  }
+  throw new Error(
+    `Failed to resolve a CDP websocket URL from ${versionUrl.toString()}: ${lastError}`
+  );
+}
+async function reserveDebugPort() {
+  return await new Promise((resolve, reject) => {
+    const server2 = (0, import_node_net.createServer)();
+    server2.unref();
+    server2.on("error", reject);
+    server2.listen(0, "127.0.0.1", () => {
+      const address = server2.address();
+      if (!address || typeof address === "string") {
+        server2.close();
+        reject(new Error("Failed to reserve a local debug port."));
+        return;
+      }
+      server2.close((error) => {
+        if (error) {
+          reject(error);
+          return;
+        }
+        resolve(address.port);
+      });
+    });
+  });
+}
+async function cloneProfileToTempDir(userDataDir, profileDirectory) {
+  const resolvedUserDataDir = expandHome(userDataDir);
+  const tempUserDataDir = await (0, import_promises.mkdtemp)(
+    (0, import_node_path.join)((0, import_node_os.tmpdir)(), "opensteer-real-browser-")
+  );
+  const sourceProfileDir = (0, import_node_path.join)(resolvedUserDataDir, profileDirectory);
+  const targetProfileDir = (0, import_node_path.join)(tempUserDataDir, profileDirectory);
+  if ((0, import_node_fs.existsSync)(sourceProfileDir)) {
+    await (0, import_promises.cp)(sourceProfileDir, targetProfileDir, {
+      recursive: true
+    });
+  } else {
+    await (0, import_promises.mkdir)(targetProfileDir, {
+      recursive: true
+    });
+  }
+  const localStatePath = (0, import_node_path.join)(resolvedUserDataDir, "Local State");
+  if ((0, import_node_fs.existsSync)(localStatePath)) {
+    await (0, import_promises.copyFile)(localStatePath, (0, import_node_path.join)(tempUserDataDir, "Local State"));
+  }
+  return tempUserDataDir;
+}
+function buildRealBrowserLaunchArgs(options) {
+  const args = [
+    `--user-data-dir=${options.userDataDir}`,
+    `--profile-directory=${options.profileDirectory}`,
+    `--remote-debugging-port=${options.debugPort}`,
+    "--no-first-run",
+    "--no-default-browser-check",
+    "--disable-background-networking",
+    "--disable-sync",
+    "--disable-popup-blocking"
+  ];
+  if (options.headless) {
+    args.push("--headless=new");
+  }
+  return args;
+}
+async function killProcessTree(processHandle) {
+  if (!processHandle || processHandle.pid == null || processHandle.exitCode !== null) {
+    return;
+  }
+  if (process.platform === "win32") {
+    await new Promise((resolve) => {
+      const killer = (0, import_node_child_process.spawn)(
+        "taskkill",
+        ["/pid", String(processHandle.pid), "/t", "/f"],
+        {
+          stdio: "ignore"
+        }
+      );
+      killer.on("error", () => resolve());
+      killer.on("exit", () => resolve());
+    });
+    return;
+  }
+  try {
+    process.kill(-processHandle.pid, "SIGKILL");
+  } catch {
+    try {
+      processHandle.kill("SIGKILL");
+    } catch {
+    }
+  }
+}
+async function sleep(ms) {
+  await new Promise((resolve) => setTimeout(resolve, ms));
+}
 
 // src/config.ts
-var import_fs = __toESM(require("fs"), 1);
+var import_fs2 = __toESM(require("fs"), 1);
 var import_path3 = __toESM(require("path"), 1);
 var import_url = require("url");
 var import_dotenv = require("dotenv");
@@ -1210,6 +1528,65 @@ function toJsonSafeValue(value, seen) {
   return void 0;
 }
 
+// src/cloud/credential-selection.ts
+function selectCloudCredential(options) {
+  const apiKey = normalizeNonEmptyString(options.apiKey);
+  const accessToken = normalizeNonEmptyString(options.accessToken);
+  if (apiKey) {
+    if (options.authScheme === "bearer") {
+      return {
+        apiKey,
+        authScheme: "bearer",
+        kind: "access-token",
+        token: apiKey,
+        compatibilityBearerApiKey: true
+      };
+    }
+    return {
+      apiKey,
+      authScheme: "api-key",
+      kind: "api-key",
+      token: apiKey
+    };
+  }
+  if (accessToken) {
+    return {
+      accessToken,
+      authScheme: "bearer",
+      kind: "access-token",
+      token: accessToken
+    };
+  }
+  return null;
+}
+function selectCloudCredentialByPrecedence(layers, authScheme) {
+  for (const layer of layers) {
+    const hasApiKey = layer.hasApiKey ?? Object.prototype.hasOwnProperty.call(layer, "apiKey");
+    const hasAccessToken = layer.hasAccessToken ?? Object.prototype.hasOwnProperty.call(layer, "accessToken");
+    if (!hasApiKey && !hasAccessToken) {
+      continue;
+    }
+    return {
+      source: layer.source,
+      apiKey: layer.apiKey,
+      accessToken: layer.accessToken,
+      hasApiKey,
+      hasAccessToken,
+      credential: selectCloudCredential({
+        apiKey: layer.apiKey,
+        accessToken: layer.accessToken,
+        authScheme: layer.authScheme ?? authScheme
+      })
+    };
+  }
+  return null;
+}
+function normalizeNonEmptyString(value) {
+  if (typeof value !== "string") return void 0;
+  const normalized = value.trim();
+  return normalized.length ? normalized : void 0;
+}
+
 // src/storage/namespace.ts
 var import_path2 = __toESM(require("path"), 1);
 var DEFAULT_NAMESPACE = "default";
@@ -1248,9 +1625,10 @@ var DEFAULT_CONFIG = {
     headless: false,
     executablePath: void 0,
     slowMo: 0,
-    connectUrl: void 0,
-    channel: void 0,
-    profileDir: void 0
+    mode: void 0,
+    cdpUrl: void 0,
+    userDataDir: void 0,
+    profileDirectory: void 0
   },
   storage: {
     rootDir: process.cwd()
@@ -1287,9 +1665,9 @@ function loadDotenvValues(rootDir, baseEnv, options = {}) {
   const nodeEnv = baseEnv.NODE_ENV?.trim() || "";
   for (const filename of dotenvFileOrder(nodeEnv)) {
     const filePath = import_path3.default.join(baseDir, filename);
-    if (!import_fs.default.existsSync(filePath)) continue;
+    if (!import_fs2.default.existsSync(filePath)) continue;
     try {
-      const raw = import_fs.default.readFileSync(filePath, "utf8");
+      const raw = import_fs2.default.readFileSync(filePath, "utf8");
       const parsed = (0, import_dotenv.parse)(raw);
       for (const [key, value] of Object.entries(parsed)) {
         if (values[key] === void 0) {
@@ -1359,9 +1737,9 @@ function assertNoLegacyRuntimeConfig(source, config) {
 }
 function loadConfigFile(rootDir, options = {}) {
   const configPath = import_path3.default.join(rootDir, ".opensteer", "config.json");
-  if (!import_fs.default.existsSync(configPath)) return {};
+  if (!import_fs2.default.existsSync(configPath)) return {};
   try {
-    const raw = import_fs.default.readFileSync(configPath, "utf8");
+    const raw = import_fs2.default.readFileSync(configPath, "utf8");
     return JSON.parse(raw);
   } catch (error) {
     const message = extractErrorMessage(
@@ -1534,11 +1912,6 @@ function normalizeCloudOptions(value) {
   }
   return value;
 }
-function normalizeNonEmptyString(value) {
-  if (typeof value !== "string") return void 0;
-  const normalized = value.trim();
-  return normalized.length ? normalized : void 0;
-}
 function parseCloudEnabled(value, source) {
   if (value == null) return void 0;
   if (typeof value === "boolean") return value;
@@ -1547,6 +1920,18 @@ function parseCloudEnabled(value, source) {
     `Invalid ${source} value "${String(value)}". Use true, false, or a cloud options object.`
   );
 }
+function resolveCloudCredentialFields(selectedLayer) {
+  const credential = selectedLayer?.credential;
+  if (!credential) return {};
+  if (credential.kind === "api-key" || credential.compatibilityBearerApiKey === true && selectedLayer?.source !== "env") {
+    return {
+      apiKey: credential.token
+    };
+  }
+  return {
+    accessToken: credential.token
+  };
+}
 function resolveCloudSelection(config, env = process.env) {
   const configCloud = parseCloudEnabled(config.cloud, "cloud");
   if (configCloud !== void 0) {
@@ -1583,7 +1968,12 @@ function resolveConfigWithEnv(input = {}, options = {}) {
   });
   assertNoLegacyAiConfig(".opensteer/config.json", fileConfig);
   assertNoLegacyRuntimeConfig(".opensteer/config.json", fileConfig);
+  const fileCloudOptions = normalizeCloudOptions(fileConfig.cloud);
+  const fileHasCloudApiKey = hasOwn(fileCloudOptions, "apiKey");
+  const fileHasCloudAccessToken = hasOwn(fileCloudOptions, "accessToken");
   const fileRootDir = typeof fileConfig.storage?.rootDir === "string" ? fileConfig.storage.rootDir : void 0;
+  assertNoRemovedBrowserConfig(input.browser, "Opensteer constructor config");
+  assertNoRemovedBrowserConfig(fileConfig.browser, ".opensteer/config.json");
   const envRootDir = input.storage?.rootDir ?? fileRootDir ?? initialRootDir;
   const env = resolveEnv(envRootDir, {
     debug: debugHint,
@@ -1599,14 +1989,30 @@ function resolveConfigWithEnv(input = {}, options = {}) {
       "OPENSTEER_RUNTIME is no longer supported. Use OPENSTEER_MODE instead."
     );
   }
+  if (env.OPENSTEER_CONNECT_URL != null) {
+    throw new Error(
+      "OPENSTEER_CONNECT_URL is no longer supported. Use OPENSTEER_CDP_URL instead."
+    );
+  }
+  if (env.OPENSTEER_CHANNEL != null) {
+    throw new Error(
+      "OPENSTEER_CHANNEL is no longer supported. Use OPENSTEER_BROWSER plus OPENSTEER_BROWSER_PATH when needed."
+    );
+  }
+  if (env.OPENSTEER_PROFILE_DIR != null) {
+    throw new Error(
+      "OPENSTEER_PROFILE_DIR is no longer supported. Use OPENSTEER_USER_DATA_DIR and OPENSTEER_PROFILE_DIRECTORY instead."
+    );
+  }
   const envConfig = {
     browser: {
       headless: parseBool(env.OPENSTEER_HEADLESS),
       executablePath: env.OPENSTEER_BROWSER_PATH || void 0,
       slowMo: parseNumber(env.OPENSTEER_SLOW_MO),
-      connectUrl: env.OPENSTEER_CONNECT_URL || void 0,
-      channel: env.OPENSTEER_CHANNEL || void 0,
-      profileDir: env.OPENSTEER_PROFILE_DIR || void 0
+      mode: env.OPENSTEER_BROWSER === "real" || env.OPENSTEER_BROWSER === "chromium" ? env.OPENSTEER_BROWSER : void 0,
+      cdpUrl: env.OPENSTEER_CDP_URL || void 0,
+      userDataDir: env.OPENSTEER_USER_DATA_DIR || void 0,
+      profileDirectory: env.OPENSTEER_PROFILE_DIRECTORY || void 0
     },
     cursor: {
       enabled: parseBool(env.OPENSTEER_CURSOR)
@@ -1617,17 +2023,38 @@ function resolveConfigWithEnv(input = {}, options = {}) {
   const mergedWithFile = mergeDeep(runtimeDefaults, fileConfig);
   const mergedWithEnv = mergeDeep(mergedWithFile, envConfig);
   const resolved = mergeDeep(mergedWithEnv, input);
+  const browserHeadlessExplicit = input.browser?.headless !== void 0 || fileConfig.browser?.headless !== void 0 || envConfig.browser?.headless !== void 0;
+  if (!browserHeadlessExplicit && resolved.browser?.mode === "real") {
+    resolved.browser = {
+      ...resolved.browser,
+      headless: true
+    };
+  }
+  function assertNoRemovedBrowserConfig(value, source) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      return;
+    }
+    const record = value;
+    if (record.connectUrl !== void 0) {
+      throw new Error(
+        `${source}.browser.connectUrl is no longer supported. Use browser.cdpUrl instead.`
+      );
+    }
+    if (record.channel !== void 0) {
+      throw new Error(
+        `${source}.browser.channel is no longer supported. Use browser.mode plus browser.executablePath instead.`
+      );
+    }
+    if (record.profileDir !== void 0) {
+      throw new Error(
+        `${source}.browser.profileDir is no longer supported. Use browser.userDataDir and browser.profileDirectory instead.`
+      );
+    }
+  }
   const envApiKey = resolveOpensteerApiKey(env);
   const envAccessTokenRaw = resolveOpensteerAccessToken(env);
   const envBaseUrl = resolveOpensteerBaseUrl(env);
   const envAuthScheme = resolveOpensteerAuthScheme(env);
-  if (envApiKey && envAccessTokenRaw) {
-    throw new Error(
-      "OPENSTEER_API_KEY and OPENSTEER_ACCESS_TOKEN are mutually exclusive. Set only one."
-    );
-  }
-  const envAccessToken = envAccessTokenRaw || (envAuthScheme === "bearer" ? envApiKey : void 0);
-  const envApiCredential = envAuthScheme === "bearer" && !envAccessTokenRaw ? void 0 : envApiKey;
   const envCloudProfileId = resolveOpensteerCloudProfileId(env);
   const envCloudProfileReuseIfActive = resolveOpensteerCloudProfileReuseIfActive(env);
   const envCloudAnnounce = parseCloudAnnounce(
@@ -1656,11 +2083,6 @@ function resolveConfigWithEnv(input = {}, options = {}) {
   const inputHasCloudBaseUrl = Boolean(
     inputCloudOptions && Object.prototype.hasOwnProperty.call(inputCloudOptions, "baseUrl")
   );
-  if (normalizeNonEmptyString(inputCloudOptions?.apiKey) && normalizeNonEmptyString(inputCloudOptions?.accessToken)) {
-    throw new Error(
-      "cloud.apiKey and cloud.accessToken are mutually exclusive. Set only one."
-    );
-  }
   const cloudSelection = resolveCloudSelection({
     cloud: resolved.cloud
   }, env);
@@ -1671,11 +2093,6 @@ function resolveConfigWithEnv(input = {}, options = {}) {
       accessToken: resolvedCloudAccessTokenRaw,
       ...resolvedCloudRest
     } = resolvedCloud;
-    if (normalizeNonEmptyString(resolvedCloudApiKeyRaw) && normalizeNonEmptyString(resolvedCloudAccessTokenRaw)) {
-      throw new Error(
-        "Cloud config cannot include both apiKey and accessToken at the same time."
-      );
-    }
     const resolvedCloudBrowserProfile = normalizeCloudBrowserProfileOptions(
       resolvedCloud.browserProfile,
       "resolved.cloud.browserProfile"
@@ -1687,25 +2104,40 @@ function resolveConfigWithEnv(input = {}, options = {}) {
     const browserProfile = inputCloudBrowserProfile ?? envCloudBrowserProfile ?? resolvedCloudBrowserProfile;
     let authScheme = inputAuthScheme ?? envAuthScheme ?? parseAuthScheme(resolvedCloud.authScheme, "cloud.authScheme") ?? "api-key";
     const announce = inputCloudAnnounce ?? envCloudAnnounce ?? parseCloudAnnounce(resolvedCloud.announce, "cloud.announce") ?? "always";
-    const credentialOverriddenByInput = inputHasCloudApiKey || inputHasCloudAccessToken;
-    let apiKey = normalizeNonEmptyString(resolvedCloudApiKeyRaw);
-    let accessToken = normalizeNonEmptyString(resolvedCloudAccessTokenRaw);
-    if (!credentialOverriddenByInput) {
-      if (envAccessToken) {
-        accessToken = envAccessToken;
-        apiKey = void 0;
-      } else if (envApiCredential) {
-        apiKey = envApiCredential;
-        accessToken = void 0;
-      }
-    }
+    const selectedCredentialLayer = selectCloudCredentialByPrecedence(
+      [
+        {
+          source: "input",
+          apiKey: inputCloudOptions?.apiKey,
+          accessToken: inputCloudOptions?.accessToken,
+          hasApiKey: inputHasCloudApiKey,
+          hasAccessToken: inputHasCloudAccessToken
+        },
+        {
+          source: "env",
+          apiKey: envApiKey,
+          accessToken: envAccessTokenRaw,
+          hasApiKey: envApiKey !== void 0,
+          hasAccessToken: envAccessTokenRaw !== void 0
+        },
+        {
+          source: "file",
+          apiKey: fileCloudOptions?.apiKey,
+          accessToken: fileCloudOptions?.accessToken,
+          hasApiKey: fileHasCloudApiKey,
+          hasAccessToken: fileHasCloudAccessToken
+        }
+      ],
+      authScheme
+    );
+    const { apiKey, accessToken } = resolveCloudCredentialFields(selectedCredentialLayer);
     if (accessToken) {
       authScheme = "bearer";
     }
     resolved.cloud = {
       ...resolvedCloudRest,
-      ...inputHasCloudApiKey ? { apiKey: resolvedCloudApiKeyRaw } : apiKey ? { apiKey } : {},
-      ...inputHasCloudAccessToken ? { accessToken: resolvedCloudAccessTokenRaw } : accessToken ? { accessToken } : {},
+      ...apiKey ? { apiKey } : selectedCredentialLayer?.hasApiKey && !accessToken ? { apiKey: selectedCredentialLayer.apiKey } : {},
+      ...accessToken ? { accessToken } : selectedCredentialLayer?.hasAccessToken && !apiKey ? { accessToken: selectedCredentialLayer.accessToken } : {},
       authScheme,
       announce,
       ...browserProfile ? { browserProfile } : {}
@@ -2134,7 +2566,7 @@ var StealthCdpRuntime = class _StealthCdpRuntime {
           TRANSIENT_CONTEXT_RETRY_DELAY_MS,
           Math.max(0, deadline - Date.now())
         );
-        await sleep(retryDelay);
+        await sleep2(retryDelay);
       }
     }
   }
@@ -2167,7 +2599,7 @@ var StealthCdpRuntime = class _StealthCdpRuntime {
       () => ({ kind: "resolved" }),
       (error) => ({ kind: "rejected", error })
     );
-    const timeoutPromise = sleep(
+    const timeoutPromise = sleep2(
       timeout + FRAME_EVALUATE_GRACE_MS
     ).then(() => ({ kind: "timeout" }));
     const result = await Promise.race([
@@ -2309,14 +2741,14 @@ function isIgnorableFrameError(error) {
   const message = error.message;
   return message.includes("Frame was detached") || message.includes("Target page, context or browser has been closed") || isTransientExecutionContextError(error) || message.includes("No frame for given id found");
 }
-function sleep(ms) {
+function sleep2(ms) {
   return new Promise((resolve) => {
     setTimeout(resolve, ms);
   });
 }
 
 // src/storage/local.ts
-var import_fs2 = __toESM(require("fs"), 1);
+var import_fs3 = __toESM(require("fs"), 1);
 var import_path4 = __toESM(require("path"), 1);
 
 // src/storage/registry.ts
@@ -2360,14 +2792,14 @@ var LocalSelectorStorage = class {
     return import_path4.default.join(this.getNamespaceDir(), this.getSelectorFileName(id));
   }
   ensureDirs() {
-    import_fs2.default.mkdirSync(this.getNamespaceDir(), { recursive: true });
+    import_fs3.default.mkdirSync(this.getNamespaceDir(), { recursive: true });
   }
   loadRegistry() {
     this.ensureDirs();
     const file = this.getRegistryPath();
-    if (!import_fs2.default.existsSync(file)) return createEmptyRegistry(this.namespace);
+    if (!import_fs3.default.existsSync(file)) return createEmptyRegistry(this.namespace);
     try {
-      const raw = import_fs2.default.readFileSync(file, "utf8");
+      const raw = import_fs3.default.readFileSync(file, "utf8");
       return JSON.parse(raw);
     } catch (error) {
       const message = extractErrorMessage(
@@ -2384,16 +2816,16 @@ var LocalSelectorStorage = class {
   }
   saveRegistry(registry) {
     this.ensureDirs();
-    import_fs2.default.writeFileSync(
+    import_fs3.default.writeFileSync(
       this.getRegistryPath(),
       JSON.stringify(registry, null, 2)
     );
   }
   readSelector(id) {
     const file = this.getSelectorPath(id);
-    if (!import_fs2.default.existsSync(file)) return null;
+    if (!import_fs3.default.existsSync(file)) return null;
     try {
-      const raw = import_fs2.default.readFileSync(file, "utf8");
+      const raw = import_fs3.default.readFileSync(file, "utf8");
       return JSON.parse(raw);
     } catch (error) {
       const message = extractErrorMessage(
@@ -2410,15 +2842,15 @@ var LocalSelectorStorage = class {
   }
   writeSelector(payload) {
     this.ensureDirs();
-    import_fs2.default.writeFileSync(
+    import_fs3.default.writeFileSync(
       this.getSelectorPath(payload.id),
       JSON.stringify(payload, null, 2)
     );
   }
   clearNamespace() {
     const dir = this.getNamespaceDir();
-    if (!import_fs2.default.existsSync(dir)) return;
-    import_fs2.default.rmSync(dir, { recursive: true, force: true });
+    if (!import_fs3.default.existsSync(dir)) return;
+    import_fs3.default.rmSync(dir, { recursive: true, force: true });
   }
 };
 
@@ -6862,7 +7294,7 @@ var AdaptiveNetworkTracker = class {
         this.idleSince = 0;
       }
       const remaining = Math.max(1, options.deadline - now);
-      await sleep2(Math.min(NETWORK_POLL_MS, remaining));
+      await sleep3(Math.min(NETWORK_POLL_MS, remaining));
     }
   }
   handleRequestStarted = (request) => {
@@ -6907,7 +7339,7 @@ var AdaptiveNetworkTracker = class {
     return false;
   }
 };
-async function sleep2(ms) {
+async function sleep3(ms) {
   await new Promise((resolve) => {
     setTimeout(resolve, ms);
   });
@@ -8384,15 +8816,15 @@ function withTokenQuery(wsUrl, token) {
 }
 
 // src/cloud/local-cache-sync.ts
-var import_fs3 = __toESM(require("fs"), 1);
+var import_fs4 = __toESM(require("fs"), 1);
 var import_path5 = __toESM(require("path"), 1);
 function collectLocalSelectorCacheEntries(storage, options = {}) {
   const debug = options.debug === true;
   const namespace = storage.getNamespace();
   const namespaceDir = storage.getNamespaceDir();
-  if (!import_fs3.default.existsSync(namespaceDir)) return [];
+  if (!import_fs4.default.existsSync(namespaceDir)) return [];
   const entries = [];
-  const fileNames = import_fs3.default.readdirSync(namespaceDir);
+  const fileNames = import_fs4.default.readdirSync(namespaceDir);
   for (const fileName of fileNames) {
     if (fileName === "index.json" || !fileName.endsWith(".json")) continue;
     const filePath = import_path5.default.join(namespaceDir, fileName);
@@ -8423,7 +8855,7 @@ function collectLocalSelectorCacheEntries(storage, options = {}) {
 }
 function readSelectorFile(filePath, debug) {
   try {
-    const raw = import_fs3.default.readFileSync(filePath, "utf8");
+    const raw = import_fs4.default.readFileSync(filePath, "utf8");
     return JSON.parse(raw);
   } catch (error) {
     const message = extractErrorMessage(
@@ -8518,13 +8950,13 @@ function dedupeNewest(entries) {
 }
 
 // src/cloud/cdp-client.ts
-var import_playwright3 = require("playwright");
+var import_playwright2 = require("playwright");
 var CloudCdpClient = class {
   async connect(args) {
     const endpoint = withTokenQuery2(args.wsUrl, args.token);
     let browser;
     try {
-      browser = await import_playwright3.chromium.connectOverCDP(endpoint);
+      browser = await import_playwright2.chromium.connectOverCDP(endpoint);
     } catch (error) {
       const message = error instanceof Error ? error.message : "Failed to connect to cloud CDP endpoint.";
       throw new OpensteerCloudError("CLOUD_TRANSPORT_ERROR", message);
@@ -10317,7 +10749,7 @@ async function executeAgentAction(page, action) {
     }
     case "wait": {
       const ms = numberOr(action.timeMs, action.time_ms, 1e3);
-      await sleep3(ms);
+      await sleep4(ms);
       return;
     }
     case "goto": {
@@ -10482,7 +10914,7 @@ async function pressKeyCombo(page, combo) {
     }
   }
 }
-function sleep3(ms) {
+function sleep4(ms) {
   return new Promise((resolve) => setTimeout(resolve, Math.max(0, ms)));
 }
 
@@ -10513,7 +10945,7 @@ var OpensteerCuaAgentHandler = class {
       if (isMutatingAgentAction(action)) {
         this.onMutatingAction?.(action);
       }
-      await sleep4(this.config.waitBetweenActionsMs);
+      await sleep5(this.config.waitBetweenActionsMs);
     });
     try {
       const result = await this.client.execute({
@@ -10575,7 +11007,7 @@ var OpensteerCuaAgentHandler = class {
     await this.cursorController.preview({ x, y }, "agent");
   }
 };
-function sleep4(ms) {
+function sleep5(ms) {
   return new Promise((resolve) => setTimeout(resolve, Math.max(0, ms)));
 }
 
@@ -11011,7 +11443,7 @@ var CursorController = class {
       for (const step of motion.points) {
         await this.renderer.move(step, this.style);
         if (motion.stepDelayMs > 0) {
-          await sleep5(motion.stepDelayMs);
+          await sleep6(motion.stepDelayMs);
         }
       }
       if (shouldPulse(intent)) {
@@ -11169,7 +11601,7 @@ function clamp2(value, min, max) {
 function shouldPulse(intent) {
   return intent === "click" || intent === "dblclick" || intent === "rightclick" || intent === "agent";
 }
-function sleep5(ms) {
+function sleep6(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
@@ -11220,30 +11652,20 @@ var Opensteer = class _Opensteer {
     this.pool = new BrowserPool(resolved.browser || {});
     if (cloudSelection.cloud) {
       const cloudConfig = resolved.cloud && typeof resolved.cloud === "object" ? resolved.cloud : void 0;
-      const apiKey = cloudConfig?.apiKey?.trim();
-      const accessToken = cloudConfig?.accessToken?.trim();
-      if (apiKey && accessToken) {
-        throw new Error(
-          "Cloud mode cannot use both cloud.apiKey and cloud.accessToken. Set only one credential."
-        );
-      }
-      let credential = "";
-      let authScheme = cloudConfig?.authScheme ?? "api-key";
-      if (accessToken) {
-        credential = accessToken;
-        authScheme = "bearer";
-      } else if (apiKey) {
-        credential = apiKey;
-      }
+      const credential = selectCloudCredential({
+        apiKey: cloudConfig?.apiKey,
+        accessToken: cloudConfig?.accessToken,
+        authScheme: cloudConfig?.authScheme
+      });
       if (!credential) {
         throw new Error(
           "Cloud mode requires credentials via cloud.apiKey/cloud.accessToken or OPENSTEER_API_KEY/OPENSTEER_ACCESS_TOKEN."
         );
       }
       this.cloud = createCloudRuntimeState(
-        credential,
+        credential.token,
         cloudConfig?.baseUrl,
-        authScheme
+        credential.authScheme
       );
     } else {
       this.cloud = null;
@@ -11564,9 +11986,11 @@ var Opensteer = class _Opensteer {
     }
     const session2 = await this.pool.launch({
       ...options,
-      connectUrl: options.connectUrl ?? this.config.browser?.connectUrl,
-      channel: options.channel ?? this.config.browser?.channel,
-      profileDir: options.profileDir ?? this.config.browser?.profileDir
+      mode: options.mode ?? this.config.browser?.mode,
+      cdpUrl: options.cdpUrl ?? this.config.browser?.cdpUrl,
+      userDataDir: options.userDataDir ?? this.config.browser?.userDataDir,
+      profileDirectory: options.profileDirectory ?? this.config.browser?.profileDirectory,
+      executablePath: options.executablePath ?? this.config.browser?.executablePath
     });
     this.browser = session2.browser;
     this.contextRef = session2.context;
@@ -11597,6 +12021,32 @@ var Opensteer = class _Opensteer {
     instance2.snapshotCache = null;
     return instance2;
   }
+  static listLocalProfiles(userDataDir) {
+    return listLocalChromeProfiles(userDataDir);
+  }
+  static fromSystemChrome(browser = {}, config = {}) {
+    const chromePaths = detectChromePaths();
+    const executablePath = browser.executablePath ?? config.browser?.executablePath ?? chromePaths.executable ?? void 0;
+    if (!executablePath) {
+      throw new Error(
+        "Chrome was not found. Pass executablePath explicitly or install Chrome in a supported location."
+      );
+    }
+    const userDataDir = browser.userDataDir ?? config.browser?.userDataDir ?? chromePaths.defaultUserDataDir;
+    const autoDetectedProfiles = listLocalChromeProfiles(userDataDir);
+    const profileDirectory = browser.profileDirectory ?? config.browser?.profileDirectory ?? autoDetectedProfiles[0]?.directory ?? "Default";
+    return new _Opensteer({
+      ...config,
+      browser: {
+        ...config.browser || {},
+        mode: "real",
+        headless: browser.headless ?? config.browser?.headless ?? true,
+        executablePath,
+        userDataDir,
+        profileDirectory
+      }
+    });
+  }
   async close() {
     this.snapshotCache = null;
     if (this.cloud) {
@@ -14330,10 +14780,12 @@ function buildServerOpenConfig(options) {
       enabled: options.cursorEnabled
     },
     browser: {
-      headless: options.headless ?? false,
-      connectUrl: options.connectUrl,
-      channel: options.channel,
-      profileDir: options.profileDir
+      headless: options.headless,
+      mode: options.mode,
+      cdpUrl: options.cdpUrl,
+      userDataDir: options.userDataDir,
+      profileDirectory: options.profileDirectory,
+      executablePath: options.executablePath
     }
   };
   if (!options.cloudAuth) {
@@ -14385,6 +14837,19 @@ function normalizeAuthScheme(value) {
   );
 }
 
+// src/cli/open-browser-config.ts
+function resolveCliBrowserRequestConfig(options) {
+  const mode = options.browser ?? (options.profileDirectory || options.userDataDir || options.executablePath ? "real" : void 0);
+  return {
+    mode,
+    headless: options.headless ?? (mode === "real" ? true : void 0),
+    cdpUrl: options.cdpUrl,
+    profileDirectory: options.profileDirectory,
+    userDataDir: options.userDataDir,
+    executablePath: options.executablePath
+  };
+}
+
 // src/cli/server.ts
 var instance = null;
 var launchPromise = null;
@@ -14459,15 +14924,15 @@ var socketPath = getSocketPath(session);
 var pidPath = getPidPath(session);
 function cleanup() {
   try {
-    (0, import_fs4.unlinkSync)(socketPath);
+    (0, import_fs5.unlinkSync)(socketPath);
   } catch {
   }
   try {
-    (0, import_fs4.unlinkSync)(pidPath);
+    (0, import_fs5.unlinkSync)(pidPath);
   } catch {
   }
   try {
-    (0, import_fs4.unlinkSync)(getMetadataPath(session));
+    (0, import_fs5.unlinkSync)(getMetadataPath(session));
   } catch {
   }
 }
@@ -14545,9 +15010,11 @@ async function handleRequest(request, socket) {
     try {
       const url = args.url;
       const headless = args.headless;
-      const connectUrl = args["connect-url"];
-      const channel = args.channel;
-      const profileDir = args["profile-dir"];
+      const browser = args.browser === "real" || args.browser === "chromium" ? args.browser : args.browser === void 0 ? void 0 : null;
+      const cdpUrl = args["cdp-url"];
+      const profileDirectory = args.profile;
+      const userDataDir = args["user-data-dir"];
+      const executablePath = args["browser-path"];
       const cloudProfileId = typeof args["cloud-profile-id"] === "string" ? args["cloud-profile-id"].trim() : void 0;
       const cloudProfileReuseIfActive = typeof args["cloud-profile-reuse-if-active"] === "boolean" ? args["cloud-profile-reuse-if-active"] : void 0;
       const requestedCloudProfileBinding = normalizeCloudProfileBinding({
@@ -14562,6 +15029,21 @@ async function handleRequest(request, socket) {
           "--cloud-profile-reuse-if-active requires --cloud-profile-id."
         );
       }
+      if (browser === null) {
+        throw new Error(
+          '--browser must be either "chromium" or "real".'
+        );
+      }
+      if (browser === "chromium" && (profileDirectory || userDataDir || executablePath)) {
+        throw new Error(
+          "--profile, --user-data-dir, and --browser-path require --browser real."
+        );
+      }
+      if (cdpUrl && browser === "real") {
+        throw new Error(
+          "--cdp-url cannot be combined with --browser real."
+        );
+      }
       const requestedCursor = normalizeCursorFlag(args.cursor);
       const requestedName = typeof args.name === "string" && args.name.trim().length > 0 ? sanitizeNamespace(args.name) : null;
       if (requestedCursor !== null) {
@@ -14603,26 +15085,45 @@ async function handleRequest(request, socket) {
           invalidateInstance();
         }
       }
+      const requestedBrowserConfig = resolveCliBrowserRequestConfig({
+        browser: browser ?? void 0,
+        headless,
+        cdpUrl,
+        profileDirectory,
+        userDataDir,
+        executablePath
+      });
       if (instance && !launchPromise) {
         assertCompatibleCloudProfileBinding(
           logicalSession,
           cloudProfileBinding,
           requestedCloudProfileBinding
         );
+        const existingBrowserConfig = instance.getConfig().browser || {};
+        const existingBrowserRecord = existingBrowserConfig;
+        const mismatch = Object.entries(requestedBrowserConfig).find(
+          ([key, value]) => value !== void 0 && existingBrowserRecord[key] !== value
+        );
+        if (mismatch) {
+          const [key, value] = mismatch;
+          throw new Error(
+            `Session '${logicalSession}' is already bound to browser setting "${key}"=${JSON.stringify(existingBrowserRecord[key])}. Requested ${JSON.stringify(value)} does not match. Use the same browser flags for this session or start a different --session.`
+          );
+        }
       }
+      let shouldLaunchInitialUrl = false;
       if (!instance) {
         instance = new Opensteer(
           buildServerOpenConfig({
             scopeDir,
             name: activeNamespace,
             cursorEnabled: effectiveCursorEnabled,
-            headless,
-            connectUrl,
-            channel,
-            profileDir,
+            ...requestedBrowserConfig,
             cloudAuth: cloudAuthOverride
           })
         );
+        const resolvedBrowserConfig = instance.getConfig().browser || {};
+        shouldLaunchInitialUrl = Boolean(url) && resolvedBrowserConfig.mode === "real" && !resolvedBrowserConfig.cdpUrl;
         const nextCloudProfileBinding = resolveSessionCloudProfileBinding(
           instance.getConfig(),
           requestedCloudProfileBinding
@@ -14634,12 +15135,13 @@ async function handleRequest(request, socket) {
           );
         }
         launchPromise = instance.launch({
-          headless: headless ?? false,
+          initialUrl: shouldLaunchInitialUrl ? url : void 0,
+          ...requestedBrowserConfig,
           cloudBrowserProfile: cloudProfileId ? {
             profileId: cloudProfileId,
             reuseIfActive: cloudProfileReuseIfActive
           } : void 0,
-          timeout: connectUrl ? 12e4 : 3e4
+          timeout: cdpUrl ? 12e4 : 3e4
         });
         try {
           await launchPromise;
@@ -14657,7 +15159,7 @@ async function handleRequest(request, socket) {
       } else if (requestedCursor !== null) {
         instance.setCursorEnabled(requestedCursor);
       }
-      if (url) {
+      if (url && !shouldLaunchInitialUrl) {
         await instance.goto(url);
       }
       sendResponse(socket, {
@@ -14787,8 +15289,8 @@ async function handleRequest(request, socket) {
     );
   }
 }
-if ((0, import_fs4.existsSync)(socketPath)) {
-  (0, import_fs4.unlinkSync)(socketPath);
+if ((0, import_fs5.existsSync)(socketPath)) {
+  (0, import_fs5.unlinkSync)(socketPath);
 }
 var server = (0, import_net.createServer)((socket) => {
   let buffer = "";
@@ -14818,7 +15320,7 @@ var server = (0, import_net.createServer)((socket) => {
   });
 });
 server.listen(socketPath, () => {
-  (0, import_fs4.writeFileSync)(pidPath, String(process.pid));
+  (0, import_fs5.writeFileSync)(pidPath, String(process.pid));
   if (process.send) {
     process.send("ready");
   }