@godscene/core 1.7.11

package/dist/es/agent/execution-session.mjs

@@ -0,0 +1,39 @@
+import { TaskRunner } from "../task-runner.mjs";
+function _define_property(obj, key, value) {
+    if (key in obj) Object.defineProperty(obj, key, {
+        value: value,
+        enumerable: true,
+        configurable: true,
+        writable: true
+    });
+    else obj[key] = value;
+    return obj;
+}
+class ExecutionSession {
+    async append(tasks, options) {
+        await this.runner.append(tasks, options);
+    }
+    async appendAndRun(tasks, options) {
+        return this.runner.appendAndFlush(tasks, options);
+    }
+    async run(options) {
+        return this.runner.flush(options);
+    }
+    isInErrorState() {
+        return this.runner.isInErrorState();
+    }
+    latestErrorTask() {
+        return this.runner.latestErrorTask();
+    }
+    appendErrorPlan(errorMsg) {
+        return this.runner.appendErrorPlan(errorMsg);
+    }
+    getRunner() {
+        return this.runner;
+    }
+    constructor(name, contextProvider, options){
+        _define_property(this, "runner", void 0);
+        this.runner = new TaskRunner(name, contextProvider, options);
+    }
+}
+export { ExecutionSession };

package/dist/es/agent/index.mjs

@@ -0,0 +1,6 @@
+import { Agent, createAgent } from "./agent.mjs";
+import { commonContextParser, getReportFileName, printReportMsg } from "./utils.mjs";
+import { extractInsightParam, locateParamStr, paramStr, taskTitleStr, typeStr } from "./ui-utils.mjs";
+import { TaskCache, cacheFileExt } from "./task-cache.mjs";
+import { TaskExecutor } from "./tasks.mjs";
+export { Agent, TaskCache, TaskExecutor, cacheFileExt, commonContextParser, createAgent, extractInsightParam, getReportFileName, locateParamStr, paramStr, printReportMsg, taskTitleStr, typeStr };

package/dist/es/agent/task-builder.mjs

@@ -0,0 +1,343 @@
+import { findAllMidsceneLocatorField, parseActionParam } from "../ai-model/index.mjs";
+import { setTimingFieldOnce } from "../task-timing.mjs";
+import { ServiceError } from "../types.mjs";
+import { sleep } from "../utils.mjs";
+import { generateElementByRect } from "@godscene/shared/extractor";
+import { getDebug } from "@godscene/shared/logger";
+import { assert } from "@godscene/shared/utils";
+import { ifPlanLocateParamIsBbox, matchElementFromCache, matchElementFromPlan, transformLogicalElementToScreenshot, transformLogicalRectToScreenshotRect } from "./utils.mjs";
+function _define_property(obj, key, value) {
+    if (key in obj) Object.defineProperty(obj, key, {
+        value: value,
+        enumerable: true,
+        configurable: true,
+        writable: true
+    });
+    else obj[key] = value;
+    return obj;
+}
+const debug = getDebug('agent:task-builder');
+function hasNonEmptyCache(cache) {
+    return null != cache && 'object' == typeof cache && Object.keys(cache).length > 0;
+}
+function locatePlanForLocate(param) {
+    const locate = 'string' == typeof param ? {
+        prompt: param
+    } : param;
+    const locatePlan = {
+        type: 'Locate',
+        param: locate,
+        thought: ''
+    };
+    return locatePlan;
+}
+class TaskBuilder {
+    async build(plans, modelConfigForPlanning, modelConfigForDefaultIntent, options) {
+        const tasks = [];
+        const cacheable = options?.cacheable;
+        const context = {
+            tasks,
+            modelConfigForPlanning,
+            modelConfigForDefaultIntent,
+            cacheable,
+            deepLocate: options?.deepLocate,
+            abortSignal: options?.abortSignal
+        };
+        const planHandlers = new Map([
+            [
+                'Locate',
+                (plan)=>this.handleLocatePlan(plan, context)
+            ],
+            [
+                'Finished',
+                (plan)=>this.handleFinishedPlan(plan, context)
+            ]
+        ]);
+        const defaultHandler = (plan)=>this.handleActionPlan(plan, context);
+        for (const plan of plans){
+            const handler = planHandlers.get(plan.type) ?? defaultHandler;
+            await handler(plan);
+        }
+        return {
+            tasks
+        };
+    }
+    handleFinishedPlan(plan, context) {
+        const taskActionFinished = {
+            type: 'Action Space',
+            subType: 'Finished',
+            param: null,
+            thought: plan.thought,
+            executor: async ()=>{}
+        };
+        context.tasks.push(taskActionFinished);
+    }
+    async handleLocatePlan(plan, context) {
+        const taskLocate = this.createLocateTask(plan, plan.param, context);
+        context.tasks.push(taskLocate);
+    }
+    async handleActionPlan(plan, context) {
+        const planType = plan.type;
+        const actionSpace = this.actionSpace;
+        const action = actionSpace.find((item)=>item.name === planType);
+        const param = plan.param;
+        if (!action) throw new Error(`Action type '${planType}' not found`);
+        const locateFields = action ? findAllMidsceneLocatorField(action.paramSchema) : [];
+        const requiredLocateFields = action ? findAllMidsceneLocatorField(action.paramSchema, true) : [];
+        locateFields.forEach((field)=>{
+            if (param[field]) {
+                const locatePlan = locatePlanForLocate(param[field]);
+                debug('will prepend locate param for field', `action.type=${planType}`, `param=${JSON.stringify(param[field])}`, `locatePlan=${JSON.stringify(locatePlan)}`, `hasBbox=${ifPlanLocateParamIsBbox(param[field])}`);
+                const locateTask = this.createLocateTask(locatePlan, param[field], context, (result)=>{
+                    param[field] = result;
+                });
+                context.tasks.push(locateTask);
+            } else {
+                assert(!requiredLocateFields.includes(field), `Required locate field '${field}' is not provided for action ${planType}`);
+                debug(`field '${field}' is not provided for action ${planType}`);
+            }
+        });
+        const task = {
+            type: 'Action Space',
+            subType: planType,
+            thought: plan.thought,
+            param: plan.param,
+            executor: async (param, taskContext)=>{
+                const timing = taskContext.task.timing;
+                debug('executing action', planType, param, `taskContext.element.center: ${taskContext.element?.center}`);
+                const uiContext = taskContext.uiContext;
+                assert(uiContext, 'uiContext is required for Action task');
+                requiredLocateFields.forEach((field)=>{
+                    assert(param[field], `field '${field}' is required for action ${planType} but not provided. Cannot execute action ${planType}.`);
+                });
+                setTimingFieldOnce(timing, 'beforeInvokeActionHookStart');
+                const delayBeforeRunner = action.delayBeforeRunner ?? 200;
+                try {
+                    await Promise.all([
+                        (async ()=>{
+                            if (this.interface.beforeInvokeAction) {
+                                debug(`will call "beforeInvokeAction" for interface with action name ${action.name}`);
+                                await this.interface.beforeInvokeAction(action.name, param);
+                                debug(`called "beforeInvokeAction" for interface with action name ${action.name}`);
+                            }
+                        })(),
+                        delayBeforeRunner > 0 ? sleep(delayBeforeRunner) : Promise.resolve()
+                    ]);
+                } catch (originalError) {
+                    const originalMessage = originalError?.message || String(originalError);
+                    throw new Error(`error in running beforeInvokeAction for ${action.name}: ${originalMessage}`, {
+                        cause: originalError
+                    });
+                }
+                setTimingFieldOnce(timing, 'beforeInvokeActionHookEnd');
+                const { shrunkShotToLogicalRatio } = uiContext;
+                if (void 0 === shrunkShotToLogicalRatio) throw new Error('shrunkShotToLogicalRatio is not defined in Action task');
+                if (action.paramSchema) try {
+                    param = parseActionParam(param, action.paramSchema, {
+                        shrunkShotToLogicalRatio
+                    });
+                } catch (error) {
+                    throw new Error(`Invalid parameters for action ${action.name}: ${error.message}\nParameters: ${JSON.stringify(param)}`, {
+                        cause: error
+                    });
+                }
+                setTimingFieldOnce(timing, 'callActionStart');
+                debug('calling action', action.name);
+                const actionFn = action.call.bind(this.interface);
+                const actionResult = await actionFn(param, taskContext);
+                setTimingFieldOnce(timing, 'callActionEnd');
+                debug('called action', action.name, 'result:', actionResult);
+                setTimingFieldOnce(timing, 'afterInvokeActionHookStart');
+                const delayAfterRunner = action.delayAfterRunner ?? this.waitAfterAction ?? 300;
+                if (delayAfterRunner > 0) await sleep(delayAfterRunner);
+                try {
+                    if (this.interface.afterInvokeAction) {
+                        debug(`will call "afterInvokeAction" for interface with action name ${action.name}`);
+                        await this.interface.afterInvokeAction(action.name, param);
+                        debug(`called "afterInvokeAction" for interface with action name ${action.name}`);
+                    }
+                } catch (originalError) {
+                    const originalMessage = originalError?.message || String(originalError);
+                    throw new Error(`error in running afterInvokeAction for ${action.name}: ${originalMessage}`, {
+                        cause: originalError
+                    });
+                }
+                setTimingFieldOnce(timing, 'afterInvokeActionHookEnd');
+                return {
+                    output: actionResult
+                };
+            }
+        };
+        context.tasks.push(task);
+    }
+    createLocateTask(plan, detailedLocateParam, context, onResult) {
+        const { cacheable, modelConfigForDefaultIntent, deepLocate, abortSignal } = context;
+        let locateParam = detailedLocateParam;
+        if ('string' == typeof locateParam) locateParam = {
+            prompt: locateParam
+        };
+        if (void 0 !== cacheable) locateParam = {
+            ...locateParam,
+            cacheable
+        };
+        if (deepLocate && !locateParam.deepLocate) locateParam = {
+            ...locateParam,
+            deepLocate: true
+        };
+        const taskLocator = {
+            type: 'Planning',
+            subType: 'Locate',
+            param: locateParam,
+            thought: plan.thought,
+            executor: async (param, taskContext)=>{
+                const { task } = taskContext;
+                let { uiContext } = taskContext;
+                assert(param?.prompt || param?.bbox, `No prompt or id or position or bbox to locate, param=${JSON.stringify(param)}`);
+                if (!uiContext) uiContext = await this.service.contextRetrieverFn();
+                assert(uiContext, 'uiContext is required for Service task');
+                const { shrunkShotToLogicalRatio } = uiContext;
+                if (void 0 === shrunkShotToLogicalRatio) throw new Error('shrunkShotToLogicalRatio is not defined in locate task');
+                let locateDump;
+                let locateResult;
+                const applyDump = (dump)=>{
+                    if (!dump) return;
+                    locateDump = dump;
+                    task.log = {
+                        dump,
+                        rawResponse: dump.taskInfo?.rawResponse
+                    };
+                    task.usage = dump.taskInfo?.usage;
+                    if (dump.taskInfo?.searchAreaUsage) task.searchAreaUsage = dump.taskInfo.searchAreaUsage;
+                    if (dump.taskInfo?.reasoning_content) task.reasoning_content = dump.taskInfo.reasoning_content;
+                };
+                const planLocatedElement = ifPlanLocateParamIsBbox(param) ? matchElementFromPlan(param) : void 0;
+                const elementFromBbox = param.deepLocate ? void 0 : planLocatedElement;
+                const isPlanHit = !!elementFromBbox;
+                let rectFromXpath;
+                if (!isPlanHit && param.xpath && this.interface.rectMatchesCacheFeature) try {
+                    rectFromXpath = await this.interface.rectMatchesCacheFeature({
+                        xpaths: [
+                            param.xpath
+                        ]
+                    });
+                } catch  {}
+                const elementFromXpath = rectFromXpath ? generateElementByRect(transformLogicalRectToScreenshotRect(rectFromXpath, shrunkShotToLogicalRatio), 'string' == typeof param.prompt ? param.prompt : param.prompt?.prompt || '') : void 0;
+                const isXpathHit = !!elementFromXpath;
+                const cachePrompt = param.prompt;
+                const locateCacheRecord = this.taskCache?.matchLocateCache(cachePrompt);
+                const cacheEntry = locateCacheRecord?.cacheContent?.cache;
+                const elementFromCacheResult = isPlanHit || isXpathHit ? null : await matchElementFromCache({
+                    taskCache: this.taskCache,
+                    interfaceInstance: this.interface
+                }, cacheEntry, cachePrompt, param.cacheable);
+                const elementFromCache = elementFromCacheResult ? transformLogicalElementToScreenshot(elementFromCacheResult, shrunkShotToLogicalRatio) : void 0;
+                const isCacheHit = !!elementFromCache;
+                let elementFromAiLocate;
+                const timing = taskContext.task.timing;
+                if (!isXpathHit && !isCacheHit && !isPlanHit) try {
+                    setTimingFieldOnce(timing, 'callAiStart');
+                    locateResult = await this.service.locate(param, {
+                        context: uiContext,
+                        planLocatedElement
+                    }, modelConfigForDefaultIntent, abortSignal);
+                    applyDump(locateResult.dump);
+                    elementFromAiLocate = locateResult.element;
+                } catch (error) {
+                    if (error instanceof ServiceError) applyDump(error.dump);
+                    throw error;
+                } finally{
+                    setTimingFieldOnce(timing, 'callAiEnd');
+                }
+                const element = elementFromBbox || elementFromXpath || elementFromCache || elementFromAiLocate;
+                const locateCacheAlreadyExists = hasNonEmptyCache(locateCacheRecord?.cacheContent?.cache);
+                let currentCacheEntry;
+                if (element && this.taskCache && !isCacheHit && (!isPlanHit || !locateCacheAlreadyExists) && param?.cacheable !== false) if (this.interface.cacheFeatureForPoint) try {
+                    let pointForCache = element.center;
+                    if (1 !== shrunkShotToLogicalRatio) {
+                        pointForCache = [
+                            Math.round(element.center[0] / shrunkShotToLogicalRatio),
+                            Math.round(element.center[1] / shrunkShotToLogicalRatio)
+                        ];
+                        debug('Transformed coordinates for cacheFeatureForPoint: %o -> %o', element.center, pointForCache);
+                    }
+                    const feature = await this.interface.cacheFeatureForPoint(pointForCache, {
+                        targetDescription: 'string' == typeof param.prompt ? param.prompt : param.prompt?.prompt,
+                        modelConfig: modelConfigForDefaultIntent
+                    });
+                    if (hasNonEmptyCache(feature)) {
+                        debug('update cache, prompt: %s, cache: %o', cachePrompt, feature);
+                        currentCacheEntry = feature;
+                        this.taskCache.updateOrAppendCacheRecord({
+                            type: 'locate',
+                            prompt: cachePrompt,
+                            cache: feature
+                        }, locateCacheRecord);
+                    } else debug('no cache data returned, skip cache update, prompt: %s', cachePrompt);
+                } catch (error) {
+                    debug('cacheFeatureForPoint failed: %s', error);
+                }
+                else debug('cacheFeatureForPoint is not supported, skip cache update');
+                if (!element) {
+                    if (locateDump) throw new ServiceError(`Element not found : ${param.prompt}`, locateDump);
+                    throw new Error(`Element not found: ${param.prompt}`);
+                }
+                let hitBy;
+                if (isPlanHit) hitBy = {
+                    from: 'Plan',
+                    context: {
+                        bbox: param.bbox
+                    }
+                };
+                else if (isXpathHit) hitBy = {
+                    from: 'User expected path',
+                    context: {
+                        xpath: param.xpath
+                    }
+                };
+                else if (isCacheHit) hitBy = {
+                    from: 'Cache',
+                    context: {
+                        cacheEntry,
+                        cacheToSave: currentCacheEntry
+                    }
+                };
+                if (this.interface.getElementFromPoint && element.center) try {
+                    const [x, y] = element.center;
+                    const data = await this.interface.getElementFromPoint({
+                        x,
+                        y
+                    });
+                    element.allPaths = data?.allPaths || [];
+                    element.containerPaths = data?.containerPaths || [];
+                } catch (error) {
+                    element.allPaths = [];
+                    element.containerPaths = [];
+                }
+                onResult?.(element);
+                return {
+                    output: {
+                        element: {
+                            ...element,
+                            dpr: uiContext.deprecatedDpr
+                        }
+                    },
+                    hitBy
+                };
+            }
+        };
+        return taskLocator;
+    }
+    constructor({ interfaceInstance, service, taskCache, actionSpace, waitAfterAction }){
+        _define_property(this, "interface", void 0);
+        _define_property(this, "service", void 0);
+        _define_property(this, "taskCache", void 0);
+        _define_property(this, "actionSpace", void 0);
+        _define_property(this, "waitAfterAction", void 0);
+        this.interface = interfaceInstance;
+        this.service = service;
+        this.taskCache = taskCache;
+        this.actionSpace = actionSpace;
+        this.waitAfterAction = waitAfterAction;
+    }
+}
+export { TaskBuilder, locatePlanForLocate };

package/dist/es/agent/task-cache.mjs

@@ -0,0 +1,212 @@
+import node_assert from "node:assert";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { getMidsceneRunSubDir } from "@godscene/shared/common";
+import { MIDSCENE_CACHE_MAX_FILENAME_LENGTH, globalConfigManager } from "@godscene/shared/env";
+import { getDebug } from "@godscene/shared/logger";
+import { generateHashId, ifInBrowser, ifInWorker, replaceIllegalPathCharsAndSpace } from "@godscene/shared/utils";
+import js_yaml from "js-yaml";
+import semver from "semver";
+import { getMidsceneVersion } from "./utils.mjs";
+function _define_property(obj, key, value) {
+    if (key in obj) Object.defineProperty(obj, key, {
+        value: value,
+        enumerable: true,
+        configurable: true,
+        writable: true
+    });
+    else obj[key] = value;
+    return obj;
+}
+const DEFAULT_CACHE_MAX_FILENAME_LENGTH = 200;
+const debug = getDebug('cache');
+const lowestSupportedMidsceneVersion = '0.16.10';
+const cacheFileExt = '.cache.yaml';
+class TaskCache {
+    matchCache(prompt, type) {
+        if (!this.isCacheResultUsed) return;
+        const promptStr = 'string' == typeof prompt ? prompt : JSON.stringify(prompt);
+        for(let i = 0; i < this.cacheOriginalLength; i++){
+            const item = this.cache.caches[i];
+            const key = `${type}:${promptStr}:${i}`;
+            if (item.type === type && isDeepStrictEqual(item.prompt, prompt) && !this.matchedCacheIndices.has(key)) {
+                if ('locate' === item.type) {
+                    const locateItem = item;
+                    if (!locateItem.cache && Array.isArray(locateItem.xpaths)) locateItem.cache = {
+                        xpaths: locateItem.xpaths
+                    };
+                    if ('xpaths' in locateItem) locateItem.xpaths = void 0;
+                }
+                this.matchedCacheIndices.add(key);
+                debug('cache found and marked as used, type: %s, prompt: %s, index: %d', type, prompt, i);
+                return {
+                    cacheContent: item,
+                    cacheUsable: true,
+                    updateFn: (cb)=>{
+                        debug('will call updateFn to update cache, type: %s, prompt: %s, index: %d', type, prompt, i);
+                        cb(item);
+                        if (this.readOnlyMode) return void debug('read-only mode, cache updated in memory but not flushed to file');
+                        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);
+    }
+    matchPlanCache(prompt) {
+        const result = this.matchCache(prompt, 'plan');
+        if (!result) return;
+        const yamlWorkflow = result.cacheContent.yamlWorkflow;
+        if (!yamlWorkflow?.trim()) {
+            debug('plan cache matched but yamlWorkflow is empty, treat as cache miss');
+            return {
+                ...result,
+                cacheUsable: false
+            };
+        }
+        try {
+            const parsed = js_yaml.load(yamlWorkflow);
+            const hasNonEmptyFlow = parsed?.tasks?.some((task)=>Array.isArray(task.flow) && task.flow.length > 0);
+            if (!hasNonEmptyFlow) {
+                debug('plan cache matched but flow is empty, treat as cache miss');
+                return {
+                    ...result,
+                    cacheUsable: false
+                };
+            }
+        } catch  {
+            debug('plan cache matched but yamlWorkflow is invalid, treat as cache miss');
+            return {
+                ...result,
+                cacheUsable: false
+            };
+        }
+        return result;
+    }
+    matchLocateCache(prompt) {
+        return this.matchCache(prompt, 'locate');
+    }
+    appendCache(cache) {
+        debug('will append cache', cache);
+        this.cache.caches.push(cache);
+        if (this.readOnlyMode) return void debug('read-only mode, cache appended to memory but not flushed to file');
+        this.flushCacheToFile();
+    }
+    loadCacheFromFile() {
+        const cacheFile = this.cacheFilePath;
+        node_assert(cacheFile, 'cache file path is required');
+        if (!existsSync(cacheFile)) return void debug('no cache file found, path: %s', cacheFile);
+        const jsonTypeCacheFile = cacheFile.replace(cacheFileExt, '.json');
+        if (existsSync(jsonTypeCacheFile) && this.isCacheResultUsed) return void 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}.`);
+        try {
+            const data = readFileSync(cacheFile, 'utf8');
+            const jsonData = js_yaml.load(data);
+            const version = getMidsceneVersion();
+            if (!version) return void debug('no midscene version info, will not read cache from file');
+            if (semver.lt(jsonData.midsceneVersion, lowestSupportedMidsceneVersion) && !jsonData.midsceneVersion.includes('beta')) return void 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.\nPlease delete the existing cache and rebuild it. Sorry for the inconvenience.\ncache file: ${cacheFile}`);
+            debug('cache loaded from file, path: %s, cache version: %s, record length: %s', cacheFile, jsonData.midsceneVersion, jsonData.caches.length);
+            jsonData.midsceneVersion = getMidsceneVersion();
+            return jsonData;
+        } catch (err) {
+            debug('cache file exists but load failed, path: %s, error: %s', cacheFile, err);
+            return;
+        }
+    }
+    flushCacheToFile(options) {
+        const version = getMidsceneVersion();
+        if (!version) return void debug('no midscene version info, will not write cache to file');
+        if (!this.cacheFilePath) return void debug('no cache file path, will not write cache to file');
+        if (options?.cleanUnused) if (this.isCacheResultUsed) {
+            const originalLength = this.cache.caches.length;
+            const usedIndices = new Set();
+            for (const key of this.matchedCacheIndices){
+                const parts = key.split(':');
+                const index = Number.parseInt(parts[parts.length - 1], 10);
+                if (!Number.isNaN(index)) usedIndices.add(index);
+            }
+            this.cache.caches = this.cache.caches.filter((_, index)=>{
+                const isUsed = usedIndices.has(index);
+                const isNew = index >= this.cacheOriginalLength;
+                return isUsed || isNew;
+            });
+            const removedCount = originalLength - this.cache.caches.length;
+            removedCount > 0 ? debug('cleaned %d unused cache record(s)', removedCount) : debug('no unused cache to clean');
+        } else debug('skip cleaning: cache is not used for reading');
+        try {
+            const dir = dirname(this.cacheFilePath);
+            if (!existsSync(dir)) {
+                mkdirSync(dir, {
+                    recursive: true
+                });
+                debug('created cache directory: %s', dir);
+            }
+            const sortedCaches = [
+                ...this.cache.caches
+            ].sort((a, b)=>{
+                if ('plan' === a.type && 'locate' === b.type) return -1;
+                if ('locate' === a.type && 'plan' === b.type) return 1;
+                return 0;
+            });
+            const cacheToWrite = {
+                ...this.cache,
+                caches: sortedCaches
+            };
+            const yamlData = js_yaml.dump(cacheToWrite, {
+                lineWidth: -1
+            });
+            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 ('plan' === newRecord.type) cachedRecord.updateFn((cache)=>{
+            cache.yamlWorkflow = newRecord.yamlWorkflow;
+        });
+        else cachedRecord.updateFn((cache)=>{
+            const locateCache = cache;
+            locateCache.cache = newRecord.cache;
+            if ('xpaths' in locateCache) locateCache.xpaths = void 0;
+        });
+        else this.appendCache(newRecord);
+    }
+    constructor(cacheId, isCacheResultUsed, cacheFilePath, options = {}){
+        _define_property(this, "cacheId", void 0);
+        _define_property(this, "cacheFilePath", void 0);
+        _define_property(this, "cache", void 0);
+        _define_property(this, "isCacheResultUsed", void 0);
+        _define_property(this, "cacheOriginalLength", void 0);
+        _define_property(this, "readOnlyMode", void 0);
+        _define_property(this, "writeOnlyMode", void 0);
+        _define_property(this, "matchedCacheIndices", new Set());
+        node_assert(cacheId, 'cacheId is required');
+        let safeCacheId = replaceIllegalPathCharsAndSpace(cacheId);
+        const cacheMaxFilenameLength = globalConfigManager.getEnvConfigValueAsNumber(MIDSCENE_CACHE_MAX_FILENAME_LENGTH) ?? DEFAULT_CACHE_MAX_FILENAME_LENGTH;
+        if (Buffer.byteLength(safeCacheId, 'utf8') > cacheMaxFilenameLength) {
+            const prefix = safeCacheId.slice(0, 32);
+            const hash = generateHashId(void 0, safeCacheId);
+            safeCacheId = `${prefix}-${hash}`;
+        }
+        this.cacheId = safeCacheId;
+        this.cacheFilePath = ifInBrowser || ifInWorker ? void 0 : cacheFilePath || join(getMidsceneRunSubDir('cache'), `${this.cacheId}${cacheFileExt}`);
+        const readOnlyMode = Boolean(options?.readOnly);
+        const writeOnlyMode = Boolean(options?.writeOnly);
+        if (readOnlyMode && writeOnlyMode) throw new Error('TaskCache cannot be both read-only and write-only');
+        this.isCacheResultUsed = writeOnlyMode ? false : isCacheResultUsed;
+        this.readOnlyMode = readOnlyMode;
+        this.writeOnlyMode = writeOnlyMode;
+        let cacheContent;
+        if (this.cacheFilePath && !this.writeOnlyMode) cacheContent = this.loadCacheFromFile();
+        if (!cacheContent) cacheContent = {
+            midsceneVersion: getMidsceneVersion(),
+            cacheId: this.cacheId,
+            caches: []
+        };
+        this.cache = cacheContent;
+        this.cacheOriginalLength = this.isCacheResultUsed ? this.cache.caches.length : 0;
+    }
+}
+export { TaskCache, cacheFileExt, debug };