opensteer 0.4.6 → 0.4.7

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

@@ -4936,33 +4936,36 @@ var OpensteerActionError = class extends Error {
   }
 };
 
-// src/remote/errors.ts
-var OpensteerRemoteError = class extends Error {
+// src/cloud/contracts.ts
+var cloudSessionContractVersion = "v3";
+
+// 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
 import WebSocket from "ws";
 var ActionWsClient = class _ActionWsClient {
   ws;
@@ -4980,18 +4983,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."
         )
       );
     });
@@ -5003,8 +5006,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}`
           )
         );
@@ -5014,9 +5017,9 @@ var ActionWsClient = class _ActionWsClient {
   }
   async request(method, args) {
     if (this.closed || this.ws.readyState !== WebSocket.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;
@@ -5035,8 +5038,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;
   }
@@ -5054,9 +5057,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;
@@ -5069,7 +5072,7 @@ var ActionWsClient = class _ActionWsClient {
       return;
     }
     pending.reject(
-      new OpensteerRemoteError(
+      new OpensteerCloudError(
         parsed.code,
         parsed.error,
         void 0,
@@ -5097,7 +5100,7 @@ function withTokenQuery(wsUrl, token) {
   return url.toString();
 }
 
-// src/remote/local-cache-sync.ts
+// src/cloud/local-cache-sync.ts
 import fs2 from "fs";
 import path3 from "path";
 function collectLocalSelectorCacheEntries(storage) {
@@ -5221,26 +5224,26 @@ function dedupeNewest(entries) {
   return [...byKey.values()];
 }
 
-// src/remote/cdp-client.ts
+// src/cloud/cdp-client.ts
 import {
   chromium
 } from "playwright";
-var RemoteCdpClient = class {
+var CloudCdpClient = class {
   async connect(args) {
     const endpoint = withTokenQuery2(args.wsUrl, args.token);
     let browser;
     try {
       browser = await 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();
@@ -5253,9 +5256,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;
@@ -5276,7 +5279,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}`, {
@@ -5335,6 +5348,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,
@@ -5358,19 +5499,19 @@ 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/opensteer.ts
-import { createHash } from "crypto";
+import { createHash, randomUUID as randomUUID2 } from "crypto";
 
 // src/browser/pool.ts
 import {
@@ -5786,7 +5927,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);
@@ -5821,7 +5962,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 chromium2.launch({
@@ -5832,7 +5973,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 };
   }
 };
 
@@ -5869,28 +6010,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.`
     );
   }
 }
@@ -5936,20 +6076,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) {
@@ -5968,6 +6108,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;
@@ -5979,29 +6135,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"
   };
 }
@@ -6017,11 +6184,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),
@@ -6039,28 +6206,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 inputCloudAnnounce = parseCloudAnnounce(
+    inputCloudOptions?.announce,
+    "cloud.announce"
   );
-  const inputHasRemoteApiKey = Boolean(
-    inputRemoteOptions && Object.prototype.hasOwnProperty.call(inputRemoteOptions, "apiKey")
+  const inputHasCloudApiKey = Boolean(
+    inputCloudOptions && Object.prototype.hasOwnProperty.call(inputCloudOptions, "apiKey")
   );
-  const modeSelection = resolveModeSelection({
-    mode: resolved.mode
+  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
     };
   }
@@ -7456,22 +7633,35 @@ function clonePersistedExtractNode(node) {
   return JSON.parse(JSON.stringify(node));
 }
 
-// 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();
@@ -7479,7 +7669,7 @@ function readRemoteActionDescription(payload) {
 }
 
 // src/opensteer.ts
-var REMOTE_INTERACTION_METHODS = /* @__PURE__ */ new Set([
+var CLOUD_INTERACTION_METHODS = /* @__PURE__ */ new Set([
   "click",
   "dblclick",
   "rightclick",
@@ -7496,7 +7686,7 @@ var Opensteer = class _Opensteer {
   namespace;
   storage;
   pool;
-  remote;
+  cloud;
   browser = null;
   pageRef = null;
   contextRef = null;
@@ -7504,8 +7694,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;
@@ -7515,21 +7705,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) {
@@ -7567,32 +7758,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,
@@ -7633,8 +7824,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) {
@@ -7645,22 +7864,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
@@ -7671,7 +7897,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
         });
@@ -7681,8 +7907,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) {
@@ -7692,8 +7927,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;
       }
     }
@@ -7711,13 +7947,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);
@@ -7730,12 +7966,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;
@@ -7747,7 +7985,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;
     }
@@ -7759,17 +7997,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 ?? {};
@@ -7778,8 +8016,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
       });
     }
@@ -7788,8 +8026,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 {
@@ -7799,8 +8037,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
       );
@@ -7814,8 +8052,8 @@ var Opensteer = class _Opensteer {
     });
   }
   async click(options) {
-    if (this.remote) {
-      return await this.invokeRemoteActionAndResetCache(
+    if (this.cloud) {
+      return await this.invokeCloudActionAndResetCache(
         "click",
         options
       );
@@ -7827,8 +8065,8 @@ var Opensteer = class _Opensteer {
     });
   }
   async dblclick(options) {
-    if (this.remote) {
-      return await this.invokeRemoteActionAndResetCache(
+    if (this.cloud) {
+      return await this.invokeCloudActionAndResetCache(
         "dblclick",
         options
       );
@@ -7840,8 +8078,8 @@ var Opensteer = class _Opensteer {
     });
   }
   async rightclick(options) {
-    if (this.remote) {
-      return await this.invokeRemoteActionAndResetCache(
+    if (this.cloud) {
+      return await this.invokeCloudActionAndResetCache(
         "rightclick",
         options
       );
@@ -7853,8 +8091,8 @@ var Opensteer = class _Opensteer {
     });
   }
   async hover(options) {
-    if (this.remote) {
-      return await this.invokeRemoteActionAndResetCache(
+    if (this.cloud) {
+      return await this.invokeCloudActionAndResetCache(
         "hover",
         options
       );
@@ -7952,8 +8190,8 @@ var Opensteer = class _Opensteer {
     );
   }
   async input(options) {
-    if (this.remote) {
-      return await this.invokeRemoteActionAndResetCache(
+    if (this.cloud) {
+      return await this.invokeCloudActionAndResetCache(
         "input",
         options
       );
@@ -8055,8 +8293,8 @@ var Opensteer = class _Opensteer {
     );
   }
   async select(options) {
-    if (this.remote) {
-      return await this.invokeRemoteActionAndResetCache(
+    if (this.cloud) {
+      return await this.invokeCloudActionAndResetCache(
         "select",
         options
       );
@@ -8165,8 +8403,8 @@ var Opensteer = class _Opensteer {
     );
   }
   async scroll(options = {}) {
-    if (this.remote) {
-      return await this.invokeRemoteActionAndResetCache(
+    if (this.cloud) {
+      return await this.invokeCloudActionAndResetCache(
         "scroll",
         options
       );
@@ -8267,14 +8505,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
       });
     }
@@ -8284,8 +8522,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);
@@ -8293,8 +8531,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);
@@ -8305,8 +8543,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 }
       );
@@ -8314,41 +8552,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 () => {
@@ -8357,8 +8595,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 () => {
@@ -8368,8 +8606,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",
@@ -8382,8 +8620,8 @@ var Opensteer = class _Opensteer {
     );
   }
   async getElementValue(options) {
-    if (this.remote) {
-      return await this.invokeRemoteAction(
+    if (this.cloud) {
+      return await this.invokeCloudAction(
         "getElementValue",
         options
       );
@@ -8398,8 +8636,8 @@ var Opensteer = class _Opensteer {
     );
   }
   async getElementAttributes(options) {
-    if (this.remote) {
-      return await this.invokeRemoteAction(
+    if (this.cloud) {
+      return await this.invokeCloudAction(
         "getElementAttributes",
         options
       );
@@ -8420,8 +8658,8 @@ var Opensteer = class _Opensteer {
     );
   }
   async getElementBoundingBox(options) {
-    if (this.remote) {
-      return await this.invokeRemoteAction(
+    if (this.cloud) {
+      return await this.invokeCloudAction(
         "getElementBoundingBox",
         options
       );
@@ -8436,14 +8674,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);
   }
@@ -8481,10 +8719,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);
@@ -8586,15 +8824,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;
@@ -8646,8 +8884,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
       );
@@ -8696,10 +8934,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();
@@ -9727,6 +9965,16 @@ function getScrollDelta2(options) {
       return { x: 0, y: absoluteAmount };
   }
 }
+function buildLocalRunId(namespace) {
+  const normalized = namespace.trim() || "default";
+  return `${normalized}-${Date.now().toString(36)}-${randomUUID2().slice(0, 8)}`;
+}
+function buildCloudSessionUrl(appUrl, sessionId) {
+  if (!appUrl) {
+    return null;
+  }
+  return `${appUrl}/browser/${encodeURIComponent(sessionId)}`;
+}
 
 export {
   normalizeNamespace,
@@ -9789,12 +10037,13 @@ export {
   getPageTitle,
   performFileUpload,
   OpensteerActionError,
-  OpensteerRemoteError,
-  remoteUnsupportedMethodError,
-  remoteNotLaunchedError,
+  cloudSessionContractVersion,
+  OpensteerCloudError,
+  cloudUnsupportedMethodError,
+  cloudNotLaunchedError,
   ActionWsClient,
   collectLocalSelectorCacheEntries,
-  RemoteCdpClient,
-  RemoteSessionClient,
+  CloudCdpClient,
+  CloudSessionClient,
   Opensteer
 };