@midscene/web 0.19.1 → 0.20.0

package/dist/es/midscene-playground.js

@@ -8,7 +8,7 @@ import {
   traverseTree
 } from "@midscene/shared/extractor";
 import { resizeImgBase64 } from "@midscene/shared/img";
-import { assert, logMsg, uuid } from "@midscene/shared/utils";
+import { assert as assert2, logMsg, uuid } from "@midscene/shared/utils";
 import dayjs from "dayjs";
 
 // src/web-element.ts
@@ -36,9 +36,184 @@ var WebElementInfo = class {
   }
 };
 
+// src/common/task-cache.ts
+import assert from "assert";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { dirname, join } from "path";
+import { getMidsceneRunSubDir } from "@midscene/shared/common";
+import { getDebug } from "@midscene/shared/logger";
+import { ifInBrowser } from "@midscene/shared/utils";
+import yaml from "js-yaml";
+import semver from "semver";
+
+// package.json
+var version = "0.20.0";
+
+// src/common/task-cache.ts
+var debug = getDebug("cache");
+var lowestSupportedMidsceneVersion = "0.16.10";
+var cacheFileExt = ".cache.yaml";
+var TaskCache = class {
+  // Track matched records
+  constructor(cacheId, isCacheResultUsed, cacheFilePath) {
+    this.matchedCacheIndices = /* @__PURE__ */ new Set();
+    assert(cacheId, "cacheId is required");
+    this.cacheId = replaceIllegalPathCharsAndSpace(cacheId);
+    this.cacheFilePath = ifInBrowser ? void 0 : cacheFilePath || join(getMidsceneRunSubDir("cache"), `${this.cacheId}${cacheFileExt}`);
+    this.isCacheResultUsed = isCacheResultUsed;
+    let cacheContent;
+    if (this.cacheFilePath) {
+      cacheContent = this.loadCacheFromFile();
+    }
+    if (!cacheContent) {
+      cacheContent = {
+        midsceneVersion: version,
+        cacheId: this.cacheId,
+        caches: []
+      };
+    }
+    this.cache = cacheContent;
+    this.cacheOriginalLength = this.cache.caches.length;
+  }
+  matchCache(prompt, type) {
+    for (let i = 0; i < this.cacheOriginalLength; i++) {
+      const item = this.cache.caches[i];
+      const key = `${type}:${prompt}:${i}`;
+      if (item.type === type && item.prompt === prompt && !this.matchedCacheIndices.has(key)) {
+        this.matchedCacheIndices.add(key);
+        debug(
+          "cache found and marked as used, type: %s, prompt: %s, index: %d",
+          type,
+          prompt,
+          i
+        );
+        return {
+          cacheContent: item,
+          updateFn: (cb) => {
+            debug(
+              "will call updateFn to update cache, type: %s, prompt: %s, index: %d",
+              type,
+              prompt,
+              i
+            );
+            cb(item);
+            debug(
+              "cache updated, will flush to file, type: %s, prompt: %s, index: %d",
+              type,
+              prompt,
+              i
+            );
+            this.flushCacheToFile();
+          }
+        };
+      }
+    }
+    debug("no unused cache found, type: %s, prompt: %s", type, prompt);
+    return void 0;
+  }
+  matchPlanCache(prompt) {
+    return this.matchCache(prompt, "plan");
+  }
+  matchLocateCache(prompt) {
+    return this.matchCache(prompt, "locate");
+  }
+  appendCache(cache) {
+    debug("will append cache", cache);
+    this.cache.caches.push(cache);
+    this.flushCacheToFile();
+  }
+  loadCacheFromFile() {
+    const cacheFile = this.cacheFilePath;
+    assert(cacheFile, "cache file path is required");
+    if (!existsSync(cacheFile)) {
+      debug("no cache file found, path: %s", cacheFile);
+      return void 0;
+    }
+    const jsonTypeCacheFile = cacheFile.replace(cacheFileExt, ".json");
+    if (existsSync(jsonTypeCacheFile) && this.isCacheResultUsed) {
+      console.warn(
+        `An outdated cache file from an earlier version of Midscene has been detected. Since version 0.17, we have implemented an improved caching strategy. Please delete the old file located at: ${jsonTypeCacheFile}.`
+      );
+      return void 0;
+    }
+    try {
+      const data = readFileSync(cacheFile, "utf8");
+      const jsonData = yaml.load(data);
+      if (!version) {
+        debug("no midscene version info, will not read cache from file");
+        return void 0;
+      }
+      if (semver.lt(jsonData.midsceneVersion, lowestSupportedMidsceneVersion) && !jsonData.midsceneVersion.includes("beta")) {
+        console.warn(
+          `You are using an old version of Midscene cache file, and we cannot match any info from it. Starting from Midscene v0.17, we changed our strategy to use xpath for cache info, providing better performance.
+Please delete the existing cache and rebuild it. Sorry for the inconvenience.
+cache file: ${cacheFile}`
+        );
+        return void 0;
+      }
+      debug(
+        "cache loaded from file, path: %s, cache version: %s, record length: %s",
+        cacheFile,
+        jsonData.midsceneVersion,
+        jsonData.caches.length
+      );
+      jsonData.midsceneVersion = version;
+      return jsonData;
+    } catch (err) {
+      debug(
+        "cache file exists but load failed, path: %s, error: %s",
+        cacheFile,
+        err
+      );
+      return void 0;
+    }
+  }
+  flushCacheToFile() {
+    if (!version) {
+      debug("no midscene version info, will not write cache to file");
+      return;
+    }
+    if (!this.cacheFilePath) {
+      debug("no cache file path, will not write cache to file");
+      return;
+    }
+    try {
+      const dir = dirname(this.cacheFilePath);
+      if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+        debug("created cache directory: %s", dir);
+      }
+      const yamlData = yaml.dump(this.cache);
+      writeFileSync(this.cacheFilePath, yamlData);
+      debug("cache flushed to file: %s", this.cacheFilePath);
+    } catch (err) {
+      debug(
+        "write cache to file failed, path: %s, error: %s",
+        this.cacheFilePath,
+        err
+      );
+    }
+  }
+  updateOrAppendCacheRecord(newRecord, cachedRecord) {
+    if (cachedRecord) {
+      if (newRecord.type === "plan") {
+        cachedRecord.updateFn((cache) => {
+          cache.yamlWorkflow = newRecord.yamlWorkflow;
+        });
+      } else {
+        cachedRecord.updateFn((cache) => {
+          cache.xpaths = newRecord.xpaths;
+        });
+      }
+    } else {
+      this.appendCache(newRecord);
+    }
+  }
+};
+
 // src/common/utils.ts
 async function parseContextFromWebPage(page, _opt) {
-  assert(page, "page is required");
+  assert2(page, "page is required");
   if (page._forceUsePageContext) {
     return await page._forceUsePageContext();
   }
@@ -65,7 +240,7 @@ async function parseContextFromWebPage(page, _opt) {
       isVisible
     });
   });
-  assert(screenshotBase64, "screenshotBase64 is required");
+  assert2(screenshotBase64, "screenshotBase64 is required");
   const size = await page.size();
   if (size.dpr && size.dpr > 1) {
     screenshotBase64 = await resizeImgBase64(screenshotBase64, {
@@ -113,6 +288,28 @@ function matchElementFromPlan(planLocateParam, tree) {
   }
   return void 0;
 }
+async function matchElementFromCache(taskExecutor, xpaths, cachePrompt, cacheable) {
+  try {
+    if (xpaths?.length && taskExecutor.taskCache?.isCacheResultUsed && cacheable !== false) {
+      for (let i = 0; i < xpaths.length; i++) {
+        const element = await taskExecutor.page.getElementInfoByXpath(
+          xpaths[i]
+        );
+        if (element?.id) {
+          debug("cache hit, prompt: %s", cachePrompt);
+          debug(
+            "found a new new element with same xpath, xpath: %s, id: %s",
+            xpaths[i],
+            element?.id
+          );
+          return element;
+        }
+      }
+    }
+  } catch (error) {
+    debug("get element info by xpath error: ", error);
+  }
+}
 function trimContextByViewport(execution) {
   function filterVisibleTree(node) {
     if (!node)
@@ -157,10 +354,10 @@ import {
 import yaml4 from "js-yaml";
 
 // src/yaml/player.ts
-import { existsSync, mkdirSync, writeFileSync } from "fs";
-import { dirname, join, resolve } from "path";
-import { assert as assert2, ifInBrowser } from "@midscene/shared/utils";
-import { getMidsceneRunSubDir } from "@midscene/shared/common";
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, writeFileSync as writeFileSync2 } from "fs";
+import { dirname as dirname2, join as join2, resolve } from "path";
+import { assert as assert3, ifInBrowser as ifInBrowser2 } from "@midscene/shared/utils";
+import { getMidsceneRunSubDir as getMidsceneRunSubDir2 } from "@midscene/shared/common";
 var ScriptPlayer = class {
   constructor(script, setupAgent, onTaskStatusChange) {
     this.script = script;
@@ -172,14 +369,14 @@ var ScriptPlayer = class {
     this.pageAgent = null;
     this.result = {};
     this.target = script.target || script.web || script.android;
-    if (ifInBrowser) {
+    if (ifInBrowser2) {
       this.output = void 0;
     } else if (this.target?.output) {
       this.output = resolve(process.cwd(), this.target.output);
     } else {
-      this.output = join(getMidsceneRunSubDir("output"), `${process.pid}.json`);
+      this.output = join2(getMidsceneRunSubDir2("output"), `${process.pid}.json`);
     }
-    if (ifInBrowser) {
+    if (ifInBrowser2) {
       this.unstableLogContent = void 0;
     } else if (typeof this.target?.unstableLogContent === "string") {
       this.unstableLogContent = resolve(
@@ -187,8 +384,8 @@ var ScriptPlayer = class {
         this.target.unstableLogContent
       );
     } else if (this.target?.unstableLogContent === true) {
-      this.unstableLogContent = join(
-        getMidsceneRunSubDir("output"),
+      this.unstableLogContent = join2(
+        getMidsceneRunSubDir2("output"),
         "unstableLogContent.json"
       );
     }
@@ -234,27 +431,27 @@ var ScriptPlayer = class {
   flushResult() {
     if (Object.keys(this.result).length && this.output) {
       const output = resolve(process.cwd(), this.output);
-      const outputDir = dirname(output);
-      if (!existsSync(outputDir)) {
-        mkdirSync(outputDir, { recursive: true });
+      const outputDir = dirname2(output);
+      if (!existsSync2(outputDir)) {
+        mkdirSync2(outputDir, { recursive: true });
       }
-      writeFileSync(output, JSON.stringify(this.result, void 0, 2));
+      writeFileSync2(output, JSON.stringify(this.result, void 0, 2));
     }
   }
   flushUnstableLogContent() {
     if (this.unstableLogContent) {
       const content = this.pageAgent?._unstableLogContent();
       const filePath = resolve(process.cwd(), this.unstableLogContent);
-      const outputDir = dirname(filePath);
-      if (!existsSync(outputDir)) {
-        mkdirSync(outputDir, { recursive: true });
+      const outputDir = dirname2(filePath);
+      if (!existsSync2(outputDir)) {
+        mkdirSync2(outputDir, { recursive: true });
       }
-      writeFileSync(filePath, JSON.stringify(content, null, 2));
+      writeFileSync2(filePath, JSON.stringify(content, null, 2));
     }
   }
   async playTask(taskStatus, agent) {
     const { flow } = taskStatus;
-    assert2(flow, "missing flow in task");
+    assert3(flow, "missing flow in task");
     for (const flowItemIndex in flow) {
       const currentStep = Number.parseInt(flowItemIndex, 10);
       taskStatus.currentStep = currentStep;
@@ -262,8 +459,8 @@ var ScriptPlayer = class {
       if ("aiAction" in flowItem || "ai" in flowItem) {
         const actionTask = flowItem;
         const prompt = actionTask.aiAction || actionTask.ai;
-        assert2(prompt, "missing prompt for ai (aiAction)");
-        assert2(
+        assert3(prompt, "missing prompt for ai (aiAction)");
+        assert3(
           typeof prompt === "string",
           "prompt for aiAction must be a string"
         );
@@ -274,8 +471,8 @@ var ScriptPlayer = class {
         const assertTask = flowItem;
         const prompt = assertTask.aiAssert;
         const msg = assertTask.errorMessage;
-        assert2(prompt, "missing prompt for aiAssert");
-        assert2(
+        assert3(prompt, "missing prompt for aiAssert");
+        assert3(
           typeof prompt === "string",
           "prompt for aiAssert must be a string"
         );
@@ -287,8 +484,8 @@ var ScriptPlayer = class {
           domIncluded: queryTask.domIncluded,
           screenshotIncluded: queryTask.screenshotIncluded
         };
-        assert2(prompt, "missing prompt for aiQuery");
-        assert2(
+        assert3(prompt, "missing prompt for aiQuery");
+        assert3(
           typeof prompt === "string",
           "prompt for aiQuery must be a string"
         );
@@ -301,8 +498,8 @@ var ScriptPlayer = class {
           domIncluded: numberTask.domIncluded,
           screenshotIncluded: numberTask.screenshotIncluded
         };
-        assert2(prompt, "missing prompt for number");
-        assert2(
+        assert3(prompt, "missing prompt for aiNumber");
+        assert3(
           typeof prompt === "string",
           "prompt for number must be a string"
         );
@@ -315,8 +512,8 @@ var ScriptPlayer = class {
           domIncluded: stringTask.domIncluded,
           screenshotIncluded: stringTask.screenshotIncluded
         };
-        assert2(prompt, "missing prompt for string");
-        assert2(
+        assert3(prompt, "missing prompt for aiNumber");
+        assert3(
           typeof prompt === "string",
           "prompt for string must be a string"
         );
@@ -329,28 +526,35 @@ var ScriptPlayer = class {
           domIncluded: booleanTask.domIncluded,
           screenshotIncluded: booleanTask.screenshotIncluded
         };
-        assert2(prompt, "missing prompt for boolean");
-        assert2(
+        assert3(prompt, "missing prompt for aiBoolean");
+        assert3(
           typeof prompt === "string",
           "prompt for boolean must be a string"
         );
         const booleanResult = await agent.aiBoolean(prompt, options);
         this.setResult(booleanTask.name, booleanResult);
+      } else if ("aiAsk" in flowItem) {
+        const askTask = flowItem;
+        const prompt = askTask.aiAsk;
+        assert3(prompt, "missing prompt for aiAsk");
+        assert3(typeof prompt === "string", "prompt for aiAsk must be a string");
+        const askResult = await agent.aiAsk(prompt);
+        this.setResult(askTask.name, askResult);
       } else if ("aiLocate" in flowItem) {
         const locateTask = flowItem;
         const prompt = locateTask.aiLocate;
-        assert2(prompt, "missing prompt for aiLocate");
-        assert2(
+        assert3(prompt, "missing prompt for aiLocate");
+        assert3(
           typeof prompt === "string",
           "prompt for aiLocate must be a string"
         );
-        const locateResult = await agent.aiLocate(prompt);
+        const locateResult = await agent.aiLocate(prompt, locateTask);
         this.setResult(locateTask.name, locateResult);
       } else if ("aiWaitFor" in flowItem) {
         const waitForTask = flowItem;
         const prompt = waitForTask.aiWaitFor;
-        assert2(prompt, "missing prompt for aiWaitFor");
-        assert2(
+        assert3(prompt, "missing prompt for aiWaitFor");
+        assert3(
           typeof prompt === "string",
           "prompt for aiWaitFor must be a string"
         );
@@ -363,7 +567,7 @@ var ScriptPlayer = class {
         if (typeof ms === "string") {
           msNumber = Number.parseInt(ms, 10);
         }
-        assert2(
+        assert3(
           msNumber && msNumber > 0,
           `ms for sleep must be greater than 0, but got ${ms}`
         );
@@ -482,11 +686,11 @@ var ScriptPlayer = class {
 };
 
 // src/yaml/builder.ts
-import yaml from "js-yaml";
+import yaml2 from "js-yaml";
 
 // src/yaml/utils.ts
-import { assert as assert3 } from "@midscene/shared/utils";
-import yaml2 from "js-yaml";
+import { assert as assert4 } from "@midscene/shared/utils";
+import yaml3 from "js-yaml";
 function interpolateEnvVars(content) {
   return content.replace(/\$\{([^}]+)\}/g, (_, envVar) => {
     const value = process.env[envVar.trim()];
@@ -512,31 +716,31 @@ function parseYamlScript(content, filePath, ignoreCheckingTarget) {
     );
   }
   const interpolatedContent = interpolateEnvVars(processedContent);
-  const obj = yaml2.load(interpolatedContent, {
-    schema: yaml2.JSON_SCHEMA
+  const obj = yaml3.load(interpolatedContent, {
+    schema: yaml3.JSON_SCHEMA
   });
   const pathTip = filePath ? `, failed to load ${filePath}` : "";
   const android = typeof obj.android !== "undefined" ? Object.assign({}, obj.android || {}) : void 0;
   const webConfig = obj.web || obj.target;
   const web = typeof webConfig !== "undefined" ? Object.assign({}, webConfig || {}) : void 0;
   if (!ignoreCheckingTarget) {
-    assert3(
+    assert4(
       web || android,
       `at least one of "target", "web", or "android" properties is required in yaml script${pathTip}`
     );
-    assert3(
+    assert4(
       web && !android || !web && android,
       `only one of "target", "web", or "android" properties is allowed in yaml script${pathTip}`
     );
     if (web || android) {
-      assert3(
+      assert4(
         typeof web === "object" || typeof android === "object",
         `property "target/web/android" must be an object${pathTip}`
       );
     }
   }
-  assert3(obj.tasks, `property "tasks" is required in yaml script ${pathTip}`);
-  assert3(
+  assert4(obj.tasks, `property "tasks" is required in yaml script ${pathTip}`);
+  assert4(
     Array.isArray(obj.tasks),
     `property "tasks" must be an array in yaml script, but got ${obj.tasks}`
   );
@@ -570,8 +774,8 @@ import {
 } from "@midscene/core/ai-model";
 import { sleep } from "@midscene/core/utils";
 import { NodeType } from "@midscene/shared/constants";
-import { getDebug } from "@midscene/shared/logger";
-import { assert as assert4 } from "@midscene/shared/utils";
+import { getDebug as getDebug2 } from "@midscene/shared/logger";
+import { assert as assert5 } from "@midscene/shared/utils";
 
 // src/common/ui-utils.ts
 function typeStr(task) {
@@ -647,7 +851,7 @@ function paramStr(task) {
 }
 
 // src/common/tasks.ts
-var debug = getDebug("page-task-executor");
+var debug2 = getDebug2("page-task-executor");
 var replanningCountLimit = 10;
 var isAndroidPage = (page) => {
   return page.pageType === "android";
@@ -688,7 +892,7 @@ var PageTaskExecutor = class {
       if (info?.id) {
         elementId = info.id;
       } else {
-        debug(
+        debug2(
           "no element id found for position node, will not update cache",
           element
         );
@@ -701,7 +905,7 @@ var PageTaskExecutor = class {
       const result = await this.page.getXpathsById(elementId);
       return result;
     } catch (error) {
-      debug("getXpathsById error: ", error);
+      debug2("getXpathsById error: ", error);
     }
   }
   prependExecutorWithScreenshot(taskApply, appendAfterExecution = false) {
@@ -755,7 +959,7 @@ var PageTaskExecutor = class {
           locate: plan2.locate,
           executor: async (param, taskContext) => {
             const { task } = taskContext;
-            assert4(
+            assert5(
               param?.prompt || param?.id || param?.bbox,
               "No prompt or id or position or bbox to locate"
             );
@@ -780,39 +984,29 @@ var PageTaskExecutor = class {
               timing: "before Insight"
             };
             task.recorder = [recordItem];
-            let cacheHitFlag = false;
+            const elementFromXpath = param.xpath ? await this.page.getElementInfoByXpath(param.xpath) : void 0;
+            const userExpectedPathHitFlag = !!elementFromXpath;
             const cachePrompt = param.prompt;
             const locateCacheRecord = this.taskCache?.matchLocateCache(cachePrompt);
             const xpaths = locateCacheRecord?.cacheContent?.xpaths;
-            let elementFromCache = null;
-            try {
-              if (xpaths?.length && this.taskCache?.isCacheResultUsed && param?.cacheable !== false) {
-                for (let i = 0; i < xpaths.length; i++) {
-                  const element2 = await this.page.getElementInfoByXpath(
-                    xpaths[i]
-                  );
-                  if (element2?.id) {
-                    elementFromCache = element2;
-                    debug("cache hit, prompt: %s", cachePrompt);
-                    cacheHitFlag = true;
-                    debug(
-                      "found a new new element with same xpath, xpath: %s, id: %s",
-                      xpaths[i],
-                      element2?.id
-                    );
-                    break;
-                  }
-                }
-              }
-            } catch (error) {
-              debug("get element info by xpath error: ", error);
-            }
-            const startTime = Date.now();
-            const element = elementFromCache || // try to match element from cache
-            matchElementFromPlan(param, pageContext.tree) || // try to match element from plan
-            (await this.insight.locate(param, {
+            const elementFromCache = userExpectedPathHitFlag ? null : await matchElementFromCache(
+              this,
+              xpaths,
+              cachePrompt,
+              param.cacheable
+            );
+            const cacheHitFlag = !!elementFromCache;
+            const elementFromPlan = !userExpectedPathHitFlag && !cacheHitFlag ? matchElementFromPlan(param, pageContext.tree) : void 0;
+            const planHitFlag = !!elementFromPlan;
+            const elementFromAiLocate = !userExpectedPathHitFlag && !cacheHitFlag && !planHitFlag ? (await this.insight.locate(param, {
+              // fallback to ai locate
               context: pageContext
-            })).element;
+            })).element : void 0;
+            const aiLocateHitFlag = !!elementFromAiLocate;
+            const element = elementFromXpath || // highest priority
+            elementFromCache || // second priority
+            elementFromPlan || // third priority
+            elementFromAiLocate;
             let currentXpaths;
             if (element && this.taskCache && !cacheHitFlag && param?.cacheable !== false) {
               const elementXpaths = await this.getElementXpath(
@@ -830,7 +1024,7 @@ var PageTaskExecutor = class {
                   locateCacheRecord
                 );
               } else {
-                debug(
+                debug2(
                   "no xpaths found, will not update cache",
                   cachePrompt,
                   elementXpaths
@@ -840,16 +1034,44 @@ var PageTaskExecutor = class {
             if (!element) {
               throw new Error(`Element not found: ${param.prompt}`);
             }
+            let hitBy;
+            if (userExpectedPathHitFlag) {
+              hitBy = {
+                from: "User expected path",
+                context: {
+                  xpath: param.xpath
+                }
+              };
+            } else if (cacheHitFlag) {
+              hitBy = {
+                from: "Cache",
+                context: {
+                  xpathsFromCache: xpaths,
+                  xpathsToSave: currentXpaths
+                }
+              };
+            } else if (planHitFlag) {
+              hitBy = {
+                from: "Planning",
+                context: {
+                  id: elementFromPlan?.id,
+                  bbox: elementFromPlan?.bbox
+                }
+              };
+            } else if (aiLocateHitFlag) {
+              hitBy = {
+                from: "AI model",
+                context: {
+                  prompt: param.prompt
+                }
+              };
+            }
             return {
               output: {
                 element
               },
               pageContext,
-              cache: {
-                hit: cacheHitFlag,
-                originalXpaths: xpaths,
-                currentXpaths
-              }
+              hitBy
             };
           }
         };
@@ -945,7 +1167,7 @@ var PageTaskExecutor = class {
           thought: plan2.thought,
           locate: plan2.locate,
           executor: async (param, { element }) => {
-            assert4(element, "Element not found, cannot tap");
+            assert5(element, "Element not found, cannot tap");
             await this.page.mouse.click(element.center[0], element.center[1]);
           }
         };
@@ -957,7 +1179,7 @@ var PageTaskExecutor = class {
           thought: plan2.thought,
           locate: plan2.locate,
           executor: async (param, { element }) => {
-            assert4(element, "Element not found, cannot right click");
+            assert5(element, "Element not found, cannot right click");
             await this.page.mouse.click(
               element.center[0],
               element.center[1],
@@ -974,7 +1196,7 @@ var PageTaskExecutor = class {
           thought: plan2.thought,
           locate: plan2.locate,
           executor: async (taskParam) => {
-            assert4(
+            assert5(
               taskParam?.start_box && taskParam?.end_box,
               "No start_box or end_box to drag"
             );
@@ -989,7 +1211,7 @@ var PageTaskExecutor = class {
           thought: plan2.thought,
           locate: plan2.locate,
           executor: async (param, { element }) => {
-            assert4(element, "Element not found, cannot hover");
+            assert5(element, "Element not found, cannot hover");
             await this.page.mouse.move(element.center[0], element.center[1]);
           }
         };
@@ -1108,7 +1330,7 @@ var PageTaskExecutor = class {
           thought: plan2.thought,
           locate: plan2.locate,
           executor: async (param) => {
-            assert4(
+            assert5(
               isAndroidPage(this.page),
               "Cannot use home button on non-Android devices"
             );
@@ -1124,7 +1346,7 @@ var PageTaskExecutor = class {
           thought: plan2.thought,
           locate: plan2.locate,
           executor: async (param) => {
-            assert4(
+            assert5(
               isAndroidPage(this.page),
               "Cannot use back button on non-Android devices"
             );
@@ -1140,7 +1362,7 @@ var PageTaskExecutor = class {
           thought: plan2.thought,
           locate: plan2.locate,
           executor: async (param) => {
-            assert4(
+            assert5(
               isAndroidPage(this.page),
               "Cannot use recent apps button on non-Android devices"
             );
@@ -1291,7 +1513,7 @@ var PageTaskExecutor = class {
           }
         }
         if (finalActions.length === 0) {
-          assert4(
+          assert5(
             !more_actions_needed_by_instruction || sleep2,
             error ? `Failed to plan: ${error}` : planParsingError || "No plan found"
           );
@@ -1529,7 +1751,7 @@ var PageTaskExecutor = class {
         );
         let outputResult = data;
         if (ifTypeRestricted) {
-          assert4(data?.result !== void 0, "No result in query data");
+          assert5(data?.result !== void 0, "No result in query data");
           outputResult = data.result;
         }
         return {
@@ -1625,9 +1847,9 @@ var PageTaskExecutor = class {
       onTaskStart: this.onTaskStartCallback
     });
     const { timeoutMs, checkIntervalMs } = opt;
-    assert4(assertion, "No assertion for waitFor");
-    assert4(timeoutMs, "No timeoutMs for waitFor");
-    assert4(checkIntervalMs, "No checkIntervalMs for waitFor");
+    assert5(assertion, "No assertion for waitFor");
+    assert5(timeoutMs, "No timeoutMs for waitFor");
+    assert5(checkIntervalMs, "No checkIntervalMs for waitFor");
     const overallStartTime = Date.now();
     let startTime = Date.now();
     let errorThought = "";
@@ -1681,9 +1903,9 @@ var PageTaskExecutor = class {
 };
 
 // src/common/plan-builder.ts
-import { getDebug as getDebug2 } from "@midscene/shared/logger";
-import { assert as assert5 } from "@midscene/shared/utils";
-var debug2 = getDebug2("plan-builder");
+import { getDebug as getDebug3 } from "@midscene/shared/logger";
+import { assert as assert6 } from "@midscene/shared/utils";
+var debug3 = getDebug3("plan-builder");
 function buildPlans(type, locateParam, param) {
   let returnPlans = [];
   const locatePlan = locateParam ? {
@@ -1693,8 +1915,8 @@ function buildPlans(type, locateParam, param) {
     thought: ""
   } : null;
   if (type === "Tap" || type === "Hover" || type === "RightClick") {
-    assert5(locateParam, `missing locate info for action "${type}"`);
-    assert5(locatePlan, `missing locate info for action "${type}"`);
+    assert6(locateParam, `missing locate info for action "${type}"`);
+    assert6(locatePlan, `missing locate info for action "${type}"`);
     const tapPlan = {
       type,
       param: null,
@@ -1705,9 +1927,9 @@ function buildPlans(type, locateParam, param) {
   }
   if (type === "Input" || type === "KeyboardPress") {
     if (type === "Input") {
-      assert5(locateParam, `missing locate info for action "${type}"`);
+      assert6(locateParam, `missing locate info for action "${type}"`);
     }
-    assert5(param, `missing param for action "${type}"`);
+    assert6(param, `missing param for action "${type}"`);
     const inputPlan = {
       type,
       param,
@@ -1721,7 +1943,7 @@ function buildPlans(type, locateParam, param) {
     }
   }
   if (type === "Scroll") {
-    assert5(param, `missing param for action "${type}"`);
+    assert6(param, `missing param for action "${type}"`);
     const scrollPlan = {
       type,
       param,
@@ -1735,7 +1957,7 @@ function buildPlans(type, locateParam, param) {
     }
   }
   if (type === "Sleep") {
-    assert5(param, `missing param for action "${type}"`);
+    assert6(param, `missing param for action "${type}"`);
     const sleepPlan = {
       type,
       param,
@@ -1745,7 +1967,7 @@ function buildPlans(type, locateParam, param) {
     returnPlans = [sleepPlan];
   }
   if (type === "Locate") {
-    assert5(locateParam, `missing locate info for action "${type}"`);
+    assert6(locateParam, `missing locate info for action "${type}"`);
     const locatePlan2 = {
       type,
       param: locateParam,
@@ -1755,187 +1977,12 @@ function buildPlans(type, locateParam, param) {
     returnPlans = [locatePlan2];
   }
   if (returnPlans) {
-    debug2("buildPlans", returnPlans);
+    debug3("buildPlans", returnPlans);
     return returnPlans;
   }
   throw new Error(`Not supported type: ${type}`);
 }
 
-// src/common/task-cache.ts
-import assert6 from "assert";
-import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync, writeFileSync as writeFileSync2 } from "fs";
-import { dirname as dirname2, join as join2 } from "path";
-import { getMidsceneRunSubDir as getMidsceneRunSubDir2 } from "@midscene/shared/common";
-import { getDebug as getDebug3 } from "@midscene/shared/logger";
-import { ifInBrowser as ifInBrowser2 } from "@midscene/shared/utils";
-import yaml3 from "js-yaml";
-import semver from "semver";
-
-// package.json
-var version = "0.19.1";
-
-// src/common/task-cache.ts
-var debug3 = getDebug3("cache");
-var lowestSupportedMidsceneVersion = "0.16.10";
-var cacheFileExt = ".cache.yaml";
-var TaskCache = class {
-  // Track matched records
-  constructor(cacheId, isCacheResultUsed, cacheFilePath) {
-    this.matchedCacheIndices = /* @__PURE__ */ new Set();
-    assert6(cacheId, "cacheId is required");
-    this.cacheId = replaceIllegalPathCharsAndSpace(cacheId);
-    this.cacheFilePath = ifInBrowser2 ? void 0 : cacheFilePath || join2(getMidsceneRunSubDir2("cache"), `${this.cacheId}${cacheFileExt}`);
-    this.isCacheResultUsed = isCacheResultUsed;
-    let cacheContent;
-    if (this.cacheFilePath) {
-      cacheContent = this.loadCacheFromFile();
-    }
-    if (!cacheContent) {
-      cacheContent = {
-        midsceneVersion: version,
-        cacheId: this.cacheId,
-        caches: []
-      };
-    }
-    this.cache = cacheContent;
-    this.cacheOriginalLength = this.cache.caches.length;
-  }
-  matchCache(prompt, type) {
-    for (let i = 0; i < this.cacheOriginalLength; i++) {
-      const item = this.cache.caches[i];
-      const key = `${type}:${prompt}:${i}`;
-      if (item.type === type && item.prompt === prompt && !this.matchedCacheIndices.has(key)) {
-        this.matchedCacheIndices.add(key);
-        debug3(
-          "cache found and marked as used, type: %s, prompt: %s, index: %d",
-          type,
-          prompt,
-          i
-        );
-        return {
-          cacheContent: item,
-          updateFn: (cb) => {
-            debug3(
-              "will call updateFn to update cache, type: %s, prompt: %s, index: %d",
-              type,
-              prompt,
-              i
-            );
-            cb(item);
-            debug3(
-              "cache updated, will flush to file, type: %s, prompt: %s, index: %d",
-              type,
-              prompt,
-              i
-            );
-            this.flushCacheToFile();
-          }
-        };
-      }
-    }
-    debug3("no unused cache found, type: %s, prompt: %s", type, prompt);
-    return void 0;
-  }
-  matchPlanCache(prompt) {
-    return this.matchCache(prompt, "plan");
-  }
-  matchLocateCache(prompt) {
-    return this.matchCache(prompt, "locate");
-  }
-  appendCache(cache) {
-    debug3("will append cache", cache);
-    this.cache.caches.push(cache);
-    this.flushCacheToFile();
-  }
-  loadCacheFromFile() {
-    const cacheFile = this.cacheFilePath;
-    assert6(cacheFile, "cache file path is required");
-    if (!existsSync2(cacheFile)) {
-      debug3("no cache file found, path: %s", cacheFile);
-      return void 0;
-    }
-    const jsonTypeCacheFile = cacheFile.replace(cacheFileExt, ".json");
-    if (existsSync2(jsonTypeCacheFile) && this.isCacheResultUsed) {
-      console.warn(
-        `An outdated cache file from an earlier version of Midscene has been detected. Since version 0.17, we have implemented an improved caching strategy. Please delete the old file located at: ${jsonTypeCacheFile}.`
-      );
-      return void 0;
-    }
-    try {
-      const data = readFileSync(cacheFile, "utf8");
-      const jsonData = yaml3.load(data);
-      if (!version) {
-        debug3("no midscene version info, will not read cache from file");
-        return void 0;
-      }
-      if (semver.lt(jsonData.midsceneVersion, lowestSupportedMidsceneVersion) && !jsonData.midsceneVersion.includes("beta")) {
-        console.warn(
-          `You are using an old version of Midscene cache file, and we cannot match any info from it. Starting from Midscene v0.17, we changed our strategy to use xpath for cache info, providing better performance.
-Please delete the existing cache and rebuild it. Sorry for the inconvenience.
-cache file: ${cacheFile}`
-        );
-        return void 0;
-      }
-      debug3(
-        "cache loaded from file, path: %s, cache version: %s, record length: %s",
-        cacheFile,
-        jsonData.midsceneVersion,
-        jsonData.caches.length
-      );
-      jsonData.midsceneVersion = version;
-      return jsonData;
-    } catch (err) {
-      debug3(
-        "cache file exists but load failed, path: %s, error: %s",
-        cacheFile,
-        err
-      );
-      return void 0;
-    }
-  }
-  flushCacheToFile() {
-    if (!version) {
-      debug3("no midscene version info, will not write cache to file");
-      return;
-    }
-    if (!this.cacheFilePath) {
-      debug3("no cache file path, will not write cache to file");
-      return;
-    }
-    try {
-      const dir = dirname2(this.cacheFilePath);
-      if (!existsSync2(dir)) {
-        mkdirSync2(dir, { recursive: true });
-        debug3("created cache directory: %s", dir);
-      }
-      const yamlData = yaml3.dump(this.cache);
-      writeFileSync2(this.cacheFilePath, yamlData);
-      debug3("cache flushed to file: %s", this.cacheFilePath);
-    } catch (err) {
-      debug3(
-        "write cache to file failed, path: %s, error: %s",
-        this.cacheFilePath,
-        err
-      );
-    }
-  }
-  updateOrAppendCacheRecord(newRecord, cachedRecord) {
-    if (cachedRecord) {
-      if (newRecord.type === "plan") {
-        cachedRecord.updateFn((cache) => {
-          cache.yamlWorkflow = newRecord.yamlWorkflow;
-        });
-      } else {
-        cachedRecord.updateFn((cache) => {
-          cache.xpaths = newRecord.xpaths;
-        });
-      }
-    } else {
-      this.appendCache(newRecord);
-    }
-  }
-};
-
 // src/common/agent.ts
 var debug4 = getDebug4("web-integration");
 var distanceOfTwoPoints = (p1, p2) => {
@@ -2064,10 +2111,12 @@ ${errorTask?.errorStack}`);
       const prompt = opt.prompt ?? locatePrompt;
       const deepThink = opt.deepThink ?? false;
       const cacheable = opt.cacheable ?? true;
+      const xpath = opt.xpath;
       return {
         prompt,
         deepThink,
-        cacheable
+        cacheable,
+        xpath
       };
     }
     return {
@@ -2225,6 +2274,9 @@ ${errorTask?.errorStack}`);
     this.afterTaskRunning(executor);
     return output;
   }
+  async aiAsk(prompt, opt = defaultInsightExtractOption) {
+    return this.aiString(prompt, opt);
+  }
   async describeElementAtPoint(center, opt) {
     const { verifyPrompt = true, retryLimit = 3 } = opt || {};
     let success = false;