opensteer 0.4.6 → 0.4.8

package/dist/index.cjs

@@ -338,6 +338,8 @@ var init_extractor = __esm({
 var index_exports = {};
 __export(index_exports, {
   ActionWsClient: () => ActionWsClient,
+  CloudCdpClient: () => CloudCdpClient,
+  CloudSessionClient: () => CloudSessionClient,
   CounterResolutionError: () => CounterResolutionError,
   ElementPathError: () => ElementPathError,
   LocalSelectorStorage: () => LocalSelectorStorage,
@@ -351,9 +353,7 @@ __export(index_exports, {
   OS_UNAVAILABLE_ATTR: () => OS_UNAVAILABLE_ATTR,
   Opensteer: () => Opensteer,
   OpensteerActionError: () => OpensteerActionError,
-  OpensteerRemoteError: () => OpensteerRemoteError,
-  RemoteCdpClient: () => RemoteCdpClient,
-  RemoteSessionClient: () => RemoteSessionClient,
+  OpensteerCloudError: () => OpensteerCloudError,
   buildElementPathFromHandle: () => buildElementPathFromHandle,
   buildElementPathFromSelector: () => buildElementPathFromSelector,
   buildPathSelectorHint: () => buildPathSelectorHint,
@@ -365,6 +365,9 @@ __export(index_exports, {
   clearCookies: () => clearCookies,
   cloneElementPath: () => cloneElementPath,
   closeTab: () => closeTab,
+  cloudNotLaunchedError: () => cloudNotLaunchedError,
+  cloudSessionContractVersion: () => cloudSessionContractVersion,
+  cloudUnsupportedMethodError: () => cloudUnsupportedMethodError,
   collectLocalSelectorCacheEntries: () => collectLocalSelectorCacheEntries,
   countArrayItemsWithPath: () => countArrayItemsWithPath,
   createEmptyRegistry: () => createEmptyRegistry,
@@ -396,8 +399,6 @@ __export(index_exports, {
   performSelect: () => performSelect,
   prepareSnapshot: () => prepareSnapshot,
   pressKey: () => pressKey,
-  remoteNotLaunchedError: () => remoteNotLaunchedError,
-  remoteUnsupportedMethodError: () => remoteUnsupportedMethodError,
   resolveCounterElement: () => resolveCounterElement,
   resolveCountersBatch: () => resolveCountersBatch,
   resolveElementPath: () => resolveElementPath,
@@ -826,7 +827,7 @@ var BrowserPool = class {
       const context = contexts[0];
       const pages = context.pages();
       const page = pages.length > 0 ? pages[0] : await context.newPage();
-      return { browser, context, page, isRemote: true };
+      return { browser, context, page, isExternal: true };
     } catch (error) {
       if (browser) {
         await browser.close().catch(() => void 0);
@@ -861,7 +862,7 @@ var BrowserPool = class {
       context = await browser.newContext(options.context || {});
       page = await context.newPage();
     }
-    return { browser, context, page, isRemote: false };
+    return { browser, context, page, isExternal: false };
   }
   async launchSandbox(options) {
     const browser = await import_playwright.chromium.launch({
@@ -872,7 +873,7 @@ var BrowserPool = class {
     const context = await browser.newContext(options.context || {});
     const page = await context.newPage();
     this.browser = browser;
-    return { browser, context, page, isRemote: false };
+    return { browser, context, page, isExternal: false };
   }
 };
 
@@ -880,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);
@@ -929,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);
@@ -943,28 +992,27 @@ function assertNoLegacyAiConfig(source, config) {
     );
   }
 }
-function assertNoLegacyModeConfig(source, config) {
+function assertNoLegacyRuntimeConfig(source, config) {
   if (!config || typeof config !== "object") return;
   const configRecord = config;
   if (hasOwn(configRecord, "runtime")) {
     throw new Error(
-      `Legacy "runtime" config is no longer supported in ${source}. Use top-level "mode" instead.`
+      `Legacy "runtime" config is no longer supported in ${source}. Use top-level "cloud" instead.`
     );
   }
-  if (hasOwn(configRecord, "apiKey")) {
+  if (hasOwn(configRecord, "mode")) {
     throw new Error(
-      `Top-level "apiKey" config is not supported in ${source}. Use "remote.apiKey" instead.`
+      `Top-level "mode" config is no longer supported in ${source}. Use "cloud: true" to enable cloud mode.`
     );
   }
-  const remoteValue = configRecord.remote;
-  if (typeof remoteValue === "boolean") {
+  if (hasOwn(configRecord, "remote")) {
     throw new Error(
-      `Boolean "remote" config is no longer supported in ${source}. Use "mode: \\"remote\\"" with "remote" options.`
+      `Top-level "remote" config is no longer supported in ${source}. Use "cloud" options instead.`
     );
   }
-  if (remoteValue && typeof remoteValue === "object" && !Array.isArray(remoteValue) && hasOwn(remoteValue, "key")) {
+  if (hasOwn(configRecord, "apiKey")) {
     throw new Error(
-      `Legacy "remote.key" config is no longer supported in ${source}. Use "remote.apiKey" instead.`
+      `Top-level "apiKey" config is not supported in ${source}. Use "cloud.apiKey" instead.`
     );
   }
 }
@@ -1010,20 +1058,20 @@ function parseNumber(value) {
   if (!Number.isFinite(parsed)) return void 0;
   return parsed;
 }
-function parseMode(value, source) {
+function parseRuntimeMode(value, source) {
   if (value == null) return void 0;
   if (typeof value !== "string") {
     throw new Error(
-      `Invalid ${source} value "${String(value)}". Use "local" or "remote".`
+      `Invalid ${source} value "${String(value)}". Use "local" or "cloud".`
     );
   }
   const normalized = value.trim().toLowerCase();
   if (!normalized) return void 0;
-  if (normalized === "local" || normalized === "remote") {
+  if (normalized === "local" || normalized === "cloud") {
     return normalized;
   }
   throw new Error(
-    `Invalid ${source} value "${value}". Use "local" or "remote".`
+    `Invalid ${source} value "${value}". Use "local" or "cloud".`
   );
 }
 function parseAuthScheme(value, source) {
@@ -1042,99 +1090,138 @@ function parseAuthScheme(value, source) {
     `Invalid ${source} value "${value}". Use "api-key" or "bearer".`
   );
 }
-function resolveOpensteerApiKey() {
-  const value = process.env.OPENSTEER_API_KEY?.trim();
+function parseCloudAnnounce(value, source) {
+  if (value == null) return void 0;
+  if (typeof value !== "string") {
+    throw new Error(
+      `Invalid ${source} value "${String(value)}". Use "always", "off", or "tty".`
+    );
+  }
+  const normalized = value.trim().toLowerCase();
+  if (!normalized) return void 0;
+  if (normalized === "always" || normalized === "off" || normalized === "tty") {
+    return normalized;
+  }
+  throw new Error(
+    `Invalid ${source} value "${value}". Use "always", "off", or "tty".`
+  );
+}
+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 normalizeRemoteOptions(value) {
+function normalizeCloudOptions(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
     return void 0;
   }
   return value;
 }
-function resolveModeSelection(config) {
-  const configMode = parseMode(config.mode, "mode");
-  if (configMode) {
+function parseCloudEnabled(value, source) {
+  if (value == null) return void 0;
+  if (typeof value === "boolean") return value;
+  if (typeof value === "object" && !Array.isArray(value)) return true;
+  throw new Error(
+    `Invalid ${source} value "${String(value)}". Use true, false, or a cloud options object.`
+  );
+}
+function resolveCloudSelection(config, env = process.env) {
+  const configCloud = parseCloudEnabled(config.cloud, "cloud");
+  if (configCloud !== void 0) {
     return {
-      mode: configMode,
-      source: "config.mode"
+      cloud: configCloud,
+      source: "config.cloud"
     };
   }
-  const envMode = parseMode(process.env.OPENSTEER_MODE, "OPENSTEER_MODE");
+  const envMode = parseRuntimeMode(env.OPENSTEER_MODE, "OPENSTEER_MODE");
   if (envMode) {
     return {
-      mode: envMode,
+      cloud: envMode === "cloud",
       source: "env.OPENSTEER_MODE"
     };
   }
   return {
-    mode: "local",
+    cloud: false,
     source: "default"
   };
 }
 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);
-  assertNoLegacyModeConfig("Opensteer constructor config", input);
-  const rootDir = input.storage?.rootDir ?? DEFAULT_CONFIG.storage.rootDir ?? process.cwd();
-  const fileConfig = loadConfigFile(rootDir);
-  assertNoLegacyAiConfig(".opensteer/config.json", fileConfig);
-  assertNoLegacyModeConfig(".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 inputRemoteOptions = normalizeRemoteOptions(input.remote);
+  const envApiKey = resolveOpensteerApiKey(env);
+  const envAuthScheme = resolveOpensteerAuthScheme(env);
+  const envCloudAnnounce = parseCloudAnnounce(
+    env.OPENSTEER_REMOTE_ANNOUNCE,
+    "OPENSTEER_REMOTE_ANNOUNCE"
+  );
+  const inputCloudOptions = normalizeCloudOptions(input.cloud);
   const inputAuthScheme = parseAuthScheme(
-    inputRemoteOptions?.authScheme,
-    "remote.authScheme"
+    inputCloudOptions?.authScheme,
+    "cloud.authScheme"
   );
-  const inputHasRemoteApiKey = Boolean(
-    inputRemoteOptions && Object.prototype.hasOwnProperty.call(inputRemoteOptions, "apiKey")
+  const inputCloudAnnounce = parseCloudAnnounce(
+    inputCloudOptions?.announce,
+    "cloud.announce"
   );
-  const modeSelection = resolveModeSelection({
-    mode: resolved.mode
-  });
-  if (modeSelection.mode === "remote") {
-    const resolvedRemote = normalizeRemoteOptions(resolved.remote) ?? {};
-    const authScheme = inputAuthScheme ?? envAuthScheme ?? parseAuthScheme(resolvedRemote.authScheme, "remote.authScheme") ?? "api-key";
-    resolved.remote = {
-      ...resolvedRemote,
-      authScheme
+  const inputHasCloudApiKey = Boolean(
+    inputCloudOptions && Object.prototype.hasOwnProperty.call(inputCloudOptions, "apiKey")
+  );
+  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";
+    const announce = inputCloudAnnounce ?? envCloudAnnounce ?? parseCloudAnnounce(resolvedCloud.announce, "cloud.announce") ?? "always";
+    resolved.cloud = {
+      ...resolvedCloud,
+      authScheme,
+      announce
     };
   }
-  if (envApiKey && modeSelection.mode === "remote" && !inputHasRemoteApiKey) {
-    resolved.remote = {
-      ...normalizeRemoteOptions(resolved.remote) ?? {},
+  if (envApiKey && cloudSelection.cloud && !inputHasCloudApiKey) {
+    resolved.cloud = {
+      ...normalizeCloudOptions(resolved.cloud) ?? {},
       apiKey: envApiKey
     };
   }
@@ -7441,36 +7528,39 @@ function clonePersistedExtractNode(node) {
   return JSON.parse(JSON.stringify(node));
 }
 
-// src/remote/action-ws-client.ts
+// src/cloud/contracts.ts
+var cloudSessionContractVersion = "v3";
+
+// src/cloud/action-ws-client.ts
 var import_ws2 = __toESM(require("ws"), 1);
 
-// src/remote/errors.ts
-var OpensteerRemoteError = class extends Error {
+// src/cloud/errors.ts
+var OpensteerCloudError = class extends Error {
   code;
   status;
   details;
   constructor(code, message, status, details) {
     super(message);
-    this.name = "OpensteerRemoteError";
+    this.name = "OpensteerCloudError";
     this.code = code;
     this.status = status;
     this.details = details;
   }
 };
-function remoteUnsupportedMethodError(method, message) {
-  return new OpensteerRemoteError(
-    "REMOTE_UNSUPPORTED_METHOD",
-    message || `${method} is not supported in remote mode.`
+function cloudUnsupportedMethodError(method, message) {
+  return new OpensteerCloudError(
+    "CLOUD_UNSUPPORTED_METHOD",
+    message || `${method} is not supported in cloud mode.`
   );
 }
-function remoteNotLaunchedError() {
-  return new OpensteerRemoteError(
-    "REMOTE_SESSION_NOT_FOUND",
-    "Remote session is not connected. Call launch() first."
+function cloudNotLaunchedError() {
+  return new OpensteerCloudError(
+    "CLOUD_SESSION_NOT_FOUND",
+    "Cloud session is not connected. Call launch() first."
   );
 }
 
-// src/remote/action-ws-client.ts
+// src/cloud/action-ws-client.ts
 var ActionWsClient = class _ActionWsClient {
   ws;
   sessionId;
@@ -7487,18 +7577,18 @@ var ActionWsClient = class _ActionWsClient {
     });
     ws.on("error", (error) => {
       this.rejectAll(
-        new OpensteerRemoteError(
-          "REMOTE_TRANSPORT_ERROR",
-          `Remote action websocket error: ${error.message}`
+        new OpensteerCloudError(
+          "CLOUD_TRANSPORT_ERROR",
+          `Cloud action websocket error: ${error.message}`
         )
       );
     });
     ws.on("close", () => {
       this.closed = true;
       this.rejectAll(
-        new OpensteerRemoteError(
-          "REMOTE_SESSION_CLOSED",
-          "Remote action websocket closed."
+        new OpensteerCloudError(
+          "CLOUD_SESSION_CLOSED",
+          "Cloud action websocket closed."
         )
       );
     });
@@ -7510,8 +7600,8 @@ var ActionWsClient = class _ActionWsClient {
       ws.once("open", () => resolve());
       ws.once("error", (error) => {
         reject(
-          new OpensteerRemoteError(
-            "REMOTE_TRANSPORT_ERROR",
+          new OpensteerCloudError(
+            "CLOUD_TRANSPORT_ERROR",
             `Failed to connect action websocket: ${error.message}`
           )
         );
@@ -7521,9 +7611,9 @@ var ActionWsClient = class _ActionWsClient {
   }
   async request(method, args) {
     if (this.closed || this.ws.readyState !== import_ws2.default.OPEN) {
-      throw new OpensteerRemoteError(
-        "REMOTE_SESSION_CLOSED",
-        "Remote action websocket is closed."
+      throw new OpensteerCloudError(
+        "CLOUD_SESSION_CLOSED",
+        "Cloud action websocket is closed."
       );
     }
     const id = this.nextRequestId;
@@ -7542,8 +7632,8 @@ var ActionWsClient = class _ActionWsClient {
       this.ws.send(JSON.stringify(payload));
     } catch (error) {
       this.pending.delete(id);
-      const message = error instanceof Error ? error.message : "Failed to send remote action request.";
-      throw new OpensteerRemoteError("REMOTE_TRANSPORT_ERROR", message);
+      const message = error instanceof Error ? error.message : "Failed to send cloud action request.";
+      throw new OpensteerCloudError("CLOUD_TRANSPORT_ERROR", message);
     }
     return await resultPromise;
   }
@@ -7561,9 +7651,9 @@ var ActionWsClient = class _ActionWsClient {
       parsed = JSON.parse(rawDataToUtf8(raw));
     } catch {
       this.rejectAll(
-        new OpensteerRemoteError(
-          "REMOTE_TRANSPORT_ERROR",
-          "Invalid remote action response payload."
+        new OpensteerCloudError(
+          "CLOUD_TRANSPORT_ERROR",
+          "Invalid cloud action response payload."
         )
       );
       return;
@@ -7576,7 +7666,7 @@ var ActionWsClient = class _ActionWsClient {
       return;
     }
     pending.reject(
-      new OpensteerRemoteError(
+      new OpensteerCloudError(
         parsed.code,
         parsed.error,
         void 0,
@@ -7604,7 +7694,7 @@ function withTokenQuery(wsUrl, token) {
   return url.toString();
 }
 
-// src/remote/local-cache-sync.ts
+// src/cloud/local-cache-sync.ts
 var import_fs3 = __toESM(require("fs"), 1);
 var import_path5 = __toESM(require("path"), 1);
 function collectLocalSelectorCacheEntries(storage) {
@@ -7728,24 +7818,24 @@ function dedupeNewest(entries) {
   return [...byKey.values()];
 }
 
-// src/remote/cdp-client.ts
+// src/cloud/cdp-client.ts
 var import_playwright2 = require("playwright");
-var RemoteCdpClient = class {
+var CloudCdpClient = class {
   async connect(args) {
     const endpoint = withTokenQuery2(args.wsUrl, args.token);
     let browser;
     try {
       browser = await import_playwright2.chromium.connectOverCDP(endpoint);
     } catch (error) {
-      const message = error instanceof Error ? error.message : "Failed to connect to remote CDP endpoint.";
-      throw new OpensteerRemoteError("REMOTE_TRANSPORT_ERROR", message);
+      const message = error instanceof Error ? error.message : "Failed to connect to cloud CDP endpoint.";
+      throw new OpensteerCloudError("CLOUD_TRANSPORT_ERROR", message);
     }
     const context = browser.contexts()[0];
     if (!context) {
       await browser.close();
-      throw new OpensteerRemoteError(
-        "REMOTE_INTERNAL",
-        "Remote browser returned no context."
+      throw new OpensteerCloudError(
+        "CLOUD_INTERNAL",
+        "Cloud browser returned no context."
       );
     }
     const page = context.pages()[0] || await context.newPage();
@@ -7758,9 +7848,9 @@ function withTokenQuery2(wsUrl, token) {
   return url.toString();
 }
 
-// src/remote/session-client.ts
+// src/cloud/session-client.ts
 var CACHE_IMPORT_BATCH_SIZE = 200;
-var RemoteSessionClient = class {
+var CloudSessionClient = class {
   baseUrl;
   key;
   authScheme;
@@ -7781,7 +7871,17 @@ var RemoteSessionClient = class {
     if (!response.ok) {
       throw await parseHttpError(response);
     }
-    return await response.json();
+    let body;
+    try {
+      body = await response.json();
+    } catch {
+      throw new OpensteerCloudError(
+        "CLOUD_CONTRACT_MISMATCH",
+        "Invalid cloud session create response: expected a JSON object.",
+        response.status
+      );
+    }
+    return parseCreateResponse(body, response.status);
   }
   async close(sessionId) {
     const response = await fetch(`${this.baseUrl}/sessions/${sessionId}`, {
@@ -7840,6 +7940,134 @@ var RemoteSessionClient = class {
 function normalizeBaseUrl(baseUrl) {
   return baseUrl.replace(/\/+$/, "");
 }
+function parseCreateResponse(body, status) {
+  const root = requireObject(
+    body,
+    "Invalid cloud session create response: expected a JSON object.",
+    status
+  );
+  const sessionId = requireString(root, "sessionId", status);
+  const actionWsUrl = requireString(root, "actionWsUrl", status);
+  const cdpWsUrl = requireString(root, "cdpWsUrl", status);
+  const actionToken = requireString(root, "actionToken", status);
+  const cdpToken = requireString(root, "cdpToken", status);
+  const cloudSessionUrl = requireString(root, "cloudSessionUrl", status);
+  const cloudSessionRoot = requireObject(
+    root.cloudSession,
+    "Invalid cloud session create response: cloudSession must be an object.",
+    status
+  );
+  const cloudSession = {
+    sessionId: requireString(cloudSessionRoot, "sessionId", status, "cloudSession"),
+    workspaceId: requireString(
+      cloudSessionRoot,
+      "workspaceId",
+      status,
+      "cloudSession"
+    ),
+    state: requireString(cloudSessionRoot, "state", status, "cloudSession"),
+    createdAt: requireNumber(cloudSessionRoot, "createdAt", status, "cloudSession"),
+    sourceType: requireSourceType(cloudSessionRoot, "sourceType", status, "cloudSession"),
+    sourceRef: optionalString(cloudSessionRoot, "sourceRef", status, "cloudSession"),
+    label: optionalString(cloudSessionRoot, "label", status, "cloudSession")
+  };
+  const expiresAt = optionalNumber(root, "expiresAt", status);
+  return {
+    sessionId,
+    actionWsUrl,
+    cdpWsUrl,
+    actionToken,
+    cdpToken,
+    expiresAt,
+    cloudSessionUrl,
+    cloudSession
+  };
+}
+function requireObject(value, message, status) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new OpensteerCloudError("CLOUD_CONTRACT_MISMATCH", message, status);
+  }
+  return value;
+}
+function requireString(source, field, status, parent) {
+  const value = source[field];
+  if (typeof value !== "string" || !value.trim()) {
+    throw new OpensteerCloudError(
+      "CLOUD_CONTRACT_MISMATCH",
+      `Invalid cloud session create response: ${formatFieldPath(
+        field,
+        parent
+      )} must be a non-empty string.`,
+      status
+    );
+  }
+  return value;
+}
+function requireNumber(source, field, status, parent) {
+  const value = source[field];
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new OpensteerCloudError(
+      "CLOUD_CONTRACT_MISMATCH",
+      `Invalid cloud session create response: ${formatFieldPath(
+        field,
+        parent
+      )} must be a finite number.`,
+      status
+    );
+  }
+  return value;
+}
+function optionalString(source, field, status, parent) {
+  const value = source[field];
+  if (value == null) {
+    return void 0;
+  }
+  if (typeof value !== "string") {
+    throw new OpensteerCloudError(
+      "CLOUD_CONTRACT_MISMATCH",
+      `Invalid cloud session create response: ${formatFieldPath(
+        field,
+        parent
+      )} must be a string when present.`,
+      status
+    );
+  }
+  return value;
+}
+function optionalNumber(source, field, status, parent) {
+  const value = source[field];
+  if (value == null) {
+    return void 0;
+  }
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new OpensteerCloudError(
+      "CLOUD_CONTRACT_MISMATCH",
+      `Invalid cloud session create response: ${formatFieldPath(
+        field,
+        parent
+      )} must be a finite number when present.`,
+      status
+    );
+  }
+  return value;
+}
+function requireSourceType(source, field, status, parent) {
+  const value = source[field];
+  if (value === "agent-thread" || value === "agent-run" || value === "local-cloud" || value === "manual") {
+    return value;
+  }
+  throw new OpensteerCloudError(
+    "CLOUD_CONTRACT_MISMATCH",
+    `Invalid cloud session create response: ${formatFieldPath(
+      field,
+      parent
+    )} must be one of "agent-thread", "agent-run", "local-cloud", or "manual".`,
+    status
+  );
+}
+function formatFieldPath(field, parent) {
+  return parent ? `"${parent}.${field}"` : `"${field}"`;
+}
 function zeroImportResponse() {
   return {
     imported: 0,
@@ -7863,33 +8091,46 @@ async function parseHttpError(response) {
   } catch {
     body = null;
   }
-  const code = typeof body?.code === "string" ? toRemoteErrorCode(body.code) : "REMOTE_TRANSPORT_ERROR";
-  const message = typeof body?.error === "string" ? body.error : `Remote request failed with status ${response.status}.`;
-  return new OpensteerRemoteError(code, message, response.status, body?.details);
+  const code = typeof body?.code === "string" ? toCloudErrorCode(body.code) : "CLOUD_TRANSPORT_ERROR";
+  const message = typeof body?.error === "string" ? body.error : `Cloud request failed with status ${response.status}.`;
+  return new OpensteerCloudError(code, message, response.status, body?.details);
 }
-function toRemoteErrorCode(code) {
-  if (code === "REMOTE_AUTH_FAILED" || code === "REMOTE_SESSION_NOT_FOUND" || code === "REMOTE_SESSION_CLOSED" || code === "REMOTE_UNSUPPORTED_METHOD" || code === "REMOTE_INVALID_REQUEST" || code === "REMOTE_MODEL_NOT_ALLOWED" || code === "REMOTE_ACTION_FAILED" || code === "REMOTE_INTERNAL" || code === "REMOTE_CAPACITY_EXHAUSTED" || code === "REMOTE_RUNTIME_UNAVAILABLE" || code === "REMOTE_RUNTIME_MISMATCH" || code === "REMOTE_SESSION_STALE" || code === "REMOTE_CONTROL_PLANE_ERROR") {
+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") {
     return code;
   }
-  return "REMOTE_TRANSPORT_ERROR";
+  return "CLOUD_TRANSPORT_ERROR";
 }
 
-// src/remote/runtime.ts
-var DEFAULT_REMOTE_BASE_URL = "https://remote.opensteer.com";
-function createRemoteRuntimeState(key, baseUrl = resolveRemoteBaseUrl(), authScheme = "api-key") {
+// 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()) {
   return {
-    sessionClient: new RemoteSessionClient(baseUrl, key, authScheme),
-    cdpClient: new RemoteCdpClient(),
+    sessionClient: new CloudSessionClient(baseUrl, key, authScheme),
+    cdpClient: new CloudCdpClient(),
+    appUrl: normalizeCloudAppUrl(appUrl),
     actionClient: null,
-    sessionId: null
+    sessionId: null,
+    localRunId: null,
+    cloudSessionUrl: null
   };
 }
-function resolveRemoteBaseUrl() {
+function resolveCloudBaseUrl() {
   const value = process.env.OPENSTEER_BASE_URL?.trim();
-  if (!value) return DEFAULT_REMOTE_BASE_URL;
+  if (!value) return DEFAULT_CLOUD_BASE_URL;
   return value.replace(/\/+$/, "");
 }
-function readRemoteActionDescription(payload) {
+function resolveCloudAppUrl() {
+  const value = process.env.OPENSTEER_APP_URL?.trim();
+  if (!value) return DEFAULT_CLOUD_APP_URL;
+  return normalizeCloudAppUrl(value);
+}
+function normalizeCloudAppUrl(value) {
+  if (!value) return null;
+  return value.replace(/\/+$/, "");
+}
+function readCloudActionDescription(payload) {
   const description = payload.description;
   if (typeof description !== "string") return void 0;
   const normalized = description.trim();
@@ -7897,7 +8138,7 @@ function readRemoteActionDescription(payload) {
 }
 
 // src/opensteer.ts
-var REMOTE_INTERACTION_METHODS = /* @__PURE__ */ new Set([
+var CLOUD_INTERACTION_METHODS = /* @__PURE__ */ new Set([
   "click",
   "dblclick",
   "rightclick",
@@ -7914,7 +8155,7 @@ var Opensteer = class _Opensteer {
   namespace;
   storage;
   pool;
-  remote;
+  cloud;
   browser = null;
   pageRef = null;
   contextRef = null;
@@ -7922,8 +8163,8 @@ var Opensteer = class _Opensteer {
   snapshotCache = null;
   constructor(config = {}) {
     const resolved = resolveConfig(config);
-    const modeSelection = resolveModeSelection({
-      mode: resolved.mode
+    const cloudSelection = resolveCloudSelection({
+      cloud: resolved.cloud
     });
     const model = resolved.model;
     this.config = resolved;
@@ -7933,21 +8174,22 @@ var Opensteer = class _Opensteer {
     this.namespace = resolveNamespace(resolved, rootDir);
     this.storage = new LocalSelectorStorage(rootDir, this.namespace);
     this.pool = new BrowserPool(resolved.browser || {});
-    if (modeSelection.mode === "remote") {
-      const remoteConfig = resolved.remote && typeof resolved.remote === "object" ? resolved.remote : void 0;
-      const apiKey = remoteConfig?.apiKey?.trim();
+    if (cloudSelection.cloud) {
+      const cloudConfig = resolved.cloud && typeof resolved.cloud === "object" ? resolved.cloud : void 0;
+      const apiKey = cloudConfig?.apiKey?.trim();
       if (!apiKey) {
         throw new Error(
-          "Remote mode requires a non-empty API key via remote.apiKey or OPENSTEER_API_KEY."
+          "Cloud mode requires a non-empty API key via cloud.apiKey or OPENSTEER_API_KEY."
         );
       }
-      this.remote = createRemoteRuntimeState(
+      this.cloud = createCloudRuntimeState(
         apiKey,
-        remoteConfig?.baseUrl,
-        remoteConfig?.authScheme
+        cloudConfig?.baseUrl,
+        cloudConfig?.authScheme,
+        cloudConfig?.appUrl
       );
     } else {
-      this.remote = null;
+      this.cloud = null;
     }
   }
   createLazyResolveCallback(model) {
@@ -7985,32 +8227,32 @@ var Opensteer = class _Opensteer {
     };
     return extract;
   }
-  async invokeRemoteActionAndResetCache(method, args) {
-    const result = await this.invokeRemoteAction(method, args);
+  async invokeCloudActionAndResetCache(method, args) {
+    const result = await this.invokeCloudAction(method, args);
     this.snapshotCache = null;
     return result;
   }
-  async invokeRemoteAction(method, args) {
-    const actionClient = this.remote?.actionClient;
-    const sessionId = this.remote?.sessionId;
+  async invokeCloudAction(method, args) {
+    const actionClient = this.cloud?.actionClient;
+    const sessionId = this.cloud?.sessionId;
     if (!actionClient || !sessionId) {
-      throw remoteNotLaunchedError();
+      throw cloudNotLaunchedError();
     }
     const payload = args && typeof args === "object" ? args : {};
     try {
       return await actionClient.request(method, payload);
     } catch (err) {
-      if (err instanceof OpensteerRemoteError && err.code === "REMOTE_ACTION_FAILED" && REMOTE_INTERACTION_METHODS.has(method)) {
+      if (err instanceof OpensteerCloudError && err.code === "CLOUD_ACTION_FAILED" && CLOUD_INTERACTION_METHODS.has(method)) {
         const detailsRecord = err.details && typeof err.details === "object" ? err.details : null;
-        const remoteFailure = normalizeActionFailure(
+        const cloudFailure = normalizeActionFailure(
           detailsRecord?.actionFailure
         );
-        const failure = remoteFailure || classifyActionFailure({
+        const failure = cloudFailure || classifyActionFailure({
           action: method,
           error: err,
           fallbackMessage: defaultActionFailureMessage(method)
         });
-        const description = readRemoteActionDescription(payload);
+        const description = readCloudActionDescription(payload);
         throw this.buildActionError(
           method,
           description,
@@ -8051,8 +8293,36 @@ var Opensteer = class _Opensteer {
     }
     return this.contextRef;
   }
-  getRemoteSessionId() {
-    return this.remote?.sessionId ?? null;
+  getCloudSessionId() {
+    return this.cloud?.sessionId ?? null;
+  }
+  getCloudSessionUrl() {
+    return this.cloud?.cloudSessionUrl ?? null;
+  }
+  announceCloudSession(args) {
+    if (!this.shouldAnnounceCloudSession()) {
+      return;
+    }
+    const fields = [
+      `sessionId=${args.sessionId}`,
+      `workspaceId=${args.workspaceId}`
+    ];
+    if (args.cloudSessionUrl) {
+      fields.push(`url=${args.cloudSessionUrl}`);
+    }
+    process.stderr.write(`[opensteer] cloud session ready ${fields.join(" ")}
+`);
+  }
+  shouldAnnounceCloudSession() {
+    const cloudConfig = this.config.cloud && typeof this.config.cloud === "object" ? this.config.cloud : null;
+    const announce = cloudConfig?.announce ?? "always";
+    if (announce === "off") {
+      return false;
+    }
+    if (announce === "tty") {
+      return Boolean(process.stderr.isTTY);
+    }
+    return true;
   }
   async launch(options = {}) {
     if (this.pageRef && !this.ownsBrowser) {
@@ -8063,22 +8333,29 @@ var Opensteer = class _Opensteer {
     if (this.pageRef && this.ownsBrowser) {
       return;
     }
-    if (this.remote) {
+    if (this.cloud) {
       let actionClient = null;
       let browser = null;
       let sessionId = null;
+      let localRunId = null;
       try {
         try {
-          await this.syncLocalSelectorCacheToRemote();
+          await this.syncLocalSelectorCacheToCloud();
         } catch (error) {
           if (this.config.debug) {
             const message = error instanceof Error ? error.message : String(error);
             console.warn(
-              `[opensteer] remote selector cache sync failed: ${message}`
+              `[opensteer] cloud selector cache sync failed: ${message}`
             );
           }
         }
-        const session2 = await this.remote.sessionClient.create({
+        localRunId = this.cloud.localRunId || buildLocalRunId(this.namespace);
+        this.cloud.localRunId = localRunId;
+        const session2 = await this.cloud.sessionClient.create({
+          cloudSessionContractVersion,
+          sourceType: "local-cloud",
+          clientSessionHint: this.namespace,
+          localRunId,
           name: this.namespace,
           model: this.config.model,
           launchContext: options.context || void 0
@@ -8089,7 +8366,7 @@ var Opensteer = class _Opensteer {
           token: session2.actionToken,
           sessionId: session2.sessionId
         });
-        const cdpConnection = await this.remote.cdpClient.connect({
+        const cdpConnection = await this.cloud.cdpClient.connect({
           wsUrl: session2.cdpWsUrl,
           token: session2.cdpToken
         });
@@ -8099,8 +8376,17 @@ var Opensteer = class _Opensteer {
         this.pageRef = cdpConnection.page;
         this.ownsBrowser = true;
         this.snapshotCache = null;
-        this.remote.actionClient = actionClient;
-        this.remote.sessionId = sessionId;
+        this.cloud.actionClient = actionClient;
+        this.cloud.sessionId = sessionId;
+        this.cloud.cloudSessionUrl = buildCloudSessionUrl(
+          this.cloud.appUrl,
+          session2.cloudSession.sessionId
+        );
+        this.announceCloudSession({
+          sessionId: session2.sessionId,
+          workspaceId: session2.cloudSession.workspaceId,
+          cloudSessionUrl: this.cloud.cloudSessionUrl
+        });
         return;
       } catch (error) {
         if (actionClient) {
@@ -8110,8 +8396,9 @@ var Opensteer = class _Opensteer {
           await browser.close().catch(() => void 0);
         }
         if (sessionId) {
-          await this.remote.sessionClient.close(sessionId).catch(() => void 0);
+          await this.cloud.sessionClient.close(sessionId).catch(() => void 0);
         }
+        this.cloud.cloudSessionUrl = null;
         throw error;
       }
     }
@@ -8129,13 +8416,13 @@ var Opensteer = class _Opensteer {
   }
   static from(page, config = {}) {
     const resolvedConfig = resolveConfig(config);
-    const modeSelection = resolveModeSelection({
-      mode: resolvedConfig.mode
+    const cloudSelection = resolveCloudSelection({
+      cloud: resolvedConfig.cloud
     });
-    if (modeSelection.mode === "remote") {
-      throw remoteUnsupportedMethodError(
+    if (cloudSelection.cloud) {
+      throw cloudUnsupportedMethodError(
         "Opensteer.from(page)",
-        "Opensteer.from(page) is not supported in remote mode."
+        "Opensteer.from(page) is not supported in cloud mode."
       );
     }
     const instance = new _Opensteer(config);
@@ -8148,12 +8435,14 @@ var Opensteer = class _Opensteer {
   }
   async close() {
     this.snapshotCache = null;
-    if (this.remote) {
-      const actionClient = this.remote.actionClient;
-      const sessionId = this.remote.sessionId;
+    if (this.cloud) {
+      const actionClient = this.cloud.actionClient;
+      const sessionId = this.cloud.sessionId;
       const browser = this.browser;
-      this.remote.actionClient = null;
-      this.remote.sessionId = null;
+      this.cloud.actionClient = null;
+      this.cloud.sessionId = null;
+      this.cloud.localRunId = null;
+      this.cloud.cloudSessionUrl = null;
       this.browser = null;
       this.pageRef = null;
       this.contextRef = null;
@@ -8165,7 +8454,7 @@ var Opensteer = class _Opensteer {
         await browser.close().catch(() => void 0);
       }
       if (sessionId) {
-        await this.remote.sessionClient.close(sessionId).catch(() => void 0);
+        await this.cloud.sessionClient.close(sessionId).catch(() => void 0);
       }
       return;
     }
@@ -8177,17 +8466,17 @@ var Opensteer = class _Opensteer {
     this.contextRef = null;
     this.ownsBrowser = false;
   }
-  async syncLocalSelectorCacheToRemote() {
-    if (!this.remote) return;
+  async syncLocalSelectorCacheToCloud() {
+    if (!this.cloud) return;
     const entries = collectLocalSelectorCacheEntries(this.storage);
     if (!entries.length) return;
-    await this.remote.sessionClient.importSelectorCache({
+    await this.cloud.sessionClient.importSelectorCache({
       entries
     });
   }
   async goto(url, options) {
-    if (this.remote) {
-      await this.invokeRemoteActionAndResetCache("goto", { url, options });
+    if (this.cloud) {
+      await this.invokeCloudActionAndResetCache("goto", { url, options });
       return;
     }
     const { waitUntil = "domcontentloaded", ...rest } = options ?? {};
@@ -8196,8 +8485,8 @@ var Opensteer = class _Opensteer {
     this.snapshotCache = null;
   }
   async snapshot(options = {}) {
-    if (this.remote) {
-      return await this.invokeRemoteActionAndResetCache("snapshot", {
+    if (this.cloud) {
+      return await this.invokeCloudActionAndResetCache("snapshot", {
         options
       });
     }
@@ -8206,8 +8495,8 @@ var Opensteer = class _Opensteer {
     return prepared.cleanedHtml;
   }
   async state() {
-    if (this.remote) {
-      return await this.invokeRemoteAction("state", {});
+    if (this.cloud) {
+      return await this.invokeCloudAction("state", {});
     }
     const html = await this.snapshot({ mode: "action" });
     return {
@@ -8217,8 +8506,8 @@ var Opensteer = class _Opensteer {
     };
   }
   async screenshot(options = {}) {
-    if (this.remote) {
-      const b64 = await this.invokeRemoteAction(
+    if (this.cloud) {
+      const b64 = await this.invokeCloudAction(
         "screenshot",
         options
       );
@@ -8232,8 +8521,8 @@ var Opensteer = class _Opensteer {
     });
   }
   async click(options) {
-    if (this.remote) {
-      return await this.invokeRemoteActionAndResetCache(
+    if (this.cloud) {
+      return await this.invokeCloudActionAndResetCache(
         "click",
         options
       );
@@ -8245,8 +8534,8 @@ var Opensteer = class _Opensteer {
     });
   }
   async dblclick(options) {
-    if (this.remote) {
-      return await this.invokeRemoteActionAndResetCache(
+    if (this.cloud) {
+      return await this.invokeCloudActionAndResetCache(
         "dblclick",
         options
       );
@@ -8258,8 +8547,8 @@ var Opensteer = class _Opensteer {
     });
   }
   async rightclick(options) {
-    if (this.remote) {
-      return await this.invokeRemoteActionAndResetCache(
+    if (this.cloud) {
+      return await this.invokeCloudActionAndResetCache(
         "rightclick",
         options
       );
@@ -8271,8 +8560,8 @@ var Opensteer = class _Opensteer {
     });
   }
   async hover(options) {
-    if (this.remote) {
-      return await this.invokeRemoteActionAndResetCache(
+    if (this.cloud) {
+      return await this.invokeCloudActionAndResetCache(
         "hover",
         options
       );
@@ -8370,8 +8659,8 @@ var Opensteer = class _Opensteer {
     );
   }
   async input(options) {
-    if (this.remote) {
-      return await this.invokeRemoteActionAndResetCache(
+    if (this.cloud) {
+      return await this.invokeCloudActionAndResetCache(
         "input",
         options
       );
@@ -8473,8 +8762,8 @@ var Opensteer = class _Opensteer {
     );
   }
   async select(options) {
-    if (this.remote) {
-      return await this.invokeRemoteActionAndResetCache(
+    if (this.cloud) {
+      return await this.invokeCloudActionAndResetCache(
         "select",
         options
       );
@@ -8583,8 +8872,8 @@ var Opensteer = class _Opensteer {
     );
   }
   async scroll(options = {}) {
-    if (this.remote) {
-      return await this.invokeRemoteActionAndResetCache(
+    if (this.cloud) {
+      return await this.invokeCloudActionAndResetCache(
         "scroll",
         options
       );
@@ -8685,14 +8974,14 @@ var Opensteer = class _Opensteer {
   }
   // --- Tab Management ---
   async tabs() {
-    if (this.remote) {
-      return await this.invokeRemoteAction("tabs", {});
+    if (this.cloud) {
+      return await this.invokeCloudAction("tabs", {});
     }
     return listTabs(this.context, this.page);
   }
   async newTab(url) {
-    if (this.remote) {
-      return await this.invokeRemoteActionAndResetCache("newTab", {
+    if (this.cloud) {
+      return await this.invokeCloudActionAndResetCache("newTab", {
         url
       });
     }
@@ -8702,8 +8991,8 @@ var Opensteer = class _Opensteer {
     return info;
   }
   async switchTab(index) {
-    if (this.remote) {
-      await this.invokeRemoteActionAndResetCache("switchTab", { index });
+    if (this.cloud) {
+      await this.invokeCloudActionAndResetCache("switchTab", { index });
       return;
     }
     const page = await switchTab(this.context, index);
@@ -8711,8 +9000,8 @@ var Opensteer = class _Opensteer {
     this.snapshotCache = null;
   }
   async closeTab(index) {
-    if (this.remote) {
-      await this.invokeRemoteActionAndResetCache("closeTab", { index });
+    if (this.cloud) {
+      await this.invokeCloudActionAndResetCache("closeTab", { index });
       return;
     }
     const newPage = await closeTab(this.context, this.page, index);
@@ -8723,8 +9012,8 @@ var Opensteer = class _Opensteer {
   }
   // --- Cookie Management ---
   async getCookies(url) {
-    if (this.remote) {
-      return await this.invokeRemoteAction(
+    if (this.cloud) {
+      return await this.invokeCloudAction(
         "getCookies",
         { url }
       );
@@ -8732,41 +9021,41 @@ var Opensteer = class _Opensteer {
     return getCookies(this.context, url);
   }
   async setCookie(cookie) {
-    if (this.remote) {
-      await this.invokeRemoteAction("setCookie", cookie);
+    if (this.cloud) {
+      await this.invokeCloudAction("setCookie", cookie);
       return;
     }
     return setCookie(this.context, cookie);
   }
   async clearCookies() {
-    if (this.remote) {
-      await this.invokeRemoteAction("clearCookies", {});
+    if (this.cloud) {
+      await this.invokeCloudAction("clearCookies", {});
       return;
     }
     return clearCookies(this.context);
   }
   async exportCookies(filePath, url) {
-    if (this.remote) {
-      throw remoteUnsupportedMethodError(
+    if (this.cloud) {
+      throw cloudUnsupportedMethodError(
         "exportCookies",
-        "exportCookies() is not supported in remote mode because it depends on local filesystem paths."
+        "exportCookies() is not supported in cloud mode because it depends on local filesystem paths."
       );
     }
     return exportCookies(this.context, filePath, url);
   }
   async importCookies(filePath) {
-    if (this.remote) {
-      throw remoteUnsupportedMethodError(
+    if (this.cloud) {
+      throw cloudUnsupportedMethodError(
         "importCookies",
-        "importCookies() is not supported in remote mode because it depends on local filesystem paths."
+        "importCookies() is not supported in cloud mode because it depends on local filesystem paths."
       );
     }
     return importCookies(this.context, filePath);
   }
   // --- Keyboard Input ---
   async pressKey(key) {
-    if (this.remote) {
-      await this.invokeRemoteActionAndResetCache("pressKey", { key });
+    if (this.cloud) {
+      await this.invokeCloudActionAndResetCache("pressKey", { key });
       return;
     }
     await this.runWithPostActionWait("pressKey", void 0, async () => {
@@ -8775,8 +9064,8 @@ var Opensteer = class _Opensteer {
     this.snapshotCache = null;
   }
   async type(text) {
-    if (this.remote) {
-      await this.invokeRemoteActionAndResetCache("type", { text });
+    if (this.cloud) {
+      await this.invokeCloudActionAndResetCache("type", { text });
       return;
     }
     await this.runWithPostActionWait("type", void 0, async () => {
@@ -8786,8 +9075,8 @@ var Opensteer = class _Opensteer {
   }
   // --- Element Info ---
   async getElementText(options) {
-    if (this.remote) {
-      return await this.invokeRemoteAction("getElementText", options);
+    if (this.cloud) {
+      return await this.invokeCloudAction("getElementText", options);
     }
     return this.executeElementInfoAction(
       "getElementText",
@@ -8800,8 +9089,8 @@ var Opensteer = class _Opensteer {
     );
   }
   async getElementValue(options) {
-    if (this.remote) {
-      return await this.invokeRemoteAction(
+    if (this.cloud) {
+      return await this.invokeCloudAction(
         "getElementValue",
         options
       );
@@ -8816,8 +9105,8 @@ var Opensteer = class _Opensteer {
     );
   }
   async getElementAttributes(options) {
-    if (this.remote) {
-      return await this.invokeRemoteAction(
+    if (this.cloud) {
+      return await this.invokeCloudAction(
         "getElementAttributes",
         options
       );
@@ -8838,8 +9127,8 @@ var Opensteer = class _Opensteer {
     );
   }
   async getElementBoundingBox(options) {
-    if (this.remote) {
-      return await this.invokeRemoteAction(
+    if (this.cloud) {
+      return await this.invokeCloudAction(
         "getElementBoundingBox",
         options
       );
@@ -8854,14 +9143,14 @@ var Opensteer = class _Opensteer {
     );
   }
   async getHtml(selector) {
-    if (this.remote) {
-      return await this.invokeRemoteAction("getHtml", { selector });
+    if (this.cloud) {
+      return await this.invokeCloudAction("getHtml", { selector });
     }
     return getPageHtml(this.page, selector);
   }
   async getTitle() {
-    if (this.remote) {
-      return await this.invokeRemoteAction("getTitle", {});
+    if (this.cloud) {
+      return await this.invokeCloudAction("getTitle", {});
     }
     return getPageTitle(this.page);
   }
@@ -8899,10 +9188,10 @@ var Opensteer = class _Opensteer {
   }
   // --- File Upload ---
   async uploadFile(options) {
-    if (this.remote) {
-      throw remoteUnsupportedMethodError(
+    if (this.cloud) {
+      throw cloudUnsupportedMethodError(
         "uploadFile",
-        "uploadFile() is not supported in remote mode because file paths must be accessible on the remote server."
+        "uploadFile() is not supported in cloud mode because file paths must be accessible on the cloud runtime."
       );
     }
     const storageKey = this.resolveStorageKey(options.description);
@@ -9004,15 +9293,15 @@ var Opensteer = class _Opensteer {
   }
   // --- Wait for Text ---
   async waitForText(text, options) {
-    if (this.remote) {
-      await this.invokeRemoteAction("waitForText", { text, options });
+    if (this.cloud) {
+      await this.invokeCloudAction("waitForText", { text, options });
       return;
     }
     await this.page.getByText(text).first().waitFor({ timeout: options?.timeout ?? 3e4 });
   }
   async extract(options) {
-    if (this.remote) {
-      return await this.invokeRemoteAction("extract", options);
+    if (this.cloud) {
+      return await this.invokeCloudAction("extract", options);
     }
     const storageKey = this.resolveStorageKey(options.description);
     const schemaHash = options.schema ? computeSchemaHash(options.schema) : null;
@@ -9064,8 +9353,8 @@ var Opensteer = class _Opensteer {
     return inflateDataPathObject(data);
   }
   async extractFromPlan(options) {
-    if (this.remote) {
-      return await this.invokeRemoteAction(
+    if (this.cloud) {
+      return await this.invokeCloudAction(
         "extractFromPlan",
         options
       );
@@ -9114,10 +9403,10 @@ var Opensteer = class _Opensteer {
     return this.storage;
   }
   clearCache() {
-    if (this.remote) {
+    if (this.cloud) {
       this.snapshotCache = null;
-      if (!this.remote.actionClient) return;
-      void this.invokeRemoteAction("clearCache", {});
+      if (!this.cloud.actionClient) return;
+      void this.invokeCloudAction("clearCache", {});
       return;
     }
     this.storage.clearNamespace();
@@ -10145,6 +10434,16 @@ function getScrollDelta2(options) {
       return { x: 0, y: absoluteAmount };
   }
 }
+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();
@@ -10153,6 +10452,8 @@ init_model();
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ActionWsClient,
+  CloudCdpClient,
+  CloudSessionClient,
   CounterResolutionError,
   ElementPathError,
   LocalSelectorStorage,
@@ -10166,9 +10467,7 @@ init_model();
   OS_UNAVAILABLE_ATTR,
   Opensteer,
   OpensteerActionError,
-  OpensteerRemoteError,
-  RemoteCdpClient,
-  RemoteSessionClient,
+  OpensteerCloudError,
   buildElementPathFromHandle,
   buildElementPathFromSelector,
   buildPathSelectorHint,
@@ -10180,6 +10479,9 @@ init_model();
   clearCookies,
   cloneElementPath,
   closeTab,
+  cloudNotLaunchedError,
+  cloudSessionContractVersion,
+  cloudUnsupportedMethodError,
   collectLocalSelectorCacheEntries,
   countArrayItemsWithPath,
   createEmptyRegistry,
@@ -10211,8 +10513,6 @@ init_model();
   performSelect,
   prepareSnapshot,
   pressKey,
-  remoteNotLaunchedError,
-  remoteUnsupportedMethodError,
   resolveCounterElement,
   resolveCountersBatch,
   resolveElementPath,