opensteer 0.4.6 → 0.4.7

package/dist/cli/server.cjs

@@ -752,7 +752,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);
@@ -787,7 +787,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({
@@ -798,7 +798,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 };
   }
 };
 
@@ -869,28 +869,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.`
     );
   }
 }
@@ -936,20 +935,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) {
@@ -968,6 +967,22 @@ function parseAuthScheme(value, source) {
     `Invalid ${source} value "${value}". Use "api-key" or "bearer".`
   );
 }
+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() {
   const value = process.env.OPENSTEER_API_KEY?.trim();
   if (!value) return void 0;
@@ -979,29 +994,40 @@ function resolveOpensteerAuthScheme() {
     "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) {
+  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(
+    process.env.OPENSTEER_MODE,
+    "OPENSTEER_MODE"
+  );
   if (envMode) {
     return {
-      mode: envMode,
+      cloud: envMode === "cloud",
       source: "env.OPENSTEER_MODE"
     };
   }
   return {
-    mode: "local",
+    cloud: false,
     source: "default"
   };
 }
@@ -1017,11 +1043,11 @@ function resolveConfig(input = {}) {
     );
   }
   assertNoLegacyAiConfig("Opensteer constructor config", input);
-  assertNoLegacyModeConfig("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);
-  assertNoLegacyModeConfig(".opensteer/config.json", fileConfig);
+  assertNoLegacyRuntimeConfig(".opensteer/config.json", fileConfig);
   const envConfig = {
     browser: {
       headless: parseBool(process.env.OPENSTEER_HEADLESS),
@@ -1039,28 +1065,38 @@ function resolveConfig(input = {}) {
   const resolved = mergeDeep(mergedWithEnv, input);
   const envApiKey = resolveOpensteerApiKey();
   const envAuthScheme = resolveOpensteerAuthScheme();
-  const inputRemoteOptions = normalizeRemoteOptions(input.remote);
+  const envCloudAnnounce = parseCloudAnnounce(
+    process.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
+  const inputHasCloudApiKey = Boolean(
+    inputCloudOptions && Object.prototype.hasOwnProperty.call(inputCloudOptions, "apiKey")
+  );
+  const cloudSelection = resolveCloudSelection({
+    cloud: resolved.cloud
   });
-  if (modeSelection.mode === "remote") {
-    const resolvedRemote = normalizeRemoteOptions(resolved.remote) ?? {};
-    const authScheme = inputAuthScheme ?? envAuthScheme ?? parseAuthScheme(resolvedRemote.authScheme, "remote.authScheme") ?? "api-key";
-    resolved.remote = {
-      ...resolvedRemote,
-      authScheme
+  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
     };
   }
@@ -7357,36 +7393,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;
@@ -7403,18 +7442,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."
         )
       );
     });
@@ -7426,8 +7465,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}`
           )
         );
@@ -7437,9 +7476,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;
@@ -7458,8 +7497,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;
   }
@@ -7477,9 +7516,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;
@@ -7492,7 +7531,7 @@ var ActionWsClient = class _ActionWsClient {
       return;
     }
     pending.reject(
-      new OpensteerRemoteError(
+      new OpensteerCloudError(
         parsed.code,
         parsed.error,
         void 0,
@@ -7520,7 +7559,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) {
@@ -7644,24 +7683,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();
@@ -7674,9 +7713,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;
@@ -7697,7 +7736,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}`, {
@@ -7756,6 +7805,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,
@@ -7779,33 +7956,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();
@@ -7813,7 +8003,7 @@ function readRemoteActionDescription(payload) {
 }
 
 // src/opensteer.ts
-var REMOTE_INTERACTION_METHODS = /* @__PURE__ */ new Set([
+var CLOUD_INTERACTION_METHODS = /* @__PURE__ */ new Set([
   "click",
   "dblclick",
   "rightclick",
@@ -7830,7 +8020,7 @@ var Opensteer = class _Opensteer {
   namespace;
   storage;
   pool;
-  remote;
+  cloud;
   browser = null;
   pageRef = null;
   contextRef = null;
@@ -7838,8 +8028,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;
@@ -7849,21 +8039,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) {
@@ -7901,32 +8092,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,
@@ -7967,8 +8158,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) {
@@ -7979,22 +8198,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 session3 = await this.remote.sessionClient.create({
+        localRunId = this.cloud.localRunId || buildLocalRunId(this.namespace);
+        this.cloud.localRunId = localRunId;
+        const session3 = 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
@@ -8005,7 +8231,7 @@ var Opensteer = class _Opensteer {
           token: session3.actionToken,
           sessionId: session3.sessionId
         });
-        const cdpConnection = await this.remote.cdpClient.connect({
+        const cdpConnection = await this.cloud.cdpClient.connect({
           wsUrl: session3.cdpWsUrl,
           token: session3.cdpToken
         });
@@ -8015,8 +8241,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,
+          session3.cloudSession.sessionId
+        );
+        this.announceCloudSession({
+          sessionId: session3.sessionId,
+          workspaceId: session3.cloudSession.workspaceId,
+          cloudSessionUrl: this.cloud.cloudSessionUrl
+        });
         return;
       } catch (error) {
         if (actionClient) {
@@ -8026,8 +8261,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;
       }
     }
@@ -8045,13 +8281,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 instance2 = new _Opensteer(config);
@@ -8064,12 +8300,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;
@@ -8081,7 +8319,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;
     }
@@ -8093,17 +8331,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 ?? {};
@@ -8112,8 +8350,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
       });
     }
@@ -8122,8 +8360,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 {
@@ -8133,8 +8371,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
       );
@@ -8148,8 +8386,8 @@ var Opensteer = class _Opensteer {
     });
   }
   async click(options) {
-    if (this.remote) {
-      return await this.invokeRemoteActionAndResetCache(
+    if (this.cloud) {
+      return await this.invokeCloudActionAndResetCache(
         "click",
         options
       );
@@ -8161,8 +8399,8 @@ var Opensteer = class _Opensteer {
     });
   }
   async dblclick(options) {
-    if (this.remote) {
-      return await this.invokeRemoteActionAndResetCache(
+    if (this.cloud) {
+      return await this.invokeCloudActionAndResetCache(
         "dblclick",
         options
       );
@@ -8174,8 +8412,8 @@ var Opensteer = class _Opensteer {
     });
   }
   async rightclick(options) {
-    if (this.remote) {
-      return await this.invokeRemoteActionAndResetCache(
+    if (this.cloud) {
+      return await this.invokeCloudActionAndResetCache(
         "rightclick",
         options
       );
@@ -8187,8 +8425,8 @@ var Opensteer = class _Opensteer {
     });
   }
   async hover(options) {
-    if (this.remote) {
-      return await this.invokeRemoteActionAndResetCache(
+    if (this.cloud) {
+      return await this.invokeCloudActionAndResetCache(
         "hover",
         options
       );
@@ -8286,8 +8524,8 @@ var Opensteer = class _Opensteer {
     );
   }
   async input(options) {
-    if (this.remote) {
-      return await this.invokeRemoteActionAndResetCache(
+    if (this.cloud) {
+      return await this.invokeCloudActionAndResetCache(
         "input",
         options
       );
@@ -8389,8 +8627,8 @@ var Opensteer = class _Opensteer {
     );
   }
   async select(options) {
-    if (this.remote) {
-      return await this.invokeRemoteActionAndResetCache(
+    if (this.cloud) {
+      return await this.invokeCloudActionAndResetCache(
         "select",
         options
       );
@@ -8499,8 +8737,8 @@ var Opensteer = class _Opensteer {
     );
   }
   async scroll(options = {}) {
-    if (this.remote) {
-      return await this.invokeRemoteActionAndResetCache(
+    if (this.cloud) {
+      return await this.invokeCloudActionAndResetCache(
         "scroll",
         options
       );
@@ -8601,14 +8839,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
       });
     }
@@ -8618,8 +8856,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);
@@ -8627,8 +8865,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);
@@ -8639,8 +8877,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 }
       );
@@ -8648,41 +8886,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 () => {
@@ -8691,8 +8929,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 () => {
@@ -8702,8 +8940,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",
@@ -8716,8 +8954,8 @@ var Opensteer = class _Opensteer {
     );
   }
   async getElementValue(options) {
-    if (this.remote) {
-      return await this.invokeRemoteAction(
+    if (this.cloud) {
+      return await this.invokeCloudAction(
         "getElementValue",
         options
       );
@@ -8732,8 +8970,8 @@ var Opensteer = class _Opensteer {
     );
   }
   async getElementAttributes(options) {
-    if (this.remote) {
-      return await this.invokeRemoteAction(
+    if (this.cloud) {
+      return await this.invokeCloudAction(
         "getElementAttributes",
         options
       );
@@ -8754,8 +8992,8 @@ var Opensteer = class _Opensteer {
     );
   }
   async getElementBoundingBox(options) {
-    if (this.remote) {
-      return await this.invokeRemoteAction(
+    if (this.cloud) {
+      return await this.invokeCloudAction(
         "getElementBoundingBox",
         options
       );
@@ -8770,14 +9008,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);
   }
@@ -8815,10 +9053,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);
@@ -8920,15 +9158,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;
@@ -8980,8 +9218,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
       );
@@ -9030,10 +9268,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();
@@ -10061,6 +10299,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/cli/paths.ts
 var import_os2 = require("os");
@@ -10462,7 +10710,8 @@ async function handleRequest(request, socket) {
           url: instance.page.url(),
           session,
           name: activeNamespace,
-          remoteSessionId: instance.getRemoteSessionId() ?? void 0
+          cloudSessionId: instance.getCloudSessionId() ?? void 0,
+          cloudSessionUrl: instance.getCloudSessionUrl() ?? void 0
         }
       });
     } catch (err) {