opensteer 0.4.9 → 0.4.11

package/CHANGELOG.md

@@ -36,6 +36,11 @@
   timeout/stale-target cases more accurately.
 - Cloud action failures now accept optional structured failure details and map
   them to `OpensteerActionError` when available.
+- Docs: refreshed README and getting-started guidance to match current SDK/CLI
+  behavior and env vars.
+- Docs: added CLI reference and docs index.
+- OSS community docs: expanded `CONTRIBUTING.md` and added `SECURITY.md` +
+  `SUPPORT.md`.
 
 ## 0.1.0
 

package/README.md

@@ -1,186 +1,115 @@
 # Opensteer
 
-Lean browser automation SDK for coding agents and script replay.
+Open-source browser automation SDK for coding agents and deterministic replay.
 
-`opensteer` provides descriptor-aware actions (`click`, `dblclick`,
-`rightclick`, `hover`, `input`, `select`, `scroll`, `extract`,
-`extractFromPlan`, `uploadFile`), observation (`snapshot`, `state`,
-`screenshot`), navigation (`goto`), and convenience methods for tabs, cookies,
-keyboard, element info, and wait.
+Opensteer combines descriptor-aware actions, resilient selector persistence,
+clean HTML snapshots, and first-class local or cloud runtime support.
 
-For anything not covered, use raw Playwright via `opensteer.page` and
-`opensteer.context`.
+## Requirements
+
+- Node.js `>=20`
+- A browser environment supported by Playwright
+- API key for your selected model provider if you use LLM resolve/extract
 
 ## Install
 
 ```bash
 # npm
-npm install opensteer playwright
+npm install opensteer
 # pnpm
-pnpm add opensteer playwright
+pnpm add opensteer
 ```
 
-## CLI Session Routing
-
-OpenSteer CLI now separates runtime routing from selector caching:
-
-- Runtime routing: `--session` or `OPENSTEER_SESSION`
-- Selector cache namespace: `--name` or `OPENSTEER_NAME` (used on `open`)
-
-If neither `--session` nor `OPENSTEER_SESSION` is set:
-
-- In an interactive terminal, OpenSteer creates/reuses a terminal-scoped default session.
-- In non-interactive environments (agents/CI), it fails fast unless you set
-  `OPENSTEER_SESSION` or `OPENSTEER_CLIENT_ID`.
-
-Example:
+If your environment skips Playwright browser downloads, run:
 
 ```bash
-export OPENSTEER_SESSION=agent-a
-opensteer open https://example.com --name product-scraper
-opensteer snapshot
-opensteer click 3
-opensteer status
+npx playwright install chromium
 ```
 
-`opensteer status` reports `resolvedSession`, `sessionSource`, `resolvedName`, and `nameSource`.
-
-## Quickstart
+## Quickstart (SDK)
 
 ```ts
 import { Opensteer } from "opensteer";
 
-const opensteer = new Opensteer({ name: "my-scraper" }); // defaults to model: 'gpt-5.1'
+const opensteer = new Opensteer({ name: "my-scraper" });
 await opensteer.launch({ headless: false });
 
-await opensteer.goto("https://example.com");
-const html = await opensteer.snapshot();
-
-await opensteer.click({ description: "login-button" });
-await opensteer.input({ description: "email", text: "user@example.com" });
-await opensteer.page.keyboard.press("Enter");
-
-await opensteer.close();
-```
-
-## Core Model
-
-- `opensteer.page`: raw Playwright `Page`
-- `opensteer.context`: raw Playwright `BrowserContext`
-- Opensteer methods: descriptor-aware operations that can persist selectors
-- Selector storage: `.opensteer/selectors/<namespace>`
-
-## Resolution Chain
-
-For actions like `click`/`input`/`hover`/`select`/`scroll`:
-
-1. Use persisted path for `description` (if present)
-2. Use `element` counter from snapshot
-3. Use explicit CSS `selector`
-4. Use built-in LLM resolution (`description` required)
-5. Throw
-
-When steps 2-4 resolve and `description` is provided, the path is persisted.
-
-## Smart Post-Action Wait
-
-Mutating actions (`click`, `input`, `select`, `scroll`, etc.) include a
-best-effort post-action wait so delayed visual updates are usually settled
-before the method resolves.
-
-You can disable or tune this per call:
-
-```ts
-await opensteer.click({ description: "Save button", wait: false });
+try {
+  await opensteer.goto("https://example.com");
+  const html = await opensteer.snapshot();
+  console.log(html.slice(0, 500));
 
-await opensteer.click({
-  description: "Save button",
-  wait: { timeout: 9000, settleMs: 900, includeNetwork: true, networkQuietMs: 400 },
-});
+  await opensteer.click({ description: "main call to action", element: 3 });
+} finally {
+  await opensteer.close();
+}
 ```
 
-## Action Failure Diagnostics
-
-Descriptor-aware interaction methods (`click`, `dblclick`, `rightclick`,
-`hover`, `input`, `select`, `scroll`, `uploadFile`) throw
-`OpensteerActionError` when an interaction cannot be completed.
-
-The error includes structured failure metadata for agent/tooling decisions:
+## Quickstart (CLI)
 
-- `error.failure.code` (`ActionFailureCode`)
-- `error.failure.message`
-- `error.failure.retryable`
-- `error.failure.classificationSource`
-- `error.failure.details` (for blocker and observation details when available)
-
-```ts
-import { Opensteer, OpensteerActionError } from "opensteer";
-
-try {
-  await opensteer.click({ description: "Save button" });
-} catch (err) {
-  if (err instanceof OpensteerActionError) {
-    console.error(err.failure.code); // e.g. BLOCKED_BY_INTERCEPTOR
-    console.error(err.failure.message);
-    console.error(err.failure.classificationSource);
-  }
-  throw err;
-}
-```
+Opensteer CLI separates runtime routing from selector namespace routing.
 
-## Snapshot Modes
+- Runtime routing: `--session` or `OPENSTEER_SESSION`
+- Selector namespace: `--name` or `OPENSTEER_NAME` (used by `open`)
 
-```ts
-await opensteer.snapshot(); // action mode (default)
-await opensteer.snapshot({ mode: "extraction" });
-await opensteer.snapshot({ mode: "clickable" });
-await opensteer.snapshot({ mode: "scrollable" });
-await opensteer.snapshot({ mode: "full" });
+```bash
+opensteer open https://example.com --session agent-a --name product-scraper
+opensteer snapshot --session agent-a
+opensteer click 3 --session agent-a
+opensteer status --session agent-a
+opensteer close --session agent-a
 ```
 
-## Two Usage Patterns
+In non-interactive environments, set `OPENSTEER_SESSION` or
+`OPENSTEER_CLIENT_ID` explicitly.
 
-### Explore (coding agent, no API key required)
+## Resolution and Replay Model
 
-Use `snapshot()` + `element` counters while exploring in real time, then persist
-stable descriptions for replay.
+For descriptor-aware actions (`click`, `input`, `hover`, `select`, `scroll`):
 
-### Run (script replay / built-in LLM)
-
-Opensteer uses built-in LLM resolve/extract by default. You can override the
-default model with top-level `model` or `OPENSTEER_MODEL`.
+1. Reuse persisted path for `description`
+2. Use `element` counter from snapshot
+3. Use explicit CSS `selector`
+4. Use built-in LLM resolution (`description` required)
+5. Throw actionable error
 
-```ts
-const opensteer = new Opensteer({
-  name: "run-mode",
-  model: "gpt-5-mini",
-});
-```
+When steps 2-4 succeed and `description` is present, Opensteer persists the
+path for deterministic replay in `.opensteer/selectors/<namespace>`.
 
-## Mode Selection
+## Cloud Mode
 
 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.
+- `OPENSTEER_MODE=local|cloud`
+- `OPENSTEER_API_KEY` or `cloud.apiKey` required in cloud mode
+- `OPENSTEER_BASE_URL` or `cloud.baseUrl` to override the default cloud host
+- `OPENSTEER_AUTH_SCHEME` or `cloud.authScheme` for auth header mode
+  (`api-key` or `bearer`)
+- `cloud: true` or a `cloud` options object overrides `OPENSTEER_MODE`
 
-Cloud mode is fail-fast: it does not automatically fall back to local mode.
+`.env` files are auto-loaded from `storage.rootDir` (default `process.cwd()`)
+in this order: `.env.<NODE_ENV>.local`, `.env.local` (except in test),
+`.env.<NODE_ENV>`, `.env`. Existing `process.env` values are not overwritten.
+Set `OPENSTEER_DISABLE_DOTENV_AUTOLOAD=true` to disable.
 
 ## Docs
 
-- `docs/getting-started.md`
-- `docs/api-reference.md`
-- `docs/cloud-integration.md`
-- `docs/html-cleaning.md`
-- `docs/selectors.md`
-- `docs/live-web-tests.md`
+- [Getting Started](docs/getting-started.md)
+- [API Reference](docs/api-reference.md)
+- [CLI Reference](docs/cli-reference.md)
+- [Cloud Integration](docs/cloud-integration.md)
+- [Selectors and Storage](docs/selectors.md)
+- [HTML Cleaning and Snapshot Modes](docs/html-cleaning.md)
+- [Live Web Validation Suite](docs/live-web-tests.md)
+
+## Community
+
+- [Contributing Guide](CONTRIBUTING.md)
+- [Code of Conduct](CODE_OF_CONDUCT.md)
+- [Security Policy](SECURITY.md)
+- [Support](SUPPORT.md)
+- [Changelog](CHANGELOG.md)
 
 ## License
 
-MIT
+[MIT](LICENSE)

package/bin/opensteer.mjs

@@ -781,7 +781,7 @@ Environment:
   OPENSTEER_MODE            Runtime routing: "local" (default) or "cloud"
   OPENSTEER_API_KEY         Required when cloud mode is selected
   OPENSTEER_BASE_URL        Override cloud control-plane base URL
-  OPENSTEER_APP_URL         Cloud app base URL for emitting browser session links (default: https://opensteer.com)
+  OPENSTEER_AUTH_SCHEME     Cloud auth scheme: api-key (default) or bearer
   OPENSTEER_REMOTE_ANNOUNCE Cloud session announcement policy: always (default), off, tty
 `)
 }

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

@@ -38,6 +38,7 @@ function sanitizeNamespaceSegment(segment) {
 var DEFAULT_TIMEOUT = 3e4;
 var DEFAULT_SETTLE_MS = 750;
 var FRAME_EVALUATE_GRACE_MS = 200;
+var TRANSIENT_CONTEXT_RETRY_DELAY_MS = 25;
 var STEALTH_WORLD_NAME = "__opensteer_wait__";
 var StealthWaitUnavailableError = class extends Error {
   constructor(cause) {
@@ -341,9 +342,12 @@ var StealthCdpRuntime = class _StealthCdpRuntime {
     const frameRecords = await this.getFrameRecords();
     const mainFrame = frameRecords[0];
     if (!mainFrame) return;
-    await this.waitForFrameVisualStability(mainFrame.frameId, timeout, settleMs, {
-      retryTransientContextErrors: true
-    });
+    await this.waitForFrameVisualStability(
+      mainFrame.frameId,
+      timeout,
+      settleMs,
+      true
+    );
   }
   async collectVisibleFrameIds() {
     const frameRecords = await this.getFrameRecords();
@@ -372,16 +376,15 @@ var StealthCdpRuntime = class _StealthCdpRuntime {
     }
     return visibleFrameIds;
   }
-  async waitForFrameVisualStability(frameId, timeout, settleMs, options = {}) {
+  async waitForFrameVisualStability(frameId, timeout, settleMs, retryTransientContextErrors = true) {
     if (timeout <= 0) return;
     const script = buildStabilityScript(timeout, settleMs);
-    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)) {
+        if (!isMissingExecutionContextError(error)) {
           throw error;
         }
         this.contextsByFrame.delete(frameId);
@@ -405,6 +408,11 @@ var StealthCdpRuntime = class _StealthCdpRuntime {
           throw error;
         }
         this.contextsByFrame.delete(frameId);
+        const retryDelay = Math.min(
+          TRANSIENT_CONTEXT_RETRY_DELAY_MS,
+          Math.max(0, deadline - Date.now())
+        );
+        await sleep(retryDelay);
       }
     }
   }
@@ -526,9 +534,7 @@ async function waitForVisualStabilityAcrossFrames(page, options = {}) {
               frameId,
               remaining,
               settleMs,
-              {
-                retryTransientContextErrors: false
-              }
+              false
             );
           } catch (error) {
             if (isIgnorableFrameError(error)) return;
@@ -571,7 +577,7 @@ function isTransientExecutionContextError(error) {
   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) {
+function isMissingExecutionContextError(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");
@@ -6208,6 +6214,11 @@ function resolveOpensteerApiKey(env) {
   if (!value) return void 0;
   return value;
 }
+function resolveOpensteerBaseUrl(env) {
+  const value = env.OPENSTEER_BASE_URL?.trim();
+  if (!value) return void 0;
+  return value;
+}
 function resolveOpensteerAuthScheme(env) {
   return parseAuthScheme(env.OPENSTEER_AUTH_SCHEME, "OPENSTEER_AUTH_SCHEME");
 }
@@ -6286,6 +6297,7 @@ function resolveConfig(input = {}) {
   const mergedWithEnv = mergeDeep(mergedWithFile, envConfig);
   const resolved = mergeDeep(mergedWithEnv, input);
   const envApiKey = resolveOpensteerApiKey(env);
+  const envBaseUrl = resolveOpensteerBaseUrl(env);
   const envAuthScheme = resolveOpensteerAuthScheme(env);
   const envCloudAnnounce = parseCloudAnnounce(
     env.OPENSTEER_REMOTE_ANNOUNCE,
@@ -6303,6 +6315,9 @@ function resolveConfig(input = {}) {
   const inputHasCloudApiKey = Boolean(
     inputCloudOptions && Object.prototype.hasOwnProperty.call(inputCloudOptions, "apiKey")
   );
+  const inputHasCloudBaseUrl = Boolean(
+    inputCloudOptions && Object.prototype.hasOwnProperty.call(inputCloudOptions, "baseUrl")
+  );
   const cloudSelection = resolveCloudSelection({
     cloud: resolved.cloud
   }, env);
@@ -6322,6 +6337,12 @@ function resolveConfig(input = {}) {
       apiKey: envApiKey
     };
   }
+  if (envBaseUrl && cloudSelection.cloud && !inputHasCloudBaseUrl) {
+    resolved.cloud = {
+      ...normalizeCloudOptions(resolved.cloud) ?? {},
+      baseUrl: envBaseUrl
+    };
+  }
   return resolved;
 }
 function resolveNamespace(config, rootDir) {
@@ -7716,12 +7737,16 @@ function clonePersistedExtractNode(node) {
 
 // src/cloud/runtime.ts
 var DEFAULT_CLOUD_BASE_URL = "https://remote.opensteer.com";
-var DEFAULT_CLOUD_APP_URL = "https://opensteer.com";
-function createCloudRuntimeState(key, baseUrl = resolveCloudBaseUrl(), authScheme = "api-key", appUrl = resolveCloudAppUrl()) {
+function createCloudRuntimeState(key, baseUrl = resolveCloudBaseUrl(), authScheme = "api-key") {
+  const normalizedBaseUrl = normalizeCloudBaseUrl(baseUrl);
   return {
-    sessionClient: new CloudSessionClient(baseUrl, key, authScheme),
+    sessionClient: new CloudSessionClient(
+      normalizedBaseUrl,
+      key,
+      authScheme
+    ),
     cdpClient: new CloudCdpClient(),
-    appUrl: normalizeCloudAppUrl(appUrl),
+    baseUrl: normalizedBaseUrl,
     actionClient: null,
     sessionId: null,
     localRunId: null,
@@ -7731,15 +7756,9 @@ function createCloudRuntimeState(key, baseUrl = resolveCloudBaseUrl(), authSchem
 function resolveCloudBaseUrl() {
   const value = process.env.OPENSTEER_BASE_URL?.trim();
   if (!value) return DEFAULT_CLOUD_BASE_URL;
-  return value.replace(/\/+$/, "");
-}
-function resolveCloudAppUrl() {
-  const value = process.env.OPENSTEER_APP_URL?.trim();
-  if (!value) return DEFAULT_CLOUD_APP_URL;
-  return normalizeCloudAppUrl(value);
+  return normalizeCloudBaseUrl(value);
 }
-function normalizeCloudAppUrl(value) {
-  if (!value) return null;
+function normalizeCloudBaseUrl(value) {
   return value.replace(/\/+$/, "");
 }
 function readCloudActionDescription(payload) {
@@ -7797,8 +7816,7 @@ var Opensteer = class _Opensteer {
       this.cloud = createCloudRuntimeState(
         apiKey,
         cloudConfig?.baseUrl,
-        cloudConfig?.authScheme,
-        cloudConfig?.appUrl
+        cloudConfig?.authScheme
       );
     } else {
       this.cloud = null;
@@ -7990,10 +8008,7 @@ var Opensteer = class _Opensteer {
         this.snapshotCache = null;
         this.cloud.actionClient = actionClient;
         this.cloud.sessionId = sessionId;
-        this.cloud.cloudSessionUrl = buildCloudSessionUrl(
-          this.cloud.appUrl,
-          session2.cloudSession.sessionId
-        );
+        this.cloud.cloudSessionUrl = session2.cloudSessionUrl;
         this.announceCloudSession({
           sessionId: session2.sessionId,
           workspaceId: session2.cloudSession.workspaceId,
@@ -10050,12 +10065,6 @@ function buildLocalRunId(namespace) {
   const normalized = namespace.trim() || "default";
   return `${normalized}-${Date.now().toString(36)}-${randomUUID2().slice(0, 8)}`;
 }
-function buildCloudSessionUrl(appUrl, sessionId) {
-  if (!appUrl) {
-    return null;
-  }
-  return `${appUrl}/browser/${encodeURIComponent(sessionId)}`;
-}
 
 export {
   normalizeNamespace,

package/dist/cli/server.cjs

@@ -1036,6 +1036,11 @@ function resolveOpensteerApiKey(env) {
   if (!value) return void 0;
   return value;
 }
+function resolveOpensteerBaseUrl(env) {
+  const value = env.OPENSTEER_BASE_URL?.trim();
+  if (!value) return void 0;
+  return value;
+}
 function resolveOpensteerAuthScheme(env) {
   return parseAuthScheme(env.OPENSTEER_AUTH_SCHEME, "OPENSTEER_AUTH_SCHEME");
 }
@@ -1114,6 +1119,7 @@ function resolveConfig(input = {}) {
   const mergedWithEnv = mergeDeep(mergedWithFile, envConfig);
   const resolved = mergeDeep(mergedWithEnv, input);
   const envApiKey = resolveOpensteerApiKey(env);
+  const envBaseUrl = resolveOpensteerBaseUrl(env);
   const envAuthScheme = resolveOpensteerAuthScheme(env);
   const envCloudAnnounce = parseCloudAnnounce(
     env.OPENSTEER_REMOTE_ANNOUNCE,
@@ -1131,6 +1137,9 @@ function resolveConfig(input = {}) {
   const inputHasCloudApiKey = Boolean(
     inputCloudOptions && Object.prototype.hasOwnProperty.call(inputCloudOptions, "apiKey")
   );
+  const inputHasCloudBaseUrl = Boolean(
+    inputCloudOptions && Object.prototype.hasOwnProperty.call(inputCloudOptions, "baseUrl")
+  );
   const cloudSelection = resolveCloudSelection({
     cloud: resolved.cloud
   }, env);
@@ -1150,6 +1159,12 @@ function resolveConfig(input = {}) {
       apiKey: envApiKey
     };
   }
+  if (envBaseUrl && cloudSelection.cloud && !inputHasCloudBaseUrl) {
+    resolved.cloud = {
+      ...normalizeCloudOptions(resolved.cloud) ?? {},
+      baseUrl: envBaseUrl
+    };
+  }
   return resolved;
 }
 function resolveNamespace(config, rootDir) {
@@ -1190,6 +1205,7 @@ function getCallerFilePath() {
 var DEFAULT_TIMEOUT = 3e4;
 var DEFAULT_SETTLE_MS = 750;
 var FRAME_EVALUATE_GRACE_MS = 200;
+var TRANSIENT_CONTEXT_RETRY_DELAY_MS = 25;
 var STEALTH_WORLD_NAME = "__opensteer_wait__";
 var StealthWaitUnavailableError = class extends Error {
   constructor(cause) {
@@ -1493,9 +1509,12 @@ var StealthCdpRuntime = class _StealthCdpRuntime {
     const frameRecords = await this.getFrameRecords();
     const mainFrame = frameRecords[0];
     if (!mainFrame) return;
-    await this.waitForFrameVisualStability(mainFrame.frameId, timeout, settleMs, {
-      retryTransientContextErrors: true
-    });
+    await this.waitForFrameVisualStability(
+      mainFrame.frameId,
+      timeout,
+      settleMs,
+      true
+    );
   }
   async collectVisibleFrameIds() {
     const frameRecords = await this.getFrameRecords();
@@ -1524,16 +1543,15 @@ var StealthCdpRuntime = class _StealthCdpRuntime {
     }
     return visibleFrameIds;
   }
-  async waitForFrameVisualStability(frameId, timeout, settleMs, options = {}) {
+  async waitForFrameVisualStability(frameId, timeout, settleMs, retryTransientContextErrors = true) {
     if (timeout <= 0) return;
     const script = buildStabilityScript(timeout, settleMs);
-    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)) {
+        if (!isMissingExecutionContextError(error)) {
           throw error;
         }
         this.contextsByFrame.delete(frameId);
@@ -1557,6 +1575,11 @@ var StealthCdpRuntime = class _StealthCdpRuntime {
           throw error;
         }
         this.contextsByFrame.delete(frameId);
+        const retryDelay = Math.min(
+          TRANSIENT_CONTEXT_RETRY_DELAY_MS,
+          Math.max(0, deadline - Date.now())
+        );
+        await sleep(retryDelay);
       }
     }
   }
@@ -1678,9 +1701,7 @@ async function waitForVisualStabilityAcrossFrames(page, options = {}) {
               frameId,
               remaining,
               settleMs,
-              {
-                retryTransientContextErrors: false
-              }
+              false
             );
           } catch (error) {
             if (isIgnorableFrameError(error)) return;
@@ -1723,7 +1744,7 @@ function isTransientExecutionContextError(error) {
   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) {
+function isMissingExecutionContextError(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");
@@ -8050,12 +8071,16 @@ function toCloudErrorCode(code) {
 
 // src/cloud/runtime.ts
 var DEFAULT_CLOUD_BASE_URL = "https://remote.opensteer.com";
-var DEFAULT_CLOUD_APP_URL = "https://opensteer.com";
-function createCloudRuntimeState(key, baseUrl = resolveCloudBaseUrl(), authScheme = "api-key", appUrl = resolveCloudAppUrl()) {
+function createCloudRuntimeState(key, baseUrl = resolveCloudBaseUrl(), authScheme = "api-key") {
+  const normalizedBaseUrl = normalizeCloudBaseUrl(baseUrl);
   return {
-    sessionClient: new CloudSessionClient(baseUrl, key, authScheme),
+    sessionClient: new CloudSessionClient(
+      normalizedBaseUrl,
+      key,
+      authScheme
+    ),
     cdpClient: new CloudCdpClient(),
-    appUrl: normalizeCloudAppUrl(appUrl),
+    baseUrl: normalizedBaseUrl,
     actionClient: null,
     sessionId: null,
     localRunId: null,
@@ -8065,15 +8090,9 @@ function createCloudRuntimeState(key, baseUrl = resolveCloudBaseUrl(), authSchem
 function resolveCloudBaseUrl() {
   const value = process.env.OPENSTEER_BASE_URL?.trim();
   if (!value) return DEFAULT_CLOUD_BASE_URL;
-  return value.replace(/\/+$/, "");
-}
-function resolveCloudAppUrl() {
-  const value = process.env.OPENSTEER_APP_URL?.trim();
-  if (!value) return DEFAULT_CLOUD_APP_URL;
-  return normalizeCloudAppUrl(value);
+  return normalizeCloudBaseUrl(value);
 }
-function normalizeCloudAppUrl(value) {
-  if (!value) return null;
+function normalizeCloudBaseUrl(value) {
   return value.replace(/\/+$/, "");
 }
 function readCloudActionDescription(payload) {
@@ -8131,8 +8150,7 @@ var Opensteer = class _Opensteer {
       this.cloud = createCloudRuntimeState(
         apiKey,
         cloudConfig?.baseUrl,
-        cloudConfig?.authScheme,
-        cloudConfig?.appUrl
+        cloudConfig?.authScheme
       );
     } else {
       this.cloud = null;
@@ -8324,10 +8342,7 @@ var Opensteer = class _Opensteer {
         this.snapshotCache = null;
         this.cloud.actionClient = actionClient;
         this.cloud.sessionId = sessionId;
-        this.cloud.cloudSessionUrl = buildCloudSessionUrl(
-          this.cloud.appUrl,
-          session3.cloudSession.sessionId
-        );
+        this.cloud.cloudSessionUrl = session3.cloudSessionUrl;
         this.announceCloudSession({
           sessionId: session3.sessionId,
           workspaceId: session3.cloudSession.workspaceId,
@@ -10384,12 +10399,6 @@ function buildLocalRunId(namespace) {
   const normalized = namespace.trim() || "default";
   return `${normalized}-${Date.now().toString(36)}-${(0, import_crypto2.randomUUID)().slice(0, 8)}`;
 }
-function buildCloudSessionUrl(appUrl, sessionId) {
-  if (!appUrl) {
-    return null;
-  }
-  return `${appUrl}/browser/${encodeURIComponent(sessionId)}`;
-}
 
 // src/cli/paths.ts
 var import_os2 = require("os");

package/dist/cli/server.js

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

package/dist/index.cjs

@@ -1111,6 +1111,11 @@ function resolveOpensteerApiKey(env) {
   if (!value) return void 0;
   return value;
 }
+function resolveOpensteerBaseUrl(env) {
+  const value = env.OPENSTEER_BASE_URL?.trim();
+  if (!value) return void 0;
+  return value;
+}
 function resolveOpensteerAuthScheme(env) {
   return parseAuthScheme(env.OPENSTEER_AUTH_SCHEME, "OPENSTEER_AUTH_SCHEME");
 }
@@ -1189,6 +1194,7 @@ function resolveConfig(input = {}) {
   const mergedWithEnv = mergeDeep(mergedWithFile, envConfig);
   const resolved = mergeDeep(mergedWithEnv, input);
   const envApiKey = resolveOpensteerApiKey(env);
+  const envBaseUrl = resolveOpensteerBaseUrl(env);
   const envAuthScheme = resolveOpensteerAuthScheme(env);
   const envCloudAnnounce = parseCloudAnnounce(
     env.OPENSTEER_REMOTE_ANNOUNCE,
@@ -1206,6 +1212,9 @@ function resolveConfig(input = {}) {
   const inputHasCloudApiKey = Boolean(
     inputCloudOptions && Object.prototype.hasOwnProperty.call(inputCloudOptions, "apiKey")
   );
+  const inputHasCloudBaseUrl = Boolean(
+    inputCloudOptions && Object.prototype.hasOwnProperty.call(inputCloudOptions, "baseUrl")
+  );
   const cloudSelection = resolveCloudSelection({
     cloud: resolved.cloud
   }, env);
@@ -1225,6 +1234,12 @@ function resolveConfig(input = {}) {
       apiKey: envApiKey
     };
   }
+  if (envBaseUrl && cloudSelection.cloud && !inputHasCloudBaseUrl) {
+    resolved.cloud = {
+      ...normalizeCloudOptions(resolved.cloud) ?? {},
+      baseUrl: envBaseUrl
+    };
+  }
   return resolved;
 }
 function resolveNamespace(config, rootDir) {
@@ -1265,6 +1280,7 @@ function getCallerFilePath() {
 var DEFAULT_TIMEOUT = 3e4;
 var DEFAULT_SETTLE_MS = 750;
 var FRAME_EVALUATE_GRACE_MS = 200;
+var TRANSIENT_CONTEXT_RETRY_DELAY_MS = 25;
 var STEALTH_WORLD_NAME = "__opensteer_wait__";
 var StealthWaitUnavailableError = class extends Error {
   constructor(cause) {
@@ -1568,9 +1584,12 @@ var StealthCdpRuntime = class _StealthCdpRuntime {
     const frameRecords = await this.getFrameRecords();
     const mainFrame = frameRecords[0];
     if (!mainFrame) return;
-    await this.waitForFrameVisualStability(mainFrame.frameId, timeout, settleMs, {
-      retryTransientContextErrors: true
-    });
+    await this.waitForFrameVisualStability(
+      mainFrame.frameId,
+      timeout,
+      settleMs,
+      true
+    );
   }
   async collectVisibleFrameIds() {
     const frameRecords = await this.getFrameRecords();
@@ -1599,16 +1618,15 @@ var StealthCdpRuntime = class _StealthCdpRuntime {
     }
     return visibleFrameIds;
   }
-  async waitForFrameVisualStability(frameId, timeout, settleMs, options = {}) {
+  async waitForFrameVisualStability(frameId, timeout, settleMs, retryTransientContextErrors = true) {
     if (timeout <= 0) return;
     const script = buildStabilityScript(timeout, settleMs);
-    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)) {
+        if (!isMissingExecutionContextError(error)) {
           throw error;
         }
         this.contextsByFrame.delete(frameId);
@@ -1632,6 +1650,11 @@ var StealthCdpRuntime = class _StealthCdpRuntime {
           throw error;
         }
         this.contextsByFrame.delete(frameId);
+        const retryDelay = Math.min(
+          TRANSIENT_CONTEXT_RETRY_DELAY_MS,
+          Math.max(0, deadline - Date.now())
+        );
+        await sleep(retryDelay);
       }
     }
   }
@@ -1753,9 +1776,7 @@ async function waitForVisualStabilityAcrossFrames(page, options = {}) {
               frameId,
               remaining,
               settleMs,
-              {
-                retryTransientContextErrors: false
-              }
+              false
             );
           } catch (error) {
             if (isIgnorableFrameError(error)) return;
@@ -1798,7 +1819,7 @@ function isTransientExecutionContextError(error) {
   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) {
+function isMissingExecutionContextError(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");
@@ -8135,12 +8156,16 @@ function toCloudErrorCode(code) {
 
 // src/cloud/runtime.ts
 var DEFAULT_CLOUD_BASE_URL = "https://remote.opensteer.com";
-var DEFAULT_CLOUD_APP_URL = "https://opensteer.com";
-function createCloudRuntimeState(key, baseUrl = resolveCloudBaseUrl(), authScheme = "api-key", appUrl = resolveCloudAppUrl()) {
+function createCloudRuntimeState(key, baseUrl = resolveCloudBaseUrl(), authScheme = "api-key") {
+  const normalizedBaseUrl = normalizeCloudBaseUrl(baseUrl);
   return {
-    sessionClient: new CloudSessionClient(baseUrl, key, authScheme),
+    sessionClient: new CloudSessionClient(
+      normalizedBaseUrl,
+      key,
+      authScheme
+    ),
     cdpClient: new CloudCdpClient(),
-    appUrl: normalizeCloudAppUrl(appUrl),
+    baseUrl: normalizedBaseUrl,
     actionClient: null,
     sessionId: null,
     localRunId: null,
@@ -8150,15 +8175,9 @@ function createCloudRuntimeState(key, baseUrl = resolveCloudBaseUrl(), authSchem
 function resolveCloudBaseUrl() {
   const value = process.env.OPENSTEER_BASE_URL?.trim();
   if (!value) return DEFAULT_CLOUD_BASE_URL;
-  return value.replace(/\/+$/, "");
-}
-function resolveCloudAppUrl() {
-  const value = process.env.OPENSTEER_APP_URL?.trim();
-  if (!value) return DEFAULT_CLOUD_APP_URL;
-  return normalizeCloudAppUrl(value);
+  return normalizeCloudBaseUrl(value);
 }
-function normalizeCloudAppUrl(value) {
-  if (!value) return null;
+function normalizeCloudBaseUrl(value) {
   return value.replace(/\/+$/, "");
 }
 function readCloudActionDescription(payload) {
@@ -8216,8 +8235,7 @@ var Opensteer = class _Opensteer {
       this.cloud = createCloudRuntimeState(
         apiKey,
         cloudConfig?.baseUrl,
-        cloudConfig?.authScheme,
-        cloudConfig?.appUrl
+        cloudConfig?.authScheme
       );
     } else {
       this.cloud = null;
@@ -8409,10 +8427,7 @@ var Opensteer = class _Opensteer {
         this.snapshotCache = null;
         this.cloud.actionClient = actionClient;
         this.cloud.sessionId = sessionId;
-        this.cloud.cloudSessionUrl = buildCloudSessionUrl(
-          this.cloud.appUrl,
-          session2.cloudSession.sessionId
-        );
+        this.cloud.cloudSessionUrl = session2.cloudSessionUrl;
         this.announceCloudSession({
           sessionId: session2.sessionId,
           workspaceId: session2.cloudSession.workspaceId,
@@ -10469,12 +10484,6 @@ function buildLocalRunId(namespace) {
   const normalized = namespace.trim() || "default";
   return `${normalized}-${Date.now().toString(36)}-${(0, import_crypto2.randomUUID)().slice(0, 8)}`;
 }
-function buildCloudSessionUrl(appUrl, sessionId) {
-  if (!appUrl) {
-    return null;
-  }
-  return `${appUrl}/browser/${encodeURIComponent(sessionId)}`;
-}
 
 // src/ai/index.ts
 init_resolver();

package/dist/index.d.cts

@@ -127,7 +127,6 @@ type OpensteerCloudAnnouncePolicy = 'always' | 'off' | 'tty';
 interface OpensteerCloudOptions {
     apiKey?: string;
     baseUrl?: string;
-    appUrl?: string;
     authScheme?: OpensteerAuthScheme;
     announce?: OpensteerCloudAnnouncePolicy;
 }

package/dist/index.d.ts

@@ -127,7 +127,6 @@ type OpensteerCloudAnnouncePolicy = 'always' | 'off' | 'tty';
 interface OpensteerCloudOptions {
     apiKey?: string;
     baseUrl?: string;
-    appUrl?: string;
     authScheme?: OpensteerAuthScheme;
     announce?: OpensteerCloudAnnouncePolicy;
 }

package/dist/index.js

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

package/package.json

@@ -1,82 +1,75 @@
 {
-    "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"
+  "name": "opensteer",
+  "version": "0.4.11",
+  "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"
+  ],
+  "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"
+  }
+}