opensteer 0.4.7 → 0.4.9

package/CHANGELOG.md

@@ -21,6 +21,8 @@
 - Breaking: `OPENSTEER_MODE` now uses `local` or `cloud`; `remote` is no longer a supported value.
 - Opensteer now enables built-in LLM resolve/extract by default with model `gpt-5.1`.
 - Cloud mode now falls back to `OPENSTEER_API_KEY` when `cloud.apiKey` is omitted.
+- Added automatic `.env` loading from `storage.rootDir` (default `process.cwd()`) so constructor config can consume env vars without requiring `import 'dotenv/config'`.
+- `.env` autoload follows common precedence (`.env.<NODE_ENV>.local`, `.env.local`, `.env.<NODE_ENV>`, `.env`) with `.env.local` skipped in `test`, does not overwrite existing env values, and can be disabled via `OPENSTEER_DISABLE_DOTENV_AUTOLOAD`.
 - Mutating actions now include smart best-effort post-action wait with per-action
   profiles and optional per-call overrides via `wait`.
 - Added structured interaction diagnostics via `OpensteerActionError` for

package/README.md

@@ -164,6 +164,11 @@ Opensteer defaults to local mode.
 - `OPENSTEER_MODE=local` runs local Playwright.
 - `OPENSTEER_MODE=cloud` enables cloud mode (requires `OPENSTEER_API_KEY`).
 - `cloud: true` in constructor config always enables cloud mode.
+- Opensteer auto-loads `.env` files from your `storage.rootDir` (default:
+  `process.cwd()`) using this order: `.env.<NODE_ENV>.local`, `.env.local`
+  (skipped when `NODE_ENV=test`), `.env.<NODE_ENV>`, `.env`.
+- Existing `process.env` values are never overwritten by `.env` values.
+- Set `OPENSTEER_DISABLE_DOTENV_AUTOLOAD=true` to disable auto-loading.
 
 Cloud mode is fail-fast: it does not automatically fall back to local mode.
 

package/dist/{chunk-PIJI7FBH.js → chunk-U6YJI5GO.js}

@@ -341,7 +341,9 @@ var StealthCdpRuntime = class _StealthCdpRuntime {
     const frameRecords = await this.getFrameRecords();
     const mainFrame = frameRecords[0];
     if (!mainFrame) return;
-    await this.waitForFrameVisualStability(mainFrame.frameId, timeout, settleMs);
+    await this.waitForFrameVisualStability(mainFrame.frameId, timeout, settleMs, {
+      retryTransientContextErrors: true
+    });
   }
   async collectVisibleFrameIds() {
     const frameRecords = await this.getFrameRecords();
@@ -370,19 +372,40 @@ var StealthCdpRuntime = class _StealthCdpRuntime {
     }
     return visibleFrameIds;
   }
-  async waitForFrameVisualStability(frameId, timeout, settleMs) {
+  async waitForFrameVisualStability(frameId, timeout, settleMs, options = {}) {
     if (timeout <= 0) return;
     const script = buildStabilityScript(timeout, settleMs);
-    let contextId = await this.ensureFrameContextId(frameId);
-    try {
-      await this.evaluateWithGuard(contextId, script, timeout);
-    } catch (error) {
-      if (!isMissingExecutionContextError(error)) {
-        throw error;
+    const retryTransientContextErrors = options.retryTransientContextErrors ?? true;
+    if (!retryTransientContextErrors) {
+      let contextId = await this.ensureFrameContextId(frameId);
+      try {
+        await this.evaluateWithGuard(contextId, script, timeout);
+      } catch (error) {
+        if (!isMissingExecutionContextReferenceError(error)) {
+          throw error;
+        }
+        this.contextsByFrame.delete(frameId);
+        contextId = await this.ensureFrameContextId(frameId);
+        await this.evaluateWithGuard(contextId, script, timeout);
+      }
+      return;
+    }
+    const deadline = Date.now() + timeout;
+    while (true) {
+      const remaining = Math.max(0, deadline - Date.now());
+      if (remaining === 0) {
+        return;
+      }
+      const contextId = await this.ensureFrameContextId(frameId);
+      try {
+        await this.evaluateWithGuard(contextId, script, remaining);
+        return;
+      } catch (error) {
+        if (!isTransientExecutionContextError(error)) {
+          throw error;
+        }
+        this.contextsByFrame.delete(frameId);
       }
-      this.contextsByFrame.delete(frameId);
-      contextId = await this.ensureFrameContextId(frameId);
-      await this.evaluateWithGuard(contextId, script, timeout);
     }
   }
   async initialize() {
@@ -502,7 +525,10 @@ async function waitForVisualStabilityAcrossFrames(page, options = {}) {
             await runtime.waitForFrameVisualStability(
               frameId,
               remaining,
-              settleMs
+              settleMs,
+              {
+                retryTransientContextErrors: false
+              }
             );
           } catch (error) {
             if (isIgnorableFrameError(error)) return;
@@ -540,7 +566,12 @@ function sameFrameIds(before, after) {
 function formatCdpException(details) {
   return details.exception?.description || details.text || "CDP runtime evaluation failed.";
 }
-function isMissingExecutionContextError(error) {
+function isTransientExecutionContextError(error) {
+  if (!(error instanceof Error)) return false;
+  const message = error.message;
+  return message.includes("Execution context was destroyed") || message.includes("Cannot find context with specified id") || message.includes("Cannot find execution context");
+}
+function isMissingExecutionContextReferenceError(error) {
   if (!(error instanceof Error)) return false;
   const message = error.message;
   return message.includes("Cannot find context with specified id") || message.includes("Cannot find execution context");
@@ -548,7 +579,7 @@ function isMissingExecutionContextError(error) {
 function isIgnorableFrameError(error) {
   if (!(error instanceof Error)) return false;
   const message = error.message;
-  return message.includes("Frame was detached") || message.includes("Execution context was destroyed") || message.includes("Target page, context or browser has been closed") || message.includes("Cannot find context with specified id") || message.includes("Cannot find execution context") || message.includes("No frame for given id found");
+  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) {
   return new Promise((resolve) => {
@@ -5981,6 +6012,7 @@ var BrowserPool = class {
 import fs3 from "fs";
 import path4 from "path";
 import { fileURLToPath } from "url";
+import { parse as parseDotenv } from "dotenv";
 var DEFAULT_CONFIG = {
   browser: {
     headless: false,
@@ -5996,6 +6028,53 @@ var DEFAULT_CONFIG = {
   model: "gpt-5.1",
   debug: false
 };
+function dotenvFileOrder(nodeEnv) {
+  const normalized = nodeEnv?.trim() || "";
+  const files = [];
+  if (normalized) {
+    files.push(`.env.${normalized}.local`);
+  }
+  if (normalized !== "test") {
+    files.push(".env.local");
+  }
+  if (normalized) {
+    files.push(`.env.${normalized}`);
+  }
+  files.push(".env");
+  return files;
+}
+function loadDotenvValues(rootDir, baseEnv) {
+  const values = {};
+  if (parseBool(baseEnv.OPENSTEER_DISABLE_DOTENV_AUTOLOAD) === true) {
+    return values;
+  }
+  const baseDir = path4.resolve(rootDir);
+  const nodeEnv = baseEnv.NODE_ENV?.trim() || "";
+  for (const filename of dotenvFileOrder(nodeEnv)) {
+    const filePath = path4.join(baseDir, filename);
+    if (!fs3.existsSync(filePath)) continue;
+    try {
+      const raw = fs3.readFileSync(filePath, "utf8");
+      const parsed = parseDotenv(raw);
+      for (const [key, value] of Object.entries(parsed)) {
+        if (values[key] === void 0) {
+          values[key] = value;
+        }
+      }
+    } catch {
+      continue;
+    }
+  }
+  return values;
+}
+function resolveEnv(rootDir) {
+  const baseEnv = process.env;
+  const dotenvValues = loadDotenvValues(rootDir, baseEnv);
+  return {
+    ...dotenvValues,
+    ...baseEnv
+  };
+}
 function hasOwn(config, key) {
   if (!config || typeof config !== "object") return false;
   return Object.prototype.hasOwnProperty.call(config, key);
@@ -6124,16 +6203,13 @@ function parseCloudAnnounce(value, source) {
     `Invalid ${source} value "${value}". Use "always", "off", or "tty".`
   );
 }
-function resolveOpensteerApiKey() {
-  const value = process.env.OPENSTEER_API_KEY?.trim();
+function resolveOpensteerApiKey(env) {
+  const value = env.OPENSTEER_API_KEY?.trim();
   if (!value) return void 0;
   return value;
 }
-function resolveOpensteerAuthScheme() {
-  return parseAuthScheme(
-    process.env.OPENSTEER_AUTH_SCHEME,
-    "OPENSTEER_AUTH_SCHEME"
-  );
+function resolveOpensteerAuthScheme(env) {
+  return parseAuthScheme(env.OPENSTEER_AUTH_SCHEME, "OPENSTEER_AUTH_SCHEME");
 }
 function normalizeCloudOptions(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
@@ -6149,7 +6225,7 @@ function parseCloudEnabled(value, source) {
     `Invalid ${source} value "${String(value)}". Use true, false, or a cloud options object.`
   );
 }
-function resolveCloudSelection(config) {
+function resolveCloudSelection(config, env = process.env) {
   const configCloud = parseCloudEnabled(config.cloud, "cloud");
   if (configCloud !== void 0) {
     return {
@@ -6157,10 +6233,7 @@ function resolveCloudSelection(config) {
       source: "config.cloud"
     };
   }
-  const envMode = parseRuntimeMode(
-    process.env.OPENSTEER_MODE,
-    "OPENSTEER_MODE"
-  );
+  const envMode = parseRuntimeMode(env.OPENSTEER_MODE, "OPENSTEER_MODE");
   if (envMode) {
     return {
       cloud: envMode === "cloud",
@@ -6173,41 +6246,49 @@ function resolveCloudSelection(config) {
   };
 }
 function resolveConfig(input = {}) {
-  if (process.env.OPENSTEER_AI_MODEL) {
+  const initialRootDir = input.storage?.rootDir ?? process.cwd();
+  const runtimeDefaults = mergeDeep(DEFAULT_CONFIG, {
+    storage: {
+      rootDir: initialRootDir
+    }
+  });
+  assertNoLegacyAiConfig("Opensteer constructor config", input);
+  assertNoLegacyRuntimeConfig("Opensteer constructor config", input);
+  const fileConfig = loadConfigFile(initialRootDir);
+  assertNoLegacyAiConfig(".opensteer/config.json", fileConfig);
+  assertNoLegacyRuntimeConfig(".opensteer/config.json", fileConfig);
+  const fileRootDir = typeof fileConfig.storage?.rootDir === "string" ? fileConfig.storage.rootDir : void 0;
+  const envRootDir = input.storage?.rootDir ?? fileRootDir ?? initialRootDir;
+  const env = resolveEnv(envRootDir);
+  if (env.OPENSTEER_AI_MODEL) {
     throw new Error(
       "OPENSTEER_AI_MODEL is no longer supported. Use OPENSTEER_MODEL instead."
     );
   }
-  if (process.env.OPENSTEER_RUNTIME != null) {
+  if (env.OPENSTEER_RUNTIME != null) {
     throw new Error(
       "OPENSTEER_RUNTIME is no longer supported. Use OPENSTEER_MODE instead."
     );
   }
-  assertNoLegacyAiConfig("Opensteer constructor config", input);
-  assertNoLegacyRuntimeConfig("Opensteer constructor config", input);
-  const rootDir = input.storage?.rootDir ?? DEFAULT_CONFIG.storage.rootDir ?? process.cwd();
-  const fileConfig = loadConfigFile(rootDir);
-  assertNoLegacyAiConfig(".opensteer/config.json", fileConfig);
-  assertNoLegacyRuntimeConfig(".opensteer/config.json", fileConfig);
   const envConfig = {
     browser: {
-      headless: parseBool(process.env.OPENSTEER_HEADLESS),
-      executablePath: process.env.OPENSTEER_BROWSER_PATH || void 0,
-      slowMo: parseNumber(process.env.OPENSTEER_SLOW_MO),
-      connectUrl: process.env.OPENSTEER_CONNECT_URL || void 0,
-      channel: process.env.OPENSTEER_CHANNEL || void 0,
-      profileDir: process.env.OPENSTEER_PROFILE_DIR || void 0
+      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
     },
-    model: process.env.OPENSTEER_MODEL || void 0,
-    debug: parseBool(process.env.OPENSTEER_DEBUG)
+    model: env.OPENSTEER_MODEL || void 0,
+    debug: parseBool(env.OPENSTEER_DEBUG)
   };
-  const mergedWithFile = mergeDeep(DEFAULT_CONFIG, fileConfig);
+  const mergedWithFile = mergeDeep(runtimeDefaults, fileConfig);
   const mergedWithEnv = mergeDeep(mergedWithFile, envConfig);
   const resolved = mergeDeep(mergedWithEnv, input);
-  const envApiKey = resolveOpensteerApiKey();
-  const envAuthScheme = resolveOpensteerAuthScheme();
+  const envApiKey = resolveOpensteerApiKey(env);
+  const envAuthScheme = resolveOpensteerAuthScheme(env);
   const envCloudAnnounce = parseCloudAnnounce(
-    process.env.OPENSTEER_REMOTE_ANNOUNCE,
+    env.OPENSTEER_REMOTE_ANNOUNCE,
     "OPENSTEER_REMOTE_ANNOUNCE"
   );
   const inputCloudOptions = normalizeCloudOptions(input.cloud);
@@ -6224,7 +6305,7 @@ function resolveConfig(input = {}) {
   );
   const cloudSelection = resolveCloudSelection({
     cloud: resolved.cloud
-  });
+  }, env);
   if (cloudSelection.cloud) {
     const resolvedCloud = normalizeCloudOptions(resolved.cloud) ?? {};
     const authScheme = inputAuthScheme ?? envAuthScheme ?? parseAuthScheme(resolvedCloud.authScheme, "cloud.authScheme") ?? "api-key";

package/dist/cli/server.cjs

@@ -806,6 +806,7 @@ var BrowserPool = class {
 var import_fs = __toESM(require("fs"), 1);
 var import_path3 = __toESM(require("path"), 1);
 var import_url = require("url");
+var import_dotenv = require("dotenv");
 
 // src/storage/namespace.ts
 var import_path2 = __toESM(require("path"), 1);
@@ -855,6 +856,53 @@ var DEFAULT_CONFIG = {
   model: "gpt-5.1",
   debug: false
 };
+function dotenvFileOrder(nodeEnv) {
+  const normalized = nodeEnv?.trim() || "";
+  const files = [];
+  if (normalized) {
+    files.push(`.env.${normalized}.local`);
+  }
+  if (normalized !== "test") {
+    files.push(".env.local");
+  }
+  if (normalized) {
+    files.push(`.env.${normalized}`);
+  }
+  files.push(".env");
+  return files;
+}
+function loadDotenvValues(rootDir, baseEnv) {
+  const values = {};
+  if (parseBool(baseEnv.OPENSTEER_DISABLE_DOTENV_AUTOLOAD) === true) {
+    return values;
+  }
+  const baseDir = import_path3.default.resolve(rootDir);
+  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;
+    try {
+      const raw = import_fs.default.readFileSync(filePath, "utf8");
+      const parsed = (0, import_dotenv.parse)(raw);
+      for (const [key, value] of Object.entries(parsed)) {
+        if (values[key] === void 0) {
+          values[key] = value;
+        }
+      }
+    } catch {
+      continue;
+    }
+  }
+  return values;
+}
+function resolveEnv(rootDir) {
+  const baseEnv = process.env;
+  const dotenvValues = loadDotenvValues(rootDir, baseEnv);
+  return {
+    ...dotenvValues,
+    ...baseEnv
+  };
+}
 function hasOwn(config, key) {
   if (!config || typeof config !== "object") return false;
   return Object.prototype.hasOwnProperty.call(config, key);
@@ -983,16 +1031,13 @@ function parseCloudAnnounce(value, source) {
     `Invalid ${source} value "${value}". Use "always", "off", or "tty".`
   );
 }
-function resolveOpensteerApiKey() {
-  const value = process.env.OPENSTEER_API_KEY?.trim();
+function resolveOpensteerApiKey(env) {
+  const value = env.OPENSTEER_API_KEY?.trim();
   if (!value) return void 0;
   return value;
 }
-function resolveOpensteerAuthScheme() {
-  return parseAuthScheme(
-    process.env.OPENSTEER_AUTH_SCHEME,
-    "OPENSTEER_AUTH_SCHEME"
-  );
+function resolveOpensteerAuthScheme(env) {
+  return parseAuthScheme(env.OPENSTEER_AUTH_SCHEME, "OPENSTEER_AUTH_SCHEME");
 }
 function normalizeCloudOptions(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
@@ -1008,7 +1053,7 @@ function parseCloudEnabled(value, source) {
     `Invalid ${source} value "${String(value)}". Use true, false, or a cloud options object.`
   );
 }
-function resolveCloudSelection(config) {
+function resolveCloudSelection(config, env = process.env) {
   const configCloud = parseCloudEnabled(config.cloud, "cloud");
   if (configCloud !== void 0) {
     return {
@@ -1016,10 +1061,7 @@ function resolveCloudSelection(config) {
       source: "config.cloud"
     };
   }
-  const envMode = parseRuntimeMode(
-    process.env.OPENSTEER_MODE,
-    "OPENSTEER_MODE"
-  );
+  const envMode = parseRuntimeMode(env.OPENSTEER_MODE, "OPENSTEER_MODE");
   if (envMode) {
     return {
       cloud: envMode === "cloud",
@@ -1032,41 +1074,49 @@ function resolveCloudSelection(config) {
   };
 }
 function resolveConfig(input = {}) {
-  if (process.env.OPENSTEER_AI_MODEL) {
+  const initialRootDir = input.storage?.rootDir ?? process.cwd();
+  const runtimeDefaults = mergeDeep(DEFAULT_CONFIG, {
+    storage: {
+      rootDir: initialRootDir
+    }
+  });
+  assertNoLegacyAiConfig("Opensteer constructor config", input);
+  assertNoLegacyRuntimeConfig("Opensteer constructor config", input);
+  const fileConfig = loadConfigFile(initialRootDir);
+  assertNoLegacyAiConfig(".opensteer/config.json", fileConfig);
+  assertNoLegacyRuntimeConfig(".opensteer/config.json", fileConfig);
+  const fileRootDir = typeof fileConfig.storage?.rootDir === "string" ? fileConfig.storage.rootDir : void 0;
+  const envRootDir = input.storage?.rootDir ?? fileRootDir ?? initialRootDir;
+  const env = resolveEnv(envRootDir);
+  if (env.OPENSTEER_AI_MODEL) {
     throw new Error(
       "OPENSTEER_AI_MODEL is no longer supported. Use OPENSTEER_MODEL instead."
     );
   }
-  if (process.env.OPENSTEER_RUNTIME != null) {
+  if (env.OPENSTEER_RUNTIME != null) {
     throw new Error(
       "OPENSTEER_RUNTIME is no longer supported. Use OPENSTEER_MODE instead."
     );
   }
-  assertNoLegacyAiConfig("Opensteer constructor config", input);
-  assertNoLegacyRuntimeConfig("Opensteer constructor config", input);
-  const rootDir = input.storage?.rootDir ?? DEFAULT_CONFIG.storage.rootDir ?? process.cwd();
-  const fileConfig = loadConfigFile(rootDir);
-  assertNoLegacyAiConfig(".opensteer/config.json", fileConfig);
-  assertNoLegacyRuntimeConfig(".opensteer/config.json", fileConfig);
   const envConfig = {
     browser: {
-      headless: parseBool(process.env.OPENSTEER_HEADLESS),
-      executablePath: process.env.OPENSTEER_BROWSER_PATH || void 0,
-      slowMo: parseNumber(process.env.OPENSTEER_SLOW_MO),
-      connectUrl: process.env.OPENSTEER_CONNECT_URL || void 0,
-      channel: process.env.OPENSTEER_CHANNEL || void 0,
-      profileDir: process.env.OPENSTEER_PROFILE_DIR || void 0
+      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
     },
-    model: process.env.OPENSTEER_MODEL || void 0,
-    debug: parseBool(process.env.OPENSTEER_DEBUG)
+    model: env.OPENSTEER_MODEL || void 0,
+    debug: parseBool(env.OPENSTEER_DEBUG)
   };
-  const mergedWithFile = mergeDeep(DEFAULT_CONFIG, fileConfig);
+  const mergedWithFile = mergeDeep(runtimeDefaults, fileConfig);
   const mergedWithEnv = mergeDeep(mergedWithFile, envConfig);
   const resolved = mergeDeep(mergedWithEnv, input);
-  const envApiKey = resolveOpensteerApiKey();
-  const envAuthScheme = resolveOpensteerAuthScheme();
+  const envApiKey = resolveOpensteerApiKey(env);
+  const envAuthScheme = resolveOpensteerAuthScheme(env);
   const envCloudAnnounce = parseCloudAnnounce(
-    process.env.OPENSTEER_REMOTE_ANNOUNCE,
+    env.OPENSTEER_REMOTE_ANNOUNCE,
     "OPENSTEER_REMOTE_ANNOUNCE"
   );
   const inputCloudOptions = normalizeCloudOptions(input.cloud);
@@ -1083,7 +1133,7 @@ function resolveConfig(input = {}) {
   );
   const cloudSelection = resolveCloudSelection({
     cloud: resolved.cloud
-  });
+  }, env);
   if (cloudSelection.cloud) {
     const resolvedCloud = normalizeCloudOptions(resolved.cloud) ?? {};
     const authScheme = inputAuthScheme ?? envAuthScheme ?? parseAuthScheme(resolvedCloud.authScheme, "cloud.authScheme") ?? "api-key";
@@ -1443,7 +1493,9 @@ var StealthCdpRuntime = class _StealthCdpRuntime {
     const frameRecords = await this.getFrameRecords();
     const mainFrame = frameRecords[0];
     if (!mainFrame) return;
-    await this.waitForFrameVisualStability(mainFrame.frameId, timeout, settleMs);
+    await this.waitForFrameVisualStability(mainFrame.frameId, timeout, settleMs, {
+      retryTransientContextErrors: true
+    });
   }
   async collectVisibleFrameIds() {
     const frameRecords = await this.getFrameRecords();
@@ -1472,19 +1524,40 @@ var StealthCdpRuntime = class _StealthCdpRuntime {
     }
     return visibleFrameIds;
   }
-  async waitForFrameVisualStability(frameId, timeout, settleMs) {
+  async waitForFrameVisualStability(frameId, timeout, settleMs, options = {}) {
     if (timeout <= 0) return;
     const script = buildStabilityScript(timeout, settleMs);
-    let contextId = await this.ensureFrameContextId(frameId);
-    try {
-      await this.evaluateWithGuard(contextId, script, timeout);
-    } catch (error) {
-      if (!isMissingExecutionContextError(error)) {
-        throw error;
+    const retryTransientContextErrors = options.retryTransientContextErrors ?? true;
+    if (!retryTransientContextErrors) {
+      let contextId = await this.ensureFrameContextId(frameId);
+      try {
+        await this.evaluateWithGuard(contextId, script, timeout);
+      } catch (error) {
+        if (!isMissingExecutionContextReferenceError(error)) {
+          throw error;
+        }
+        this.contextsByFrame.delete(frameId);
+        contextId = await this.ensureFrameContextId(frameId);
+        await this.evaluateWithGuard(contextId, script, timeout);
+      }
+      return;
+    }
+    const deadline = Date.now() + timeout;
+    while (true) {
+      const remaining = Math.max(0, deadline - Date.now());
+      if (remaining === 0) {
+        return;
+      }
+      const contextId = await this.ensureFrameContextId(frameId);
+      try {
+        await this.evaluateWithGuard(contextId, script, remaining);
+        return;
+      } catch (error) {
+        if (!isTransientExecutionContextError(error)) {
+          throw error;
+        }
+        this.contextsByFrame.delete(frameId);
       }
-      this.contextsByFrame.delete(frameId);
-      contextId = await this.ensureFrameContextId(frameId);
-      await this.evaluateWithGuard(contextId, script, timeout);
     }
   }
   async initialize() {
@@ -1604,7 +1677,10 @@ async function waitForVisualStabilityAcrossFrames(page, options = {}) {
             await runtime.waitForFrameVisualStability(
               frameId,
               remaining,
-              settleMs
+              settleMs,
+              {
+                retryTransientContextErrors: false
+              }
             );
           } catch (error) {
             if (isIgnorableFrameError(error)) return;
@@ -1642,7 +1718,12 @@ function sameFrameIds(before, after) {
 function formatCdpException(details) {
   return details.exception?.description || details.text || "CDP runtime evaluation failed.";
 }
-function isMissingExecutionContextError(error) {
+function isTransientExecutionContextError(error) {
+  if (!(error instanceof Error)) return false;
+  const message = error.message;
+  return message.includes("Execution context was destroyed") || message.includes("Cannot find context with specified id") || message.includes("Cannot find execution context");
+}
+function isMissingExecutionContextReferenceError(error) {
   if (!(error instanceof Error)) return false;
   const message = error.message;
   return message.includes("Cannot find context with specified id") || message.includes("Cannot find execution context");
@@ -1650,7 +1731,7 @@ function isMissingExecutionContextError(error) {
 function isIgnorableFrameError(error) {
   if (!(error instanceof Error)) return false;
   const message = error.message;
-  return message.includes("Frame was detached") || message.includes("Execution context was destroyed") || message.includes("Target page, context or browser has been closed") || message.includes("Cannot find context with specified id") || message.includes("Cannot find execution context") || message.includes("No frame for given id found");
+  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) {
   return new Promise((resolve) => {

package/dist/cli/server.js

@@ -1,6 +1,6 @@
 import {
   Opensteer
-} from "../chunk-PIJI7FBH.js";
+} from "../chunk-U6YJI5GO.js";
 import "../chunk-3H5RRIMZ.js";
 
 // src/cli/server.ts

package/dist/index.cjs

@@ -881,6 +881,7 @@ var BrowserPool = class {
 var import_fs = __toESM(require("fs"), 1);
 var import_path3 = __toESM(require("path"), 1);
 var import_url = require("url");
+var import_dotenv = require("dotenv");
 
 // src/storage/namespace.ts
 var import_path2 = __toESM(require("path"), 1);
@@ -930,6 +931,53 @@ var DEFAULT_CONFIG = {
   model: "gpt-5.1",
   debug: false
 };
+function dotenvFileOrder(nodeEnv) {
+  const normalized = nodeEnv?.trim() || "";
+  const files = [];
+  if (normalized) {
+    files.push(`.env.${normalized}.local`);
+  }
+  if (normalized !== "test") {
+    files.push(".env.local");
+  }
+  if (normalized) {
+    files.push(`.env.${normalized}`);
+  }
+  files.push(".env");
+  return files;
+}
+function loadDotenvValues(rootDir, baseEnv) {
+  const values = {};
+  if (parseBool(baseEnv.OPENSTEER_DISABLE_DOTENV_AUTOLOAD) === true) {
+    return values;
+  }
+  const baseDir = import_path3.default.resolve(rootDir);
+  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;
+    try {
+      const raw = import_fs.default.readFileSync(filePath, "utf8");
+      const parsed = (0, import_dotenv.parse)(raw);
+      for (const [key, value] of Object.entries(parsed)) {
+        if (values[key] === void 0) {
+          values[key] = value;
+        }
+      }
+    } catch {
+      continue;
+    }
+  }
+  return values;
+}
+function resolveEnv(rootDir) {
+  const baseEnv = process.env;
+  const dotenvValues = loadDotenvValues(rootDir, baseEnv);
+  return {
+    ...dotenvValues,
+    ...baseEnv
+  };
+}
 function hasOwn(config, key) {
   if (!config || typeof config !== "object") return false;
   return Object.prototype.hasOwnProperty.call(config, key);
@@ -1058,16 +1106,13 @@ function parseCloudAnnounce(value, source) {
     `Invalid ${source} value "${value}". Use "always", "off", or "tty".`
   );
 }
-function resolveOpensteerApiKey() {
-  const value = process.env.OPENSTEER_API_KEY?.trim();
+function resolveOpensteerApiKey(env) {
+  const value = env.OPENSTEER_API_KEY?.trim();
   if (!value) return void 0;
   return value;
 }
-function resolveOpensteerAuthScheme() {
-  return parseAuthScheme(
-    process.env.OPENSTEER_AUTH_SCHEME,
-    "OPENSTEER_AUTH_SCHEME"
-  );
+function resolveOpensteerAuthScheme(env) {
+  return parseAuthScheme(env.OPENSTEER_AUTH_SCHEME, "OPENSTEER_AUTH_SCHEME");
 }
 function normalizeCloudOptions(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
@@ -1083,7 +1128,7 @@ function parseCloudEnabled(value, source) {
     `Invalid ${source} value "${String(value)}". Use true, false, or a cloud options object.`
   );
 }
-function resolveCloudSelection(config) {
+function resolveCloudSelection(config, env = process.env) {
   const configCloud = parseCloudEnabled(config.cloud, "cloud");
   if (configCloud !== void 0) {
     return {
@@ -1091,10 +1136,7 @@ function resolveCloudSelection(config) {
       source: "config.cloud"
     };
   }
-  const envMode = parseRuntimeMode(
-    process.env.OPENSTEER_MODE,
-    "OPENSTEER_MODE"
-  );
+  const envMode = parseRuntimeMode(env.OPENSTEER_MODE, "OPENSTEER_MODE");
   if (envMode) {
     return {
       cloud: envMode === "cloud",
@@ -1107,41 +1149,49 @@ function resolveCloudSelection(config) {
   };
 }
 function resolveConfig(input = {}) {
-  if (process.env.OPENSTEER_AI_MODEL) {
+  const initialRootDir = input.storage?.rootDir ?? process.cwd();
+  const runtimeDefaults = mergeDeep(DEFAULT_CONFIG, {
+    storage: {
+      rootDir: initialRootDir
+    }
+  });
+  assertNoLegacyAiConfig("Opensteer constructor config", input);
+  assertNoLegacyRuntimeConfig("Opensteer constructor config", input);
+  const fileConfig = loadConfigFile(initialRootDir);
+  assertNoLegacyAiConfig(".opensteer/config.json", fileConfig);
+  assertNoLegacyRuntimeConfig(".opensteer/config.json", fileConfig);
+  const fileRootDir = typeof fileConfig.storage?.rootDir === "string" ? fileConfig.storage.rootDir : void 0;
+  const envRootDir = input.storage?.rootDir ?? fileRootDir ?? initialRootDir;
+  const env = resolveEnv(envRootDir);
+  if (env.OPENSTEER_AI_MODEL) {
     throw new Error(
       "OPENSTEER_AI_MODEL is no longer supported. Use OPENSTEER_MODEL instead."
     );
   }
-  if (process.env.OPENSTEER_RUNTIME != null) {
+  if (env.OPENSTEER_RUNTIME != null) {
     throw new Error(
       "OPENSTEER_RUNTIME is no longer supported. Use OPENSTEER_MODE instead."
     );
   }
-  assertNoLegacyAiConfig("Opensteer constructor config", input);
-  assertNoLegacyRuntimeConfig("Opensteer constructor config", input);
-  const rootDir = input.storage?.rootDir ?? DEFAULT_CONFIG.storage.rootDir ?? process.cwd();
-  const fileConfig = loadConfigFile(rootDir);
-  assertNoLegacyAiConfig(".opensteer/config.json", fileConfig);
-  assertNoLegacyRuntimeConfig(".opensteer/config.json", fileConfig);
   const envConfig = {
     browser: {
-      headless: parseBool(process.env.OPENSTEER_HEADLESS),
-      executablePath: process.env.OPENSTEER_BROWSER_PATH || void 0,
-      slowMo: parseNumber(process.env.OPENSTEER_SLOW_MO),
-      connectUrl: process.env.OPENSTEER_CONNECT_URL || void 0,
-      channel: process.env.OPENSTEER_CHANNEL || void 0,
-      profileDir: process.env.OPENSTEER_PROFILE_DIR || void 0
+      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
     },
-    model: process.env.OPENSTEER_MODEL || void 0,
-    debug: parseBool(process.env.OPENSTEER_DEBUG)
+    model: env.OPENSTEER_MODEL || void 0,
+    debug: parseBool(env.OPENSTEER_DEBUG)
   };
-  const mergedWithFile = mergeDeep(DEFAULT_CONFIG, fileConfig);
+  const mergedWithFile = mergeDeep(runtimeDefaults, fileConfig);
   const mergedWithEnv = mergeDeep(mergedWithFile, envConfig);
   const resolved = mergeDeep(mergedWithEnv, input);
-  const envApiKey = resolveOpensteerApiKey();
-  const envAuthScheme = resolveOpensteerAuthScheme();
+  const envApiKey = resolveOpensteerApiKey(env);
+  const envAuthScheme = resolveOpensteerAuthScheme(env);
   const envCloudAnnounce = parseCloudAnnounce(
-    process.env.OPENSTEER_REMOTE_ANNOUNCE,
+    env.OPENSTEER_REMOTE_ANNOUNCE,
     "OPENSTEER_REMOTE_ANNOUNCE"
   );
   const inputCloudOptions = normalizeCloudOptions(input.cloud);
@@ -1158,7 +1208,7 @@ function resolveConfig(input = {}) {
   );
   const cloudSelection = resolveCloudSelection({
     cloud: resolved.cloud
-  });
+  }, env);
   if (cloudSelection.cloud) {
     const resolvedCloud = normalizeCloudOptions(resolved.cloud) ?? {};
     const authScheme = inputAuthScheme ?? envAuthScheme ?? parseAuthScheme(resolvedCloud.authScheme, "cloud.authScheme") ?? "api-key";
@@ -1518,7 +1568,9 @@ var StealthCdpRuntime = class _StealthCdpRuntime {
     const frameRecords = await this.getFrameRecords();
     const mainFrame = frameRecords[0];
     if (!mainFrame) return;
-    await this.waitForFrameVisualStability(mainFrame.frameId, timeout, settleMs);
+    await this.waitForFrameVisualStability(mainFrame.frameId, timeout, settleMs, {
+      retryTransientContextErrors: true
+    });
   }
   async collectVisibleFrameIds() {
     const frameRecords = await this.getFrameRecords();
@@ -1547,19 +1599,40 @@ var StealthCdpRuntime = class _StealthCdpRuntime {
     }
     return visibleFrameIds;
   }
-  async waitForFrameVisualStability(frameId, timeout, settleMs) {
+  async waitForFrameVisualStability(frameId, timeout, settleMs, options = {}) {
     if (timeout <= 0) return;
     const script = buildStabilityScript(timeout, settleMs);
-    let contextId = await this.ensureFrameContextId(frameId);
-    try {
-      await this.evaluateWithGuard(contextId, script, timeout);
-    } catch (error) {
-      if (!isMissingExecutionContextError(error)) {
-        throw error;
+    const retryTransientContextErrors = options.retryTransientContextErrors ?? true;
+    if (!retryTransientContextErrors) {
+      let contextId = await this.ensureFrameContextId(frameId);
+      try {
+        await this.evaluateWithGuard(contextId, script, timeout);
+      } catch (error) {
+        if (!isMissingExecutionContextReferenceError(error)) {
+          throw error;
+        }
+        this.contextsByFrame.delete(frameId);
+        contextId = await this.ensureFrameContextId(frameId);
+        await this.evaluateWithGuard(contextId, script, timeout);
+      }
+      return;
+    }
+    const deadline = Date.now() + timeout;
+    while (true) {
+      const remaining = Math.max(0, deadline - Date.now());
+      if (remaining === 0) {
+        return;
+      }
+      const contextId = await this.ensureFrameContextId(frameId);
+      try {
+        await this.evaluateWithGuard(contextId, script, remaining);
+        return;
+      } catch (error) {
+        if (!isTransientExecutionContextError(error)) {
+          throw error;
+        }
+        this.contextsByFrame.delete(frameId);
       }
-      this.contextsByFrame.delete(frameId);
-      contextId = await this.ensureFrameContextId(frameId);
-      await this.evaluateWithGuard(contextId, script, timeout);
     }
   }
   async initialize() {
@@ -1679,7 +1752,10 @@ async function waitForVisualStabilityAcrossFrames(page, options = {}) {
             await runtime.waitForFrameVisualStability(
               frameId,
               remaining,
-              settleMs
+              settleMs,
+              {
+                retryTransientContextErrors: false
+              }
             );
           } catch (error) {
             if (isIgnorableFrameError(error)) return;
@@ -1717,7 +1793,12 @@ function sameFrameIds(before, after) {
 function formatCdpException(details) {
   return details.exception?.description || details.text || "CDP runtime evaluation failed.";
 }
-function isMissingExecutionContextError(error) {
+function isTransientExecutionContextError(error) {
+  if (!(error instanceof Error)) return false;
+  const message = error.message;
+  return message.includes("Execution context was destroyed") || message.includes("Cannot find context with specified id") || message.includes("Cannot find execution context");
+}
+function isMissingExecutionContextReferenceError(error) {
   if (!(error instanceof Error)) return false;
   const message = error.message;
   return message.includes("Cannot find context with specified id") || message.includes("Cannot find execution context");
@@ -1725,7 +1806,7 @@ function isMissingExecutionContextError(error) {
 function isIgnorableFrameError(error) {
   if (!(error instanceof Error)) return false;
   const message = error.message;
-  return message.includes("Frame was detached") || message.includes("Execution context was destroyed") || message.includes("Target page, context or browser has been closed") || message.includes("Cannot find context with specified id") || message.includes("Cannot find execution context") || message.includes("No frame for given id found");
+  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) {
   return new Promise((resolve) => {

package/dist/index.js

@@ -68,7 +68,7 @@ import {
   switchTab,
   typeText,
   waitForVisualStability
-} from "./chunk-PIJI7FBH.js";
+} from "./chunk-U6YJI5GO.js";
 import {
   createResolveCallback
 } from "./chunk-SRJLH34D.js";

package/package.json

@@ -1,75 +1,82 @@
 {
-  "name": "opensteer",
-  "version": "0.4.7",
-  "description": "Open-source browser automation SDK with robust selectors and deterministic replay.",
-  "license": "MIT",
-  "type": "module",
-  "bin": {
-    "opensteer": "./bin/opensteer.mjs"
-  },
-  "main": "./dist/index.cjs",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
+    "name": "opensteer",
+    "version": "0.4.9",
+    "packageManager": "pnpm@10.29.3",
+    "description": "Open-source browser automation SDK with robust selectors and deterministic replay.",
+    "license": "MIT",
+    "type": "module",
+    "bin": {
+        "opensteer": "./bin/opensteer.mjs"
+    },
+    "main": "./dist/index.cjs",
+    "module": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js",
+            "require": "./dist/index.cjs"
+        }
+    },
+    "files": [
+        "dist",
+        "bin",
+        "README.md",
+        "LICENSE",
+        "CHANGELOG.md"
+    ],
+    "scripts": {
+        "build": "tsup src/index.ts src/cli/server.ts --dts --format esm,cjs --clean --external ai --external zod --external @ai-sdk/openai --external @ai-sdk/anthropic --external @ai-sdk/google --external @ai-sdk/xai --external @ai-sdk/groq",
+        "prepublishOnly": "pnpm run build",
+        "test": "vitest run",
+        "test:live-web": "vitest run --config vitest.live-web.config.ts",
+        "test:unit": "vitest run tests/html tests/element-path tests/config.test.ts tests/storage",
+        "test:actions": "vitest run tests/actions",
+        "test:integration": "vitest run tests/integration",
+        "test:ai": "vitest run tests/ai tests/e2e/ai-resolve.test.ts tests/e2e/ai-extract-products.test.ts",
+        "test:e2e": "vitest run tests/e2e",
+        "test:app:dev": "pnpm --dir tests/test-app run dev",
+        "typecheck": "tsc -p tsconfig.json --noEmit"
+    },
+    "dependencies": {
+        "@ai-sdk/anthropic": "^3.0.46",
+        "@ai-sdk/google": "^3.0.30",
+        "@ai-sdk/groq": "^3.0.24",
+        "@ai-sdk/openai": "^3.0.26",
+        "@ai-sdk/xai": "^3.0.57",
+        "ai": "^6.0.77",
+        "cheerio": "^1.0.0-rc.12",
+        "dotenv": "^17.2.4",
+        "playwright": "^1.50.0",
+        "ws": "^8.18.0",
+        "zod": "^4.3.6"
+    },
+    "devDependencies": {
+        "@types/node": "^22.10.0",
+        "@types/ws": "^8.5.13",
+        "domhandler": "^5.0.3",
+        "tsup": "^8.0.1",
+        "typescript": "^5.6.3",
+        "vite": "^7.3.1",
+        "vitest": "^2.1.8"
+    },
+    "pnpm": {
+        "onlyBuiltDependencies": [
+            "esbuild"
+        ]
+    },
+    "engines": {
+        "node": ">=20"
+    },
+    "keywords": [
+        "browser-automation",
+        "selectors",
+        "playwright",
+        "llm",
+        "agents"
+    ],
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/opensteer-ai/opensteer"
     }
-  },
-  "files": [
-    "dist",
-    "bin",
-    "README.md",
-    "LICENSE",
-    "CHANGELOG.md"
-  ],
-  "dependencies": {
-    "@ai-sdk/anthropic": "^3.0.46",
-    "@ai-sdk/google": "^3.0.30",
-    "@ai-sdk/groq": "^3.0.24",
-    "@ai-sdk/openai": "^3.0.26",
-    "@ai-sdk/xai": "^3.0.57",
-    "ai": "^6.0.77",
-    "cheerio": "^1.0.0-rc.12",
-    "dotenv": "^17.2.4",
-    "playwright": "^1.50.0",
-    "ws": "^8.18.0",
-    "zod": "^4.3.6"
-  },
-  "devDependencies": {
-    "@types/node": "^22.10.0",
-    "@types/ws": "^8.5.13",
-    "domhandler": "^5.0.3",
-    "tsup": "^8.0.1",
-    "typescript": "^5.6.3",
-    "vite": "^7.3.1",
-    "vitest": "^2.1.8"
-  },
-  "engines": {
-    "node": ">=20"
-  },
-  "keywords": [
-    "browser-automation",
-    "selectors",
-    "playwright",
-    "llm",
-    "agents"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/opensteer-ai/opensteer"
-  },
-  "scripts": {
-    "build": "tsup src/index.ts src/cli/server.ts --dts --format esm,cjs --clean --external ai --external zod --external @ai-sdk/openai --external @ai-sdk/anthropic --external @ai-sdk/google --external @ai-sdk/xai --external @ai-sdk/groq",
-    "test": "vitest run",
-    "test:live-web": "vitest run --config vitest.live-web.config.ts",
-    "test:unit": "vitest run tests/html tests/element-path tests/config.test.ts tests/storage",
-    "test:actions": "vitest run tests/actions",
-    "test:integration": "vitest run tests/integration",
-    "test:ai": "vitest run tests/ai tests/e2e/ai-resolve.test.ts tests/e2e/ai-extract-products.test.ts",
-    "test:e2e": "vitest run tests/e2e",
-    "test:app:dev": "pnpm --dir tests/test-app run dev",
-    "typecheck": "tsc -p tsconfig.json --noEmit"
-  }
-}
+}