opensteer 0.6.6 → 0.6.8

package/dist/index.cjs

@@ -421,6 +421,7 @@ var init_extractor = __esm({
 var index_exports = {};
 __export(index_exports, {
   ActionWsClient: () => ActionWsClient,
+  BrowserPool: () => BrowserPool,
   BrowserProfileClient: () => BrowserProfileClient,
   CdpOverlayCursorRenderer: () => CdpOverlayCursorRenderer,
   CloudCdpClient: () => CloudCdpClient,
@@ -459,10 +460,15 @@ __export(index_exports, {
   cleanForFull: () => cleanForFull,
   cleanForScrollable: () => cleanForScrollable,
   clearCookies: () => clearCookies,
+  clearPersistentProfileSingletons: () => clearPersistentProfileSingletons,
   cloneElementPath: () => cloneElementPath,
   closeTab: () => closeTab,
+  cloudActionMethods: () => cloudActionMethods,
+  cloudErrorCodes: () => cloudErrorCodes,
   cloudNotLaunchedError: () => cloudNotLaunchedError,
   cloudSessionContractVersion: () => cloudSessionContractVersion,
+  cloudSessionSourceTypes: () => cloudSessionSourceTypes,
+  cloudSessionStatuses: () => cloudSessionStatuses,
   cloudUnsupportedMethodError: () => cloudUnsupportedMethodError,
   collectLocalSelectorCacheEntries: () => collectLocalSelectorCacheEntries,
   countArrayItemsWithPath: () => countArrayItemsWithPath,
@@ -471,6 +477,8 @@ __export(index_exports, {
   createExtractCallback: () => createExtractCallback,
   createResolveCallback: () => createResolveCallback,
   createTab: () => createTab,
+  detectChromePaths: () => detectChromePaths,
+  expandHome: () => expandHome,
   exportCookies: () => exportCookies,
   extractArrayRowsWithPaths: () => extractArrayRowsWithPaths,
   extractArrayWithPaths: () => extractArrayWithPaths,
@@ -481,9 +489,15 @@ __export(index_exports, {
   getElementText: () => getElementText,
   getElementValue: () => getElementValue,
   getModelProvider: () => getModelProvider,
+  getOrCreatePersistentProfile: () => getOrCreatePersistentProfile,
   getPageHtml: () => getPageHtml,
   getPageTitle: () => getPageTitle,
   importCookies: () => importCookies,
+  isCloudActionMethod: () => isCloudActionMethod,
+  isCloudErrorCode: () => isCloudErrorCode,
+  isCloudSessionSourceType: () => isCloudSessionSourceType,
+  isCloudSessionStatus: () => isCloudSessionStatus,
+  listLocalChromeProfiles: () => listLocalChromeProfiles,
   listTabs: () => listTabs,
   markInteractiveElements: () => markInteractiveElements,
   normalizeNamespace: () => normalizeNamespace,
@@ -516,11 +530,8 @@ var import_crypto = require("crypto");
 
 // src/browser/pool.ts
 var import_node_child_process = require("child_process");
-var import_node_fs = require("fs");
-var import_promises = require("fs/promises");
+var import_promises2 = 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
@@ -1013,18 +1024,282 @@ function listLocalChromeProfiles(userDataDir = detectChromePaths().defaultUserDa
   }
 }
 
+// src/browser/persistent-profile.ts
+var import_node_crypto = require("crypto");
+var import_node_fs = require("fs");
+var import_promises = require("fs/promises");
+var import_node_os = require("os");
+var import_node_path = require("path");
+var OPENSTEER_META_FILE = ".opensteer-meta.json";
+var PROCESS_STARTED_AT_MS = Math.floor(Date.now() - process.uptime() * 1e3);
+var PROCESS_START_TIME_TOLERANCE_MS = 1e3;
+var CHROME_SINGLETON_ENTRIES = /* @__PURE__ */ new Set([
+  "SingletonCookie",
+  "SingletonLock",
+  "SingletonSocket",
+  "DevToolsActivePort",
+  "lockfile"
+]);
+var COPY_SKIP_ENTRIES = /* @__PURE__ */ new Set([
+  ...CHROME_SINGLETON_ENTRIES,
+  OPENSTEER_META_FILE
+]);
+var SKIPPED_ROOT_DIRECTORIES = /* @__PURE__ */ new Set([
+  "Crash Reports",
+  "Crashpad",
+  "BrowserMetrics",
+  "GrShaderCache",
+  "ShaderCache",
+  "GraphiteDawnCache",
+  "component_crx_cache",
+  "Crowd Deny",
+  "hyphen-data",
+  "OnDeviceHeadSuggestModel",
+  "OptimizationGuidePredictionModels",
+  "Segmentation Platform",
+  "SmartCardDeviceNames",
+  "WidevineCdm",
+  "pnacl"
+]);
+async function getOrCreatePersistentProfile(sourceUserDataDir, profileDirectory, profilesRootDir = defaultPersistentProfilesRootDir()) {
+  const resolvedSourceUserDataDir = expandHome(sourceUserDataDir);
+  const targetUserDataDir = (0, import_node_path.join)(
+    expandHome(profilesRootDir),
+    buildPersistentProfileKey(resolvedSourceUserDataDir, profileDirectory)
+  );
+  const sourceProfileDir = (0, import_node_path.join)(resolvedSourceUserDataDir, profileDirectory);
+  const metadata = buildPersistentProfileMetadata(
+    resolvedSourceUserDataDir,
+    profileDirectory
+  );
+  await (0, import_promises.mkdir)((0, import_node_path.dirname)(targetUserDataDir), { recursive: true });
+  await cleanOrphanedTempDirs(
+    (0, import_node_path.dirname)(targetUserDataDir),
+    (0, import_node_path.basename)(targetUserDataDir)
+  );
+  if (!(0, import_node_fs.existsSync)(sourceProfileDir)) {
+    throw new Error(
+      `Chrome profile "${profileDirectory}" was not found in "${resolvedSourceUserDataDir}".`
+    );
+  }
+  const created = await createPersistentProfileClone(
+    resolvedSourceUserDataDir,
+    sourceProfileDir,
+    targetUserDataDir,
+    profileDirectory,
+    metadata
+  );
+  await ensurePersistentProfileMetadata(targetUserDataDir, metadata);
+  return {
+    created,
+    userDataDir: targetUserDataDir
+  };
+}
+async function clearPersistentProfileSingletons(userDataDir) {
+  await Promise.all(
+    [...CHROME_SINGLETON_ENTRIES].map(
+      (entry) => (0, import_promises.rm)((0, import_node_path.join)(userDataDir, entry), {
+        force: true,
+        recursive: true
+      }).catch(() => void 0)
+    )
+  );
+}
+function buildPersistentProfileKey(sourceUserDataDir, profileDirectory) {
+  const hash = (0, import_node_crypto.createHash)("sha256").update(`${sourceUserDataDir}\0${profileDirectory}`).digest("hex").slice(0, 16);
+  const sourceLabel = sanitizePathSegment((0, import_node_path.basename)(sourceUserDataDir) || "user-data");
+  const profileLabel = sanitizePathSegment(profileDirectory || "Default");
+  return `${sourceLabel}-${profileLabel}-${hash}`;
+}
+function defaultPersistentProfilesRootDir() {
+  return (0, import_node_path.join)((0, import_node_os.homedir)(), ".opensteer", "real-browser-profiles");
+}
+function sanitizePathSegment(value) {
+  const sanitized = value.replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/-+/g, "-");
+  return sanitized.replace(/^-|-$/g, "") || "profile";
+}
+function isProfileDirectory(userDataDir, entry) {
+  return (0, import_node_fs.existsSync)((0, import_node_path.join)(userDataDir, entry, "Preferences"));
+}
+async function copyRootLevelEntries(sourceUserDataDir, targetUserDataDir, targetProfileDirectory) {
+  let entries;
+  try {
+    entries = await (0, import_promises.readdir)(sourceUserDataDir);
+  } catch {
+    return;
+  }
+  const copyTasks = [];
+  for (const entry of entries) {
+    if (COPY_SKIP_ENTRIES.has(entry)) continue;
+    if (entry === targetProfileDirectory) continue;
+    const sourcePath = (0, import_node_path.join)(sourceUserDataDir, entry);
+    const targetPath = (0, import_node_path.join)(targetUserDataDir, entry);
+    if ((0, import_node_fs.existsSync)(targetPath)) continue;
+    let entryStat;
+    try {
+      entryStat = await (0, import_promises.stat)(sourcePath);
+    } catch {
+      continue;
+    }
+    if (entryStat.isFile()) {
+      copyTasks.push((0, import_promises.copyFile)(sourcePath, targetPath).catch(() => void 0));
+    } else if (entryStat.isDirectory()) {
+      if (isProfileDirectory(sourceUserDataDir, entry)) continue;
+      if (SKIPPED_ROOT_DIRECTORIES.has(entry)) continue;
+      copyTasks.push(
+        (0, import_promises.cp)(sourcePath, targetPath, { recursive: true }).catch(
+          () => void 0
+        )
+      );
+    }
+  }
+  await Promise.all(copyTasks);
+}
+async function writePersistentProfileMetadata(userDataDir, metadata) {
+  await (0, import_promises.writeFile)(
+    (0, import_node_path.join)(userDataDir, OPENSTEER_META_FILE),
+    JSON.stringify(metadata, null, 2)
+  );
+}
+function buildPersistentProfileMetadata(sourceUserDataDir, profileDirectory) {
+  return {
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    profileDirectory,
+    source: sourceUserDataDir
+  };
+}
+async function createPersistentProfileClone(sourceUserDataDir, sourceProfileDir, targetUserDataDir, profileDirectory, metadata) {
+  if ((0, import_node_fs.existsSync)(targetUserDataDir)) {
+    return false;
+  }
+  const tempUserDataDir = await (0, import_promises.mkdtemp)(
+    buildPersistentProfileTempDirPrefix(targetUserDataDir)
+  );
+  let published = false;
+  try {
+    await (0, import_promises.cp)(sourceProfileDir, (0, import_node_path.join)(tempUserDataDir, profileDirectory), {
+      recursive: true
+    });
+    await copyRootLevelEntries(
+      sourceUserDataDir,
+      tempUserDataDir,
+      profileDirectory
+    );
+    await writePersistentProfileMetadata(tempUserDataDir, metadata);
+    try {
+      await (0, import_promises.rename)(tempUserDataDir, targetUserDataDir);
+    } catch (error) {
+      if (wasProfilePublishedByAnotherProcess(error, targetUserDataDir)) {
+        return false;
+      }
+      throw error;
+    }
+    published = true;
+    return true;
+  } finally {
+    if (!published) {
+      await (0, import_promises.rm)(tempUserDataDir, {
+        recursive: true,
+        force: true
+      }).catch(() => void 0);
+    }
+  }
+}
+async function ensurePersistentProfileMetadata(userDataDir, metadata) {
+  if ((0, import_node_fs.existsSync)((0, import_node_path.join)(userDataDir, OPENSTEER_META_FILE))) {
+    return;
+  }
+  await writePersistentProfileMetadata(userDataDir, metadata);
+}
+function wasProfilePublishedByAnotherProcess(error, targetUserDataDir) {
+  const code = typeof error === "object" && error !== null && "code" in error && typeof error.code === "string" ? error.code : void 0;
+  return (0, import_node_fs.existsSync)(targetUserDataDir) && (code === "EEXIST" || code === "ENOTEMPTY" || code === "EPERM");
+}
+function buildPersistentProfileTempDirPrefix(targetUserDataDir) {
+  return (0, import_node_path.join)(
+    (0, import_node_path.dirname)(targetUserDataDir),
+    `${(0, import_node_path.basename)(targetUserDataDir)}-tmp-${process.pid}-${PROCESS_STARTED_AT_MS}-`
+  );
+}
+async function cleanOrphanedTempDirs(profilesDir, targetBaseName) {
+  let entries;
+  try {
+    entries = await (0, import_promises.readdir)(profilesDir, {
+      encoding: "utf8",
+      withFileTypes: true
+    });
+  } catch {
+    return;
+  }
+  const tempDirPrefix = `${targetBaseName}-tmp-`;
+  await Promise.all(
+    entries.map(async (entry) => {
+      if (!entry.isDirectory() || !entry.name.startsWith(tempDirPrefix)) {
+        return;
+      }
+      if (isTempDirOwnedByLiveProcess(entry.name, tempDirPrefix)) {
+        return;
+      }
+      await (0, import_promises.rm)((0, import_node_path.join)(profilesDir, entry.name), {
+        recursive: true,
+        force: true
+      }).catch(() => void 0);
+    })
+  );
+}
+function isTempDirOwnedByLiveProcess(tempDirName, tempDirPrefix) {
+  const owner = parseTempDirOwner(tempDirName, tempDirPrefix);
+  if (!owner) {
+    return false;
+  }
+  if (owner.pid === process.pid && Math.abs(owner.processStartedAtMs - PROCESS_STARTED_AT_MS) <= PROCESS_START_TIME_TOLERANCE_MS) {
+    return true;
+  }
+  return isProcessRunning(owner.pid);
+}
+function parseTempDirOwner(tempDirName, tempDirPrefix) {
+  const remainder = tempDirName.slice(tempDirPrefix.length);
+  const firstDashIndex = remainder.indexOf("-");
+  const secondDashIndex = firstDashIndex === -1 ? -1 : remainder.indexOf("-", firstDashIndex + 1);
+  if (firstDashIndex === -1 || secondDashIndex === -1) {
+    return null;
+  }
+  const pid = Number.parseInt(remainder.slice(0, firstDashIndex), 10);
+  const processStartedAtMs = Number.parseInt(
+    remainder.slice(firstDashIndex + 1, secondDashIndex),
+    10
+  );
+  if (!Number.isInteger(pid) || pid <= 0) {
+    return null;
+  }
+  if (!Number.isInteger(processStartedAtMs) || processStartedAtMs <= 0) {
+    return null;
+  }
+  return { pid, processStartedAtMs };
+}
+function isProcessRunning(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    const code = typeof error === "object" && error !== null && "code" in error && typeof error.code === "string" ? error.code : void 0;
+    return code !== "ESRCH";
+  }
+}
+
 // src/browser/pool.ts
 var BrowserPool = class {
   browser = null;
   cdpProxy = null;
   launchedProcess = null;
-  tempUserDataDir = null;
+  managedUserDataDir = null;
+  persistentProfile = false;
   defaults;
   constructor(defaults = {}) {
     this.defaults = defaults;
   }
   async launch(options = {}) {
-    if (this.browser || this.cdpProxy || this.launchedProcess || this.tempUserDataDir) {
+    if (this.browser || this.cdpProxy || this.launchedProcess || this.managedUserDataDir) {
       await this.close();
     }
     const mode = options.mode ?? this.defaults.mode ?? "chromium";
@@ -1074,11 +1349,13 @@ var BrowserPool = class {
     const browser = this.browser;
     const cdpProxy = this.cdpProxy;
     const launchedProcess = this.launchedProcess;
-    const tempUserDataDir = this.tempUserDataDir;
+    const managedUserDataDir = this.managedUserDataDir;
+    const persistentProfile = this.persistentProfile;
     this.browser = null;
     this.cdpProxy = null;
     this.launchedProcess = null;
-    this.tempUserDataDir = null;
+    this.managedUserDataDir = null;
+    this.persistentProfile = false;
     try {
       if (browser) {
         await browser.close().catch(() => void 0);
@@ -1086,8 +1363,8 @@ var BrowserPool = class {
     } finally {
       cdpProxy?.close();
       await killProcessTree(launchedProcess);
-      if (tempUserDataDir) {
-        await (0, import_promises.rm)(tempUserDataDir, {
+      if (managedUserDataDir && !persistentProfile) {
+        await (0, import_promises2.rm)(managedUserDataDir, {
           recursive: true,
           force: true
         }).catch(() => void 0);
@@ -1136,10 +1413,11 @@ var BrowserPool = class {
       options.userDataDir ?? chromePaths.defaultUserDataDir
     );
     const profileDirectory = options.profileDirectory ?? "Default";
-    const tempUserDataDir = await cloneProfileToTempDir(
+    const persistentProfile = await getOrCreatePersistentProfile(
       sourceUserDataDir,
       profileDirectory
     );
+    await clearPersistentProfileSingletons(persistentProfile.userDataDir);
     const debugPort = await reserveDebugPort();
     const headless = resolveLaunchHeadless(
       "real",
@@ -1147,7 +1425,7 @@ var BrowserPool = class {
       this.defaults.headless
     );
     const launchArgs = buildRealBrowserLaunchArgs({
-      userDataDir: tempUserDataDir,
+      userDataDir: persistentProfile.userDataDir,
       profileDirectory,
       debugPort,
       headless
@@ -1167,24 +1445,22 @@ var BrowserPool = class {
         timeout: options.timeout ?? 3e4
       });
       const { context, page } = await createOwnedBrowserContextAndPage(
-        browser,
-        {
-          headless,
-          initialUrl: options.initialUrl,
-          timeoutMs: options.timeout ?? 3e4
-        }
+        browser
       );
+      if (options.initialUrl) {
+        await page.goto(options.initialUrl, {
+          waitUntil: "domcontentloaded",
+          timeout: options.timeout ?? 3e4
+        });
+      }
       this.browser = browser;
       this.launchedProcess = processHandle;
-      this.tempUserDataDir = tempUserDataDir;
+      this.managedUserDataDir = persistentProfile.userDataDir;
+      this.persistentProfile = true;
       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;
     }
   }
@@ -1207,8 +1483,7 @@ var BrowserPool = class {
 };
 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();
+  const page = await getAttachedPageOrCreate(context);
   return { context, page };
 }
 function resolveLaunchHeadless(mode, requestedHeadless, defaultHeadless) {
@@ -1220,77 +1495,31 @@ function resolveLaunchHeadless(mode, requestedHeadless, defaultHeadless) {
   }
   return mode === "real";
 }
-async function createOwnedBrowserContextAndPage(browser, options) {
+async function createOwnedBrowserContextAndPage(browser) {
   const context = getPrimaryBrowserContext(browser);
-  const page = await createOwnedBrowserPage(browser, context, options);
+  const page = await getExistingPageOrCreate(context);
   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;
+async function getAttachedPageOrCreate(context) {
+  const pages = context.pages();
+  const inspectablePage = pages.find(
+    (candidate) => isInspectablePageUrl2(safePageUrl(candidate))
+  );
+  if (inspectablePage) {
+    return inspectablePage;
   }
-  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);
+  const attachedPage = pages[0];
+  if (attachedPage) {
+    return attachedPage;
   }
+  return await context.newPage();
 }
-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;
+async function getExistingPageOrCreate(context) {
+  const existingPage = context.pages()[0];
+  if (existingPage) {
+    return existingPage;
   }
-  throw new Error(
-    `Chrome created a target for ${options.targetUrl}, but Playwright did not expose the page in time.`
-  );
+  return await context.newPage();
 }
 function getPrimaryBrowserContext(browser) {
   const contexts = browser.contexts();
@@ -1304,19 +1533,11 @@ function getPrimaryBrowserContext(browser) {
 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) {
+function safePageUrl(page) {
   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;
+    return page.url();
   } catch {
-    return currentUrl === initialUrl;
+    return "";
   }
 }
 function normalizeDiscoveryUrl(cdpUrl) {
@@ -1396,38 +1617,12 @@ async function reserveDebugPort() {
     });
   });
 }
-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"
+    "--disable-blink-features=AutomationControlled"
   ];
   if (options.headless) {
     args.push("--headless=new");
@@ -7147,7 +7342,7 @@ async function closeTab(context, activePage, index) {
 }
 
 // src/actions/cookies.ts
-var import_promises2 = require("fs/promises");
+var import_promises3 = require("fs/promises");
 async function getCookies(context, url) {
   return context.cookies(url ? [url] : void 0);
 }
@@ -7159,10 +7354,10 @@ async function clearCookies(context) {
 }
 async function exportCookies(context, filePath, url) {
   const cookies = await context.cookies(url ? [url] : void 0);
-  await (0, import_promises2.writeFile)(filePath, JSON.stringify(cookies, null, 2), "utf-8");
+  await (0, import_promises3.writeFile)(filePath, JSON.stringify(cookies, null, 2), "utf-8");
 }
 async function importCookies(context, filePath) {
-  const raw = await (0, import_promises2.readFile)(filePath, "utf-8");
+  const raw = await (0, import_promises3.readFile)(filePath, "utf-8");
   const cookies = JSON.parse(raw);
   await context.addCookies(cookies);
 }
@@ -7913,31 +8108,31 @@ function buildVariantDescriptorFromCluster(descriptors) {
   const keyStats = /* @__PURE__ */ new Map();
   for (const descriptor of descriptors) {
     for (const field of descriptor.fields) {
-      const stat = keyStats.get(field.path) || {
+      const stat2 = keyStats.get(field.path) || {
         indices: /* @__PURE__ */ new Set(),
         pathNodes: [],
         attributes: [],
         sources: []
       };
-      stat.indices.add(descriptor.index);
+      stat2.indices.add(descriptor.index);
       if (isPersistedValueNode(field.node)) {
-        stat.pathNodes.push(field.node.$path);
-        stat.attributes.push(field.node.attribute);
+        stat2.pathNodes.push(field.node.$path);
+        stat2.attributes.push(field.node.attribute);
       } else if (isPersistedSourceNode(field.node)) {
-        stat.sources.push("current_url");
+        stat2.sources.push("current_url");
       }
-      keyStats.set(field.path, stat);
+      keyStats.set(field.path, stat2);
     }
   }
   const mergedFields = [];
-  for (const [fieldPath, stat] of keyStats) {
-    if (stat.indices.size < threshold) continue;
-    if (stat.pathNodes.length >= threshold) {
+  for (const [fieldPath, stat2] of keyStats) {
+    if (stat2.indices.size < threshold) continue;
+    if (stat2.pathNodes.length >= threshold) {
       let mergedFieldPath = null;
-      if (stat.pathNodes.length === 1) {
-        mergedFieldPath = sanitizeElementPath(stat.pathNodes[0]);
+      if (stat2.pathNodes.length === 1) {
+        mergedFieldPath = sanitizeElementPath(stat2.pathNodes[0]);
       } else {
-        mergedFieldPath = mergeElementPathsByMajority(stat.pathNodes);
+        mergedFieldPath = mergeElementPathsByMajority(stat2.pathNodes);
       }
       if (!mergedFieldPath) continue;
       if (clusterSize === 1) {
@@ -7950,17 +8145,17 @@ function buildVariantDescriptorFromCluster(descriptors) {
         mergedFieldPath,
         "field"
       );
-      const attrThreshold = stat.pathNodes.length === 1 ? 1 : majorityThreshold(stat.pathNodes.length);
+      const attrThreshold = stat2.pathNodes.length === 1 ? 1 : majorityThreshold(stat2.pathNodes.length);
       mergedFields.push({
         path: fieldPath,
         node: createValueNode({
           elementPath: mergedFieldPath,
-          attribute: pickModeString(stat.attributes, attrThreshold)
+          attribute: pickModeString(stat2.attributes, attrThreshold)
         })
       });
       continue;
     }
-    const dominantSource = pickModeString(stat.sources, threshold);
+    const dominantSource = pickModeString(stat2.sources, threshold);
     if (dominantSource === "current_url") {
       mergedFields.push({
         path: fieldPath,
@@ -8829,7 +9024,99 @@ function stripPositionClauses2(path5) {
 }
 
 // src/cloud/contracts.ts
+var cloudActionMethods = [
+  "goto",
+  "snapshot",
+  "screenshot",
+  "state",
+  "click",
+  "dblclick",
+  "rightclick",
+  "hover",
+  "input",
+  "select",
+  "scroll",
+  "tabs",
+  "newTab",
+  "switchTab",
+  "closeTab",
+  "getCookies",
+  "setCookie",
+  "clearCookies",
+  "pressKey",
+  "type",
+  "getElementText",
+  "getElementValue",
+  "getElementAttributes",
+  "getElementBoundingBox",
+  "getHtml",
+  "getTitle",
+  "uploadFile",
+  "exportCookies",
+  "importCookies",
+  "waitForText",
+  "extract",
+  "extractFromPlan",
+  "clearCache"
+];
+var cloudErrorCodes = [
+  "CLOUD_AUTH_FAILED",
+  "CLOUD_SESSION_NOT_FOUND",
+  "CLOUD_SESSION_CLOSED",
+  "CLOUD_UNSUPPORTED_METHOD",
+  "CLOUD_INVALID_REQUEST",
+  "CLOUD_MODEL_NOT_ALLOWED",
+  "CLOUD_ACTION_FAILED",
+  "CLOUD_CAPACITY_EXHAUSTED",
+  "CLOUD_RUNTIME_UNAVAILABLE",
+  "CLOUD_RUNTIME_MISMATCH",
+  "CLOUD_SESSION_STALE",
+  "CLOUD_CONTROL_PLANE_ERROR",
+  "CLOUD_CONTRACT_MISMATCH",
+  "CLOUD_PROXY_UNAVAILABLE",
+  "CLOUD_PROXY_REQUIRED",
+  "CLOUD_BILLING_LIMIT_REACHED",
+  "CLOUD_RATE_LIMITED",
+  "CLOUD_BROWSER_PROFILE_NOT_FOUND",
+  "CLOUD_BROWSER_PROFILE_BUSY",
+  "CLOUD_BROWSER_PROFILE_DISABLED",
+  "CLOUD_BROWSER_PROFILE_PROXY_UNAVAILABLE",
+  "CLOUD_BROWSER_PROFILE_SYNC_FAILED",
+  "CLOUD_INTERNAL"
+];
+var cloudSessionStatuses = [
+  "provisioning",
+  "active",
+  "closing",
+  "closed",
+  "failed"
+];
 var cloudSessionContractVersion = "v3";
+var cloudSessionSourceTypes = [
+  "agent-thread",
+  "agent-run",
+  "project-agent-run",
+  "local-cloud",
+  "manual"
+];
+var cloudActionMethodSet = new Set(cloudActionMethods);
+var cloudErrorCodeSet = new Set(cloudErrorCodes);
+var cloudSessionSourceTypeSet = new Set(
+  cloudSessionSourceTypes
+);
+var cloudSessionStatusSet = new Set(cloudSessionStatuses);
+function isCloudActionMethod(value) {
+  return typeof value === "string" && cloudActionMethodSet.has(value);
+}
+function isCloudErrorCode(value) {
+  return typeof value === "string" && cloudErrorCodeSet.has(value);
+}
+function isCloudSessionSourceType(value) {
+  return typeof value === "string" && cloudSessionSourceTypeSet.has(value);
+}
+function isCloudSessionStatus(value) {
+  return typeof value === "string" && cloudSessionStatusSet.has(value);
+}
 
 // src/cloud/action-ws-client.ts
 var import_ws2 = __toESM(require("ws"), 1);
@@ -8860,6 +9147,13 @@ function cloudNotLaunchedError() {
   );
 }
 
+// src/cloud/ws-url.ts
+function withTokenQuery(wsUrl, token) {
+  const url = new URL(wsUrl);
+  url.searchParams.set("token", token);
+  return url.toString();
+}
+
 // src/cloud/action-ws-client.ts
 var ActionWsClient = class _ActionWsClient {
   ws;
@@ -8988,11 +9282,6 @@ function rawDataToUtf8(raw) {
   if (Array.isArray(raw)) return Buffer.concat(raw).toString("utf8");
   return raw.toString("utf8");
 }
-function withTokenQuery(wsUrl, token) {
-  const url = new URL(wsUrl);
-  url.searchParams.set("token", token);
-  return url.toString();
-}
 
 // src/cloud/local-cache-sync.ts
 var import_fs4 = __toESM(require("fs"), 1);
@@ -9132,7 +9421,7 @@ function dedupeNewest(entries) {
 var import_playwright2 = require("playwright");
 var CloudCdpClient = class {
   async connect(args) {
-    const endpoint = withTokenQuery2(args.wsUrl, args.token);
+    const endpoint = withTokenQuery(args.wsUrl, args.token);
     let browser;
     try {
       browser = await import_playwright2.chromium.connectOverCDP(endpoint);
@@ -9161,7 +9450,7 @@ function selectPreferredContextPage(browser, contexts) {
   let aboutBlankCandidate = null;
   for (const context of contexts) {
     for (const page of context.pages()) {
-      const url = safePageUrl(page);
+      const url = safePageUrl2(page);
       if (!isInternalOrEmptyUrl(url)) {
         return { browser, context, page };
       }
@@ -9172,7 +9461,7 @@ function selectPreferredContextPage(browser, contexts) {
   }
   return aboutBlankCandidate;
 }
-function safePageUrl(page) {
+function safePageUrl2(page) {
   try {
     return page.url();
   } catch {
@@ -9184,11 +9473,6 @@ function isInternalOrEmptyUrl(url) {
   if (url === "about:blank") return true;
   return url.startsWith("chrome://") || url.startsWith("devtools://") || url.startsWith("edge://");
 }
-function withTokenQuery2(wsUrl, token) {
-  const url = new URL(wsUrl);
-  url.searchParams.set("token", token);
-  return url.toString();
-}
 
 // src/utils/strip-trailing-slashes.ts
 function stripTrailingSlashes(value) {
@@ -9225,10 +9509,7 @@ async function parseCloudHttpError(response) {
   return new OpensteerCloudError(code, message, response.status, body?.details);
 }
 function toCloudErrorCode(code) {
-  if (code === "CLOUD_AUTH_FAILED" || code === "CLOUD_SESSION_NOT_FOUND" || code === "CLOUD_SESSION_CLOSED" || code === "CLOUD_UNSUPPORTED_METHOD" || code === "CLOUD_INVALID_REQUEST" || code === "CLOUD_MODEL_NOT_ALLOWED" || code === "CLOUD_ACTION_FAILED" || code === "CLOUD_INTERNAL" || code === "CLOUD_CAPACITY_EXHAUSTED" || code === "CLOUD_RUNTIME_UNAVAILABLE" || code === "CLOUD_RUNTIME_MISMATCH" || code === "CLOUD_SESSION_STALE" || code === "CLOUD_CONTRACT_MISMATCH" || code === "CLOUD_CONTROL_PLANE_ERROR" || code === "CLOUD_PROXY_UNAVAILABLE" || code === "CLOUD_PROXY_REQUIRED" || code === "CLOUD_BILLING_LIMIT_REACHED" || code === "CLOUD_RATE_LIMITED" || code === "CLOUD_BROWSER_PROFILE_NOT_FOUND" || code === "CLOUD_BROWSER_PROFILE_BUSY" || code === "CLOUD_BROWSER_PROFILE_DISABLED" || code === "CLOUD_BROWSER_PROFILE_PROXY_UNAVAILABLE" || code === "CLOUD_BROWSER_PROFILE_SYNC_FAILED") {
-    return code;
-  }
-  return "CLOUD_TRANSPORT_ERROR";
+  return isCloudErrorCode(code) ? code : "CLOUD_TRANSPORT_ERROR";
 }
 
 // src/cloud/session-client.ts
@@ -9335,7 +9616,12 @@ function parseCreateResponse(body, status) {
       status,
       "cloudSession"
     ),
-    state: requireString(cloudSessionRoot, "state", status, "cloudSession"),
+    state: requireSessionStatus(
+      cloudSessionRoot,
+      "state",
+      status,
+      "cloudSession"
+    ),
     createdAt: requireNumber(cloudSessionRoot, "createdAt", status, "cloudSession"),
     sourceType: requireSourceType(cloudSessionRoot, "sourceType", status, "cloudSession"),
     sourceRef: optionalString(cloudSessionRoot, "sourceRef", status, "cloudSession"),
@@ -9423,7 +9709,7 @@ function optionalNumber(source, field, status, parent) {
 }
 function requireSourceType(source, field, status, parent) {
   const value = source[field];
-  if (value === "agent-thread" || value === "agent-run" || value === "local-cloud" || value === "manual") {
+  if (isCloudSessionSourceType(value)) {
     return value;
   }
   throw new OpensteerCloudError(
@@ -9431,13 +9717,30 @@ function requireSourceType(source, field, status, parent) {
     `Invalid cloud session create response: ${formatFieldPath(
       field,
       parent
-    )} must be one of "agent-thread", "agent-run", "local-cloud", or "manual".`,
+    )} must be one of ${formatAllowedValues(cloudSessionSourceTypes)}.`,
+    status
+  );
+}
+function requireSessionStatus(source, field, status, parent) {
+  const value = source[field];
+  if (isCloudSessionStatus(value)) {
+    return value;
+  }
+  throw new OpensteerCloudError(
+    "CLOUD_CONTRACT_MISMATCH",
+    `Invalid cloud session create response: ${formatFieldPath(
+      field,
+      parent
+    )} must be one of ${formatAllowedValues(cloudSessionStatuses)}.`,
     status
   );
 }
 function formatFieldPath(field, parent) {
   return parent ? `"${parent}.${field}"` : `"${field}"`;
 }
+function formatAllowedValues(values) {
+  return values.map((value) => `"${value}"`).join(", ");
+}
 function zeroImportResponse() {
   return {
     imported: 0,
@@ -14846,6 +15149,7 @@ function sleep7(ms) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ActionWsClient,
+  BrowserPool,
   BrowserProfileClient,
   CdpOverlayCursorRenderer,
   CloudCdpClient,
@@ -14884,10 +15188,15 @@ function sleep7(ms) {
   cleanForFull,
   cleanForScrollable,
   clearCookies,
+  clearPersistentProfileSingletons,
   cloneElementPath,
   closeTab,
+  cloudActionMethods,
+  cloudErrorCodes,
   cloudNotLaunchedError,
   cloudSessionContractVersion,
+  cloudSessionSourceTypes,
+  cloudSessionStatuses,
   cloudUnsupportedMethodError,
   collectLocalSelectorCacheEntries,
   countArrayItemsWithPath,
@@ -14896,6 +15205,8 @@ function sleep7(ms) {
   createExtractCallback,
   createResolveCallback,
   createTab,
+  detectChromePaths,
+  expandHome,
   exportCookies,
   extractArrayRowsWithPaths,
   extractArrayWithPaths,
@@ -14906,9 +15217,15 @@ function sleep7(ms) {
   getElementText,
   getElementValue,
   getModelProvider,
+  getOrCreatePersistentProfile,
   getPageHtml,
   getPageTitle,
   importCookies,
+  isCloudActionMethod,
+  isCloudErrorCode,
+  isCloudSessionSourceType,
+  isCloudSessionStatus,
+  listLocalChromeProfiles,
   listTabs,
   markInteractiveElements,
   normalizeNamespace,