@aiscene/shared 8.0.3 → 8.0.5

package/dist/es/img/transform.mjs

@@ -7,6 +7,7 @@ import { getDebug } from "../logger.mjs";
 import { ifInNode } from "../utils.mjs";
 import get_photon from "./get-photon.mjs";
 import get_sharp from "./get-sharp.mjs";
+import { encodedImageInfoOfBuffer } from "./info.mjs";
 const imgDebug = getDebug('img');
 async function saveBase64Image(options) {
     const { base64Data, outputPath } = options;
@@ -69,7 +70,116 @@ async function resizeAndConvertImgBuffer(inputFormat, inputData, newSize) {
         format: 'jpeg'
     };
 }
-const createImgBase64ByFormat = (format, body)=>`data:image/${format};base64,${body}`;
+const rawBase64BodyPattern = /^[A-Za-z0-9+/]+={0,2}$/;
+const base64ImageDataUrlPattern = /^data:image\/(?:png|jpe?g);base64,[A-Za-z0-9+/=\s]+$/i;
+const supportedScreenshotDataUriPattern = /^data:image\/(png|jpe?g);base64,([A-Za-z0-9+/=\s]+)$/i;
+function normalizeBase64Body(body) {
+    return body.replace(/\s/g, '');
+}
+function detectImageMimeTypeFromBuffer(buffer) {
+    if (buffer.length >= 8 && 0x89 === buffer[0] && 0x50 === buffer[1] && 0x4e === buffer[2] && 0x47 === buffer[3] && 0x0d === buffer[4] && 0x0a === buffer[5] && 0x1a === buffer[6] && 0x0a === buffer[7]) return 'image/png';
+    if (buffer.length >= 3 && 0xff === buffer[0] && 0xd8 === buffer[1] && 0xff === buffer[2]) return 'image/jpeg';
+}
+function inferBase64ImageFormat(base64Body) {
+    const buffer = Buffer.from(normalizeBase64Body(base64Body), 'base64');
+    const mimeType = detectImageMimeTypeFromBuffer(buffer);
+    if ('image/jpeg' === mimeType) return 'jpeg';
+    return 'png';
+}
+const createImgBase64ByFormat = (format, body)=>`data:image/${format};base64,${normalizeBase64Body(body)}`;
+const normalizeScreenshotBase64 = (base64, options)=>{
+    const label = options?.label ?? 'screenshot base64';
+    const trimmedBase64 = base64.trim();
+    if (!trimmedBase64) throw new Error(`${label} cannot be empty`);
+    const dataUriMatch = trimmedBase64.match(supportedScreenshotDataUriPattern);
+    if (dataUriMatch) {
+        const imageFormat = 'jpg' === dataUriMatch[1].toLowerCase() ? 'jpeg' : dataUriMatch[1].toLowerCase();
+        const body = normalizeBase64Body(dataUriMatch[2]);
+        if (!body) throw new Error(`${label} cannot be empty`);
+        return createImgBase64ByFormat(imageFormat, body);
+    }
+    if (trimmedBase64.startsWith('data:')) throw new Error(`${label} must be a PNG/JPEG data URI or raw PNG base64 string`);
+    if (!rawBase64BodyPattern.test(normalizeBase64Body(trimmedBase64))) throw new Error(`${label} must be a PNG/JPEG data URI or raw PNG base64 string`);
+    return createImgBase64ByFormat('png', trimmedBase64);
+};
+const normalizeBase64Image = (base64)=>{
+    const trimmedBase64 = base64.trim();
+    if (base64ImageDataUrlPattern.test(trimmedBase64)) return trimmedBase64.replace(/\s/g, '');
+    const base64Body = normalizeBase64Body(trimmedBase64);
+    node_assert(base64Body, 'base64 image must include image data');
+    return createImgBase64ByFormat(inferBase64ImageFormat(base64Body), base64Body);
+};
+function assertValidJpegQuality(jpegQuality) {
+    if (!Number.isInteger(jpegQuality) || jpegQuality < 1 || jpegQuality > 100) throw new Error(`jpegQuality must be an integer between 1 and 100. Received: ${jpegQuality}`);
+}
+function assertValidImageSize(size, label) {
+    if (!Number.isInteger(size.width) || !Number.isInteger(size.height) || size.width <= 0 || size.height <= 0) throw new Error(`${label} width and height must be positive integers. Received width: ${size.width}, height: ${size.height}`);
+}
+async function convertImgBufferToJpeg(inputData, jpegQuality = 90) {
+    assertValidJpegQuality(jpegQuality);
+    if (ifInNode) try {
+        const Sharp = await get_sharp();
+        return await Sharp(inputData).jpeg({
+            quality: jpegQuality
+        }).toBuffer();
+    } catch (error) {
+        imgDebug('Sharp failed, falling back to Photon:', error);
+    }
+    const { PhotonImage } = await get_photon();
+    const inputBytes = new Uint8Array(inputData);
+    const bytesliceResult = PhotonImage.new_from_byteslice(inputBytes);
+    const image = bytesliceResult instanceof Promise ? await bytesliceResult : bytesliceResult;
+    try {
+        return Buffer.from(image.get_bytes_jpeg(jpegQuality));
+    } finally{
+        image.free();
+    }
+}
+async function convertBase64ImageToJpeg(inputBase64, jpegQuality = 90) {
+    assertValidJpegQuality(jpegQuality);
+    const normalized = normalizeBase64Image(inputBase64);
+    const { body } = parseBase64(normalized);
+    const imageBuffer = Buffer.from(body, 'base64');
+    const detectedMimeType = detectImageMimeTypeFromBuffer(imageBuffer);
+    if ('image/jpeg' === detectedMimeType) return createImgBase64ByFormat('jpeg', body);
+    if ('image/png' !== detectedMimeType) throw new Error(`inputBase64 must contain a PNG or JPEG image. Detected: ${detectedMimeType ?? 'unsupported format'}`);
+    const jpegBuffer = await convertImgBufferToJpeg(imageBuffer, jpegQuality);
+    return createImgBase64ByFormat('jpeg', jpegBuffer.toString('base64'));
+}
+async function resizeBase64ImageToJpeg(inputBase64, options) {
+    const jpegQuality = options.jpegQuality ?? 90;
+    assertValidJpegQuality(jpegQuality);
+    assertValidImageSize(options.targetSize, 'targetSize');
+    const normalized = normalizeBase64Image(inputBase64);
+    const { body, mimeType } = parseBase64(normalized);
+    const imageBuffer = Buffer.from(body, 'base64');
+    const sourceSize = encodedImageInfoOfBuffer(imageBuffer);
+    if (options.sourceSize) {
+        assertValidImageSize(options.sourceSize, 'sourceSize');
+        if (options.sourceSize.width !== sourceSize.width || options.sourceSize.height !== sourceSize.height) throw new Error(`sourceSize ${options.sourceSize.width}x${options.sourceSize.height} does not match encoded image dimensions ${sourceSize.width}x${sourceSize.height}`);
+    }
+    const dimensionsUnchanged = sourceSize.width === options.targetSize.width && sourceSize.height === options.targetSize.height;
+    if (dimensionsUnchanged) return convertBase64ImageToJpeg(normalized, jpegQuality);
+    const { buffer } = await resizeAndConvertImgBuffer(mimeType.split('/')[1], imageBuffer, options.targetSize);
+    return createImgBase64ByFormat('jpeg', buffer.toString('base64'));
+}
+async function constrainBase64ImageToMaxSize(inputBase64, options) {
+    if (!Number.isInteger(options.maxSize) || options.maxSize <= 0) throw new Error(`maxSize must be a positive integer. Received: ${options.maxSize}`);
+    const normalized = normalizeBase64Image(inputBase64);
+    const { body } = parseBase64(normalized);
+    const sourceSize = encodedImageInfoOfBuffer(Buffer.from(body, 'base64'));
+    const largestDimension = Math.max(sourceSize.width, sourceSize.height);
+    if (largestDimension <= options.maxSize) return normalized;
+    const scale = options.maxSize / largestDimension;
+    return resizeBase64ImageToJpeg(normalized, {
+        targetSize: {
+            width: Math.max(1, Math.round(sourceSize.width * scale)),
+            height: Math.max(1, Math.round(sourceSize.height * scale))
+        },
+        sourceSize,
+        jpegQuality: options.jpegQuality
+    });
+}
 async function resizeImgBase64(inputBase64, newSize) {
     const { body, mimeType } = parseBase64(inputBase64);
     const imageBuffer = Buffer.from(body, 'base64');
@@ -146,7 +256,7 @@ async function paddingToMatchBlockByBase64(imageBase64, blockSize = 28) {
         photonImage.free();
     }
 }
-async function cropByRect(imageBase64, rect, paddingImage) {
+async function cropByRect(imageBase64, rect, paddingImage = false) {
     const { crop } = await get_photon();
     const photonImage = await photonFromBase64(imageBase64);
     const { left, top, width, height } = rect;
@@ -272,4 +382,4 @@ async function scaleImage(imageBase64, scale) {
         imageBase64: base64
     };
 }
-export { createImgBase64ByFormat, cropByRect, httpImg2Base64, localImg2Base64, paddingToMatchBlock, paddingToMatchBlockByBase64, parseBase64, photonFromBase64, photonToBase64, preProcessImageUrl, resizeAndConvertImgBuffer, resizeImgBase64, saveBase64Image, scaleImage, zoomForGPT4o };
+export { constrainBase64ImageToMaxSize, convertBase64ImageToJpeg, convertImgBufferToJpeg, createImgBase64ByFormat, cropByRect, httpImg2Base64, inferBase64ImageFormat, localImg2Base64, normalizeBase64Image, normalizeScreenshotBase64, paddingToMatchBlock, paddingToMatchBlockByBase64, parseBase64, photonFromBase64, photonToBase64, preProcessImageUrl, resizeAndConvertImgBuffer, resizeBase64ImageToJpeg, resizeImgBase64, saveBase64Image, scaleImage, zoomForGPT4o };

package/dist/es/recorder.mjs

@@ -0,0 +1,249 @@
+const DEFAULT_MIDSCENE_RECORDER_MARKDOWN_MAX_SCREENSHOTS = 20;
+function isMidsceneRecorderPendingDescription(value) {
+    return value?.trim() === 'AI is analyzing element...';
+}
+function getMidsceneRecorderSemantic(event) {
+    return event.semantic;
+}
+function getRecorderPointerActionVerb(actionType) {
+    switch(actionType){
+        case 'Tap':
+            return 'Tap';
+        case 'DoubleClick':
+            return 'Double click';
+        case 'LongPress':
+            return 'Long press';
+        case 'RightClick':
+            return 'Right click';
+        default:
+            return 'Click';
+    }
+}
+function getRecorderDragActionVerb(actionType) {
+    switch(actionType){
+        case 'Swipe':
+            return 'Swipe';
+        case 'DragAndDrop':
+            return 'Drag';
+        default:
+            return 'Drag';
+    }
+}
+function buildMidsceneRecorderReplayInstruction(event, elementDescription) {
+    switch(event.type){
+        case 'navigation':
+            if ('Stop' === event.actionType) return 'Stop loading the current page.';
+            if ('GoBack' === event.actionType) return 'Go back in the browser.';
+            if ('GoForward' === event.actionType) return 'Go forward in the browser.';
+            if ('Reload' === event.actionType) return 'Reload the current page.';
+            if ('NavigationChanged' === event.actionType && event.url) return `Wait for navigation to complete at \`${event.url}\`.`;
+            return event.url ? `Navigate to \`${event.url}\`.` : `Navigate using ${elementDescription}.`;
+        case 'scroll':
+            return event.scrollDestinationDescription ? `Scroll the page/region with description "${elementDescription}" by value "${event.value || 'down'}" until "${event.scrollDestinationDescription}" is visible.` : `Scroll the page/region with description "${elementDescription}" by value "${event.value || 'down'}".`;
+        case 'drag':
+            {
+                const verb = getRecorderDragActionVerb(event.actionType);
+                return `${verb} through the area described as "${elementDescription}".`;
+            }
+        case 'input':
+            return `Input "${event.value || ''}" into the element described as "${elementDescription}".`;
+        case 'keydown':
+            return `Press "${event.value || 'the recorded key'}" on the element described as "${elementDescription}".`;
+        default:
+            {
+                const verb = getRecorderPointerActionVerb(event.actionType);
+                if ('Long press' === verb) return `${verb} the element described as "${elementDescription}".`;
+                return `${verb} on the element described as "${elementDescription}".`;
+            }
+    }
+}
+function buildMidsceneRecorderActionSummary(event, elementDescription) {
+    switch(event.type){
+        case 'navigation':
+            if ('Stop' === event.actionType) return 'Stop page loading';
+            if ('GoBack' === event.actionType) return 'Go back';
+            if ('GoForward' === event.actionType) return 'Go forward';
+            if ('Reload' === event.actionType) return 'Reload page';
+            if ('NavigationChanged' === event.actionType && event.url) return `Wait for navigation to complete at ${event.url}`;
+            return event.url ? `Navigate to ${event.url}` : 'Navigate';
+        case 'scroll':
+            return event.scrollDestinationDescription ? `Scroll ${elementDescription} toward ${event.scrollDestinationDescription}` : `Scroll ${elementDescription}`;
+        case 'drag':
+            return `${getRecorderDragActionVerb(event.actionType)} ${elementDescription}`;
+        case 'input':
+            return `Input into ${elementDescription}`;
+        case 'keydown':
+            return `Press ${event.value || 'key'} on ${elementDescription}`;
+        default:
+            return `${getRecorderPointerActionVerb(event.actionType)} ${elementDescription}`;
+    }
+}
+function getMidsceneRecorderEventDescription(event) {
+    const semantic = getMidsceneRecorderSemantic(event);
+    if (semantic?.actionSummary && !isMidsceneRecorderPendingDescription(semantic.actionSummary)) return semantic.actionSummary;
+    if (semantic?.elementDescription && !isMidsceneRecorderPendingDescription(semantic.elementDescription)) return semantic.elementDescription;
+    if (semantic?.replayInstruction && !isMidsceneRecorderPendingDescription(semantic.replayInstruction)) return semantic.replayInstruction;
+    if ('navigation' === event.type && event.url) return `Navigate to ${event.url}`;
+    if (event.value) return event.actionType ? `${event.actionType} ${event.value}` : event.value;
+    if (event.elementRect?.x !== void 0 && event.elementRect?.y !== void 0) {
+        const prefix = event.actionType || event.type;
+        return `${prefix} (${Math.round(event.elementRect.x)}, ${Math.round(event.elementRect.y)})`;
+    }
+    return event.actionType || event.type;
+}
+function getMidsceneRecorderScreenshotsForLLM(events, maxScreenshots = 1) {
+    return selectRecorderScreenshotCandidates(getRecorderScreenshotCandidates(events), maxScreenshots).map((candidate)=>candidate.screenshot);
+}
+function sanitizeMidsceneRecorderFileName(value) {
+    return value.trim().replace(/[\\/:*?"<>|]+/g, '-').replace(/\s+/g, '-').replace(/-+/g, '-').replace(/^-|-$/g, '').toLowerCase() || 'midscene-recording';
+}
+function normalizeMarkdownAssetBaseDir(baseDir) {
+    const value = (baseDir || './screenshots').replace(/\/+$/g, '');
+    if (value.startsWith('./') || value.startsWith('../')) return value;
+    return `./${value}`;
+}
+function padEventIndex(index) {
+    return String(index + 1).padStart(3, '0');
+}
+function parseScreenshotDataUrl(value) {
+    const dataUrlMatch = value.match(/^data:(image\/[a-zA-Z0-9.+-]+);base64,(.+)$/);
+    if (dataUrlMatch) {
+        const mimeType = dataUrlMatch[1];
+        const extension = mimeType.includes('jpeg') ? 'jpg' : mimeType.split('/')[1]?.replace(/[^a-zA-Z0-9]/g, '') || 'png';
+        return {
+            dataUrl: value,
+            base64Data: dataUrlMatch[2],
+            mimeType,
+            extension
+        };
+    }
+    if (/^[a-zA-Z0-9+/=\s]+$/.test(value) && value.trim().length > 0) {
+        const base64Data = value.replace(/\s+/g, '');
+        return {
+            dataUrl: `data:image/png;base64,${base64Data}`,
+            base64Data,
+            mimeType: 'image/png',
+            extension: 'png'
+        };
+    }
+}
+function getRecorderEventScreenshot(event) {
+    return event.screenshotWithBox || event.screenshotAfter || event.screenshotBefore;
+}
+function hasCoordinateFallback(event) {
+    const semantic = getMidsceneRecorderSemantic(event);
+    return !semantic?.elementDescription && event.elementRect?.x !== void 0 && event.elementRect?.y !== void 0;
+}
+function shouldIncludeMarkdownScreenshot(event, eventIndex, lastEventIndex) {
+    const semantic = getMidsceneRecorderSemantic(event);
+    return 0 === eventIndex || eventIndex === lastEventIndex || 'navigation' === event.type || 'scroll' === event.type || 'input' === event.type || Boolean(event.screenshotWithBox) || !semantic?.elementDescription || hasCoordinateFallback(event);
+}
+function getRecorderScreenshotCandidatePriority(candidate, firstEventIndex, lastEventIndex) {
+    const event = candidate.event;
+    let priority = 0;
+    if (candidate.eventIndex === firstEventIndex) priority += 100;
+    if (candidate.eventIndex === lastEventIndex) priority += 95;
+    if ('navigation' === event.type) priority += 80;
+    if (event.screenshotWithBox) priority += 70;
+    const semantic = getMidsceneRecorderSemantic(event);
+    if (semantic?.source === 'heuristic' || semantic?.confidence === 'low' || semantic?.error) priority += 60;
+    if ('input' === event.type || 'scroll' === event.type) priority += 40;
+    if (!semantic?.elementDescription || hasCoordinateFallback(event)) priority += 30;
+    return priority;
+}
+function selectEvenlyDistributedCandidates(candidates, count) {
+    if (count <= 0) return [];
+    if (candidates.length <= count) return candidates;
+    if (1 === count) return [
+        candidates[Math.floor((candidates.length - 1) / 2)]
+    ];
+    return Array.from({
+        length: count
+    }, (_, index)=>{
+        const candidateIndex = Math.round(index * (candidates.length - 1) / (count - 1));
+        return candidates[candidateIndex];
+    });
+}
+function selectRecorderScreenshotCandidates(candidates, maxScreenshots) {
+    if (maxScreenshots <= 0 || 0 === candidates.length) return [];
+    if (candidates.length <= maxScreenshots) return candidates;
+    const selected = new Map();
+    const firstEventIndex = candidates[0].eventIndex;
+    const lastEventIndex = candidates[candidates.length - 1].eventIndex;
+    const addCandidate = (candidate)=>{
+        if (!candidate || selected.size >= maxScreenshots) return;
+        selected.set(candidate.eventIndex, candidate);
+    };
+    const addEvenly = (pool)=>{
+        const remaining = maxScreenshots - selected.size;
+        if (remaining <= 0) return;
+        const unselected = pool.filter((candidate)=>!selected.has(candidate.eventIndex));
+        for (const candidate of selectEvenlyDistributedCandidates(unselected, remaining))addCandidate(candidate);
+    };
+    addCandidate(candidates[0]);
+    addCandidate(candidates[candidates.length - 1]);
+    addEvenly(candidates.filter((candidate)=>getRecorderScreenshotCandidatePriority(candidate, firstEventIndex, lastEventIndex) >= 60));
+    addEvenly(candidates.filter((candidate)=>getRecorderScreenshotCandidatePriority(candidate, firstEventIndex, lastEventIndex) >= 40));
+    addEvenly(candidates);
+    return Array.from(selected.values()).sort((left, right)=>left.eventIndex - right.eventIndex);
+}
+function getRecorderScreenshotCandidates(events) {
+    const candidates = [];
+    const seenScreenshots = new Set();
+    const lastEventIndex = events.length - 1;
+    for(let eventIndex = 0; eventIndex < events.length; eventIndex += 1){
+        const event = events[eventIndex];
+        if (!shouldIncludeMarkdownScreenshot(event, eventIndex, lastEventIndex)) continue;
+        const screenshot = getRecorderEventScreenshot(event);
+        if (!(!screenshot || seenScreenshots.has(screenshot))) {
+            seenScreenshots.add(screenshot);
+            candidates.push({
+                event,
+                eventIndex,
+                screenshot
+            });
+        }
+    }
+    return candidates;
+}
+function createMidsceneRecorderMarkdownScreenshotAssets(events, options = {}) {
+    const baseDir = normalizeMarkdownAssetBaseDir(options.baseDir);
+    const maxScreenshots = options.maxScreenshots ?? DEFAULT_MIDSCENE_RECORDER_MARKDOWN_MAX_SCREENSHOTS;
+    const candidates = [];
+    for (const candidate of getRecorderScreenshotCandidates(events)){
+        const parsedScreenshot = parseScreenshotDataUrl(candidate.screenshot);
+        if (parsedScreenshot) candidates.push({
+            ...candidate,
+            parsedScreenshot
+        });
+    }
+    return selectRecorderScreenshotCandidates(candidates, maxScreenshots).map(({ event, eventIndex, parsedScreenshot })=>{
+        const safeType = event.type.replace(/[^a-zA-Z0-9-]/g, '-');
+        const fileName = `event-${padEventIndex(eventIndex)}-${safeType}.${parsedScreenshot.extension}`;
+        return {
+            eventIndex,
+            eventHashId: event.hashId,
+            eventType: event.type,
+            relativePath: `${baseDir}/${fileName}`,
+            dataUrl: parsedScreenshot.dataUrl,
+            base64Data: parsedScreenshot.base64Data,
+            mimeType: parsedScreenshot.mimeType
+        };
+    });
+}
+function scalarToYaml(value) {
+    return JSON.stringify(value);
+}
+function stringifyMidsceneRecorderTargetBlock(target) {
+    const lines = [
+        `${target.platformId}:`
+    ];
+    const values = Object.entries(target.values);
+    if (0 === values.length) {
+        lines.push('  {}');
+        return lines.join('\n');
+    }
+    for (const [key, value] of values)lines.push(`  ${key}: ${scalarToYaml(value)}`);
+    return lines.join('\n');
+}
+export { DEFAULT_MIDSCENE_RECORDER_MARKDOWN_MAX_SCREENSHOTS, buildMidsceneRecorderActionSummary, buildMidsceneRecorderReplayInstruction, createMidsceneRecorderMarkdownScreenshotAssets, getMidsceneRecorderEventDescription, getMidsceneRecorderScreenshotsForLLM, getMidsceneRecorderSemantic, sanitizeMidsceneRecorderFileName, stringifyMidsceneRecorderTargetBlock };

package/dist/lib/agent-tools/agent-behavior-init-args.js

@@ -0,0 +1,87 @@
+"use strict";
+var __webpack_require__ = {};
+(()=>{
+    __webpack_require__.d = (exports1, definition)=>{
+        for(var key in definition)if (__webpack_require__.o(definition, key) && !__webpack_require__.o(exports1, key)) Object.defineProperty(exports1, key, {
+            enumerable: true,
+            get: definition[key]
+        });
+    };
+})();
+(()=>{
+    __webpack_require__.o = (obj, prop)=>Object.prototype.hasOwnProperty.call(obj, prop);
+})();
+(()=>{
+    __webpack_require__.r = (exports1)=>{
+        if ('undefined' != typeof Symbol && Symbol.toStringTag) Object.defineProperty(exports1, Symbol.toStringTag, {
+            value: 'Module'
+        });
+        Object.defineProperty(exports1, '__esModule', {
+            value: true
+        });
+    };
+})();
+var __webpack_exports__ = {};
+__webpack_require__.r(__webpack_exports__);
+__webpack_require__.d(__webpack_exports__, {
+    extractAgentBehaviorInitArgs: ()=>extractAgentBehaviorInitArgs,
+    agentBehaviorInitArgShape: ()=>agentBehaviorInitArgShape,
+    getAgentInitArgsSignature: ()=>getAgentInitArgsSignature,
+    shouldRebuildAgentForInitArgs: ()=>shouldRebuildAgentForInitArgs
+});
+const external_zod_namespaceObject = require("zod");
+const agentBehaviorInitArgShape = {
+    aiActContext: external_zod_namespaceObject.z.string().optional().describe('Background knowledge passed to aiAct. Default: no extra context.'),
+    replanningCycleLimit: external_zod_namespaceObject.z.number().int().nonnegative().optional().describe('Maximum number of replanning cycles for aiAct. Default: model adapter default.'),
+    waitAfterAction: external_zod_namespaceObject.z.number().nonnegative().optional().describe('Wait time in milliseconds after each action execution. Default: 300ms.'),
+    screenshotShrinkFactor: external_zod_namespaceObject.z.number().min(1).optional().describe('Screenshot shrink factor before sending images to AI. Default: 1; high values may reduce recognition quality, especially on mobile.')
+};
+function extractAgentBehaviorInitArgs(extracted) {
+    if (!extracted) return;
+    const agentOptions = {
+        ...'string' == typeof extracted.aiActContext ? {
+            aiActContext: extracted.aiActContext
+        } : {},
+        ...'string' == typeof extracted.aiActionContext ? {
+            aiActionContext: extracted.aiActionContext
+        } : {},
+        ...'number' == typeof extracted.replanningCycleLimit ? {
+            replanningCycleLimit: extracted.replanningCycleLimit
+        } : {},
+        ...'number' == typeof extracted.waitAfterAction ? {
+            waitAfterAction: extracted.waitAfterAction
+        } : {},
+        ...'number' == typeof extracted.screenshotShrinkFactor ? {
+            screenshotShrinkFactor: extracted.screenshotShrinkFactor
+        } : {}
+    };
+    return Object.keys(agentOptions).length > 0 ? agentOptions : void 0;
+}
+function stableJsonValue(value) {
+    if (Array.isArray(value)) return value.map(stableJsonValue);
+    if (value && 'object' == typeof value) return Object.fromEntries(Object.entries(value).sort(([left], [right])=>left.localeCompare(right)).map(([key, nestedValue])=>[
+            key,
+            stableJsonValue(nestedValue)
+        ]));
+    return value;
+}
+function getAgentInitArgsSignature(initArgs) {
+    if (!initArgs || 0 === Object.keys(initArgs).length) return;
+    return JSON.stringify(stableJsonValue(initArgs));
+}
+function shouldRebuildAgentForInitArgs(currentSignature, nextSignature) {
+    return currentSignature !== nextSignature && (void 0 !== currentSignature || void 0 !== nextSignature);
+}
+exports.agentBehaviorInitArgShape = __webpack_exports__.agentBehaviorInitArgShape;
+exports.extractAgentBehaviorInitArgs = __webpack_exports__.extractAgentBehaviorInitArgs;
+exports.getAgentInitArgsSignature = __webpack_exports__.getAgentInitArgsSignature;
+exports.shouldRebuildAgentForInitArgs = __webpack_exports__.shouldRebuildAgentForInitArgs;
+for(var __rspack_i in __webpack_exports__)if (-1 === [
+    "agentBehaviorInitArgShape",
+    "extractAgentBehaviorInitArgs",
+    "getAgentInitArgsSignature",
+    "shouldRebuildAgentForInitArgs"
+].indexOf(__rspack_i)) exports[__rspack_i] = __webpack_exports__[__rspack_i];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});

package/dist/lib/agent-tools/base-tools.js

@@ -0,0 +1,197 @@
+"use strict";
+var __webpack_require__ = {};
+(()=>{
+    __webpack_require__.d = (exports1, definition)=>{
+        for(var key in definition)if (__webpack_require__.o(definition, key) && !__webpack_require__.o(exports1, key)) Object.defineProperty(exports1, key, {
+            enumerable: true,
+            get: definition[key]
+        });
+    };
+})();
+(()=>{
+    __webpack_require__.o = (obj, prop)=>Object.prototype.hasOwnProperty.call(obj, prop);
+})();
+(()=>{
+    __webpack_require__.r = (exports1)=>{
+        if ('undefined' != typeof Symbol && Symbol.toStringTag) Object.defineProperty(exports1, Symbol.toStringTag, {
+            value: 'Module'
+        });
+        Object.defineProperty(exports1, '__esModule', {
+            value: true
+        });
+    };
+})();
+var __webpack_exports__ = {};
+__webpack_require__.r(__webpack_exports__);
+__webpack_require__.d(__webpack_exports__, {
+    BaseMidsceneTools: ()=>BaseMidsceneTools
+});
+const img_namespaceObject = require("@aiscene/shared/img");
+const logger_namespaceObject = require("@aiscene/shared/logger");
+const record_command_js_namespaceObject = require("../cli/record-command.js");
+const external_key_alias_utils_js_namespaceObject = require("../key-alias-utils.js");
+const external_cli_report_session_js_namespaceObject = require("./cli-report-session.js");
+const external_init_arg_utils_js_namespaceObject = require("./init-arg-utils.js");
+const external_tool_defaults_js_namespaceObject = require("./tool-defaults.js");
+const external_tool_generator_js_namespaceObject = require("./tool-generator.js");
+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 = (0, logger_namespaceObject.getDebug)('agent-tools:base-tools');
+class BaseMidsceneTools {
+    getInitArgKeys() {
+        return this.initArgSpec ? Object.keys(this.initArgSpec.shape) : [];
+    }
+    extractAgentInitParam(args) {
+        if (!this.initArgSpec) return;
+        const extracted = (0, external_init_arg_utils_js_namespaceObject.extractNamespacedArgs)(args, this.initArgSpec.namespace, this.getInitArgKeys());
+        if (this.initArgSpec.adapt) return this.initArgSpec.adapt(extracted);
+        return extracted;
+    }
+    sanitizeToolArgs(args) {
+        if (!this.initArgSpec) return args;
+        return (0, external_init_arg_utils_js_namespaceObject.sanitizeNamespacedArgs)(args, this.initArgSpec.namespace, this.getInitArgKeys());
+    }
+    getAgentInitArgSchema() {
+        if (!this.initArgSpec) return {};
+        return (0, external_init_arg_utils_js_namespaceObject.createNamespacedInitArgSchema)(this.initArgSpec.namespace, this.initArgSpec.shape);
+    }
+    getAgentInitArgCliMetadata() {
+        if (!this.initArgSpec?.cli) return;
+        const options = Object.fromEntries(this.getInitArgKeys().map((key)=>{
+            const canonicalKey = `${this.initArgSpec.namespace}.${key}`;
+            const preferredName = this.initArgSpec.cli?.preferredNames?.[key] ?? (this.initArgSpec.cli?.preferBareKeys ? (0, external_key_alias_utils_js_namespaceObject.camelToKebab)(key) : canonicalKey);
+            const acceptedNames = new Set([
+                preferredName,
+                ...this.initArgSpec.cli?.preferBareKeys ? (0, external_key_alias_utils_js_namespaceObject.getKeyAliases)(key) : (0, external_key_alias_utils_js_namespaceObject.getKeyAliases)(canonicalKey)
+            ]);
+            acceptedNames.delete(preferredName);
+            return [
+                canonicalKey,
+                {
+                    preferredName,
+                    aliases: [
+                        ...acceptedNames
+                    ]
+                }
+            ];
+        }));
+        return {
+            options
+        };
+    }
+    preparePlatformTools() {
+        return [];
+    }
+    getCliReportSessionName() {}
+    createNewCliReportSession(targetIdentity) {
+        const sessionName = this.getCliReportSessionName();
+        if (!sessionName) return;
+        return (0, external_cli_report_session_js_namespaceObject.generateCliReportSession)(sessionName, targetIdentity);
+    }
+    commitCliReportSession(session) {
+        if (session) (0, external_cli_report_session_js_namespaceObject.writeCliReportSession)(session);
+    }
+    readCliReportFileName() {
+        const sessionName = this.getCliReportSessionName();
+        if (!sessionName) return;
+        return (0, external_cli_report_session_js_namespaceObject.readCliReportSession)(sessionName)?.reportFileName;
+    }
+    readCliReportAgentOptions() {
+        const reportFileName = this.readCliReportFileName();
+        if (!reportFileName) return;
+        return {
+            reportFileName,
+            reportAttributes: {
+                'data-group-id': reportFileName
+            }
+        };
+    }
+    async initTools() {
+        this.toolDefinitions = [];
+        const platformTools = this.preparePlatformTools();
+        this.toolDefinitions.push(...platformTools);
+        let actionSpace;
+        if (this.agent) {
+            actionSpace = await this.agent.getActionSpace();
+            debug('Action space from agent:', actionSpace.map((a)=>a.name).join(', '));
+        } else {
+            const tempDevice = this.createTemporaryDevice();
+            actionSpace = tempDevice.actionSpace();
+            await tempDevice.destroy?.();
+            debug('Action space from temporary device:', actionSpace.map((a)=>a.name).join(', '));
+        }
+        const actionTools = (0, external_tool_generator_js_namespaceObject.generateToolsFromActionSpace)(actionSpace, (args = {})=>this.ensureAgent(this.extractAgentInitParam(args)), (args = {})=>this.sanitizeToolArgs(args), this.getAgentInitArgSchema(), this.getAgentInitArgCliMetadata(), this.toolDefaults);
+        const commonTools = (0, external_tool_generator_js_namespaceObject.generateCommonTools)((args = {})=>this.ensureAgent(this.extractAgentInitParam(args)), this.getAgentInitArgSchema(), this.getAgentInitArgCliMetadata(), this.toolDefaults);
+        this.toolDefinitions.push(...actionTools, ...commonTools);
+        debug('Total tools prepared:', this.toolDefinitions.length);
+    }
+    async destroy() {
+        await this.agent?.destroy?.();
+    }
+    getToolDefinitions() {
+        return this.toolDefinitions;
+    }
+    getCliToolDefinitions() {
+        return [
+            (0, record_command_js_namespaceObject.createRecordCliCommand)((args = {})=>this.ensureAgent(this.extractAgentInitParam(args)), this.getAgentInitArgSchema(), this.getAgentInitArgCliMetadata())
+        ];
+    }
+    setAgent(agent) {
+        this.agent = agent;
+    }
+    setToolDefaults(toolDefaults) {
+        this.toolDefaults = (0, external_tool_defaults_js_namespaceObject.mergeToolDefaults)(this.toolDefaults, toolDefaults);
+    }
+    buildScreenshotContent(screenshot) {
+        const { mimeType, body } = (0, img_namespaceObject.parseBase64)(screenshot);
+        return [
+            {
+                type: 'image',
+                data: body,
+                mimeType
+            }
+        ];
+    }
+    buildTextResult(text) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text
+                }
+            ]
+        };
+    }
+    createDisconnectHandler(platformName) {
+        return async ()=>{
+            if (!this.agent) return this.buildTextResult('No active connection to disconnect');
+            try {
+                await this.agent.destroy?.();
+            } catch (error) {
+                debug('Failed to destroy agent during disconnect:', error);
+            }
+            this.agent = void 0;
+            return this.buildTextResult(`Disconnected from ${platformName}`);
+        };
+    }
+    constructor(){
+        _define_property(this, "agent", void 0);
+        _define_property(this, "toolDefinitions", []);
+        _define_property(this, "toolDefaults", {});
+    }
+}
+exports.BaseMidsceneTools = __webpack_exports__.BaseMidsceneTools;
+for(var __rspack_i in __webpack_exports__)if (-1 === [
+    "BaseMidsceneTools"
+].indexOf(__rspack_i)) exports[__rspack_i] = __webpack_exports__[__rspack_i];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});