@aiscene/core 8.1.2 → 9.0.1

package/dist/types/device/index.d.ts

@@ -6,6 +6,110 @@ import type { ElementCacheFeature, Rect, Size } from '../types';
 export interface FileChooserHandler {
     accept(files: string[]): Promise<void>;
 }
+export interface MjpegStreamFrame {
+    /** Raw base64-encoded image bytes WITHOUT a `data:image/...;base64,` prefix. */
+    data: string;
+    contentType?: string;
+}
+export interface MjpegStreamHandle {
+    stop(): void | Promise<void>;
+}
+export interface MjpegStreamOptions {
+    signal?: AbortSignal;
+    onFrame(frame: MjpegStreamFrame): void;
+    onError?(error: unknown): void;
+}
+/** A point in device-pixel coordinates on the screen. */
+export interface PointerPoint {
+    x: number;
+    y: number;
+}
+export interface PointerInputPrimitives {
+    tap(p: PointerPoint, opts?: {
+        duration?: number;
+    }): Promise<void>;
+    doubleClick?(p: PointerPoint): Promise<void>;
+    rightClick?(p: PointerPoint): Promise<void>;
+    hover?(p: PointerPoint): Promise<void>;
+    longPress?(p: PointerPoint, opts?: {
+        duration?: number;
+    }): Promise<void>;
+    dragAndDrop?(from: PointerPoint, to: PointerPoint): Promise<void>;
+}
+export interface TouchInputPrimitives {
+    swipe(start: PointerPoint, end: PointerPoint, opts?: {
+        duration?: number;
+        repeat?: number;
+    }): Promise<void>;
+    pinch?(center: PointerPoint, opts: {
+        startDistance: number;
+        endDistance: number;
+        duration: number;
+    }): Promise<void>;
+}
+export interface KeyboardInputPrimitives {
+    keyboardPress(keyName: string, opts?: {
+        target?: unknown;
+    }): Promise<void>;
+    cursorMove?(direction: 'left' | 'right', times?: number): Promise<void>;
+    typeText(value: string, opts?: {
+        autoDismissKeyboard?: boolean;
+        target?: unknown;
+        replace?: boolean;
+        focusOnly?: boolean;
+    }): Promise<void>;
+    clearInput(target?: unknown): Promise<void>;
+}
+export interface ScrollInputPrimitives {
+    scroll(param: ActionScrollParam): Promise<void>;
+}
+export interface SystemInputPrimitives {
+    backButton?(): Promise<void>;
+    homeButton?(): Promise<void>;
+    recentAppsButton?(): Promise<void>;
+}
+export interface InputPrimitives {
+    pointer?: PointerInputPrimitives;
+    keyboard?: KeyboardInputPrimitives;
+    touch?: TouchInputPrimitives;
+    scroll?: ScrollInputPrimitives;
+    system?: SystemInputPrimitives;
+}
+export interface MobileInputPrimitives extends InputPrimitives {
+    pointer: PointerInputPrimitives & {
+        doubleClick(p: PointerPoint): Promise<void>;
+        longPress(p: PointerPoint, opts?: {
+            duration?: number;
+        }): Promise<void>;
+        dragAndDrop(from: PointerPoint, to: PointerPoint): Promise<void>;
+    };
+    keyboard: KeyboardInputPrimitives;
+    touch: TouchInputPrimitives;
+}
+export interface BrowserInputPrimitives extends InputPrimitives {
+    pointer: PointerInputPrimitives & {
+        doubleClick(p: PointerPoint): Promise<void>;
+        rightClick(p: PointerPoint): Promise<void>;
+        hover(p: PointerPoint): Promise<void>;
+        dragAndDrop(from: PointerPoint, to: PointerPoint): Promise<void>;
+        longPress(p: PointerPoint, opts?: {
+            duration?: number;
+        }): Promise<void>;
+    };
+    keyboard: KeyboardInputPrimitives;
+    scroll: ScrollInputPrimitives;
+    touch: TouchInputPrimitives;
+}
+export interface ComputerInputPrimitives extends InputPrimitives {
+    pointer: PointerInputPrimitives & {
+        doubleClick(p: PointerPoint): Promise<void>;
+        rightClick(p: PointerPoint): Promise<void>;
+        hover(p: PointerPoint): Promise<void>;
+        dragAndDrop(from: PointerPoint, to: PointerPoint): Promise<void>;
+    };
+    keyboard: KeyboardInputPrimitives;
+    scroll: ScrollInputPrimitives;
+}
 export declare abstract class AbstractInterface {
     abstract interfaceType: string;
     abstract screenshotBase64(): Promise<string>;
@@ -28,13 +132,39 @@ export declare abstract class AbstractInterface {
     abstract url?: () => string | Promise<string>;
     abstract evaluateJavaScript?<T = any>(script: string): Promise<T>;
     /**
-     * Get the current time from the device.
-     * Returns the device's current timestamp in milliseconds.
-     * This is useful when the system time and device time are not synchronized.
+     * Get the current device-local time as a formatted string.
+     * Prefer this for user-visible time because timestamps alone do not preserve
+     * the target device's timezone when formatted on the host machine.
      */
-    getTimestamp?(): Promise<number>;
+    getDeviceLocalTimeString?(format?: string): Promise<string>;
     /** URL of native MJPEG stream for real-time screen preview (e.g. WDA MJPEG server) */
     mjpegStreamUrl?: string;
+    /**
+     * Optional in-process MJPEG frame producer. Implementations can push raw
+     * base64 frames here when there is no standalone native MJPEG URL, e.g.
+     * Chromium CDP Page.startScreencast for web previews.
+     */
+    startMjpegStream?(options: MjpegStreamOptions): MjpegStreamHandle | undefined | Promise<MjpegStreamHandle | undefined>;
+    /**
+     * Optional hook used after keyboard-only actions to force a fresh frame on
+     * the active MJPEG stream. Implementations should be a no-op when no stream
+     * is active.
+     */
+    flushPendingVisualUpdate?(): Promise<void>;
+    /**
+     * Optional navigation state probe for browser-like interfaces, used to drive
+     * loading indicators in playground UIs. Returning `undefined` means the
+     * interface does not expose this concept.
+     */
+    navigationState?(): Promise<{
+        isLoading: boolean;
+    }>;
+    /**
+     * Low-level device input surface. Platform implementations expose transport
+     * primitives here; higher-level AI actions and manual pointer dispatch should
+     * adapt to this instead of duplicating platform gesture logic.
+     */
+    inputPrimitives?: InputPrimitives;
 }
 export declare const defineAction: <TSchema extends z.ZodType | undefined = undefined, TRuntime = TSchema extends z.ZodType ? z.infer<TSchema> : undefined, TReturn = any>(config: {
     name: string;
@@ -193,7 +323,7 @@ export declare const actionTapParamSchema: z.ZodObject<{
 export type ActionTapParam = {
     locate: LocateResultElement;
 };
-export declare const defineActionTap: (call: (param: ActionTapParam) => Promise<void>) => DeviceAction<ActionTapParam>;
+export declare const defineActionTap: (tap: PointerInputPrimitives["tap"]) => DeviceAction<ActionTapParam>;
 export declare const actionRightClickParamSchema: z.ZodObject<{
     locate: z.ZodObject<{
         prompt: z.ZodUnion<[z.ZodString, z.ZodIntersection<z.ZodObject<{
@@ -344,7 +474,7 @@ export declare const actionRightClickParamSchema: z.ZodObject<{
 export type ActionRightClickParam = {
     locate: LocateResultElement;
 };
-export declare const defineActionRightClick: (call: (param: ActionRightClickParam) => Promise<void>) => DeviceAction<ActionRightClickParam>;
+export declare const defineActionRightClick: (rightClick: NonNullable<PointerInputPrimitives["rightClick"]>) => DeviceAction<ActionRightClickParam>;
 export declare const actionDoubleClickParamSchema: z.ZodObject<{
     locate: z.ZodObject<{
         prompt: z.ZodUnion<[z.ZodString, z.ZodIntersection<z.ZodObject<{
@@ -495,7 +625,7 @@ export declare const actionDoubleClickParamSchema: z.ZodObject<{
 export type ActionDoubleClickParam = {
     locate: LocateResultElement;
 };
-export declare const defineActionDoubleClick: (call: (param: ActionDoubleClickParam) => Promise<void>) => DeviceAction<ActionDoubleClickParam>;
+export declare const defineActionDoubleClick: (doubleClick: NonNullable<PointerInputPrimitives["doubleClick"]>) => DeviceAction<ActionDoubleClickParam>;
 export declare const actionHoverParamSchema: z.ZodObject<{
     locate: z.ZodObject<{
         prompt: z.ZodUnion<[z.ZodString, z.ZodIntersection<z.ZodObject<{
@@ -646,7 +776,7 @@ export declare const actionHoverParamSchema: z.ZodObject<{
 export type ActionHoverParam = {
     locate: LocateResultElement;
 };
-export declare const defineActionHover: (call: (param: ActionHoverParam) => Promise<void>) => DeviceAction<ActionHoverParam>;
+export declare const defineActionHover: (hover: NonNullable<PointerInputPrimitives["hover"]>) => DeviceAction<ActionHoverParam>;
 export declare const actionInputParamSchema: z.ZodObject<{
     value: z.ZodEffects<z.ZodUnion<[z.ZodString, z.ZodNumber]>, string, string | number>;
     locate: z.ZodOptional<z.ZodObject<{
@@ -759,6 +889,7 @@ export declare const actionInputParamSchema: z.ZodObject<{
         xpath: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodBoolean]>>;
     }, z.ZodTypeAny, "passthrough">>>;
     mode: z.ZodDefault<z.ZodEnum<["replace", "clear", "typeOnly"]>>;
+    autoDismissKeyboard: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
     value: string;
     mode: "replace" | "clear" | "typeOnly";
@@ -799,6 +930,7 @@ export declare const actionInputParamSchema: z.ZodObject<{
         cacheable: z.ZodOptional<z.ZodBoolean>;
         xpath: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodBoolean]>>;
     }, z.ZodTypeAny, "passthrough"> | undefined;
+    autoDismissKeyboard?: boolean | undefined;
 }, {
     value: string | number;
     locate?: z.objectInputType<{
@@ -839,13 +971,15 @@ export declare const actionInputParamSchema: z.ZodObject<{
         xpath: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodBoolean]>>;
     }, z.ZodTypeAny, "passthrough"> | undefined;
     mode?: "replace" | "clear" | "typeOnly" | undefined;
+    autoDismissKeyboard?: boolean | undefined;
 }>;
 export type ActionInputParam = {
     value: string;
     locate?: LocateResultElement;
     mode?: 'replace' | 'clear' | 'typeOnly' | 'append';
+    autoDismissKeyboard?: boolean;
 };
-export declare const defineActionInput: (call: (param: ActionInputParam) => Promise<void>) => DeviceAction<ActionInputParam>;
+export declare const defineActionInput: (keyboard: KeyboardInputPrimitives) => DeviceAction<ActionInputParam>;
 export declare const actionKeyboardPressParamSchema: z.ZodObject<{
     locate: z.ZodOptional<z.ZodObject<{
         prompt: z.ZodUnion<[z.ZodString, z.ZodIntersection<z.ZodObject<{
@@ -1040,7 +1174,7 @@ export type ActionKeyboardPressParam = {
     locate?: LocateResultElement;
     keyName: string;
 };
-export declare const defineActionKeyboardPress: (call: (param: ActionKeyboardPressParam) => Promise<void>) => DeviceAction<ActionKeyboardPressParam>;
+export declare const defineActionKeyboardPress: (keyboardPress: KeyboardInputPrimitives["keyboardPress"]) => DeviceAction<ActionKeyboardPressParam>;
 export declare const actionScrollParamSchema: z.ZodObject<{
     scrollType: z.ZodDefault<z.ZodEnum<["singleAction", "scrollToBottom", "scrollToTop", "scrollToRight", "scrollToLeft"]>>;
     direction: z.ZodDefault<z.ZodEnum<["down", "up", "right", "left"]>>;
@@ -1156,7 +1290,7 @@ export declare const actionScrollParamSchema: z.ZodObject<{
     }, z.ZodTypeAny, "passthrough">>>;
 }, "strip", z.ZodTypeAny, {
     scrollType: "singleAction" | "scrollToBottom" | "scrollToTop" | "scrollToRight" | "scrollToLeft";
-    direction: "down" | "up" | "right" | "left";
+    direction: "left" | "right" | "down" | "up";
     locate?: z.objectOutputType<{
         prompt: z.ZodUnion<[z.ZodString, z.ZodIntersection<z.ZodObject<{
             prompt: z.ZodString;
@@ -1234,10 +1368,10 @@ export declare const actionScrollParamSchema: z.ZodObject<{
         xpath: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodBoolean]>>;
     }, z.ZodTypeAny, "passthrough"> | undefined;
     scrollType?: "singleAction" | "scrollToBottom" | "scrollToTop" | "scrollToRight" | "scrollToLeft" | undefined;
-    direction?: "down" | "up" | "right" | "left" | undefined;
+    direction?: "left" | "right" | "down" | "up" | undefined;
     distance?: number | null | undefined;
 }>;
-export declare const defineActionScroll: (call: (param: ActionScrollParam) => Promise<void>) => DeviceAction<ActionScrollParam>;
+export declare const defineActionScroll: (scroll: ScrollInputPrimitives["scroll"]) => DeviceAction<ActionScrollParam>;
 export declare const actionDragAndDropParamSchema: z.ZodObject<{
     from: z.ZodObject<{
         prompt: z.ZodUnion<[z.ZodString, z.ZodIntersection<z.ZodObject<{
@@ -1532,7 +1666,7 @@ export type ActionDragAndDropParam = {
     from: LocateResultElement;
     to: LocateResultElement;
 };
-export declare const defineActionDragAndDrop: (call: (param: ActionDragAndDropParam) => Promise<void>) => DeviceAction<ActionDragAndDropParam>;
+export declare const defineActionDragAndDrop: (dragAndDrop: NonNullable<PointerInputPrimitives["dragAndDrop"]>) => DeviceAction<ActionDragAndDropParam>;
 export declare const ActionLongPressParamSchema: z.ZodObject<{
     locate: z.ZodObject<{
         prompt: z.ZodUnion<[z.ZodString, z.ZodIntersection<z.ZodObject<{
@@ -1643,7 +1777,7 @@ export declare const ActionLongPressParamSchema: z.ZodObject<{
         cacheable: z.ZodOptional<z.ZodBoolean>;
         xpath: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodBoolean]>>;
     }, z.ZodTypeAny, "passthrough">>;
-    duration: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+    duration: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     locate: {
         prompt: string | ({
@@ -1687,7 +1821,7 @@ export type ActionLongPressParam = {
     locate: LocateResultElement;
     duration?: number;
 };
-export declare const defineActionLongPress: (call: (param: ActionLongPressParam) => Promise<void>) => DeviceAction<ActionLongPressParam>;
+export declare const defineActionLongPress: (longPress: NonNullable<PointerInputPrimitives["longPress"]>) => DeviceAction<ActionLongPressParam>;
 export declare const ActionSwipeParamSchema: z.ZodObject<{
     start: z.ZodOptional<z.ZodObject<{
         prompt: z.ZodUnion<[z.ZodString, z.ZodIntersection<z.ZodObject<{
@@ -1913,7 +2047,7 @@ export declare const ActionSwipeParamSchema: z.ZodObject<{
     repeat: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     duration: number;
-    direction?: "down" | "up" | "right" | "left" | undefined;
+    direction?: "left" | "right" | "down" | "up" | undefined;
     distance?: number | undefined;
     start?: z.objectOutputType<{
         prompt: z.ZodUnion<[z.ZodString, z.ZodIntersection<z.ZodObject<{
@@ -1991,7 +2125,7 @@ export declare const ActionSwipeParamSchema: z.ZodObject<{
     }, z.ZodTypeAny, "passthrough"> | undefined;
     repeat?: number | undefined;
 }, {
-    direction?: "down" | "up" | "right" | "left" | undefined;
+    direction?: "left" | "right" | "down" | "up" | undefined;
     distance?: number | undefined;
     duration?: number | undefined;
     start?: z.objectInputType<{
@@ -2093,7 +2227,10 @@ export declare function normalizeMobileSwipeParam(param: ActionSwipeParam, scree
     duration: number;
     repeatCount: number;
 };
-export declare const defineActionSwipe: (call: (param: ActionSwipeParam) => Promise<void>) => DeviceAction<ActionSwipeParam>;
+export declare const defineActionSwipe: (config: {
+    swipe: TouchInputPrimitives["swipe"];
+    size(): Promise<Size>;
+}) => DeviceAction<ActionSwipeParam>;
 export declare const actionClearInputParamSchema: z.ZodObject<{
     locate: z.ZodOptional<z.ZodObject<{
         prompt: z.ZodUnion<[z.ZodString, z.ZodIntersection<z.ZodObject<{
@@ -2284,22 +2421,25 @@ export declare const actionClearInputParamSchema: z.ZodObject<{
 export type ActionClearInputParam = {
     locate?: LocateResultElement;
 };
-export declare const defineActionClearInput: (call: (param: ActionClearInputParam) => Promise<void>) => DeviceAction<ActionClearInputParam>;
+export declare const defineActionClearInput: (clearInput: KeyboardInputPrimitives["clearInput"]) => DeviceAction<ActionClearInputParam>;
 export declare const actionCursorMoveParamSchema: z.ZodObject<{
     direction: z.ZodEnum<["left", "right"]>;
     times: z.ZodDefault<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
-    direction: "right" | "left";
+    direction: "left" | "right";
     times: number;
 }, {
-    direction: "right" | "left";
+    direction: "left" | "right";
     times?: number | undefined;
 }>;
 export type ActionCursorMoveParam = {
     direction: 'left' | 'right';
     times?: number;
 };
-export declare const defineActionCursorMove: (call: (param: ActionCursorMoveParam) => Promise<void>) => DeviceAction<ActionCursorMoveParam>;
+export declare const defineActionCursorMove: (config: {
+    keyboard: Pick<KeyboardInputPrimitives, "keyboardPress" | "cursorMove">;
+    sleep?(timeMs: number): Promise<void>;
+}) => DeviceAction<ActionCursorMoveParam>;
 export declare const ActionPinchParamSchema: z.ZodObject<{
     locate: z.ZodOptional<z.ZodObject<{
         prompt: z.ZodUnion<[z.ZodString, z.ZodIntersection<z.ZodObject<{
@@ -2502,7 +2642,10 @@ export type ActionPinchParam = {
     distance?: number;
     duration?: number;
 };
-export declare const defineActionPinch: (call: (param: ActionPinchParam) => Promise<void>) => DeviceAction<ActionPinchParam>;
+export declare const defineActionPinch: (config: {
+    pinch: TouchInputPrimitives["pinch"];
+    size(): Promise<Size>;
+}) => DeviceAction<ActionPinchParam> | undefined;
 export declare function normalizePinchParam(param: ActionPinchParam, screenSize: {
     width: number;
     height: number;
@@ -2513,6 +2656,34 @@ export declare function normalizePinchParam(param: ActionPinchParam, screenSize:
     endDistance: number;
     duration: number;
 };
+export interface MobileInputActionContext {
+    input: MobileInputPrimitives;
+    size(): Promise<Size>;
+    sleep?(timeMs: number): Promise<void>;
+    getDefaultAutoDismissKeyboard?(): boolean | undefined;
+    systemActions?: SystemInputActionOptions;
+}
+export interface SystemInputActionConfig {
+    name: string;
+    description: string;
+    interfaceAlias?: string;
+    delayBeforeRunner?: number;
+    delayAfterRunner?: number;
+}
+export interface SystemInputActionOptions {
+    backButton?: SystemInputActionConfig;
+    homeButton?: SystemInputActionConfig;
+    recentAppsButton?: SystemInputActionConfig;
+}
+export interface InputPrimitiveActionOptions {
+    size?: () => Promise<Size>;
+    sleep?: (timeMs: number) => Promise<void>;
+    includeSwipe?: boolean;
+    includePinch?: boolean;
+    systemActions?: SystemInputActionOptions;
+}
+export declare function defineActionsFromInputPrimitives(input: InputPrimitives, options?: InputPrimitiveActionOptions): DeviceAction<any>[];
+export declare function createDefaultMobileActions(context: MobileInputActionContext): DeviceAction<any>[];
 export declare const ActionSleepParamSchema: z.ZodObject<{
     timeMs: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
 }, "strip", z.ZodTypeAny, {

package/dist/types/dump/screenshot-store.d.ts

@@ -36,12 +36,12 @@ export declare class ScreenshotStore {
         mode: 'inline' | 'directory';
         reportPath: string;
         screenshotsDir?: string;
-        writeInlineImage?: (id: string, base64: string) => void;
+        writeInlineImage?: (id: string, base64: string) => void | Promise<void>;
         alsoWriteFileCopy?: boolean;
         /** @deprecated Use alsoWriteFileCopy instead. */
         ensureFileCopy?: boolean;
     });
-    persist(screenshot: ScreenshotItem): ScreenshotRef;
+    persist(screenshot: ScreenshotItem): Promise<ScreenshotRef>;
     private persistToSharedFileIfNeeded;
     loadBase64(refInput: unknown): string;
     cleanup(): void;

package/dist/types/index.d.ts

@@ -5,8 +5,7 @@ import { getVersion } from './utils';
 export { plan, AiLocateElement, runConnectivityTest, getMidsceneLocationSchema, PointSchema, SizeSchema, RectSchema, TMultimodalPromptSchema, TUserPromptSchema, type TMultimodalPrompt, type TUserPrompt, type ConnectivityCheckResultItem, type ConnectivityTestConfig, type ConnectivityTestResult, } from './ai-model/index';
 export { MIDSCENE_MODEL_NAME, type CreateOpenAIClientFn, } from '@aiscene/shared/env';
 export type * from './types';
-export type { DeviceAction, } from './types';
-export { ServiceError, ExecutionDump, ReportActionDump, GroupedActionDump, type IExecutionDump, type IReportActionDump, type IGroupedActionDump, type ReportMeta, type GroupMeta, } from './types';
+export { ServiceError, ActionAssertionError, isActionAssertionError, ExecutionDump, ReportActionDump, GroupedActionDump, type IExecutionDump, type IReportActionDump, type IGroupedActionDump, type ReportMeta, type GroupMeta, } from './types';
 export { z };
 export default Service;
 export { TaskRunner, Service, getVersion };

package/dist/types/report-generator.d.ts

@@ -49,12 +49,14 @@ export declare class ReportGenerator implements IReportGenerator {
         screenshotMode: 'inline' | 'directory';
         persistExecutionDump?: boolean;
         autoPrint?: boolean;
+        reuseExistingReport?: boolean;
     });
     static create(reportFileName: string, opts: {
         generateReport?: boolean;
         persistExecutionDump?: boolean;
         outputFormat?: 'single-html' | 'html-and-external-assets';
         autoPrintReportMsg?: boolean;
+        reuseExistingReport?: boolean;
     }): IReportGenerator;
     onExecutionUpdate(execution: ExecutionDump, reportMeta: ReportMeta, attributes?: ReportAttributes): void;
     flush(): Promise<void>;
@@ -73,6 +75,11 @@ export declare class ReportGenerator implements IReportGenerator {
      * Append-only inline mode: write new screenshots and a dump tag on every call.
      * The frontend deduplicates executions with the same id/name (keeps last).
      * Duplicate dump JSON is acceptable; only screenshots are deduplicated.
+     *
+     * All writes go through `fs/promises` so they run on libuv's thread pool
+     * rather than blocking the Node event loop. A long agent run previously
+     * appended multi-MB dumps (screenshots + serialized tasks) per progress
+     * tick on the main thread, starving IPC and UI for >10s per stall.
      */
     private writeInlineExecution;
     private writeDirectoryExecution;

package/dist/types/types.d.ts

@@ -15,7 +15,15 @@ export type AIUsageInfo = Record<string, any> & {
     time_cost: number | undefined;
     model_name: string | undefined;
     model_description: string | undefined;
+    /**
+     * Semantic intent of the model call, such as default, planning, or insight.
+     */
     intent: string | undefined;
+    /**
+     * Config slot where the model config was resolved from. For example, a
+     * planning call may use the default slot when no planning model is configured.
+     */
+    slot: string | undefined;
     request_id: string | undefined;
 };
 export type { LocateResultElement };
@@ -155,6 +163,41 @@ export declare class ServiceError extends Error {
     dump: ServiceDump;
     constructor(message: string, dump: ServiceDump);
 }
+/**
+ * Thrown by a DeviceAction whose semantics are "assert / verify".
+ *
+ * The task executor in [`tasks.ts`](packages/core/src/agent/tasks.ts) treats
+ * regular action errors as soft failures and asks the planner to retry — that
+ * is the right behavior for transient issues like a missed tap, but it is the
+ * wrong behavior for actions like `ExpectToast` whose entire purpose is to
+ * guarantee a postcondition. When an `ActionAssertionError` bubbles out of
+ * `action.call()`, the executor MUST stop the current `aiAct` run and surface
+ * the error to the caller without re-planning.
+ *
+ * Use this class (or a subclass) instead of a plain `Error` from any action
+ * whose contract is verification rather than mutation.
+ */
+export declare class ActionAssertionError extends Error {
+    /** Name of the action that raised the assertion (e.g. "ExpectToast"). */
+    readonly actionName?: string;
+    /**
+     * Optional structured detail — surfaced to the test report so users can see
+     * what was expected vs. observed without parsing the message string.
+     */
+    readonly detail?: Record<string, unknown>;
+    constructor(message: string, options?: {
+        actionName?: string;
+        detail?: Record<string, unknown>;
+    });
+}
+/**
+ * Type guard usable across packages without instanceof issues.
+ *
+ * Walks the `.cause` chain (depth-limited) so that wrappers like
+ * `TaskExecutionError` — which the task runner uses to re-throw the failure of
+ * an individual action — still report as assertion errors.
+ */
+export declare function isActionAssertionError(err: unknown): err is ActionAssertionError;
 export interface LiteUISection {
     name: string;
     description: string;
@@ -530,6 +573,7 @@ export interface DeviceAction<TParam = any, TReturn = any> {
     interfaceAlias?: string;
     paramSchema?: z.ZodType<TParam>;
     call: (param: TParam, context: ExecutorContext) => Promise<TReturn> | TReturn;
+    delayBeforeRunner?: number;
     delayAfterRunner?: number;
     /**
      * An example param object for this action.
@@ -595,6 +639,7 @@ export interface AgentOpt {
     aiActContext?: string;
     aiActionContext?: string;
     reportFileName?: string;
+    reportAttributes?: ReportAttributes;
     modelConfig?: TModelConfig;
     cache?: Cache;
     /**
@@ -610,11 +655,12 @@ export interface AgentOpt {
      */
     waitAfterAction?: number;
     /**
-     * When set to true, Midscene will use the target device's time (Android/iOS)
-     * instead of the system time. Useful when the device time differs from the
-     * host machine. Default: false
+     * When set to true, Midscene will use the target device's formatted local
+     * time instead of the runtime system time. The target interface must implement
+     * getDeviceLocalTimeString to provide device-local wall-clock time.
+     * Default: false
      */
-    useDeviceTimestamp?: boolean;
+    useDeviceTime?: boolean;
     /**
      * Custom screenshot shrink factor to reduce AI token usage.
      * When set, the screenshot will be scaled down by this factor from the physical resolution.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@aiscene/core",
   "description": "Automate browser actions, extract data, and perform assertions using AI. It offers JavaScript SDK, Chrome extension, and support for scripting in YAML. See https://midscenejs.com/ for details.",
-  "version": "8.1.2",
+  "version": "9.0.1",
   "repository": "https://github.com/web-infra-dev/midscene",
   "homepage": "https://midscenejs.com/",
   "main": "./dist/lib/index.js",
@@ -78,7 +78,7 @@
     "test:parse-action": "npm run test:ai -- tests/ai/parse-action.test.ts"
   },
   "dependencies": {
-    "@aiscene/shared": "^8.0.2",
+    "@aiscene/shared": "workspace:*",
     "@ui-tars/action-parser": "1.2.3",
     "dayjs": "^1.11.11",
     "dotenv": "^16.4.5",