@godscene/core 1.7.11

package/dist/es/ai-model/service-caller/request-timeout.mjs

@@ -0,0 +1,47 @@
+const DEFAULT_AI_CALL_TIMEOUT_MS = 180000;
+const AI_CALL_HARD_TIMEOUT_CODE = 'AI_CALL_HARD_TIMEOUT';
+function resolveEffectiveTimeoutMs(modelConfig) {
+    const { timeout } = modelConfig;
+    if ('number' != typeof timeout) return DEFAULT_AI_CALL_TIMEOUT_MS;
+    if (timeout <= 0) return null;
+    return timeout;
+}
+function isHardTimeoutError(err) {
+    if (!err || 'object' != typeof err) return false;
+    const code = err.code;
+    if (code === AI_CALL_HARD_TIMEOUT_CODE) return true;
+    const cause = err.cause;
+    if (cause && 'object' == typeof cause && cause.code === AI_CALL_HARD_TIMEOUT_CODE) return true;
+    return false;
+}
+function buildRequestAbortSignal(timeoutMs, userSignal) {
+    const controller = new AbortController();
+    if (userSignal?.aborted) {
+        controller.abort(userSignal.reason);
+        return {
+            signal: controller.signal,
+            cleanup: ()=>{}
+        };
+    }
+    let timer;
+    if (null !== timeoutMs) {
+        timer = setTimeout(()=>{
+            const err = new Error(`AI call hard timeout after ${timeoutMs}ms (full request time exceeded)`);
+            err.code = AI_CALL_HARD_TIMEOUT_CODE;
+            controller.abort(err);
+        }, timeoutMs);
+        if ('function' == typeof timer.unref) timer.unref();
+    }
+    const onUserAbort = userSignal ? ()=>controller.abort(userSignal.reason) : void 0;
+    if (userSignal && onUserAbort) userSignal.addEventListener('abort', onUserAbort, {
+        once: true
+    });
+    return {
+        signal: controller.signal,
+        cleanup: ()=>{
+            if (timer) clearTimeout(timer);
+            if (userSignal && onUserAbort) userSignal.removeEventListener('abort', onUserAbort);
+        }
+    };
+}
+export { AI_CALL_HARD_TIMEOUT_CODE, DEFAULT_AI_CALL_TIMEOUT_MS, buildRequestAbortSignal, isHardTimeoutError, resolveEffectiveTimeoutMs };

package/dist/es/ai-model/ui-tars-planning.mjs

@@ -0,0 +1,247 @@
+import { getDebug } from "@godscene/shared/logger";
+import { transformHotkeyInput } from "@godscene/shared/us-keyboard-layout";
+import { assert } from "@godscene/shared/utils";
+import { actionParser } from "@ui-tars/action-parser";
+import { getSummary, getUiTarsPlanningPrompt } from "./prompt/ui-tars-planning.mjs";
+import { AIResponseParseError, callAIWithStringResponse } from "./service-caller/index.mjs";
+const debug = getDebug('ui-tars-planning');
+const warnLog = getDebug('ui-tars-planning', {
+    console: true
+});
+const bboxSize = 10;
+const pointToBbox = (point, width, height)=>[
+        Math.round(Math.max(point.x - bboxSize / 2, 0)),
+        Math.round(Math.max(point.y - bboxSize / 2, 0)),
+        Math.round(Math.min(point.x + bboxSize / 2, width)),
+        Math.round(Math.min(point.y + bboxSize / 2, height))
+    ];
+async function uiTarsPlanning(userInstruction, options) {
+    const { conversationHistory, context, modelConfig, actionContext } = options;
+    const { uiTarsModelVersion } = modelConfig;
+    let instruction = userInstruction;
+    if (actionContext) instruction = `<high_priority_knowledge>${actionContext}</high_priority_knowledge>\n<user_instruction>${userInstruction}</user_instruction>`;
+    const systemPrompt = getUiTarsPlanningPrompt() + instruction;
+    const screenshotBase64 = context.screenshot.base64;
+    conversationHistory.append({
+        role: 'user',
+        content: [
+            {
+                type: 'image_url',
+                image_url: {
+                    url: screenshotBase64
+                }
+            }
+        ]
+    });
+    const res = await callAIWithStringResponse([
+        {
+            role: 'user',
+            content: systemPrompt
+        },
+        ...conversationHistory.snapshot()
+    ], modelConfig, {
+        abortSignal: options.abortSignal
+    });
+    let convertedText;
+    let parsed;
+    try {
+        convertedText = convertBboxToCoordinates(res.content);
+        const { shotSize } = context;
+        const parseResult = actionParser({
+            prediction: convertedText,
+            factor: [
+                1000,
+                1000
+            ],
+            screenContext: {
+                width: shotSize.width,
+                height: shotSize.height
+            },
+            modelVer: uiTarsModelVersion
+        });
+        parsed = parseResult.parsed;
+    } catch (parseError) {
+        const errorMessage = parseError instanceof Error ? parseError.message : String(parseError);
+        throw new AIResponseParseError(`Parse error: ${errorMessage}`, JSON.stringify(res.content, void 0, 2), res.usage);
+    }
+    const { shotSize } = context;
+    debug('ui-tars modelVer', uiTarsModelVersion, ', parsed', JSON.stringify(parsed));
+    const transformActions = [];
+    const unhandledActions = [];
+    let shouldContinue = true;
+    parsed.forEach((action)=>{
+        const actionType = (action.action_type || '').toLowerCase();
+        if ('click' === actionType) {
+            assert(action.action_inputs.start_box, 'start_box is required');
+            const point = getPoint(action.action_inputs.start_box, shotSize);
+            const locate = {
+                prompt: action.thought || '',
+                bbox: pointToBbox({
+                    x: point[0],
+                    y: point[1]
+                }, shotSize.width, shotSize.height)
+            };
+            transformActions.push({
+                type: 'Tap',
+                param: {
+                    locate: locate
+                }
+            });
+        } else if ('left_double' === actionType) {
+            assert(action.action_inputs.start_box, 'start_box is required');
+            const point = getPoint(action.action_inputs.start_box, shotSize);
+            const locate = {
+                prompt: action.thought || '',
+                bbox: pointToBbox({
+                    x: point[0],
+                    y: point[1]
+                }, shotSize.width, shotSize.height)
+            };
+            transformActions.push({
+                type: 'DoubleClick',
+                param: {
+                    locate: locate
+                },
+                thought: action.thought || ''
+            });
+        } else if ('right_single' === actionType) {
+            assert(action.action_inputs.start_box, 'start_box is required');
+            const point = getPoint(action.action_inputs.start_box, shotSize);
+            const locate = {
+                prompt: action.thought || '',
+                bbox: pointToBbox({
+                    x: point[0],
+                    y: point[1]
+                }, shotSize.width, shotSize.height)
+            };
+            transformActions.push({
+                type: 'RightClick',
+                param: {
+                    locate: locate
+                },
+                thought: action.thought || ''
+            });
+        } else if ('drag' === actionType) {
+            assert(action.action_inputs.start_box, 'start_box is required');
+            assert(action.action_inputs.end_box, 'end_box is required');
+            const startPoint = getPoint(action.action_inputs.start_box, shotSize);
+            const endPoint = getPoint(action.action_inputs.end_box, shotSize);
+            transformActions.push({
+                type: 'DragAndDrop',
+                param: {
+                    from: {
+                        prompt: action.thought || '',
+                        bbox: pointToBbox({
+                            x: startPoint[0],
+                            y: startPoint[1]
+                        }, shotSize.width, shotSize.height)
+                    },
+                    to: {
+                        prompt: action.thought || '',
+                        bbox: pointToBbox({
+                            x: endPoint[0],
+                            y: endPoint[1]
+                        }, shotSize.width, shotSize.height)
+                    }
+                },
+                thought: action.thought || ''
+            });
+        } else if ('type' === actionType) transformActions.push({
+            type: 'Input',
+            param: {
+                value: action.action_inputs.content
+            },
+            thought: action.thought || ''
+        });
+        else if ('scroll' === actionType) transformActions.push({
+            type: 'Scroll',
+            param: {
+                direction: action.action_inputs.direction
+            },
+            thought: action.thought || ''
+        });
+        else if ('finished' === actionType) {
+            shouldContinue = false;
+            transformActions.push({
+                type: 'Finished',
+                param: {},
+                thought: action.thought || ''
+            });
+        } else if ('hotkey' === actionType) if (action.action_inputs.key) {
+            const keys = transformHotkeyInput(action.action_inputs.key);
+            transformActions.push({
+                type: 'KeyboardPress',
+                param: {
+                    keyName: keys.join('+')
+                },
+                thought: action.thought || ''
+            });
+        } else warnLog('No key found in action: hotkey. Will not perform action.');
+        else if ('wait' === actionType) transformActions.push({
+            type: 'Sleep',
+            param: {
+                timeMs: 1000
+            },
+            thought: action.thought || ''
+        });
+        else if (actionType) {
+            unhandledActions.push({
+                type: actionType,
+                thought: action.thought || ''
+            });
+            debug('Unhandled action type:', actionType, 'thought:', action.thought);
+        }
+    });
+    if (0 === transformActions.length) {
+        const errorDetails = [];
+        if (0 === parsed.length) {
+            errorDetails.push('Action parser returned no actions');
+            if (res.content.includes('Thought:') && !res.content.includes('Action:')) errorDetails.push('Response contains "Thought:" but missing "Action:" line');
+            else errorDetails.push('Response may be malformed or empty');
+        }
+        if (unhandledActions.length > 0) {
+            const types = unhandledActions.map((a)=>a.type).join(', ');
+            errorDetails.push(`Unhandled action types: ${types}`);
+        }
+        const errorMessage = [
+            'No actions found in UI-TARS response.',
+            ...errorDetails
+        ].join('\n');
+        throw new AIResponseParseError(errorMessage, JSON.stringify(res.content, void 0, 2), res.usage);
+    }
+    debug('transformActions', JSON.stringify(transformActions, null, 2));
+    const log = getSummary(res.content);
+    conversationHistory.append({
+        role: 'assistant',
+        content: log
+    });
+    return {
+        actions: transformActions,
+        log,
+        usage: res.usage,
+        rawResponse: JSON.stringify(res.content, void 0, 2),
+        shouldContinuePlanning: shouldContinue
+    };
+}
+function convertBboxToCoordinates(text) {
+    const pattern = /<bbox>(\d+)\s+(\d+)\s+(\d+)\s+(\d+)<\/bbox>/g;
+    function replaceMatch(match, x1, y1, x2, y2) {
+        const x1Num = Number.parseInt(x1, 10);
+        const y1Num = Number.parseInt(y1, 10);
+        const x2Num = Number.parseInt(x2, 10);
+        const y2Num = Number.parseInt(y2, 10);
+        const x = Math.floor((x1Num + x2Num) / 2);
+        const y = Math.floor((y1Num + y2Num) / 2);
+        return `(${x},${y})`;
+    }
+    const cleanedText = text.replace(/\[EOS\]/g, '');
+    return cleanedText.replace(pattern, replaceMatch).trim();
+}
+function getPoint(startBox, size) {
+    const [x, y] = JSON.parse(startBox);
+    return [
+        x * size.width,
+        y * size.height
+    ];
+}
+export { uiTarsPlanning };

package/dist/es/common.mjs

@@ -0,0 +1,382 @@
+import { assert, isPlainObject } from "@godscene/shared/utils";
+import { isUITars } from "./ai-model/auto-glm/util.mjs";
+import { NodeType } from "@godscene/shared/constants";
+import { treeToList } from "@godscene/shared/extractor";
+import { compositeElementInfoImg } from "@godscene/shared/img";
+import { getDebug } from "@godscene/shared/logger";
+import { z } from "zod";
+const defaultBboxSize = 20;
+const debugInspectUtils = getDebug('ai:common');
+function pointToBbox(x, y, bboxSize = defaultBboxSize) {
+    const halfSize = bboxSize / 2;
+    const x1 = Math.max(x - halfSize, 0);
+    const y1 = Math.max(y - halfSize, 0);
+    const x2 = Math.min(x + halfSize, 1000);
+    const y2 = Math.min(y + halfSize, 1000);
+    return [
+        x1,
+        y1,
+        x2,
+        y2
+    ];
+}
+function fillBboxParam(locate, width, height, modelFamily) {
+    if (locate.bbox_2d && !locate?.bbox) {
+        locate.bbox = locate.bbox_2d;
+        delete locate.bbox_2d;
+    }
+    if (locate?.bbox) locate.bbox = adaptBbox(locate.bbox, width, height, modelFamily);
+    return locate;
+}
+function adaptQwen2_5Bbox(bbox) {
+    if (bbox.length < 2) {
+        const msg = `invalid bbox data for qwen-vl mode: ${JSON.stringify(bbox)} `;
+        throw new Error(msg);
+    }
+    const result = [
+        Math.round(bbox[0]),
+        Math.round(bbox[1]),
+        'number' == typeof bbox[2] ? Math.round(bbox[2]) : Math.round(bbox[0] + defaultBboxSize),
+        'number' == typeof bbox[3] ? Math.round(bbox[3]) : Math.round(bbox[1] + defaultBboxSize)
+    ];
+    return result;
+}
+function adaptGpt5Bbox(bbox) {
+    if (!Array.isArray(bbox) || 4 !== bbox.length || !bbox.every((value)=>'number' == typeof value && Number.isFinite(value))) {
+        const msg = `invalid bbox data for gpt-5 mode: ${JSON.stringify(bbox)} `;
+        throw new Error(msg);
+    }
+    const numericBbox = bbox;
+    return [
+        numericBbox[0],
+        numericBbox[1],
+        numericBbox[2],
+        numericBbox[3]
+    ];
+}
+function adaptDoubaoBbox(bbox, width, height) {
+    assert(width > 0 && height > 0, 'width and height must be greater than 0 in doubao mode');
+    if ('string' == typeof bbox) {
+        assert(/^(\d+)\s(\d+)\s(\d+)\s(\d+)$/.test(bbox.trim()), `invalid bbox data string for doubao-vision mode: ${bbox}`);
+        const splitted = bbox.split(' ');
+        if (4 === splitted.length) return [
+            Math.round(Number(splitted[0]) * width / 1000),
+            Math.round(Number(splitted[1]) * height / 1000),
+            Math.round(Number(splitted[2]) * width / 1000),
+            Math.round(Number(splitted[3]) * height / 1000)
+        ];
+        throw new Error(`invalid bbox data string for doubao-vision mode: ${bbox}`);
+    }
+    let bboxList = [];
+    if (Array.isArray(bbox) && 'string' == typeof bbox[0]) bbox.forEach((item)=>{
+        if ('string' == typeof item && item.includes(',')) {
+            const [x, y] = item.split(',');
+            bboxList.push(Number(x.trim()), Number(y.trim()));
+        } else if ('string' == typeof item && item.includes(' ')) {
+            const [x, y] = item.split(' ');
+            bboxList.push(Number(x.trim()), Number(y.trim()));
+        } else bboxList.push(Number(item));
+    });
+    else bboxList = bbox;
+    if (4 === bboxList.length || 5 === bboxList.length) return [
+        Math.round(bboxList[0] * width / 1000),
+        Math.round(bboxList[1] * height / 1000),
+        Math.round(bboxList[2] * width / 1000),
+        Math.round(bboxList[3] * height / 1000)
+    ];
+    if (6 === bboxList.length || 2 === bboxList.length || 3 === bboxList.length || 7 === bboxList.length) return [
+        Math.max(0, Math.round(bboxList[0] * width / 1000) - defaultBboxSize / 2),
+        Math.max(0, Math.round(bboxList[1] * height / 1000) - defaultBboxSize / 2),
+        Math.min(width, Math.round(bboxList[0] * width / 1000) + defaultBboxSize / 2),
+        Math.min(height, Math.round(bboxList[1] * height / 1000) + defaultBboxSize / 2)
+    ];
+    if (8 === bbox.length) return [
+        Math.round(bboxList[0] * width / 1000),
+        Math.round(bboxList[1] * height / 1000),
+        Math.round(bboxList[4] * width / 1000),
+        Math.round(bboxList[5] * height / 1000)
+    ];
+    const msg = `invalid bbox data for doubao-vision mode: ${JSON.stringify(bbox)} `;
+    throw new Error(msg);
+}
+function normalizeBboxInput(bbox) {
+    if (Array.isArray(bbox)) {
+        if (Array.isArray(bbox[0])) return bbox[0];
+    }
+    return bbox;
+}
+function adaptBbox(bbox, width, height, modelFamily) {
+    const normalizedBbox = normalizeBboxInput(bbox);
+    let result = [
+        0,
+        0,
+        0,
+        0
+    ];
+    result = 'doubao-vision' === modelFamily || 'doubao-seed' === modelFamily || isUITars(modelFamily) ? adaptDoubaoBbox(normalizedBbox, width, height) : 'gemini' === modelFamily ? adaptGeminiBbox(normalizedBbox, width, height) : 'qwen2.5-vl' === modelFamily ? adaptQwen2_5Bbox(normalizedBbox) : 'gpt-5' === modelFamily ? adaptGpt5Bbox(normalizedBbox) : normalized01000(normalizedBbox, width, height);
+    return result;
+}
+function normalized01000(bbox, width, height) {
+    return [
+        Math.round(bbox[0] * width / 1000),
+        Math.round(bbox[1] * height / 1000),
+        Math.round(bbox[2] * width / 1000),
+        Math.round(bbox[3] * height / 1000)
+    ];
+}
+function adaptGeminiBbox(bbox, width, height) {
+    const left = Math.round(bbox[1] * width / 1000);
+    const top = Math.round(bbox[0] * height / 1000);
+    const right = Math.round(bbox[3] * width / 1000);
+    const bottom = Math.round(bbox[2] * height / 1000);
+    return [
+        left,
+        top,
+        right,
+        bottom
+    ];
+}
+function adaptBboxToRect(bbox, width, height, offsetX = 0, offsetY = 0, rightLimit = width, bottomLimit = height, modelFamily, scale = 1) {
+    debugInspectUtils('adaptBboxToRect', bbox, width, height, 'offset', offsetX, offsetY, 'limit', rightLimit, bottomLimit, 'modelFamily', modelFamily, 'scale', scale);
+    const [left, top, right, bottom] = adaptBbox(bbox, width, height, modelFamily);
+    const rectLeft = Math.max(0, left);
+    const rectTop = Math.max(0, top);
+    const boundedRight = Math.min(right, rightLimit);
+    const boundedBottom = Math.min(bottom, bottomLimit);
+    const rectWidth = boundedRight - rectLeft + 1;
+    const rectHeight = boundedBottom - rectTop + 1;
+    const finalLeft = 1 !== scale ? Math.round(rectLeft / scale) : rectLeft;
+    const finalTop = 1 !== scale ? Math.round(rectTop / scale) : rectTop;
+    const finalWidth = 1 !== scale ? Math.round(rectWidth / scale) : rectWidth;
+    const finalHeight = 1 !== scale ? Math.round(rectHeight / scale) : rectHeight;
+    const rect = {
+        left: finalLeft + offsetX,
+        top: finalTop + offsetY,
+        width: finalWidth,
+        height: finalHeight
+    };
+    debugInspectUtils('adaptBboxToRect, result=', rect);
+    return rect;
+}
+function mergeRects(rects) {
+    const minLeft = Math.min(...rects.map((r)=>r.left));
+    const minTop = Math.min(...rects.map((r)=>r.top));
+    const maxRight = Math.max(...rects.map((r)=>r.left + r.width));
+    const maxBottom = Math.max(...rects.map((r)=>r.top + r.height));
+    return {
+        left: minLeft,
+        top: minTop,
+        width: maxRight - minLeft,
+        height: maxBottom - minTop
+    };
+}
+function expandSearchArea(rect, screenSize) {
+    const minArea = 160000;
+    const expandSize = 100;
+    const expandedLeft = Math.max(rect.left - expandSize, 0);
+    const expandedTop = Math.max(rect.top - expandSize, 0);
+    const expandRect = {
+        left: expandedLeft,
+        top: expandedTop,
+        width: Math.min(rect.left - expandedLeft + rect.width + expandSize, screenSize.width - expandedLeft),
+        height: Math.min(rect.top - expandedTop + rect.height + expandSize, screenSize.height - expandedTop)
+    };
+    const currentArea = expandRect.width * expandRect.height;
+    if (currentArea >= minArea) return expandRect;
+    const centerX = expandRect.left + expandRect.width / 2;
+    const centerY = expandRect.top + expandRect.height / 2;
+    const scaleFactor = Math.sqrt(minArea / currentArea);
+    const newWidth = Math.round(expandRect.width * scaleFactor);
+    const newHeight = Math.round(expandRect.height * scaleFactor);
+    const newLeft = Math.round(centerX - newWidth / 2);
+    const newTop = Math.round(centerY - newHeight / 2);
+    const left = Math.max(newLeft, 0);
+    const top = Math.max(newTop, 0);
+    return {
+        left,
+        top,
+        width: Math.min(newWidth, screenSize.width - left),
+        height: Math.min(newHeight, screenSize.height - top)
+    };
+}
+async function markupImageForLLM(screenshotBase64, tree, size) {
+    const elementsInfo = treeToList(tree);
+    const elementsPositionInfoWithoutText = elementsInfo.filter((elementInfo)=>{
+        if (elementInfo.attributes.nodeType === NodeType.TEXT) return false;
+        return true;
+    });
+    const imagePayload = await compositeElementInfoImg({
+        inputImgBase64: screenshotBase64,
+        elementsPositionInfo: elementsPositionInfoWithoutText,
+        size
+    });
+    return imagePayload;
+}
+function buildYamlFlowFromPlans(plans, actionSpace) {
+    const flow = [];
+    for (const plan of plans){
+        const verb = plan.type;
+        const action = actionSpace.find((action)=>action.name === verb);
+        if (!action) {
+            console.warn(`Cannot convert action ${verb} to yaml flow. Will ignore it.`);
+            continue;
+        }
+        const flowKey = action.interfaceAlias || verb;
+        const flowParam = action.paramSchema ? dumpActionParam(plan.param || {}, action.paramSchema) : {};
+        const shortcutField = 'Launch' === action.name || 'launch' === action.interfaceAlias ? 'uri' : 'Terminate' === action.name || 'terminate' === action.interfaceAlias ? 'uri' : 'RunAdbShell' === action.name || 'runAdbShell' === action.interfaceAlias ? 'command' : void 0;
+        const shortcutKeys = shortcutField ? Object.keys(flowParam) : [];
+        const canInlineShortcut = shortcutField && 1 === shortcutKeys.length && shortcutKeys[0] === shortcutField && 'string' == typeof flowParam[shortcutField];
+        const flowItem = canInlineShortcut ? {
+            [flowKey]: flowParam[shortcutField]
+        } : {
+            [flowKey]: '',
+            ...flowParam
+        };
+        flow.push(flowItem);
+    }
+    return flow;
+}
+const PointSchema = z.object({
+    left: z.number(),
+    top: z.number()
+});
+const SizeSchema = z.object({
+    width: z.number(),
+    height: z.number()
+});
+const RectSchema = PointSchema.and(SizeSchema).and(z.object({
+    zoom: z.number().optional()
+}));
+const TMultimodalPromptSchema = z.object({
+    images: z.array(z.object({
+        name: z.string(),
+        url: z.string()
+    })).optional(),
+    convertHttpImage2Base64: z.boolean().optional()
+});
+const TUserPromptSchema = z.union([
+    z.string(),
+    z.object({
+        prompt: z.string()
+    }).and(TMultimodalPromptSchema.partial())
+]);
+const locateFieldFlagName = 'midscene_location_field_flag';
+const MidsceneLocationInput = z.object({
+    prompt: TUserPromptSchema,
+    deepLocate: z.boolean().optional(),
+    deepThink: z.boolean().optional().describe('@deprecated Use `deepLocate` instead.'),
+    cacheable: z.boolean().optional(),
+    xpath: z.union([
+        z.string(),
+        z.boolean()
+    ]).optional()
+}).passthrough();
+const getMidsceneLocationSchema = ()=>MidsceneLocationInput;
+const ifMidsceneLocatorField = (field)=>{
+    let actualField = field;
+    if (actualField._def?.typeName === 'ZodOptional') actualField = actualField._def.innerType;
+    if (actualField._def?.typeName === 'ZodObject') {
+        const shape = actualField._def.shape();
+        if (locateFieldFlagName in shape) return true;
+        if ('prompt' in shape && shape.prompt) return true;
+    }
+    return false;
+};
+const formatPromptWithImages = (promptObj)=>{
+    let promptString = promptObj.prompt;
+    if (Array.isArray(promptObj.images) && promptObj.images.length > 0) {
+        const imageCount = promptObj.images.length;
+        promptString += ` (with ${imageCount} image${imageCount > 1 ? 's' : ''})`;
+    }
+    return promptString;
+};
+const dumpMidsceneLocatorField = (field)=>{
+    assert(ifMidsceneLocatorField(field), 'field is not a midscene locator field');
+    if ('string' == typeof field) return field;
+    if (field && 'object' == typeof field && field.prompt) {
+        if ('string' == typeof field.prompt) return field.prompt;
+        if ('object' == typeof field.prompt && field.prompt.prompt) return formatPromptWithImages(field.prompt);
+    }
+    return String(field);
+};
+const findAllMidsceneLocatorField = (zodType, requiredOnly)=>{
+    if (!zodType) return [];
+    const zodObject = zodType;
+    if (zodObject._def?.typeName === 'ZodObject' && zodObject.shape) {
+        const keys = Object.keys(zodObject.shape);
+        return keys.filter((key)=>{
+            const field = zodObject.shape[key];
+            if (!ifMidsceneLocatorField(field)) return false;
+            if (requiredOnly) return field._def?.typeName !== 'ZodOptional';
+            return true;
+        });
+    }
+    return [];
+};
+const dumpActionParam = (jsonObject, zodSchema)=>{
+    if (!isPlainObject(jsonObject)) return {};
+    const locatorFields = findAllMidsceneLocatorField(zodSchema);
+    const result = {
+        ...jsonObject
+    };
+    for (const fieldName of locatorFields){
+        const fieldValue = result[fieldName];
+        if (fieldValue) {
+            if ('string' == typeof fieldValue) result[fieldName] = fieldValue;
+            else if ('object' == typeof fieldValue) {
+                if (fieldValue.prompt) {
+                    if ('string' == typeof fieldValue.prompt) result[fieldName] = fieldValue.prompt;
+                    else if ('object' == typeof fieldValue.prompt && fieldValue.prompt.prompt) result[fieldName] = formatPromptWithImages(fieldValue.prompt);
+                }
+            }
+        }
+    }
+    return result;
+};
+const parseActionParam = (rawParam, zodSchema, options)=>{
+    if (!zodSchema) return;
+    const param = rawParam ?? {};
+    const locateFields = findAllMidsceneLocatorField(zodSchema);
+    if (0 === locateFields.length) return zodSchema.parse(param);
+    const locateFieldValues = {};
+    for (const fieldName of locateFields)if (fieldName in param) locateFieldValues[fieldName] = param[fieldName];
+    const paramsForValidation = {};
+    for(const key in param)if (locateFields.includes(key)) paramsForValidation[key] = {
+        prompt: '_dummy_'
+    };
+    else paramsForValidation[key] = param[key];
+    const validated = zodSchema.parse(paramsForValidation);
+    const ratio = options?.shrunkShotToLogicalRatio;
+    for(const fieldName in locateFieldValues){
+        let value = locateFieldValues[fieldName];
+        if (void 0 !== ratio && 1 !== ratio && value && 'object' == typeof value && value.center && value.rect) value = {
+            ...value,
+            center: [
+                Math.round(value.center[0] / ratio),
+                Math.round(value.center[1] / ratio)
+            ],
+            rect: {
+                ...value.rect,
+                left: Math.round(value.rect.left / ratio),
+                top: Math.round(value.rect.top / ratio),
+                width: Math.round(value.rect.width / ratio),
+                height: Math.round(value.rect.height / ratio)
+            }
+        };
+        validated[fieldName] = value;
+    }
+    return validated;
+};
+const finalizeActionName = 'Finalize';
+const getReadableTimeString = (format = 'YYYY-MM-DD HH:mm:ss', timestamp)=>{
+    const now = void 0 !== timestamp ? new Date(timestamp) : new Date();
+    const year = now.getFullYear();
+    const month = String(now.getMonth() + 1).padStart(2, '0');
+    const day = String(now.getDate()).padStart(2, '0');
+    const hours = String(now.getHours()).padStart(2, '0');
+    const minutes = String(now.getMinutes()).padStart(2, '0');
+    const seconds = String(now.getSeconds()).padStart(2, '0');
+    const timeString = format.replace('YYYY', String(year)).replace('MM', month).replace('DD', day).replace('HH', hours).replace('mm', minutes).replace('ss', seconds);
+    return `${timeString} (${format})`;
+};
+export { PointSchema, RectSchema, SizeSchema, TMultimodalPromptSchema, TUserPromptSchema, adaptBbox, adaptBboxToRect, adaptDoubaoBbox, adaptGeminiBbox, adaptGpt5Bbox, adaptQwen2_5Bbox, buildYamlFlowFromPlans, dumpActionParam, dumpMidsceneLocatorField, expandSearchArea, fillBboxParam, finalizeActionName, findAllMidsceneLocatorField, getMidsceneLocationSchema, getReadableTimeString, ifMidsceneLocatorField, markupImageForLLM, mergeRects, normalized01000, parseActionParam, pointToBbox };