opensteer 0.6.0 → 0.6.2

package/dist/cli/server.cjs

@@ -424,7 +424,7 @@ var import_fs4 = require("fs");
 var import_crypto = require("crypto");
 
 // src/browser/pool.ts
-var import_playwright = require("playwright");
+var import_playwright2 = require("playwright");
 
 // src/browser/cdp-proxy.ts
 var import_ws = __toESM(require("ws"), 1);
@@ -763,6 +763,19 @@ function errorMessage(error) {
   return error instanceof Error ? error.message : String(error);
 }
 
+// src/browser/chromium-profile.ts
+var import_node_util = require("util");
+var import_node_child_process2 = require("child_process");
+var import_node_crypto = require("crypto");
+var import_promises = require("fs/promises");
+var import_node_fs = require("fs");
+var import_node_path = require("path");
+var import_node_os = require("os");
+var import_playwright = require("playwright");
+
+// src/auth/keychain-store.ts
+var import_node_child_process = require("child_process");
+
 // src/browser/chrome.ts
 var import_os = require("os");
 var import_path = require("path");
@@ -773,9 +786,61 @@ function expandHome(p) {
   return p;
 }
 
+// src/browser/chromium-profile.ts
+var execFileAsync = (0, import_node_util.promisify)(import_node_child_process2.execFile);
+function directoryExists(filePath) {
+  try {
+    return (0, import_node_fs.statSync)(filePath).isDirectory();
+  } catch {
+    return false;
+  }
+}
+function fileExists(filePath) {
+  try {
+    return (0, import_node_fs.statSync)(filePath).isFile();
+  } catch {
+    return false;
+  }
+}
+function resolveCookieDbPath(profileDir) {
+  const candidates = [(0, import_node_path.join)(profileDir, "Network", "Cookies"), (0, import_node_path.join)(profileDir, "Cookies")];
+  for (const candidate of candidates) {
+    if (fileExists(candidate)) {
+      return candidate;
+    }
+  }
+  return null;
+}
+function resolvePersistentChromiumLaunchProfile(inputPath) {
+  const expandedPath = expandHome(inputPath.trim());
+  if (!expandedPath) {
+    return {
+      userDataDir: inputPath
+    };
+  }
+  if (fileExists(expandedPath) && (0, import_node_path.basename)(expandedPath) === "Cookies") {
+    const directParent = (0, import_node_path.dirname)(expandedPath);
+    const profileDir = (0, import_node_path.basename)(directParent) === "Network" ? (0, import_node_path.dirname)(directParent) : directParent;
+    return {
+      userDataDir: (0, import_node_path.dirname)(profileDir),
+      profileDirectory: (0, import_node_path.basename)(profileDir)
+    };
+  }
+  if (directoryExists(expandedPath) && resolveCookieDbPath(expandedPath) && fileExists((0, import_node_path.join)((0, import_node_path.dirname)(expandedPath), "Local State"))) {
+    return {
+      userDataDir: (0, import_node_path.dirname)(expandedPath),
+      profileDirectory: (0, import_node_path.basename)(expandedPath)
+    };
+  }
+  return {
+    userDataDir: expandedPath
+  };
+}
+
 // src/browser/pool.ts
 var BrowserPool = class {
   browser = null;
+  persistentContext = null;
   cdpProxy = null;
   defaults;
   constructor(defaults = {}) {
@@ -791,16 +856,23 @@ var BrowserPool = class {
     if (connectUrl) {
       return this.connectToRunning(connectUrl, options.timeout);
     }
-    if (channel || profileDir) {
-      return this.launchWithProfile(options, channel, profileDir);
+    if (profileDir) {
+      return this.launchPersistentProfile(options, channel, profileDir);
+    }
+    if (channel) {
+      return this.launchWithChannel(options, channel);
     }
     return this.launchSandbox(options);
   }
   async close() {
     const browser = this.browser;
+    const persistentContext = this.persistentContext;
     this.browser = null;
+    this.persistentContext = null;
     try {
-      if (browser) {
+      if (persistentContext) {
+        await persistentContext.close();
+      } else if (browser) {
         await browser.close();
       }
     } finally {
@@ -822,10 +894,11 @@ var BrowserPool = class {
       const target = targets[0];
       this.cdpProxy = new CDPProxy(browserWsUrl, target.id);
       const proxyWsUrl = await this.cdpProxy.start();
-      browser = await import_playwright.chromium.connectOverCDP(proxyWsUrl, {
+      browser = await import_playwright2.chromium.connectOverCDP(proxyWsUrl, {
         timeout: timeout ?? 3e4
       });
       this.browser = browser;
+      this.persistentContext = null;
       const contexts = browser.contexts();
       if (contexts.length === 0) {
         throw new Error(
@@ -841,46 +914,66 @@ var BrowserPool = class {
         await browser.close().catch(() => void 0);
       }
       this.browser = null;
+      this.persistentContext = null;
       this.cdpProxy?.close();
       this.cdpProxy = null;
       throw error;
     }
   }
-  async launchWithProfile(options, channel, profileDir) {
+  async launchPersistentProfile(options, channel, profileDir) {
     const args = [];
-    if (profileDir) {
-      args.push(`--user-data-dir=${expandHome(profileDir)}`);
+    const launchProfile = resolvePersistentChromiumLaunchProfile(profileDir);
+    if (launchProfile.profileDirectory) {
+      args.push(`--profile-directory=${launchProfile.profileDirectory}`);
+    }
+    const context = await import_playwright2.chromium.launchPersistentContext(
+      launchProfile.userDataDir,
+      {
+        channel,
+        headless: options.headless ?? this.defaults.headless,
+        executablePath: options.executablePath ?? this.defaults.executablePath ?? void 0,
+        slowMo: options.slowMo ?? this.defaults.slowMo ?? 0,
+        timeout: options.timeout,
+        ...options.context || {},
+        args
+      }
+    );
+    const browser = context.browser();
+    if (!browser) {
+      await context.close().catch(() => void 0);
+      throw new Error("Persistent browser launch did not expose a browser instance.");
     }
-    const browser = await import_playwright.chromium.launch({
+    this.browser = browser;
+    this.persistentContext = context;
+    const pages = context.pages();
+    const page = pages.length > 0 ? pages[0] : await context.newPage();
+    return { browser, context, page, isExternal: false };
+  }
+  async launchWithChannel(options, channel) {
+    const browser = await import_playwright2.chromium.launch({
       channel,
       headless: options.headless ?? this.defaults.headless,
       executablePath: options.executablePath ?? this.defaults.executablePath ?? void 0,
       slowMo: options.slowMo ?? this.defaults.slowMo ?? 0,
-      args
+      timeout: options.timeout
     });
     this.browser = browser;
-    const contexts = browser.contexts();
-    let context;
-    let page;
-    if (contexts.length > 0) {
-      context = contexts[0];
-      const pages = context.pages();
-      page = pages.length > 0 ? pages[0] : await context.newPage();
-    } else {
-      context = await browser.newContext(options.context || {});
-      page = await context.newPage();
-    }
+    this.persistentContext = null;
+    const context = await browser.newContext(options.context || {});
+    const page = await context.newPage();
     return { browser, context, page, isExternal: false };
   }
   async launchSandbox(options) {
-    const browser = await import_playwright.chromium.launch({
+    const browser = await import_playwright2.chromium.launch({
       headless: options.headless ?? this.defaults.headless,
       executablePath: options.executablePath ?? this.defaults.executablePath ?? void 0,
-      slowMo: options.slowMo ?? this.defaults.slowMo ?? 0
+      slowMo: options.slowMo ?? this.defaults.slowMo ?? 0,
+      timeout: options.timeout
     });
     const context = await browser.newContext(options.context || {});
     const page = await context.newPage();
     this.browser = browser;
+    this.persistentContext = null;
     return { browser, context, page, isExternal: false };
   }
 };
@@ -1162,6 +1255,10 @@ var DEFAULT_CONFIG = {
   storage: {
     rootDir: process.cwd()
   },
+  cursor: {
+    enabled: false,
+    profile: "snappy"
+  },
   model: "gpt-5.1",
   debug: false
 };
@@ -1215,7 +1312,7 @@ function loadDotenvValues(rootDir, baseEnv, options = {}) {
   return values;
 }
 function resolveEnv(rootDir, options = {}) {
-  const baseEnv = process.env;
+  const baseEnv = options.baseEnv ?? process.env;
   const dotenvValues = loadDotenvValues(rootDir, baseEnv, options);
   return {
     ...dotenvValues,
@@ -1364,6 +1461,11 @@ function resolveOpensteerApiKey(env) {
   if (!value) return void 0;
   return value;
 }
+function resolveOpensteerAccessToken(env) {
+  const value = env.OPENSTEER_ACCESS_TOKEN?.trim();
+  if (!value) return void 0;
+  return value;
+}
 function resolveOpensteerBaseUrl(env) {
   const value = env.OPENSTEER_BASE_URL?.trim();
   if (!value) return void 0;
@@ -1372,12 +1474,71 @@ function resolveOpensteerBaseUrl(env) {
 function resolveOpensteerAuthScheme(env) {
   return parseAuthScheme(env.OPENSTEER_AUTH_SCHEME, "OPENSTEER_AUTH_SCHEME");
 }
+function resolveOpensteerCloudProfileId(env) {
+  const value = env.OPENSTEER_CLOUD_PROFILE_ID?.trim();
+  if (!value) return void 0;
+  return value;
+}
+function resolveOpensteerCloudProfileReuseIfActive(env) {
+  return parseBool(env.OPENSTEER_CLOUD_PROFILE_REUSE_IF_ACTIVE);
+}
+function parseCloudBrowserProfileReuseIfActive(value) {
+  if (value == null) return void 0;
+  if (typeof value !== "boolean") {
+    throw new Error(
+      `Invalid cloud.browserProfile.reuseIfActive value "${String(
+        value
+      )}". Use true or false.`
+    );
+  }
+  return value;
+}
+function normalizeCloudBrowserProfileOptions(value, source) {
+  if (value == null) {
+    return void 0;
+  }
+  if (typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(
+      `Invalid ${source} value "${String(value)}". Use an object with profileId and optional reuseIfActive.`
+    );
+  }
+  const record = value;
+  const rawProfileId = record.profileId;
+  if (typeof rawProfileId !== "string" || !rawProfileId.trim()) {
+    throw new Error(
+      `${source}.profileId must be a non-empty string when browserProfile is provided.`
+    );
+  }
+  return {
+    profileId: rawProfileId.trim(),
+    reuseIfActive: parseCloudBrowserProfileReuseIfActive(record.reuseIfActive)
+  };
+}
+function resolveEnvCloudBrowserProfile(profileId, reuseIfActive) {
+  if (reuseIfActive !== void 0 && !profileId) {
+    throw new Error(
+      "OPENSTEER_CLOUD_PROFILE_REUSE_IF_ACTIVE requires OPENSTEER_CLOUD_PROFILE_ID."
+    );
+  }
+  if (!profileId) {
+    return void 0;
+  }
+  return {
+    profileId,
+    reuseIfActive
+  };
+}
 function normalizeCloudOptions(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
     return void 0;
   }
   return value;
 }
+function normalizeNonEmptyString(value) {
+  if (typeof value !== "string") return void 0;
+  const normalized = value.trim();
+  return normalized.length ? normalized : void 0;
+}
 function parseCloudEnabled(value, source) {
   if (value == null) return void 0;
   if (typeof value === "boolean") return value;
@@ -1406,8 +1567,8 @@ function resolveCloudSelection(config, env = process.env) {
     source: "default"
   };
 }
-function resolveConfigWithEnv(input = {}) {
-  const processEnv = process.env;
+function resolveConfigWithEnv(input = {}, options = {}) {
+  const processEnv = options.env ?? process.env;
   const debugHint = typeof input.debug === "boolean" ? input.debug : parseBool(processEnv.OPENSTEER_DEBUG) === true;
   const initialRootDir = input.storage?.rootDir ?? process.cwd();
   const runtimeDefaults = mergeDeep(DEFAULT_CONFIG, {
@@ -1425,7 +1586,8 @@ function resolveConfigWithEnv(input = {}) {
   const fileRootDir = typeof fileConfig.storage?.rootDir === "string" ? fileConfig.storage.rootDir : void 0;
   const envRootDir = input.storage?.rootDir ?? fileRootDir ?? initialRootDir;
   const env = resolveEnv(envRootDir, {
-    debug: debugHint
+    debug: debugHint,
+    baseEnv: processEnv
   });
   if (env.OPENSTEER_AI_MODEL) {
     throw new Error(
@@ -1446,6 +1608,9 @@ function resolveConfigWithEnv(input = {}) {
       channel: env.OPENSTEER_CHANNEL || void 0,
       profileDir: env.OPENSTEER_PROFILE_DIR || void 0
     },
+    cursor: {
+      enabled: parseBool(env.OPENSTEER_CURSOR)
+    },
     model: env.OPENSTEER_MODEL || void 0,
     debug: parseBool(env.OPENSTEER_DEBUG)
   };
@@ -1453,13 +1618,27 @@ function resolveConfigWithEnv(input = {}) {
   const mergedWithEnv = mergeDeep(mergedWithFile, envConfig);
   const resolved = mergeDeep(mergedWithEnv, input);
   const envApiKey = resolveOpensteerApiKey(env);
+  const envAccessTokenRaw = resolveOpensteerAccessToken(env);
   const envBaseUrl = resolveOpensteerBaseUrl(env);
   const envAuthScheme = resolveOpensteerAuthScheme(env);
+  if (envApiKey && envAccessTokenRaw) {
+    throw new Error(
+      "OPENSTEER_API_KEY and OPENSTEER_ACCESS_TOKEN are mutually exclusive. Set only one."
+    );
+  }
+  const envAccessToken = envAccessTokenRaw || (envAuthScheme === "bearer" ? envApiKey : void 0);
+  const envApiCredential = envAuthScheme === "bearer" && !envAccessTokenRaw ? void 0 : envApiKey;
+  const envCloudProfileId = resolveOpensteerCloudProfileId(env);
+  const envCloudProfileReuseIfActive = resolveOpensteerCloudProfileReuseIfActive(env);
   const envCloudAnnounce = parseCloudAnnounce(
     env.OPENSTEER_REMOTE_ANNOUNCE,
     "OPENSTEER_REMOTE_ANNOUNCE"
   );
   const inputCloudOptions = normalizeCloudOptions(input.cloud);
+  const inputCloudBrowserProfile = normalizeCloudBrowserProfileOptions(
+    inputCloudOptions?.browserProfile,
+    "cloud.browserProfile"
+  );
   const inputAuthScheme = parseAuthScheme(
     inputCloudOptions?.authScheme,
     "cloud.authScheme"
@@ -1471,26 +1650,65 @@ function resolveConfigWithEnv(input = {}) {
   const inputHasCloudApiKey = Boolean(
     inputCloudOptions && Object.prototype.hasOwnProperty.call(inputCloudOptions, "apiKey")
   );
+  const inputHasCloudAccessToken = Boolean(
+    inputCloudOptions && Object.prototype.hasOwnProperty.call(inputCloudOptions, "accessToken")
+  );
   const inputHasCloudBaseUrl = Boolean(
     inputCloudOptions && Object.prototype.hasOwnProperty.call(inputCloudOptions, "baseUrl")
   );
+  if (normalizeNonEmptyString(inputCloudOptions?.apiKey) && normalizeNonEmptyString(inputCloudOptions?.accessToken)) {
+    throw new Error(
+      "cloud.apiKey and cloud.accessToken are mutually exclusive. Set only one."
+    );
+  }
   const cloudSelection = resolveCloudSelection({
     cloud: resolved.cloud
   }, env);
   if (cloudSelection.cloud) {
     const resolvedCloud = normalizeCloudOptions(resolved.cloud) ?? {};
-    const authScheme = inputAuthScheme ?? envAuthScheme ?? parseAuthScheme(resolvedCloud.authScheme, "cloud.authScheme") ?? "api-key";
+    const {
+      apiKey: resolvedCloudApiKeyRaw,
+      accessToken: resolvedCloudAccessTokenRaw,
+      ...resolvedCloudRest
+    } = resolvedCloud;
+    if (normalizeNonEmptyString(resolvedCloudApiKeyRaw) && normalizeNonEmptyString(resolvedCloudAccessTokenRaw)) {
+      throw new Error(
+        "Cloud config cannot include both apiKey and accessToken at the same time."
+      );
+    }
+    const resolvedCloudBrowserProfile = normalizeCloudBrowserProfileOptions(
+      resolvedCloud.browserProfile,
+      "resolved.cloud.browserProfile"
+    );
+    const envCloudBrowserProfile = resolveEnvCloudBrowserProfile(
+      envCloudProfileId,
+      envCloudProfileReuseIfActive
+    );
+    const browserProfile = inputCloudBrowserProfile ?? envCloudBrowserProfile ?? resolvedCloudBrowserProfile;
+    let authScheme = inputAuthScheme ?? envAuthScheme ?? parseAuthScheme(resolvedCloud.authScheme, "cloud.authScheme") ?? "api-key";
     const announce = inputCloudAnnounce ?? envCloudAnnounce ?? parseCloudAnnounce(resolvedCloud.announce, "cloud.announce") ?? "always";
+    const credentialOverriddenByInput = inputHasCloudApiKey || inputHasCloudAccessToken;
+    let apiKey = normalizeNonEmptyString(resolvedCloudApiKeyRaw);
+    let accessToken = normalizeNonEmptyString(resolvedCloudAccessTokenRaw);
+    if (!credentialOverriddenByInput) {
+      if (envAccessToken) {
+        accessToken = envAccessToken;
+        apiKey = void 0;
+      } else if (envApiCredential) {
+        apiKey = envApiCredential;
+        accessToken = void 0;
+      }
+    }
+    if (accessToken) {
+      authScheme = "bearer";
+    }
     resolved.cloud = {
-      ...resolvedCloud,
+      ...resolvedCloudRest,
+      ...inputHasCloudApiKey ? { apiKey: resolvedCloudApiKeyRaw } : apiKey ? { apiKey } : {},
+      ...inputHasCloudAccessToken ? { accessToken: resolvedCloudAccessTokenRaw } : accessToken ? { accessToken } : {},
       authScheme,
-      announce
-    };
-  }
-  if (envApiKey && cloudSelection.cloud && !inputHasCloudApiKey) {
-    resolved.cloud = {
-      ...normalizeCloudOptions(resolved.cloud) ?? {},
-      apiKey: envApiKey
+      announce,
+      ...browserProfile ? { browserProfile } : {}
     };
   }
   if (envBaseUrl && cloudSelection.cloud && !inputHasCloudBaseUrl) {
@@ -4883,6 +5101,16 @@ async function probeActionabilityState(element) {
 
 // src/extract-value-normalization.ts
 var URL_LIST_ATTRIBUTES = /* @__PURE__ */ new Set(["srcset", "imagesrcset", "ping"]);
+var IFRAME_URL_ATTRIBUTES = /* @__PURE__ */ new Set([
+  "href",
+  "src",
+  "srcset",
+  "imagesrcset",
+  "action",
+  "formaction",
+  "poster",
+  "ping"
+]);
 function normalizeExtractedValue(raw, attribute) {
   if (raw == null) return null;
   const rawText = String(raw);
@@ -4898,6 +5126,19 @@ function normalizeExtractedValue(raw, attribute) {
   const text = rawText.replace(/\s+/g, " ").trim();
   return text || null;
 }
+function resolveExtractedValueInContext(normalizedValue, options) {
+  if (normalizedValue == null) return null;
+  const normalizedAttribute = String(options.attribute || "").trim().toLowerCase();
+  if (!options.insideIframe) return normalizedValue;
+  if (!IFRAME_URL_ATTRIBUTES.has(normalizedAttribute)) return normalizedValue;
+  const baseURI = String(options.baseURI || "").trim();
+  if (!baseURI) return normalizedValue;
+  try {
+    return new URL(normalizedValue, baseURI).href;
+  } catch {
+    return normalizedValue;
+  }
+}
 function pickSingleListAttributeValue(attribute, raw) {
   if (attribute === "ping") {
     const firstUrl = raw.trim().split(/\s+/)[0] || "";
@@ -5053,6 +5294,36 @@ function readDescriptorToken(value, index) {
   };
 }
 
+// src/extract-value-reader.ts
+async function readExtractedValueFromHandle(element, options) {
+  const insideIframe = await isElementInsideIframe(element);
+  const payload = await element.evaluate(
+    (target, browserOptions) => {
+      const ownerDocument = target.ownerDocument;
+      return {
+        raw: browserOptions.attribute ? target.getAttribute(browserOptions.attribute) : target.textContent,
+        baseURI: ownerDocument?.baseURI || null
+      };
+    },
+    {
+      attribute: options.attribute
+    }
+  );
+  const normalizedValue = normalizeExtractedValue(
+    payload.raw,
+    options.attribute
+  );
+  return resolveExtractedValueInContext(normalizedValue, {
+    attribute: options.attribute,
+    baseURI: payload.baseURI,
+    insideIframe
+  });
+}
+async function isElementInsideIframe(element) {
+  const ownerFrame = await element.ownerFrame();
+  return !!ownerFrame?.parentFrame();
+}
+
 // src/html/counter-runtime.ts
 var CounterResolutionError = class extends Error {
   code;
@@ -5075,13 +5346,14 @@ async function resolveCounterElement(page, counter) {
   if (entry.count > 1) {
     throw buildCounterAmbiguousError(counter);
   }
-  const handle = await resolveUniqueHandleInFrame(entry.frame, normalized);
-  const element = handle.asElement();
-  if (!element) {
-    await handle.dispose();
+  const resolution = await resolveCounterElementInFrame(entry.frame, normalized);
+  if (resolution.status === "ambiguous") {
+    throw buildCounterAmbiguousError(counter);
+  }
+  if (resolution.status === "missing") {
     throw buildCounterNotFoundError(counter);
   }
-  return element;
+  return resolution.element;
 }
 async function resolveCountersBatch(page, requests) {
   const out = {};
@@ -5095,41 +5367,57 @@ async function resolveCountersBatch(page, requests) {
     }
   }
   const valueCache = /* @__PURE__ */ new Map();
-  for (const request of requests) {
-    const normalized = normalizeCounter(request.counter);
-    if (normalized == null) {
-      out[request.key] = null;
-      continue;
-    }
-    const entry = scan.get(normalized);
-    if (!entry || entry.count <= 0 || !entry.frame) {
-      out[request.key] = null;
-      continue;
-    }
-    const cacheKey = `${normalized}:${request.attribute || ""}`;
-    if (valueCache.has(cacheKey)) {
-      out[request.key] = valueCache.get(cacheKey);
-      continue;
-    }
-    const read = await readCounterValueInFrame(
-      entry.frame,
-      normalized,
-      request.attribute
-    );
-    if (read.status === "ambiguous") {
-      throw buildCounterAmbiguousError(normalized);
-    }
-    if (read.status === "missing") {
-      valueCache.set(cacheKey, null);
-      out[request.key] = null;
-      continue;
+  const elementCache = /* @__PURE__ */ new Map();
+  try {
+    for (const request of requests) {
+      const normalized = normalizeCounter(request.counter);
+      if (normalized == null) {
+        out[request.key] = null;
+        continue;
+      }
+      const entry = scan.get(normalized);
+      if (!entry || entry.count <= 0 || !entry.frame) {
+        out[request.key] = null;
+        continue;
+      }
+      const cacheKey = `${normalized}:${request.attribute || ""}`;
+      if (valueCache.has(cacheKey)) {
+        out[request.key] = valueCache.get(cacheKey);
+        continue;
+      }
+      if (!elementCache.has(normalized)) {
+        elementCache.set(
+          normalized,
+          await resolveCounterElementInFrame(entry.frame, normalized)
+        );
+      }
+      const resolution = elementCache.get(normalized);
+      if (resolution.status === "ambiguous") {
+        throw buildCounterAmbiguousError(normalized);
+      }
+      if (resolution.status === "missing") {
+        valueCache.set(cacheKey, null);
+        out[request.key] = null;
+        continue;
+      }
+      const value = await readCounterValueFromElement(
+        resolution.element,
+        request.attribute
+      );
+      if (value.status === "missing") {
+        await resolution.element.dispose();
+        elementCache.set(normalized, {
+          status: "missing"
+        });
+        valueCache.set(cacheKey, null);
+        out[request.key] = null;
+        continue;
+      }
+      valueCache.set(cacheKey, value.value);
+      out[request.key] = value.value;
     }
-    const normalizedValue = normalizeExtractedValue(
-      read.value ?? null,
-      request.attribute
-    );
-    valueCache.set(cacheKey, normalizedValue);
-    out[request.key] = normalizedValue;
+  } finally {
+    await disposeResolvedCounterElements(elementCache.values());
   }
   return out;
 }
@@ -5201,73 +5489,79 @@ async function scanCounterOccurrences(page, counters) {
   }
   return out;
 }
-async function resolveUniqueHandleInFrame(frame, counter) {
-  return frame.evaluateHandle((targetCounter) => {
-    const matches = [];
-    const walk = (root) => {
-      const children = Array.from(root.children);
-      for (const child of children) {
-        if (child.getAttribute("c") === targetCounter) {
-          matches.push(child);
-        }
-        walk(child);
-        if (child.shadowRoot) {
-          walk(child.shadowRoot);
+async function resolveCounterElementInFrame(frame, counter) {
+  try {
+    const handle = await frame.evaluateHandle((targetCounter) => {
+      const matches = [];
+      const walk = (root) => {
+        const children = Array.from(root.children);
+        for (const child of children) {
+          if (child.getAttribute("c") === targetCounter) {
+            matches.push(child);
+          }
+          walk(child);
+          if (child.shadowRoot) {
+            walk(child.shadowRoot);
+          }
         }
+      };
+      walk(document);
+      if (!matches.length) {
+        return "missing";
       }
-    };
-    walk(document);
-    if (matches.length !== 1) {
-      return null;
+      if (matches.length > 1) {
+        return "ambiguous";
+      }
+      return matches[0];
+    }, String(counter));
+    const element = handle.asElement();
+    if (element) {
+      return {
+        status: "resolved",
+        element
+      };
+    }
+    const status = await handle.jsonValue();
+    await handle.dispose();
+    return status === "ambiguous" ? { status: "ambiguous" } : { status: "missing" };
+  } catch (error) {
+    if (isRecoverableCounterReadRace(error)) {
+      return {
+        status: "missing"
+      };
     }
-    return matches[0];
-  }, String(counter));
+    throw error;
+  }
 }
-async function readCounterValueInFrame(frame, counter, attribute) {
+async function readCounterValueFromElement(element, attribute) {
   try {
-    return await frame.evaluate(
-      ({ targetCounter, attribute: attribute2 }) => {
-        const matches = [];
-        const walk = (root) => {
-          const children = Array.from(root.children);
-          for (const child of children) {
-            if (child.getAttribute("c") === targetCounter) {
-              matches.push(child);
-            }
-            walk(child);
-            if (child.shadowRoot) {
-              walk(child.shadowRoot);
-            }
-          }
-        };
-        walk(document);
-        if (!matches.length) {
-          return {
-            status: "missing"
-          };
-        }
-        if (matches.length > 1) {
-          return {
-            status: "ambiguous"
-          };
-        }
-        const target = matches[0];
-        const value = attribute2 ? target.getAttribute(attribute2) : target.textContent;
-        return {
-          status: "ok",
-          value
-        };
-      },
-      {
-        targetCounter: String(counter),
-        attribute
-      }
-    );
-  } catch {
     return {
-      status: "missing"
+      status: "ok",
+      value: await readExtractedValueFromHandle(element, {
+        attribute
+      })
     };
+  } catch (error) {
+    if (isRecoverableCounterReadRace(error)) {
+      return {
+        status: "missing"
+      };
+    }
+    throw error;
+  }
+}
+async function disposeResolvedCounterElements(resolutions) {
+  const disposals = [];
+  for (const resolution of resolutions) {
+    if (resolution.status !== "resolved") continue;
+    disposals.push(resolution.element.dispose());
   }
+  await Promise.all(disposals);
+}
+function isRecoverableCounterReadRace(error) {
+  if (!(error instanceof Error)) return false;
+  const message = error.message;
+  return message.includes("Execution context was destroyed") || message.includes("Cannot find context with specified id") || message.includes("Cannot find execution context") || message.includes("Frame was detached") || message.includes("Element is not attached to the DOM") || message.includes("Element is detached");
 }
 function buildCounterNotFoundError(counter) {
   return new CounterResolutionError(
@@ -5883,17 +6177,6 @@ async function performSelect(page, path5, options) {
 }
 
 // src/actions/extract.ts
-async function readFieldValueFromHandle(element, options) {
-  const raw = await element.evaluate(
-    (target, payload) => {
-      return payload.attribute ? target.getAttribute(payload.attribute) : target.textContent;
-    },
-    {
-      attribute: options.attribute
-    }
-  );
-  return normalizeExtractedValue(raw, options.attribute);
-}
 async function extractWithPaths(page, fields) {
   const result = {};
   for (const field of fields) {
@@ -5905,7 +6188,7 @@ async function extractWithPaths(page, fields) {
       continue;
     }
     try {
-      result[field.key] = await readFieldValueFromHandle(
+      result[field.key] = await readExtractedValueFromHandle(
         resolved.element,
         {
           attribute: field.attribute
@@ -5941,7 +6224,7 @@ async function extractArrayRowsWithPaths(page, array) {
           field.candidates
         ) : item;
         try {
-          const value = target ? await readFieldValueFromHandle(target, {
+          const value = target ? await readExtractedValueFromHandle(target, {
             attribute: field.attribute
           }) : null;
           if (key) {
@@ -6253,7 +6536,7 @@ async function closeTab(context, activePage, index) {
 }
 
 // src/actions/cookies.ts
-var import_promises = require("fs/promises");
+var import_promises2 = require("fs/promises");
 async function getCookies(context, url) {
   return context.cookies(url ? [url] : void 0);
 }
@@ -6265,10 +6548,10 @@ async function clearCookies(context) {
 }
 async function exportCookies(context, filePath, url) {
   const cookies = await context.cookies(url ? [url] : void 0);
-  await (0, import_promises.writeFile)(filePath, JSON.stringify(cookies, null, 2), "utf-8");
+  await (0, import_promises2.writeFile)(filePath, JSON.stringify(cookies, null, 2), "utf-8");
 }
 async function importCookies(context, filePath) {
-  const raw = await (0, import_promises.readFile)(filePath, "utf-8");
+  const raw = await (0, import_promises2.readFile)(filePath, "utf-8");
   const cookies = JSON.parse(raw);
   await context.addCookies(cookies);
 }
@@ -8235,13 +8518,13 @@ function dedupeNewest(entries) {
 }
 
 // src/cloud/cdp-client.ts
-var import_playwright2 = require("playwright");
+var import_playwright3 = require("playwright");
 var CloudCdpClient = class {
   async connect(args) {
     const endpoint = withTokenQuery2(args.wsUrl, args.token);
     let browser;
     try {
-      browser = await import_playwright2.chromium.connectOverCDP(endpoint);
+      browser = await import_playwright3.chromium.connectOverCDP(endpoint);
     } catch (error) {
       const message = error instanceof Error ? error.message : "Failed to connect to cloud CDP endpoint.";
       throw new OpensteerCloudError("CLOUD_TRANSPORT_ERROR", message);
@@ -8296,31 +8579,72 @@ function withTokenQuery2(wsUrl, token) {
   return url.toString();
 }
 
-// src/cloud/session-client.ts
-var CACHE_IMPORT_BATCH_SIZE = 200;
-var CloudSessionClient = class {
-  baseUrl;
-  key;
-  authScheme;
-  constructor(baseUrl, key, authScheme = "api-key") {
-    this.baseUrl = normalizeBaseUrl(baseUrl);
-    this.key = key;
-    this.authScheme = authScheme;
+// src/utils/strip-trailing-slashes.ts
+function stripTrailingSlashes(value) {
+  let end = value.length;
+  while (end > 0 && value.charCodeAt(end - 1) === 47) {
+    end -= 1;
   }
-  async create(request) {
-    const response = await fetch(`${this.baseUrl}/sessions`, {
-      method: "POST",
-      headers: {
-        "content-type": "application/json",
-        ...this.authHeaders()
-      },
-      body: JSON.stringify(request)
-    });
-    if (!response.ok) {
-      throw await parseHttpError(response);
-    }
-    let body;
-    try {
+  return end === value.length ? value : value.slice(0, end);
+}
+
+// src/cloud/http-client.ts
+function normalizeCloudBaseUrl(baseUrl) {
+  return stripTrailingSlashes(baseUrl);
+}
+function cloudAuthHeaders(key, authScheme) {
+  if (authScheme === "bearer") {
+    return {
+      authorization: `Bearer ${key}`
+    };
+  }
+  return {
+    "x-api-key": key
+  };
+}
+async function parseCloudHttpError(response) {
+  let body = null;
+  try {
+    body = await response.json();
+  } catch {
+    body = null;
+  }
+  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 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" || code === "CLOUD_PROXY_UNAVAILABLE" || code === "CLOUD_PROXY_REQUIRED" || code === "CLOUD_BILLING_LIMIT_REACHED" || code === "CLOUD_RATE_LIMITED" || code === "CLOUD_BROWSER_PROFILE_NOT_FOUND" || code === "CLOUD_BROWSER_PROFILE_BUSY" || code === "CLOUD_BROWSER_PROFILE_DISABLED" || code === "CLOUD_BROWSER_PROFILE_PROXY_UNAVAILABLE" || code === "CLOUD_BROWSER_PROFILE_SYNC_FAILED") {
+    return code;
+  }
+  return "CLOUD_TRANSPORT_ERROR";
+}
+
+// src/cloud/session-client.ts
+var CACHE_IMPORT_BATCH_SIZE = 200;
+var CloudSessionClient = class {
+  baseUrl;
+  key;
+  authScheme;
+  constructor(baseUrl, key, authScheme = "api-key") {
+    this.baseUrl = normalizeCloudBaseUrl(baseUrl);
+    this.key = key;
+    this.authScheme = authScheme;
+  }
+  async create(request) {
+    const response = await fetch(`${this.baseUrl}/sessions`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        ...cloudAuthHeaders(this.key, this.authScheme)
+      },
+      body: JSON.stringify(request)
+    });
+    if (!response.ok) {
+      throw await parseCloudHttpError(response);
+    }
+    let body;
+    try {
       body = await response.json();
     } catch {
       throw new OpensteerCloudError(
@@ -8335,14 +8659,14 @@ var CloudSessionClient = class {
     const response = await fetch(`${this.baseUrl}/sessions/${sessionId}`, {
       method: "DELETE",
       headers: {
-        ...this.authHeaders()
+        ...cloudAuthHeaders(this.key, this.authScheme)
       }
     });
     if (response.status === 204) {
       return;
     }
     if (!response.ok) {
-      throw await parseHttpError(response);
+      throw await parseCloudHttpError(response);
     }
   }
   async importSelectorCache(request) {
@@ -8365,29 +8689,16 @@ var CloudSessionClient = class {
       method: "POST",
       headers: {
         "content-type": "application/json",
-        ...this.authHeaders()
+        ...cloudAuthHeaders(this.key, this.authScheme)
       },
       body: JSON.stringify({ entries })
     });
     if (!response.ok) {
-      throw await parseHttpError(response);
+      throw await parseCloudHttpError(response);
     }
     return await response.json();
   }
-  authHeaders() {
-    if (this.authScheme === "bearer") {
-      return {
-        authorization: `Bearer ${this.key}`
-      };
-    }
-    return {
-      "x-api-key": this.key
-    };
-  }
 };
-function normalizeBaseUrl(baseUrl) {
-  return baseUrl.replace(/\/+$/, "");
-}
 function parseCreateResponse(body, status) {
   const root = requireObject(
     body,
@@ -8532,23 +8843,6 @@ function mergeImportResponse(first, second) {
     skipped: first.skipped + second.skipped
   };
 }
-async function parseHttpError(response) {
-  let body = null;
-  try {
-    body = await response.json();
-  } catch {
-    body = null;
-  }
-  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 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 "CLOUD_TRANSPORT_ERROR";
-}
 
 // src/cloud/runtime.ts
 var DEFAULT_CLOUD_BASE_URL = "https://api.opensteer.com";
@@ -8573,9 +8867,6 @@ function resolveCloudBaseUrl() {
   if (!value) return DEFAULT_CLOUD_BASE_URL;
   return normalizeCloudBaseUrl(value);
 }
-function normalizeCloudBaseUrl(value) {
-  return value.replace(/\/+$/, "");
-}
 function readCloudActionDescription(payload) {
   const description = payload.description;
   if (typeof description !== "string") return void 0;
@@ -9906,7 +10197,7 @@ function resolveAgentConfig(args) {
   });
   return {
     mode: "cua",
-    systemPrompt: normalizeNonEmptyString(agentConfig.systemPrompt) || DEFAULT_SYSTEM_PROMPT,
+    systemPrompt: normalizeNonEmptyString2(agentConfig.systemPrompt) || DEFAULT_SYSTEM_PROMPT,
     waitBetweenActionsMs: normalizeWaitBetween(agentConfig.waitBetweenActionsMs),
     model
   };
@@ -9925,7 +10216,7 @@ function createCuaClient(config) {
       );
   }
 }
-function normalizeNonEmptyString(value) {
+function normalizeNonEmptyString2(value) {
   if (typeof value !== "string") return void 0;
   const normalized = value.trim();
   return normalized.length ? normalized : void 0;
@@ -10200,24 +10491,22 @@ var OpensteerCuaAgentHandler = class {
   page;
   config;
   client;
-  debug;
+  cursorController;
   onMutatingAction;
-  cursorOverlayInjected = false;
   constructor(options) {
     this.page = options.page;
     this.config = options.config;
     this.client = options.client;
-    this.debug = options.debug;
+    this.cursorController = options.cursorController;
     this.onMutatingAction = options.onMutatingAction;
   }
   async execute(options) {
     const instruction = options.instruction;
     const maxSteps = options.maxSteps ?? 20;
     await this.initializeClient();
-    const highlightCursor = options.highlightCursor === true;
     this.client.setActionHandler(async (action) => {
-      if (highlightCursor) {
-        await this.maybeRenderCursor(action);
+      if (this.cursorController.isEnabled()) {
+        await this.maybePreviewCursor(action);
       }
       await executeAgentAction(this.page, action);
       this.client.setCurrentUrl(this.page.url());
@@ -10248,6 +10537,7 @@ var OpensteerCuaAgentHandler = class {
     const viewport = await this.resolveViewport();
     this.client.setViewport(viewport.width, viewport.height);
     this.client.setCurrentUrl(this.page.url());
+    await this.cursorController.attachPage(this.page);
     this.client.setScreenshotProvider(async () => {
       const buffer = await this.page.screenshot({
         fullPage: false,
@@ -10276,51 +10566,611 @@ var OpensteerCuaAgentHandler = class {
     }
     return DEFAULT_CUA_VIEWPORT;
   }
-  async maybeRenderCursor(action) {
+  async maybePreviewCursor(action) {
     const x = typeof action.x === "number" ? action.x : null;
     const y = typeof action.y === "number" ? action.y : null;
     if (x == null || y == null) {
       return;
     }
+    await this.cursorController.preview({ x, y }, "agent");
+  }
+};
+function sleep4(ms) {
+  return new Promise((resolve) => setTimeout(resolve, Math.max(0, ms)));
+}
+
+// src/cursor/motion.ts
+var DEFAULT_SNAPPY_OPTIONS = {
+  minDurationMs: 46,
+  maxDurationMs: 170,
+  maxPoints: 14
+};
+function planSnappyCursorMotion(from, to, options = {}) {
+  const resolved = {
+    ...DEFAULT_SNAPPY_OPTIONS,
+    ...options
+  };
+  const dx = to.x - from.x;
+  const dy = to.y - from.y;
+  const distance = Math.hypot(dx, dy);
+  if (distance < 5) {
+    return {
+      points: [roundPoint(to)],
+      stepDelayMs: 0
+    };
+  }
+  const durationMs = clamp(
+    44 + distance * 0.26,
+    resolved.minDurationMs,
+    resolved.maxDurationMs
+  );
+  const rawPoints = clamp(
+    Math.round(durationMs / 13),
+    4,
+    resolved.maxPoints
+  );
+  const sign = deterministicBendSign(from, to);
+  const nx = -dy / distance;
+  const ny = dx / distance;
+  const bend = clamp(distance * 0.12, 8, 28) * sign;
+  const c1 = {
+    x: from.x + dx * 0.28 + nx * bend,
+    y: from.y + dy * 0.28 + ny * bend
+  };
+  const c2 = {
+    x: from.x + dx * 0.74 + nx * bend * 0.58,
+    y: from.y + dy * 0.74 + ny * bend * 0.58
+  };
+  const points = [];
+  for (let i = 1; i <= rawPoints; i += 1) {
+    const t = i / rawPoints;
+    const sampled = cubicBezier(from, c1, c2, to, t);
+    if (i !== rawPoints) {
+      const previous = points[points.length - 1];
+      if (previous && distanceBetween(previous, sampled) < 1.4) {
+        continue;
+      }
+    }
+    points.push(roundPoint(sampled));
+  }
+  if (distance > 220) {
+    const settle = {
+      x: to.x - dx / distance,
+      y: to.y - dy / distance
+    };
+    const last = points[points.length - 1];
+    if (!last || distanceBetween(last, settle) > 1.2) {
+      points.splice(Math.max(0, points.length - 1), 0, roundPoint(settle));
+    }
+  }
+  const deduped = dedupeAdjacent(points);
+  const stepDelayMs = deduped.length > 1 ? Math.round(durationMs / deduped.length) : 0;
+  return {
+    points: deduped.length ? deduped : [roundPoint(to)],
+    stepDelayMs
+  };
+}
+function cubicBezier(p0, p1, p2, p3, t) {
+  const inv = 1 - t;
+  const inv2 = inv * inv;
+  const inv3 = inv2 * inv;
+  const t2 = t * t;
+  const t3 = t2 * t;
+  return {
+    x: inv3 * p0.x + 3 * inv2 * t * p1.x + 3 * inv * t2 * p2.x + t3 * p3.x,
+    y: inv3 * p0.y + 3 * inv2 * t * p1.y + 3 * inv * t2 * p2.y + t3 * p3.y
+  };
+}
+function deterministicBendSign(from, to) {
+  const seed = Math.sin(
+    from.x * 12.9898 + from.y * 78.233 + to.x * 37.719 + to.y * 19.113
+  ) * 43758.5453;
+  const fractional = seed - Math.floor(seed);
+  return fractional >= 0.5 ? 1 : -1;
+}
+function roundPoint(point) {
+  return {
+    x: Math.round(point.x * 100) / 100,
+    y: Math.round(point.y * 100) / 100
+  };
+}
+function distanceBetween(a, b) {
+  return Math.hypot(a.x - b.x, a.y - b.y);
+}
+function dedupeAdjacent(points) {
+  const out = [];
+  for (const point of points) {
+    const last = out[out.length - 1];
+    if (last && last.x === point.x && last.y === point.y) {
+      continue;
+    }
+    out.push(point);
+  }
+  return out;
+}
+function clamp(value, min, max) {
+  return Math.min(max, Math.max(min, value));
+}
+
+// src/cursor/renderers/svg-overlay.ts
+var PULSE_DURATION_MS = 220;
+var HOST_ELEMENT_ID = "__os_cr";
+var SvgCursorRenderer = class {
+  page = null;
+  active = false;
+  reason = "disabled";
+  lastMessage;
+  async initialize(page) {
+    this.page = page;
+    if (page.isClosed()) {
+      this.markInactive("page_closed");
+      return;
+    }
+    try {
+      await page.evaluate(injectCursor, HOST_ELEMENT_ID);
+      this.active = true;
+      this.reason = void 0;
+      this.lastMessage = void 0;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      this.markInactive("renderer_error", message);
+    }
+  }
+  isActive() {
+    return this.active;
+  }
+  status() {
+    return {
+      enabled: true,
+      active: this.active,
+      reason: this.reason ? this.lastMessage ? `${this.reason}: ${this.lastMessage}` : this.reason : void 0
+    };
+  }
+  async move(point, style) {
+    if (!this.active || !this.page || this.page.isClosed()) return;
     try {
-      if (!this.cursorOverlayInjected) {
-        await this.page.evaluate(() => {
-          if (document.getElementById("__opensteer_cua_cursor")) return;
-          const cursor = document.createElement("div");
-          cursor.id = "__opensteer_cua_cursor";
-          cursor.style.position = "fixed";
-          cursor.style.width = "14px";
-          cursor.style.height = "14px";
-          cursor.style.borderRadius = "999px";
-          cursor.style.background = "rgba(255, 51, 51, 0.85)";
-          cursor.style.border = "2px solid rgba(255, 255, 255, 0.95)";
-          cursor.style.boxShadow = "0 0 0 3px rgba(255, 51, 51, 0.25)";
-          cursor.style.pointerEvents = "none";
-          cursor.style.zIndex = "2147483647";
-          cursor.style.transform = "translate(-9999px, -9999px)";
-          cursor.style.transition = "transform 80ms linear";
-          document.documentElement.appendChild(cursor);
+      const ok = await this.page.evaluate(moveCursor, {
+        id: HOST_ELEMENT_ID,
+        x: point.x,
+        y: point.y,
+        size: style.size,
+        fill: colorToRgba(style.fillColor),
+        outline: colorToRgba(style.outlineColor)
+      });
+      if (!ok) {
+        await this.reinject();
+        await this.page.evaluate(moveCursor, {
+          id: HOST_ELEMENT_ID,
+          x: point.x,
+          y: point.y,
+          size: style.size,
+          fill: colorToRgba(style.fillColor),
+          outline: colorToRgba(style.outlineColor)
         });
-        this.cursorOverlayInjected = true;
       }
-      await this.page.evaluate(
-        ({ px, py }) => {
-          const cursor = document.getElementById("__opensteer_cua_cursor");
-          if (!cursor) return;
-          cursor.style.transform = `translate(${Math.round(px - 7)}px, ${Math.round(py - 7)}px)`;
-        },
-        { px: x, py: y }
-      );
+    } catch (error) {
+      this.handleError(error);
+    }
+  }
+  async pulse(point, style) {
+    if (!this.active || !this.page || this.page.isClosed()) return;
+    try {
+      const ok = await this.page.evaluate(pulseCursor, {
+        id: HOST_ELEMENT_ID,
+        x: point.x,
+        y: point.y,
+        size: style.size,
+        fill: colorToRgba(style.fillColor),
+        outline: colorToRgba(style.outlineColor),
+        halo: colorToRgba(style.haloColor),
+        pulseMs: PULSE_DURATION_MS
+      });
+      if (!ok) {
+        await this.reinject();
+        await this.page.evaluate(pulseCursor, {
+          id: HOST_ELEMENT_ID,
+          x: point.x,
+          y: point.y,
+          size: style.size,
+          fill: colorToRgba(style.fillColor),
+          outline: colorToRgba(style.outlineColor),
+          halo: colorToRgba(style.haloColor),
+          pulseMs: PULSE_DURATION_MS
+        });
+      }
+    } catch (error) {
+      this.handleError(error);
+    }
+  }
+  async clear() {
+    if (!this.page || this.page.isClosed()) return;
+    try {
+      await this.page.evaluate(removeCursor, HOST_ELEMENT_ID);
+    } catch {
+    }
+  }
+  async dispose() {
+    if (this.page && !this.page.isClosed()) {
+      try {
+        await this.page.evaluate(removeCursor, HOST_ELEMENT_ID);
+      } catch {
+      }
+    }
+    this.active = false;
+    this.reason = "disabled";
+    this.lastMessage = void 0;
+    this.page = null;
+  }
+  async reinject() {
+    if (!this.page || this.page.isClosed()) return;
+    try {
+      await this.page.evaluate(injectCursor, HOST_ELEMENT_ID);
+    } catch {
+    }
+  }
+  markInactive(reason, message) {
+    this.active = false;
+    this.reason = reason;
+    this.lastMessage = message;
+  }
+  handleError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (isPageGone(message)) {
+      this.markInactive("page_closed", message);
+    }
+  }
+};
+function injectCursor(hostId) {
+  const win = window;
+  if (win[hostId]) return;
+  const host = document.createElement("div");
+  host.style.cssText = "position:fixed;top:0;left:0;width:0;height:0;z-index:2147483647;pointer-events:none;";
+  const shadow = host.attachShadow({ mode: "closed" });
+  const wrapper = document.createElement("div");
+  wrapper.style.cssText = "position:fixed;top:0;left:0;pointer-events:none;will-change:transform;display:none;";
+  wrapper.innerHTML = `
+        <svg width="28" height="28" viewBox="0 0 28 28" fill="none" xmlns="http://www.w3.org/2000/svg" style="filter:drop-shadow(0 1px 2px rgba(0,0,0,0.3));display:block;">
+            <path d="M3 2L3 23L8.5 17.5L13 26L17 24L12.5 15.5L20 15.5L3 2Z"
+                  fill="white" stroke="black" stroke-width="1.5" stroke-linejoin="round"/>
+        </svg>
+        <div data-role="pulse" style="position:absolute;top:0;left:0;width:24px;height:24px;border-radius:50%;pointer-events:none;opacity:0;transform:translate(-8px,-8px);"></div>
+    `;
+  shadow.appendChild(wrapper);
+  document.documentElement.appendChild(host);
+  Object.defineProperty(window, hostId, {
+    value: {
+      host,
+      wrapper,
+      path: wrapper.querySelector("path"),
+      pulse: wrapper.querySelector('[data-role="pulse"]')
+    },
+    configurable: true,
+    enumerable: false
+  });
+}
+function moveCursor(args) {
+  const refs = window[args.id];
+  if (!refs) return false;
+  const scale = args.size / 20;
+  refs.wrapper.style.transform = `translate(${args.x}px, ${args.y}px) scale(${scale})`;
+  refs.wrapper.style.display = "block";
+  if (refs.path) {
+    refs.path.setAttribute("fill", args.fill);
+    refs.path.setAttribute("stroke", args.outline);
+  }
+  return true;
+}
+function pulseCursor(args) {
+  const refs = window[args.id];
+  if (!refs) return false;
+  const scale = args.size / 20;
+  refs.wrapper.style.transform = `translate(${args.x}px, ${args.y}px) scale(${scale})`;
+  refs.wrapper.style.display = "block";
+  if (refs.path) {
+    refs.path.setAttribute("fill", args.fill);
+    refs.path.setAttribute("stroke", args.outline);
+  }
+  const ring = refs.pulse;
+  if (!ring) return true;
+  ring.style.background = args.halo;
+  ring.style.opacity = "0.7";
+  ring.style.width = "24px";
+  ring.style.height = "24px";
+  ring.style.transition = `all ${args.pulseMs}ms ease-out`;
+  ring.offsetHeight;
+  ring.style.width = "48px";
+  ring.style.height = "48px";
+  ring.style.opacity = "0";
+  ring.style.transform = "translate(-20px, -20px)";
+  setTimeout(() => {
+    ring.style.transition = "none";
+    ring.style.width = "24px";
+    ring.style.height = "24px";
+    ring.style.transform = "translate(-8px, -8px)";
+    ring.style.opacity = "0";
+  }, args.pulseMs);
+  return true;
+}
+function removeCursor(hostId) {
+  const refs = window[hostId];
+  if (refs) {
+    refs.host.remove();
+    delete window[hostId];
+  }
+}
+function colorToRgba(c) {
+  return `rgba(${Math.round(c.r)},${Math.round(c.g)},${Math.round(c.b)},${c.a})`;
+}
+function isPageGone(message) {
+  const m = message.toLowerCase();
+  return m.includes("closed") || m.includes("detached") || m.includes("destroyed") || m.includes("target");
+}
+
+// src/cursor/controller.ts
+var DEFAULT_STYLE = {
+  size: 20,
+  fillColor: {
+    r: 255,
+    g: 255,
+    b: 255,
+    a: 0.96
+  },
+  outlineColor: {
+    r: 0,
+    g: 0,
+    b: 0,
+    a: 1
+  },
+  haloColor: {
+    r: 35,
+    g: 162,
+    b: 255,
+    a: 0.38
+  },
+  pulseScale: 2.15
+};
+var REINITIALIZE_BACKOFF_MS = 1e3;
+var FIRST_MOVE_CENTER_DISTANCE_THRESHOLD = 16;
+var FIRST_MOVE_MAX_TRAVEL = 220;
+var FIRST_MOVE_NEAR_TARGET_X_OFFSET = 28;
+var FIRST_MOVE_NEAR_TARGET_Y_OFFSET = 18;
+var MOTION_PLANNERS = {
+  snappy: planSnappyCursorMotion
+};
+var CursorController = class {
+  debug;
+  renderer;
+  page = null;
+  listenerPage = null;
+  lastPoint = null;
+  initializedForPage = false;
+  lastInitializeAttemptAt = 0;
+  enabled;
+  profile;
+  style;
+  onDomContentLoaded = () => {
+    void this.restoreCursorAfterNavigation();
+  };
+  constructor(options = {}) {
+    const config = options.config || {};
+    this.debug = Boolean(options.debug);
+    this.enabled = config.enabled === true;
+    this.profile = config.profile ?? "snappy";
+    this.style = mergeStyle(config.style);
+    this.renderer = options.renderer ?? new SvgCursorRenderer();
+  }
+  setEnabled(enabled) {
+    if (this.enabled && !enabled) {
+      this.lastPoint = null;
+      void this.clear();
+    }
+    this.enabled = enabled;
+  }
+  isEnabled() {
+    return this.enabled;
+  }
+  getStatus() {
+    if (!this.enabled) {
+      return {
+        enabled: false,
+        active: false,
+        reason: "disabled"
+      };
+    }
+    const status = this.renderer.status();
+    if (!this.initializedForPage && !status.active) {
+      return {
+        enabled: true,
+        active: false,
+        reason: "not_initialized"
+      };
+    }
+    return status;
+  }
+  async attachPage(page) {
+    if (this.page !== page) {
+      this.detachPageListeners();
+      this.page = page;
+      this.lastPoint = null;
+      this.initializedForPage = false;
+      this.lastInitializeAttemptAt = 0;
+    }
+    this.attachPageListeners(page);
+  }
+  async preview(point, intent) {
+    if (!this.enabled || !point) return;
+    if (!this.page || this.page.isClosed()) return;
+    try {
+      await this.ensureInitialized();
+      if (!this.renderer.isActive()) {
+        await this.reinitializeIfEligible();
+      }
+      if (!this.renderer.isActive()) return;
+      const start = this.resolveMotionStart(point);
+      const motion = this.planMotion(start, point);
+      for (const step of motion.points) {
+        await this.renderer.move(step, this.style);
+        if (motion.stepDelayMs > 0) {
+          await sleep5(motion.stepDelayMs);
+        }
+      }
+      if (shouldPulse(intent)) {
+        await this.renderer.pulse(point, this.style);
+      }
+      this.lastPoint = point;
+    } catch (error) {
+      if (this.debug) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.warn(`[opensteer] cursor preview failed: ${message}`);
+      }
+    }
+  }
+  async clear() {
+    try {
+      await this.renderer.clear();
+    } catch (error) {
+      if (this.debug) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.warn(`[opensteer] cursor clear failed: ${message}`);
+      }
+    }
+  }
+  async dispose() {
+    this.detachPageListeners();
+    this.lastPoint = null;
+    this.initializedForPage = false;
+    this.lastInitializeAttemptAt = 0;
+    this.page = null;
+    await this.renderer.dispose();
+  }
+  async ensureInitialized() {
+    if (!this.page || this.page.isClosed()) return;
+    if (this.initializedForPage) return;
+    await this.initializeRenderer();
+  }
+  attachPageListeners(page) {
+    if (this.listenerPage === page) {
+      return;
+    }
+    this.detachPageListeners();
+    page.on("domcontentloaded", this.onDomContentLoaded);
+    this.listenerPage = page;
+  }
+  detachPageListeners() {
+    if (!this.listenerPage) {
+      return;
+    }
+    this.listenerPage.off("domcontentloaded", this.onDomContentLoaded);
+    this.listenerPage = null;
+  }
+  planMotion(from, to) {
+    return MOTION_PLANNERS[this.profile](from, to);
+  }
+  async reinitializeIfEligible() {
+    if (!this.page || this.page.isClosed()) return;
+    const elapsed = Date.now() - this.lastInitializeAttemptAt;
+    if (elapsed < REINITIALIZE_BACKOFF_MS) return;
+    await this.initializeRenderer();
+  }
+  async initializeRenderer() {
+    if (!this.page || this.page.isClosed()) return;
+    this.lastInitializeAttemptAt = Date.now();
+    await this.renderer.initialize(this.page);
+    this.initializedForPage = true;
+  }
+  async restoreCursorAfterNavigation() {
+    if (!this.enabled || !this.lastPoint) return;
+    if (!this.page || this.page.isClosed()) return;
+    try {
+      if (!this.renderer.isActive()) {
+        await this.reinitializeIfEligible();
+      }
+      if (!this.renderer.isActive()) {
+        return;
+      }
+      await this.renderer.move(this.lastPoint, this.style);
     } catch (error) {
       if (this.debug) {
         const message = error instanceof Error ? error.message : String(error);
-        console.warn(`[opensteer] cursor overlay failed: ${message}`);
+        console.warn(
+          `[opensteer] cursor restore after navigation failed: ${message}`
+        );
+      }
+    }
+  }
+  resolveMotionStart(target) {
+    if (this.lastPoint) {
+      return this.lastPoint;
+    }
+    const viewport = this.page?.viewportSize();
+    if (!viewport?.width || !viewport?.height) {
+      return target;
+    }
+    const centerPoint = {
+      x: viewport.width / 2,
+      y: viewport.height / 2
+    };
+    if (distanceBetween2(centerPoint, target) > FIRST_MOVE_CENTER_DISTANCE_THRESHOLD) {
+      const dx = target.x - centerPoint.x;
+      const dy = target.y - centerPoint.y;
+      const distance = Math.hypot(dx, dy);
+      if (distance > FIRST_MOVE_MAX_TRAVEL) {
+        const ux = dx / distance;
+        const uy = dy / distance;
+        return {
+          x: target.x - ux * FIRST_MOVE_MAX_TRAVEL,
+          y: target.y - uy * FIRST_MOVE_MAX_TRAVEL
+        };
       }
+      return centerPoint;
     }
+    return {
+      x: clamp2(target.x - FIRST_MOVE_NEAR_TARGET_X_OFFSET, 0, viewport.width),
+      y: clamp2(target.y - FIRST_MOVE_NEAR_TARGET_Y_OFFSET, 0, viewport.height)
+    };
   }
 };
-function sleep4(ms) {
-  return new Promise((resolve) => setTimeout(resolve, Math.max(0, ms)));
+function mergeStyle(style) {
+  return {
+    size: normalizeFinite(style?.size, DEFAULT_STYLE.size, 4, 48),
+    pulseScale: normalizeFinite(
+      style?.pulseScale,
+      DEFAULT_STYLE.pulseScale,
+      1,
+      3
+    ),
+    fillColor: normalizeColor(style?.fillColor, DEFAULT_STYLE.fillColor),
+    outlineColor: normalizeColor(
+      style?.outlineColor,
+      DEFAULT_STYLE.outlineColor
+    ),
+    haloColor: normalizeColor(style?.haloColor, DEFAULT_STYLE.haloColor)
+  };
+}
+function normalizeColor(color, fallback) {
+  if (!color) return { ...fallback };
+  return {
+    r: normalizeFinite(color.r, fallback.r, 0, 255),
+    g: normalizeFinite(color.g, fallback.g, 0, 255),
+    b: normalizeFinite(color.b, fallback.b, 0, 255),
+    a: normalizeFinite(color.a, fallback.a, 0, 1)
+  };
+}
+function normalizeFinite(value, fallback, min, max) {
+  const numeric = typeof value === "number" && Number.isFinite(value) ? value : fallback;
+  return Math.min(max, Math.max(min, numeric));
+}
+function distanceBetween2(a, b) {
+  return Math.hypot(a.x - b.x, a.y - b.y);
+}
+function clamp2(value, min, max) {
+  return Math.min(max, Math.max(min, value));
+}
+function shouldPulse(intent) {
+  return intent === "click" || intent === "dblclick" || intent === "rightclick" || intent === "agent";
+}
+function sleep5(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
 // src/opensteer.ts
@@ -10349,6 +11199,7 @@ var Opensteer = class _Opensteer {
   ownsBrowser = false;
   snapshotCache = null;
   agentExecutionInFlight = false;
+  cursorController = null;
   constructor(config = {}) {
     const resolvedRuntime = resolveConfigWithEnv(config);
     const resolved = resolvedRuntime.config;
@@ -10370,15 +11221,29 @@ var Opensteer = class _Opensteer {
     if (cloudSelection.cloud) {
       const cloudConfig = resolved.cloud && typeof resolved.cloud === "object" ? resolved.cloud : void 0;
       const apiKey = cloudConfig?.apiKey?.trim();
-      if (!apiKey) {
+      const accessToken = cloudConfig?.accessToken?.trim();
+      if (apiKey && accessToken) {
+        throw new Error(
+          "Cloud mode cannot use both cloud.apiKey and cloud.accessToken. Set only one credential."
+        );
+      }
+      let credential = "";
+      let authScheme = cloudConfig?.authScheme ?? "api-key";
+      if (accessToken) {
+        credential = accessToken;
+        authScheme = "bearer";
+      } else if (apiKey) {
+        credential = apiKey;
+      }
+      if (!credential) {
         throw new Error(
-          "Cloud mode requires a non-empty API key via cloud.apiKey or OPENSTEER_API_KEY."
+          "Cloud mode requires credentials via cloud.apiKey/cloud.accessToken or OPENSTEER_API_KEY/OPENSTEER_ACCESS_TOKEN."
         );
       }
       this.cloud = createCloudRuntimeState(
-        apiKey,
+        credential,
         cloudConfig?.baseUrl,
-        cloudConfig?.authScheme
+        authScheme
       );
     } else {
       this.cloud = null;
@@ -10603,6 +11468,19 @@ var Opensteer = class _Opensteer {
     }
     return true;
   }
+  buildCloudSessionLaunchConfig(options) {
+    const cloudConfig = this.config.cloud && typeof this.config.cloud === "object" ? this.config.cloud : void 0;
+    const browserProfile = normalizeCloudBrowserProfilePreference(
+      options.cloudBrowserProfile ?? cloudConfig?.browserProfile,
+      options.cloudBrowserProfile ? "launch options" : "Opensteer config"
+    );
+    if (!browserProfile) {
+      return void 0;
+    }
+    return {
+      browserProfile
+    };
+  }
   async launch(options = {}) {
     if (this.pageRef && !this.ownsBrowser) {
       throw new Error(
@@ -10625,6 +11503,7 @@ var Opensteer = class _Opensteer {
         }
         localRunId = this.cloud.localRunId || buildLocalRunId(this.namespace);
         this.cloud.localRunId = localRunId;
+        const launchConfig = this.buildCloudSessionLaunchConfig(options);
         const session3 = await this.cloud.sessionClient.create({
           cloudSessionContractVersion,
           sourceType: "local-cloud",
@@ -10632,7 +11511,8 @@ var Opensteer = class _Opensteer {
           localRunId,
           name: this.namespace,
           model: this.config.model,
-          launchContext: options.context || void 0
+          launchContext: options.context || void 0,
+          launchConfig
         });
         sessionId = session3.sessionId;
         actionClient = await ActionWsClient.connect({
@@ -10650,6 +11530,9 @@ var Opensteer = class _Opensteer {
         this.pageRef = cdpConnection.page;
         this.ownsBrowser = true;
         this.snapshotCache = null;
+        if (this.cursorController) {
+          await this.cursorController.attachPage(this.pageRef);
+        }
         this.cloud.actionClient = actionClient;
         this.cloud.sessionId = sessionId;
         this.cloud.cloudSessionUrl = session3.cloudSessionUrl;
@@ -10690,6 +11573,9 @@ var Opensteer = class _Opensteer {
     this.pageRef = session2.page;
     this.ownsBrowser = true;
     this.snapshotCache = null;
+    if (this.cursorController) {
+      await this.cursorController.attachPage(this.pageRef);
+    }
   }
   static from(page, config = {}) {
     const resolvedRuntime = resolveConfigWithEnv(config);
@@ -10734,6 +11620,9 @@ var Opensteer = class _Opensteer {
       if (sessionId) {
         await this.cloud.sessionClient.close(sessionId).catch(() => void 0);
       }
+      if (this.cursorController) {
+        await this.cursorController.dispose().catch(() => void 0);
+      }
       return;
     }
     if (this.ownsBrowser) {
@@ -10743,6 +11632,9 @@ var Opensteer = class _Opensteer {
     this.pageRef = null;
     this.contextRef = null;
     this.ownsBrowser = false;
+    if (this.cursorController) {
+      await this.cursorController.dispose().catch(() => void 0);
+    }
   }
   async syncLocalSelectorCacheToCloud() {
     if (!this.cloud) return;
@@ -10869,12 +11761,22 @@ var Opensteer = class _Opensteer {
             resolution.counter
           );
         }
-        await this.runWithPostActionWait("hover", options.wait, async () => {
-          await handle.hover({
-            force: options.force,
-            position: options.position
-          });
-        });
+        await this.runWithCursorPreview(
+          () => this.resolveHandleTargetPoint(handle, options.position),
+          "hover",
+          async () => {
+            await this.runWithPostActionWait(
+              "hover",
+              options.wait,
+              async () => {
+                await handle.hover({
+                  force: options.force,
+                  position: options.position
+                });
+              }
+            );
+          }
+        );
       } catch (err) {
         const failure = classifyActionFailure({
           action: "hover",
@@ -10909,25 +11811,31 @@ var Opensteer = class _Opensteer {
       throw new Error("Unable to resolve element path for hover action.");
     }
     const path5 = resolution.path;
-    const result = await this.runWithPostActionWait(
+    const result = await this.runWithCursorPreview(
+      () => this.resolvePathTargetPoint(path5, options.position),
       "hover",
-      options.wait,
       async () => {
-        const actionResult = await performHover(this.page, path5, options);
-        if (!actionResult.ok) {
-          const failure = actionResult.failure || classifyActionFailure({
-            action: "hover",
-            error: actionResult.error || defaultActionFailureMessage("hover"),
-            fallbackMessage: defaultActionFailureMessage("hover")
-          });
-          throw this.buildActionError(
-            "hover",
-            options.description,
-            failure,
-            actionResult.usedSelector || null
-          );
-        }
-        return actionResult;
+        return await this.runWithPostActionWait(
+          "hover",
+          options.wait,
+          async () => {
+            const actionResult = await performHover(this.page, path5, options);
+            if (!actionResult.ok) {
+              const failure = actionResult.failure || classifyActionFailure({
+                action: "hover",
+                error: actionResult.error || defaultActionFailureMessage("hover"),
+                fallbackMessage: defaultActionFailureMessage("hover")
+              });
+              throw this.buildActionError(
+                "hover",
+                options.description,
+                failure,
+                actionResult.usedSelector || null
+              );
+            }
+            return actionResult;
+          }
+        );
       }
     );
     this.snapshotCache = null;
@@ -10968,16 +11876,26 @@ var Opensteer = class _Opensteer {
             resolution.counter
           );
         }
-        await this.runWithPostActionWait("input", options.wait, async () => {
-          if (options.clear !== false) {
-            await handle.fill(options.text);
-          } else {
-            await handle.type(options.text);
-          }
-          if (options.pressEnter) {
-            await handle.press("Enter", { noWaitAfter: true });
+        await this.runWithCursorPreview(
+          () => this.resolveHandleTargetPoint(handle),
+          "input",
+          async () => {
+            await this.runWithPostActionWait(
+              "input",
+              options.wait,
+              async () => {
+                if (options.clear !== false) {
+                  await handle.fill(options.text);
+                } else {
+                  await handle.type(options.text);
+                }
+                if (options.pressEnter) {
+                  await handle.press("Enter", { noWaitAfter: true });
+                }
+              }
+            );
           }
-        });
+        );
       } catch (err) {
         const failure = classifyActionFailure({
           action: "input",
@@ -11012,25 +11930,31 @@ var Opensteer = class _Opensteer {
       throw new Error("Unable to resolve element path for input action.");
     }
     const path5 = resolution.path;
-    const result = await this.runWithPostActionWait(
+    const result = await this.runWithCursorPreview(
+      () => this.resolvePathTargetPoint(path5),
       "input",
-      options.wait,
       async () => {
-        const actionResult = await performInput(this.page, path5, options);
-        if (!actionResult.ok) {
-          const failure = actionResult.failure || classifyActionFailure({
-            action: "input",
-            error: actionResult.error || defaultActionFailureMessage("input"),
-            fallbackMessage: defaultActionFailureMessage("input")
-          });
-          throw this.buildActionError(
-            "input",
-            options.description,
-            failure,
-            actionResult.usedSelector || null
-          );
-        }
-        return actionResult;
+        return await this.runWithPostActionWait(
+          "input",
+          options.wait,
+          async () => {
+            const actionResult = await performInput(this.page, path5, options);
+            if (!actionResult.ok) {
+              const failure = actionResult.failure || classifyActionFailure({
+                action: "input",
+                error: actionResult.error || defaultActionFailureMessage("input"),
+                fallbackMessage: defaultActionFailureMessage("input")
+              });
+              throw this.buildActionError(
+                "input",
+                options.description,
+                failure,
+                actionResult.usedSelector || null
+              );
+            }
+            return actionResult;
+          }
+        );
       }
     );
     this.snapshotCache = null;
@@ -11071,21 +11995,27 @@ var Opensteer = class _Opensteer {
             resolution.counter
           );
         }
-        await this.runWithPostActionWait(
+        await this.runWithCursorPreview(
+          () => this.resolveHandleTargetPoint(handle),
           "select",
-          options.wait,
           async () => {
-            if (options.value != null) {
-              await handle.selectOption(options.value);
-            } else if (options.label != null) {
-              await handle.selectOption({ label: options.label });
-            } else if (options.index != null) {
-              await handle.selectOption({ index: options.index });
-            } else {
-              throw new Error(
-                "Select requires value, label, or index."
-              );
-            }
+            await this.runWithPostActionWait(
+              "select",
+              options.wait,
+              async () => {
+                if (options.value != null) {
+                  await handle.selectOption(options.value);
+                } else if (options.label != null) {
+                  await handle.selectOption({ label: options.label });
+                } else if (options.index != null) {
+                  await handle.selectOption({ index: options.index });
+                } else {
+                  throw new Error(
+                    "Select requires value, label, or index."
+                  );
+                }
+              }
+            );
           }
         );
       } catch (err) {
@@ -11122,25 +12052,31 @@ var Opensteer = class _Opensteer {
       throw new Error("Unable to resolve element path for select action.");
     }
     const path5 = resolution.path;
-    const result = await this.runWithPostActionWait(
+    const result = await this.runWithCursorPreview(
+      () => this.resolvePathTargetPoint(path5),
       "select",
-      options.wait,
       async () => {
-        const actionResult = await performSelect(this.page, path5, options);
-        if (!actionResult.ok) {
-          const failure = actionResult.failure || classifyActionFailure({
-            action: "select",
-            error: actionResult.error || defaultActionFailureMessage("select"),
-            fallbackMessage: defaultActionFailureMessage("select")
-          });
-          throw this.buildActionError(
-            "select",
-            options.description,
-            failure,
-            actionResult.usedSelector || null
-          );
-        }
-        return actionResult;
+        return await this.runWithPostActionWait(
+          "select",
+          options.wait,
+          async () => {
+            const actionResult = await performSelect(this.page, path5, options);
+            if (!actionResult.ok) {
+              const failure = actionResult.failure || classifyActionFailure({
+                action: "select",
+                error: actionResult.error || defaultActionFailureMessage("select"),
+                fallbackMessage: defaultActionFailureMessage("select")
+              });
+              throw this.buildActionError(
+                "select",
+                options.description,
+                failure,
+                actionResult.usedSelector || null
+              );
+            }
+            return actionResult;
+          }
+        );
       }
     );
     this.snapshotCache = null;
@@ -11182,13 +12118,23 @@ var Opensteer = class _Opensteer {
           );
         }
         const delta = getScrollDelta2(options);
-        await this.runWithPostActionWait("scroll", options.wait, async () => {
-          await handle.evaluate((el, value) => {
-            if (el instanceof HTMLElement) {
-              el.scrollBy(value.x, value.y);
-            }
-          }, delta);
-        });
+        await this.runWithCursorPreview(
+          () => this.resolveHandleTargetPoint(handle),
+          "scroll",
+          async () => {
+            await this.runWithPostActionWait(
+              "scroll",
+              options.wait,
+              async () => {
+                await handle.evaluate((el, value) => {
+                  if (el instanceof HTMLElement) {
+                    el.scrollBy(value.x, value.y);
+                  }
+                }, delta);
+              }
+            );
+          }
+        );
       } catch (err) {
         const failure = classifyActionFailure({
           action: "scroll",
@@ -11219,29 +12165,35 @@ var Opensteer = class _Opensteer {
         `[c="${resolution.counter}"]`
       );
     }
-    const result = await this.runWithPostActionWait(
+    const result = await this.runWithCursorPreview(
+      () => resolution.path ? this.resolvePathTargetPoint(resolution.path) : this.resolveViewportAnchorPoint(),
       "scroll",
-      options.wait,
       async () => {
-        const actionResult = await performScroll(
-          this.page,
-          resolution.path,
-          options
+        return await this.runWithPostActionWait(
+          "scroll",
+          options.wait,
+          async () => {
+            const actionResult = await performScroll(
+              this.page,
+              resolution.path,
+              options
+            );
+            if (!actionResult.ok) {
+              const failure = actionResult.failure || classifyActionFailure({
+                action: "scroll",
+                error: actionResult.error || defaultActionFailureMessage("scroll"),
+                fallbackMessage: defaultActionFailureMessage("scroll")
+              });
+              throw this.buildActionError(
+                "scroll",
+                options.description,
+                failure,
+                actionResult.usedSelector || null
+              );
+            }
+            return actionResult;
+          }
         );
-        if (!actionResult.ok) {
-          const failure = actionResult.failure || classifyActionFailure({
-            action: "scroll",
-            error: actionResult.error || defaultActionFailureMessage("scroll"),
-            fallbackMessage: defaultActionFailureMessage("scroll")
-          });
-          throw this.buildActionError(
-            "scroll",
-            options.description,
-            failure,
-            actionResult.usedSelector || null
-          );
-        }
-        return actionResult;
       }
     );
     this.snapshotCache = null;
@@ -11527,11 +12479,17 @@ var Opensteer = class _Opensteer {
             resolution.counter
           );
         }
-        await this.runWithPostActionWait(
+        await this.runWithCursorPreview(
+          () => this.resolveHandleTargetPoint(handle),
           "uploadFile",
-          options.wait,
           async () => {
-            await handle.setInputFiles(options.paths);
+            await this.runWithPostActionWait(
+              "uploadFile",
+              options.wait,
+              async () => {
+                await handle.setInputFiles(options.paths);
+              }
+            );
           }
         );
       } catch (err) {
@@ -11568,29 +12526,35 @@ var Opensteer = class _Opensteer {
       throw new Error("Unable to resolve element path for file upload.");
     }
     const path5 = resolution.path;
-    const result = await this.runWithPostActionWait(
+    const result = await this.runWithCursorPreview(
+      () => this.resolvePathTargetPoint(path5),
       "uploadFile",
-      options.wait,
       async () => {
-        const actionResult = await performFileUpload(
-          this.page,
-          path5,
-          options.paths
+        return await this.runWithPostActionWait(
+          "uploadFile",
+          options.wait,
+          async () => {
+            const actionResult = await performFileUpload(
+              this.page,
+              path5,
+              options.paths
+            );
+            if (!actionResult.ok) {
+              const failure = actionResult.failure || classifyActionFailure({
+                action: "uploadFile",
+                error: actionResult.error || defaultActionFailureMessage("uploadFile"),
+                fallbackMessage: defaultActionFailureMessage("uploadFile")
+              });
+              throw this.buildActionError(
+                "uploadFile",
+                options.description,
+                failure,
+                actionResult.usedSelector || null
+              );
+            }
+            return actionResult;
+          }
         );
-        if (!actionResult.ok) {
-          const failure = actionResult.failure || classifyActionFailure({
-            action: "uploadFile",
-            error: actionResult.error || defaultActionFailureMessage("uploadFile"),
-            fallbackMessage: defaultActionFailureMessage("uploadFile")
-          });
-          throw this.buildActionError(
-            "uploadFile",
-            options.description,
-            failure,
-            actionResult.usedSelector || null
-          );
-        }
-        return actionResult;
       }
     );
     this.snapshotCache = null;
@@ -11726,6 +12690,25 @@ var Opensteer = class _Opensteer {
   getConfig() {
     return this.config;
   }
+  setCursorEnabled(enabled) {
+    this.getCursorController().setEnabled(enabled);
+  }
+  getCursorState() {
+    const controller = this.cursorController;
+    if (!controller) {
+      return {
+        enabled: this.config.cursor?.enabled === true,
+        active: false,
+        reason: this.config.cursor?.enabled === true ? "not_initialized" : "disabled"
+      };
+    }
+    const status = controller.getStatus();
+    return {
+      enabled: status.enabled,
+      active: status.active,
+      reason: status.reason
+    };
+  }
   getStorage() {
     return this.storage;
   }
@@ -11753,24 +12736,107 @@ var Opensteer = class _Opensteer {
         this.agentExecutionInFlight = true;
         try {
           const options = normalizeExecuteOptions(instructionOrOptions);
+          const cursorController = this.getCursorController();
+          const previousCursorEnabled = cursorController.isEnabled();
+          if (options.highlightCursor !== void 0) {
+            cursorController.setEnabled(options.highlightCursor);
+          }
           const handler = new OpensteerCuaAgentHandler({
             page: this.page,
             config: resolvedAgentConfig,
             client: createCuaClient(resolvedAgentConfig),
-            debug: Boolean(this.config.debug),
+            cursorController,
             onMutatingAction: () => {
               this.snapshotCache = null;
             }
           });
-          const result = await handler.execute(options);
-          this.snapshotCache = null;
-          return result;
+          try {
+            const result = await handler.execute(options);
+            this.snapshotCache = null;
+            return result;
+          } finally {
+            if (options.highlightCursor !== void 0) {
+              cursorController.setEnabled(previousCursorEnabled);
+            }
+          }
         } finally {
           this.agentExecutionInFlight = false;
         }
       }
     };
   }
+  getCursorController() {
+    if (!this.cursorController) {
+      this.cursorController = new CursorController({
+        config: this.config.cursor,
+        debug: Boolean(this.config.debug)
+      });
+      if (this.pageRef) {
+        void this.cursorController.attachPage(this.pageRef);
+      }
+    }
+    return this.cursorController;
+  }
+  async runWithCursorPreview(pointResolver, intent, execute) {
+    if (this.isCursorPreviewEnabled()) {
+      const point = await pointResolver();
+      await this.previewCursorPoint(point, intent);
+    }
+    return await execute();
+  }
+  isCursorPreviewEnabled() {
+    return this.cursorController ? this.cursorController.isEnabled() : this.config.cursor?.enabled === true;
+  }
+  async previewCursorPoint(point, intent) {
+    const cursor = this.getCursorController();
+    await cursor.attachPage(this.page);
+    await cursor.preview(point, intent);
+  }
+  resolveCursorPointFromBoundingBox(box, position) {
+    if (position) {
+      return {
+        x: box.x + position.x,
+        y: box.y + position.y
+      };
+    }
+    return {
+      x: box.x + box.width / 2,
+      y: box.y + box.height / 2
+    };
+  }
+  async resolveHandleTargetPoint(handle, position) {
+    try {
+      const box = await handle.boundingBox();
+      if (!box) return null;
+      return this.resolveCursorPointFromBoundingBox(box, position);
+    } catch {
+      return null;
+    }
+  }
+  async resolvePathTargetPoint(path5, position) {
+    if (!path5) {
+      return null;
+    }
+    let resolved = null;
+    try {
+      resolved = await resolveElementPath(this.page, path5);
+      return await this.resolveHandleTargetPoint(resolved.element, position);
+    } catch {
+      return null;
+    } finally {
+      await resolved?.element.dispose().catch(() => void 0);
+    }
+  }
+  async resolveViewportAnchorPoint() {
+    const viewport = this.page.viewportSize();
+    if (viewport?.width && viewport?.height) {
+      return {
+        x: viewport.width / 2,
+        y: viewport.height / 2
+      };
+    }
+    return null;
+  }
   async runWithPostActionWait(action, waitOverride, execute) {
     const waitSession = createPostActionWaitSession(
       this.page,
@@ -11803,13 +12869,19 @@ var Opensteer = class _Opensteer {
             resolution.counter
           );
         }
-        await this.runWithPostActionWait(method, options.wait, async () => {
-          await handle.click({
-            button: options.button,
-            clickCount: options.clickCount,
-            modifiers: options.modifiers
-          });
-        });
+        await this.runWithCursorPreview(
+          () => this.resolveHandleTargetPoint(handle),
+          method,
+          async () => {
+            await this.runWithPostActionWait(method, options.wait, async () => {
+              await handle.click({
+                button: options.button,
+                clickCount: options.clickCount,
+                modifiers: options.modifiers
+              });
+            });
+          }
+        );
       } catch (err) {
         const failure = classifyActionFailure({
           action: method,
@@ -11844,25 +12916,31 @@ var Opensteer = class _Opensteer {
       throw new Error("Unable to resolve element path for click action.");
     }
     const path5 = resolution.path;
-    const result = await this.runWithPostActionWait(
+    const result = await this.runWithCursorPreview(
+      () => this.resolvePathTargetPoint(path5),
       method,
-      options.wait,
       async () => {
-        const actionResult = await performClick(this.page, path5, options);
-        if (!actionResult.ok) {
-          const failure = actionResult.failure || classifyActionFailure({
-            action: method,
-            error: actionResult.error || defaultActionFailureMessage(method),
-            fallbackMessage: defaultActionFailureMessage(method)
-          });
-          throw this.buildActionError(
-            method,
-            options.description,
-            failure,
-            actionResult.usedSelector || null
-          );
-        }
-        return actionResult;
+        return await this.runWithPostActionWait(
+          method,
+          options.wait,
+          async () => {
+            const actionResult = await performClick(this.page, path5, options);
+            if (!actionResult.ok) {
+              const failure = actionResult.failure || classifyActionFailure({
+                action: method,
+                error: actionResult.error || defaultActionFailureMessage(method),
+                fallbackMessage: defaultActionFailureMessage(method)
+              });
+              throw this.buildActionError(
+                method,
+                options.description,
+                failure,
+                actionResult.usedSelector || null
+              );
+            }
+            return actionResult;
+          }
+        );
       }
     );
     this.snapshotCache = null;
@@ -12857,6 +13935,26 @@ function isInternalOrBlankPageUrl(url) {
   if (url === "about:blank") return true;
   return url.startsWith("chrome://") || url.startsWith("devtools://") || url.startsWith("edge://");
 }
+function normalizeCloudBrowserProfilePreference(value, source) {
+  if (!value) {
+    return void 0;
+  }
+  const profileId = typeof value.profileId === "string" ? value.profileId.trim() : "";
+  if (!profileId) {
+    throw new Error(
+      `Invalid cloud browser profile in ${source}: profileId must be a non-empty string.`
+    );
+  }
+  if (value.reuseIfActive !== void 0 && typeof value.reuseIfActive !== "boolean") {
+    throw new Error(
+      `Invalid cloud browser profile in ${source}: reuseIfActive must be a boolean.`
+    );
+  }
+  return {
+    profileId,
+    reuseIfActive: value.reuseIfActive
+  };
+}
 function buildLocalRunId(namespace) {
   const normalized = namespace.trim() || "default";
   return `${normalized}-${Date.now().toString(36)}-${(0, import_crypto.randomUUID)().slice(0, 8)}`;
@@ -12879,7 +13977,7 @@ function getMetadataPath(session2) {
 }
 
 // src/cli/commands.ts
-var import_promises2 = require("fs/promises");
+var import_promises3 = require("fs/promises");
 var commands = {
   async navigate(opensteer, args) {
     const url = args.url;
@@ -12911,6 +14009,21 @@ var commands = {
   async state(opensteer) {
     return await opensteer.state();
   },
+  async cursor(opensteer, args) {
+    const mode = typeof args.mode === "string" ? args.mode : "status";
+    if (mode === "on") {
+      opensteer.setCursorEnabled(true);
+    } else if (mode === "off") {
+      opensteer.setCursorEnabled(false);
+    } else if (mode !== "status") {
+      throw new Error(
+        `Invalid cursor mode "${String(mode)}". Use "on", "off", or "status".`
+      );
+    }
+    return {
+      cursor: opensteer.getCursorState()
+    };
+  },
   async screenshot(opensteer, args) {
     const file = args.file || "screenshot.png";
     const type = file.endsWith(".jpg") || file.endsWith(".jpeg") ? "jpeg" : "png";
@@ -12918,7 +14031,7 @@ var commands = {
       fullPage: args.fullPage,
       type
     });
-    await (0, import_promises2.writeFile)(file, buffer);
+    await (0, import_promises3.writeFile)(file, buffer);
     return { file };
   },
   async click(opensteer, args) {
@@ -13110,10 +14223,175 @@ function getCommandHandler(name) {
   return commands[name];
 }
 
+// src/cli/cloud-profile-binding.ts
+function normalizeCloudProfileBinding(value) {
+  if (!value) {
+    return null;
+  }
+  const profileId = typeof value.profileId === "string" ? value.profileId.trim() : "";
+  if (!profileId) {
+    return null;
+  }
+  return {
+    profileId,
+    reuseIfActive: typeof value.reuseIfActive === "boolean" ? value.reuseIfActive : void 0
+  };
+}
+function resolveConfiguredCloudProfileBinding(config) {
+  if (!isCloudConfigured(config)) {
+    return null;
+  }
+  return normalizeCloudProfileBinding(config.cloud.browserProfile);
+}
+function resolveSessionCloudProfileBinding(config, requested) {
+  if (!isCloudConfigured(config)) {
+    return null;
+  }
+  return requested ?? resolveConfiguredCloudProfileBinding(config);
+}
+function assertCompatibleCloudProfileBinding(sessionId, active, requested) {
+  if (!requested) {
+    return;
+  }
+  if (!active) {
+    throw new Error(
+      [
+        `Session '${sessionId}' is already running without a bound cloud browser profile.`,
+        "Cloud browser profile selection only applies when the session is first opened.",
+        "Close this session or use a different --session to target another profile."
+      ].join(" ")
+    );
+  }
+  if (active.profileId === requested.profileId && active.reuseIfActive === requested.reuseIfActive) {
+    return;
+  }
+  throw new Error(
+    [
+      `Session '${sessionId}' is already bound to cloud browser profile ${formatCloudProfileBinding(active)}.`,
+      `Requested ${formatCloudProfileBinding(requested)} does not match.`,
+      "Use the same cloud profile for this session, or start a different --session."
+    ].join(" ")
+  );
+}
+function formatCloudProfileBinding(binding) {
+  if (binding.reuseIfActive === void 0) {
+    return `'${binding.profileId}'`;
+  }
+  return `'${binding.profileId}' (reuseIfActive=${String(
+    binding.reuseIfActive
+  )})`;
+}
+function isCloudConfigured(config) {
+  return Boolean(
+    config.cloud && typeof config.cloud === "object" && !Array.isArray(config.cloud)
+  );
+}
+
+// src/cli/open-cloud-auth.ts
+function normalizeCliOpenCloudAuth(value) {
+  if (value == null) {
+    return null;
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("Invalid open request cloud auth payload.");
+  }
+  const record = value;
+  const apiKey = normalizeNonEmptyString3(record.apiKey);
+  const accessToken = normalizeNonEmptyString3(record.accessToken);
+  const baseUrl = normalizeNonEmptyString3(record.baseUrl);
+  const authScheme = normalizeAuthScheme(record.authScheme);
+  if (!baseUrl) {
+    throw new Error("Open request cloud auth payload is missing baseUrl.");
+  }
+  if ((apiKey ? 1 : 0) + (accessToken ? 1 : 0) !== 1) {
+    throw new Error(
+      "Open request cloud auth payload must include exactly one credential."
+    );
+  }
+  if (accessToken && authScheme !== "bearer") {
+    throw new Error(
+      'Open request cloud auth payload must use authScheme "bearer" with accessToken.'
+    );
+  }
+  return {
+    ...apiKey ? { apiKey } : {},
+    ...accessToken ? { accessToken } : {},
+    baseUrl,
+    authScheme
+  };
+}
+function buildServerOpenConfig(options) {
+  const config = {
+    name: options.name,
+    storage: {
+      rootDir: options.scopeDir
+    },
+    cursor: {
+      enabled: options.cursorEnabled
+    },
+    browser: {
+      headless: options.headless ?? false,
+      connectUrl: options.connectUrl,
+      channel: options.channel,
+      profileDir: options.profileDir
+    }
+  };
+  if (!options.cloudAuth) {
+    return config;
+  }
+  const resolved = resolveConfigWithEnv(
+    {
+      storage: {
+        rootDir: options.scopeDir
+      }
+    },
+    {
+      env: options.env
+    }
+  );
+  const cloudSelection = resolveCloudSelection(
+    {
+      cloud: resolved.config.cloud
+    },
+    resolved.env
+  );
+  if (!cloudSelection.cloud) {
+    return config;
+  }
+  config.cloud = toOpensteerCloudOptions(options.cloudAuth);
+  return config;
+}
+function toOpensteerCloudOptions(auth) {
+  return {
+    ...auth.apiKey ? { apiKey: auth.apiKey } : {},
+    ...auth.accessToken ? { accessToken: auth.accessToken } : {},
+    baseUrl: auth.baseUrl,
+    authScheme: auth.authScheme
+  };
+}
+function normalizeNonEmptyString3(value) {
+  if (typeof value !== "string") {
+    return void 0;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : void 0;
+}
+function normalizeAuthScheme(value) {
+  if (value === "api-key" || value === "bearer") {
+    return value;
+  }
+  throw new Error(
+    'Open request cloud auth payload must use authScheme "api-key" or "bearer".'
+  );
+}
+
 // src/cli/server.ts
 var instance = null;
 var launchPromise = null;
 var selectorNamespace = null;
+var cloudProfileBinding = null;
+var cloudAuthOverride = null;
+var cursorEnabledPreference = readCursorPreferenceFromEnv();
 var requestQueue = Promise.resolve();
 var shuttingDown = false;
 function sanitizeNamespace(value) {
@@ -13131,6 +14409,36 @@ function invalidateInstance() {
   instance.close().catch(() => {
   });
   instance = null;
+  cloudProfileBinding = null;
+}
+function normalizeCursorFlag(value) {
+  if (value === void 0 || value === null) {
+    return null;
+  }
+  if (typeof value === "boolean") {
+    return value;
+  }
+  if (typeof value === "number") {
+    if (value === 1) return true;
+    if (value === 0) return false;
+  }
+  throw new Error(
+    '--cursor must be a boolean value ("true" or "false").'
+  );
+}
+function readCursorPreferenceFromEnv() {
+  const value = process.env.OPENSTEER_CURSOR;
+  if (typeof value !== "string") {
+    return null;
+  }
+  const normalized = value.trim().toLowerCase();
+  if (normalized === "true" || normalized === "1") {
+    return true;
+  }
+  if (normalized === "false" || normalized === "0") {
+    return false;
+  }
+  return null;
 }
 function attachLifecycleListeners(inst) {
   try {
@@ -13240,7 +14548,26 @@ async function handleRequest(request, socket) {
       const connectUrl = args["connect-url"];
       const channel = args.channel;
       const profileDir = args["profile-dir"];
+      const cloudProfileId = typeof args["cloud-profile-id"] === "string" ? args["cloud-profile-id"].trim() : void 0;
+      const cloudProfileReuseIfActive = typeof args["cloud-profile-reuse-if-active"] === "boolean" ? args["cloud-profile-reuse-if-active"] : void 0;
+      const requestedCloudProfileBinding = normalizeCloudProfileBinding({
+        profileId: cloudProfileId,
+        reuseIfActive: cloudProfileReuseIfActive
+      });
+      const requestedCloudAuth = normalizeCliOpenCloudAuth(
+        args["cloud-auth"]
+      );
+      if (cloudProfileReuseIfActive !== void 0 && !cloudProfileId) {
+        throw new Error(
+          "--cloud-profile-reuse-if-active requires --cloud-profile-id."
+        );
+      }
+      const requestedCursor = normalizeCursorFlag(args.cursor);
       const requestedName = typeof args.name === "string" && args.name.trim().length > 0 ? sanitizeNamespace(args.name) : null;
+      if (requestedCursor !== null) {
+        cursorEnabledPreference = requestedCursor;
+      }
+      const effectiveCursorEnabled = cursorEnabledPreference !== null ? cursorEnabledPreference : true;
       if (selectorNamespace && requestedName && requestedName !== selectorNamespace) {
         sendResponse(socket, {
           id,
@@ -13264,6 +14591,9 @@ async function handleRequest(request, socket) {
         selectorNamespace = requestedName ?? logicalSession;
       }
       const activeNamespace = selectorNamespace ?? logicalSession;
+      if (requestedCloudAuth) {
+        cloudAuthOverride = requestedCloudAuth;
+      }
       if (instance && !launchPromise) {
         try {
           if (instance.page.isClosed()) {
@@ -13273,31 +14603,59 @@ async function handleRequest(request, socket) {
           invalidateInstance();
         }
       }
+      if (instance && !launchPromise) {
+        assertCompatibleCloudProfileBinding(
+          logicalSession,
+          cloudProfileBinding,
+          requestedCloudProfileBinding
+        );
+      }
       if (!instance) {
-        instance = new Opensteer({
-          name: activeNamespace,
-          browser: {
-            headless: headless ?? false,
+        instance = new Opensteer(
+          buildServerOpenConfig({
+            scopeDir,
+            name: activeNamespace,
+            cursorEnabled: effectiveCursorEnabled,
+            headless,
             connectUrl,
             channel,
-            profileDir
-          }
-        });
+            profileDir,
+            cloudAuth: cloudAuthOverride
+          })
+        );
+        const nextCloudProfileBinding = resolveSessionCloudProfileBinding(
+          instance.getConfig(),
+          requestedCloudProfileBinding
+        );
+        if (requestedCloudProfileBinding && !nextCloudProfileBinding) {
+          instance = null;
+          throw new Error(
+            "--cloud-profile-id can only be used when cloud mode is enabled for this session."
+          );
+        }
         launchPromise = instance.launch({
           headless: headless ?? false,
+          cloudBrowserProfile: cloudProfileId ? {
+            profileId: cloudProfileId,
+            reuseIfActive: cloudProfileReuseIfActive
+          } : void 0,
           timeout: connectUrl ? 12e4 : 3e4
         });
         try {
           await launchPromise;
           attachLifecycleListeners(instance);
+          cloudProfileBinding = nextCloudProfileBinding;
         } catch (err) {
           instance = null;
+          cloudProfileBinding = null;
           throw err;
         } finally {
           launchPromise = null;
         }
       } else if (launchPromise) {
         await launchPromise;
+      } else if (requestedCursor !== null) {
+        instance.setCursorEnabled(requestedCursor);
       }
       if (url) {
         await instance.goto(url);
@@ -13312,6 +14670,7 @@ async function handleRequest(request, socket) {
           runtimeSession: session,
           scopeDir,
           name: activeNamespace,
+          cursor: instance.getCursorState(),
           cloudSessionId: instance.getCloudSessionId() ?? void 0,
           cloudSessionUrl: instance.getCloudSessionUrl() ?? void 0
         }
@@ -13324,6 +14683,41 @@ async function handleRequest(request, socket) {
     }
     return;
   }
+  if (command === "cursor") {
+    try {
+      const mode = typeof args.mode === "string" ? args.mode : "status";
+      if (mode === "on") {
+        cursorEnabledPreference = true;
+        instance?.setCursorEnabled(true);
+      } else if (mode === "off") {
+        cursorEnabledPreference = false;
+        instance?.setCursorEnabled(false);
+      } else if (mode !== "status") {
+        throw new Error(
+          `Invalid cursor mode "${mode}". Use "on", "off", or "status".`
+        );
+      }
+      const defaultEnabled = cursorEnabledPreference !== null ? cursorEnabledPreference : true;
+      const cursor = instance ? instance.getCursorState() : {
+        enabled: defaultEnabled,
+        active: false,
+        reason: "session_not_open"
+      };
+      sendResponse(socket, {
+        id,
+        ok: true,
+        result: {
+          cursor
+        }
+      });
+    } catch (err) {
+      sendResponse(
+        socket,
+        buildErrorResponse(id, err, "Failed to update cursor mode.")
+      );
+    }
+    return;
+  }
   if (command === "close") {
     try {
       if (instance) {