@midscene/core 1.14.0 → 1.15.0

package/dist/es/agent/action-readiness.mjs

@@ -0,0 +1,72 @@
+import { getErrorMessage } from "@midscene/shared/agent-tools/error-formatter";
+import { getDebug } from "@midscene/shared/logger";
+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 warn = getDebug('agent:action-readiness', {
+    console: true
+});
+const errorCode = 'ACTION_READINESS_FAILED';
+class ActionReadinessError extends Error {
+    constructor(phase, actionName, cause){
+        super(`waitForActionReady ${phase} failed for ${actionName}: ${getErrorMessage(cause)}`, {
+            cause
+        }), _define_property(this, "code", errorCode);
+        this.name = 'ActionReadinessError';
+    }
+}
+function isActionReadinessError(error) {
+    const seen = new Set();
+    while(error && 'object' == typeof error && !seen.has(error)){
+        seen.add(error);
+        const value = error;
+        if (value.code === errorCode) return true;
+        error = value.cause;
+    }
+    return false;
+}
+class ActionReadiness {
+    async wait(action, signal) {
+        signal?.throwIfAborted();
+        let onAbort;
+        const timer = setTimeout(()=>{
+            warn(`waitForActionReady for ${action.name} (${action.id}) is still pending after 5000ms; continuing to wait.`);
+        }, 5000);
+        try {
+            await new Promise((resolve, reject)=>{
+                if (signal) {
+                    onAbort = ()=>reject(signal.reason);
+                    signal.addEventListener('abort', onAbort, {
+                        once: true
+                    });
+                }
+                Promise.resolve(this.callback({
+                    action,
+                    signal
+                })).then(resolve, reject);
+            });
+            signal?.throwIfAborted();
+        } catch (cause) {
+            signal?.throwIfAborted();
+            throw new ActionReadinessError('wait', action.name, cause);
+        } finally{
+            clearTimeout(timer);
+            if (signal && onAbort) signal.removeEventListener('abort', onAbort);
+        }
+    }
+    constructor(callback){
+        _define_property(this, "callback", void 0);
+        this.callback = callback;
+        if ('function' != typeof callback) throw new Error('waitForActionReady must be a function');
+    }
+}
+export { ActionReadiness, ActionReadinessError, isActionReadinessError };
+
+//# sourceMappingURL=action-readiness.mjs.map

package/dist/es/agent/action-readiness.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent/action-readiness.mjs","sources":["../../../src/agent/action-readiness.ts"],"sourcesContent":["import type { ActionReadyContext, WaitForActionReady } from '@/types';\nimport { getErrorMessage } from '@midscene/shared/agent-tools/error-formatter';\nimport { getDebug } from '@midscene/shared/logger';\n\nconst warn = getDebug('agent:action-readiness', { console: true });\nconst errorCode = 'ACTION_READINESS_FAILED';\n\nexport class ActionReadinessError extends Error {\n  readonly code = errorCode;\n\n  constructor(phase: string, actionName: string, cause: unknown) {\n    super(\n      `waitForActionReady ${phase} failed for ${actionName}: ${getErrorMessage(cause)}`,\n      { cause },\n    );\n    this.name = 'ActionReadinessError';\n  }\n}\n\n/** Also recognizes the bounded cause retained by TaskExecutionError. */\nexport function isActionReadinessError(error: unknown): boolean {\n  const seen = new Set<unknown>();\n  while (error && typeof error === 'object' && !seen.has(error)) {\n    seen.add(error);\n    const value = error as { code?: unknown; cause?: unknown };\n    if (value.code === errorCode) return true;\n    error = value.cause;\n  }\n  return false;\n}\n\n/** Await application readiness after a successful action; slow waits only warn. */\nexport class ActionReadiness {\n  constructor(private readonly callback: WaitForActionReady) {\n    if (typeof callback !== 'function') {\n      throw new Error('waitForActionReady must be a function');\n    }\n  }\n\n  async wait(\n    action: ActionReadyContext['action'],\n    signal?: AbortSignal,\n  ): Promise<void> {\n    signal?.throwIfAborted();\n    let onAbort: (() => void) | undefined;\n    const timer = setTimeout(() => {\n      warn(\n        `waitForActionReady for ${action.name} (${action.id}) is still pending after 5000ms; continuing to wait.`,\n      );\n    }, 5000);\n    try {\n      await new Promise<void>((resolve, reject) => {\n        // Listen before invoking user code, including callbacks that abort\n        // synchronously or never settle. Both late outcomes stay handled.\n        if (signal) {\n          onAbort = () => reject(signal.reason);\n          signal.addEventListener('abort', onAbort, { once: true });\n        }\n        Promise.resolve(this.callback({ action, signal })).then(\n          resolve,\n          reject,\n        );\n      });\n      signal?.throwIfAborted();\n    } catch (cause) {\n      // Preserve the cancellation reason instead of reporting a readiness failure.\n      signal?.throwIfAborted();\n      throw new ActionReadinessError('wait', action.name, cause);\n    } finally {\n      clearTimeout(timer);\n      if (signal && onAbort) signal.removeEventListener('abort', onAbort);\n    }\n  }\n}\n"],"names":["warn","getDebug","errorCode","ActionReadinessError","Error","phase","actionName","cause","getErrorMessage","isActionReadinessError","error","seen","Set","value","ActionReadiness","action","signal","onAbort","timer","setTimeout","Promise","resolve","reject","clearTimeout","callback"],"mappings":";;;;;;;;;;;;AAIA,MAAMA,OAAOC,SAAS,0BAA0B;IAAE,SAAS;AAAK;AAChE,MAAMC,YAAY;AAEX,MAAMC,6BAA6BC;IAGxC,YAAYC,KAAa,EAAEC,UAAkB,EAAEC,KAAc,CAAE;QAC7D,KAAK,CACH,CAAC,mBAAmB,EAAEF,MAAM,YAAY,EAAEC,WAAW,EAAE,EAAEE,gBAAgBD,QAAQ,EACjF;YAAEA;QAAM,IALZ,uBAAS,QAAOL;QAOd,IAAI,CAAC,IAAI,GAAG;IACd;AACF;AAGO,SAASO,uBAAuBC,KAAc;IACnD,MAAMC,OAAO,IAAIC;IACjB,MAAOF,SAAS,AAAiB,YAAjB,OAAOA,SAAsB,CAACC,KAAK,GAAG,CAACD,OAAQ;QAC7DC,KAAK,GAAG,CAACD;QACT,MAAMG,QAAQH;QACd,IAAIG,MAAM,IAAI,KAAKX,WAAW,OAAO;QACrCQ,QAAQG,MAAM,KAAK;IACrB;IACA,OAAO;AACT;AAGO,MAAMC;IAOX,MAAM,KACJC,MAAoC,EACpCC,MAAoB,EACL;QACfA,QAAQ;QACR,IAAIC;QACJ,MAAMC,QAAQC,WAAW;YACvBnB,KACE,CAAC,uBAAuB,EAAEe,OAAO,IAAI,CAAC,EAAE,EAAEA,OAAO,EAAE,CAAC,oDAAoD,CAAC;QAE7G,GAAG;QACH,IAAI;YACF,MAAM,IAAIK,QAAc,CAACC,SAASC;gBAGhC,IAAIN,QAAQ;oBACVC,UAAU,IAAMK,OAAON,OAAO,MAAM;oBACpCA,OAAO,gBAAgB,CAAC,SAASC,SAAS;wBAAE,MAAM;oBAAK;gBACzD;gBACAG,QAAQ,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC;oBAAEL;oBAAQC;gBAAO,IAAI,IAAI,CACrDK,SACAC;YAEJ;YACAN,QAAQ;QACV,EAAE,OAAOT,OAAO;YAEdS,QAAQ;YACR,MAAM,IAAIb,qBAAqB,QAAQY,OAAO,IAAI,EAAER;QACtD,SAAU;YACRgB,aAAaL;YACb,IAAIF,UAAUC,SAASD,OAAO,mBAAmB,CAAC,SAASC;QAC7D;IACF;IAvCA,YAA6BO,QAA4B,CAAE;;aAA9BA,QAAQ,GAARA;QAC3B,IAAI,AAAoB,cAApB,OAAOA,UACT,MAAM,IAAIpB,MAAM;IAEpB;AAoCF"}

package/dist/es/agent/agent.mjs

@@ -9,7 +9,7 @@ import { waitForResourceIdle } from "../test-runner/engine/resource-operations.m
 import { buildAgentTestRunReportDump } from "../test-runner/reporting/agent-report.mjs";
 import { executionRecordsToReportInput } from "../test-runner/reporting/execution-record.mjs";
 import { ExecutionDump, ReportActionDump } from "../types.mjs";
-import { YamlExecutionOwnershipError, enterYamlAction, enterYamlExecution, runInYamlExecutionContext } from "../yaml/execution-session.mjs";
+import { YamlExecutionOwnershipError, currentYamlSignal, enterYamlAction, enterYamlExecution, runInYamlExecutionContext } from "../yaml/execution-session.mjs";
 import { ReportGenerator, assertReportGenerationOptions } from "../report-generator.mjs";
 import { getVersion, processCacheConfig, reportHTMLContent } from "../utils.mjs";
 import { ScriptPlayer, buildDetailedLocateParam, buildDetailedLocateParamAndRestParams, parseYamlScript } from "../yaml/index.mjs";
@@ -22,6 +22,7 @@ import { MIDSCENE_REPLANNING_CYCLE_LIMIT, ModelConfigManager, globalConfigManage
 import { getDebug } from "@midscene/shared/logger";
 import { assert, ifInBrowser, uuid } from "@midscene/shared/utils";
 import { defineActionRegisterFileChooserAccept, defineActionSleep } from "../device/index.mjs";
+import { ActionReadiness, isActionReadinessError } from "./action-readiness.mjs";
 import { validateAgentCacheInput } from "./cache-config.mjs";
 import { FileChooserAccepter } from "./file-chooser.mjs";
 import { Insight } from "./insight.mjs";
@@ -352,7 +353,7 @@ class Agent {
     wrapActionInActionSpace(name) {
         return async (param)=>await this.callActionInActionSpace(name, param);
     }
-    async callActionInActionSpace(type, opt) {
+    async callActionInActionSpace(type, opt, abortSignal) {
         debug('callActionInActionSpace', type, ',', opt);
         const clonedActionParam = opt && 'object' == typeof opt && !Array.isArray(opt) ? {
             ...opt
@@ -369,7 +370,9 @@ class Agent {
         const title = taskTitleStr(type, locateParamStr(opt?.locate || {}));
         const defaultModel = this.resolveModelRuntime('default');
         const planningModel = this.resolveModelRuntime('planning');
-        const { output } = await this.taskExecutor.runPlans(title, plans, planningModel, defaultModel);
+        const { output } = await this.taskExecutor.runPlans(title, plans, planningModel, defaultModel, {
+            abortSignal: abortSignal ?? currentYamlSignal(this)
+        });
         return output;
     }
     async aiTap(locatePrompt, opt) {
@@ -558,7 +561,7 @@ class Agent {
                     });
                     return;
                 } catch (error) {
-                    if (error instanceof YamlExecutionOwnershipError) throw error;
+                    if (error instanceof YamlExecutionOwnershipError || isActionReadinessError(error)) throw error;
                     abortSignal?.throwIfAborted();
                     cachedYamlFailed = true;
                     warn(`cached aiAct plan failed, will replan and disable the stale cache: ${error instanceof Error ? error.message : String(error)}`);
@@ -686,15 +689,17 @@ class Agent {
     async ai(...args) {
         return this.aiAct(...args);
     }
-    async runYaml(yamlScriptContent) {
+    async runYaml(yamlScriptContent, options) {
         if (this.destroyed) throw new Error('Cannot run YAML using a destroyed Agent.');
         const script = parseYamlScript(yamlScriptContent, 'yaml');
         const player = new ScriptPlayer(script, async ()=>({
                 agent: this,
                 freeFn: []
-            }));
+            }), void 0, void 0, options?.abortSignal);
         await player.run();
         if ('error' === player.status) {
+            const readinessFailure = player.taskStatusList.find((task)=>isActionReadinessError(task.error));
+            if (readinessFailure) throw readinessFailure.error;
             const errors = player.taskStatusList.filter((task)=>'error' === task.status).map((task)=>`task - ${task.name}: ${task.error?.message}`).join('\n');
             throw new Error(`Error(s) occurred in running yaml script:\n${errors}`);
         }
@@ -938,6 +943,7 @@ class Agent {
         _define_property(this, "dumpUpdateListeners", []);
         _define_property(this, "progressBus", new AgentProgressBus());
         _define_property(this, "destroyed", false);
+        _define_property(this, "actionReadiness", void 0);
         _define_property(this, "modelConfigManager", void 0);
         _define_property(this, "frozenUIContext", void 0);
         _define_property(this, "activeObserver", null);
@@ -957,6 +963,7 @@ class Agent {
             groupDescription: ''
         }, opts || {});
         assertReportGenerationOptions(this.opts);
+        if (void 0 !== this.opts.waitForActionReady) this.actionReadiness = new ActionReadiness(this.opts.waitForActionReady);
         if (void 0 !== this.opts.aiContexts && ('object' != typeof this.opts.aiContexts || null === this.opts.aiContexts || Array.isArray(this.opts.aiContexts))) throw new TypeError('opts.aiContexts must be a plain object');
         for (const [key, value] of Object.entries(this.opts.aiContexts ?? {})){
             if (!isAgentAIContextKey(key)) throw new TypeError(`Unknown Agent context key: ${key}`);
@@ -1002,6 +1009,7 @@ class Agent {
             onTaskStart: this.callbackOnTaskStartTip.bind(this),
             replanningCycleLimit: this.opts.replanningCycleLimit,
             waitAfterAction: this.opts.waitAfterAction,
+            actionReadiness: this.actionReadiness,
             useDeviceTime: this.opts.useDeviceTime,
             actionSpace: this.fullActionSpace,
             hooks: {